diff --git a/IMPLEMENTATION.md b/IMPLEMENTATION.md index b156c23..edd3ff7 100644 --- a/IMPLEMENTATION.md +++ b/IMPLEMENTATION.md @@ -1,15 +1,101 @@ -# Implementation Details (WIP) +# Implementation Details -## WebExtension -### Permissions -|Permission|Description|Usage| -|--|--|--| -|`browser.history`|Access browsing history|When opening receiver selection popup windows, the history log is polluted unless these entries are removed.| -|`menus`|N/A|Display context menus for casting on pages/media, and whitelist menus on the toolbar button.| -|`nativeMessaging`|Exchange messages with programs other than Firefox|Allows communciation with the bridge.| -|`notifications`|Display notifications to you|Show notifications if a bridge issue is found on startup.| -|`storage`|N/A|Store options data.| -|`tabs`|Access browser tabs|Execute scripts within a sender application's tab content script context (possibly unnecessary due to host permissions).| -|`webNavigation`|Access browser activity during navigation|Get URL of frame to determine available cast media types.| -|`webRequest`|N/A|Intercept and redirect Cast SDK requests.| -|``|Acess your data for all websites|Wildcard host permission (may want to switch to optional host permissions).| +**Note:** This is probably a bit verbose since I'm not too experienced with technical writing, but hopefully it will be of some use in explaining the more complex extension functionality. + +## Messaging + +The extension and bridge use a unified messaging format consisting of a JSON object with a `subject` string property and optional `data` property: + +```ts +interface Message { + subject: string; + data?: any; +} +``` + +The message payloads are all fully-typed and defined in [`ext/src/messaging.ts`](./ext/src/messaging.ts). Wrappers around both WebExtension messaging and MessagePort APIs are used to provide type checking based on these message definitions. Almost all messages are sent via messaging connections, rather than one-off `sendMessage`/`postMessage` calls. + +## Cast Instances + +A cast instance is an initialized Web Sender SDK instance with the extension components that handle communication with receiver devices and other required functionality (like receiver selection) and is managed by the [Cast Manager](./ext/src/background/castManager.ts) background script module. + +Only the [Base API](https://web.archive.org/web/20150318065431/https://developers.google.com/cast/docs/chrome_sender) (`chrome.cast`) is implemented, since the Framework API (`chrome.cast.framework`) is a wrapper around the Base API and doesn't require any extra functionality on the extension-side. + +For some background, see [Cast SDK terminology](https://developers.google.com/cast/docs/web_sender/integrate#terminology). + +### Communication + +SDK instances send messages through a MessageChannel managed by the [`pageMessaging`](./ext/src/cast/pageMessenging.ts) module. One side listens for an initialization message containing a MessagePort, then receives messages from the SDK on that port and calls its message listeners so that they can be forwarded to the Cast Manager. The other side sends that initialization message and handles responses back from the Cast Manager. + +### Initialization + +The SDK can be initialized from page scripts (for web sender apps), or from extension scripts in a content script, extension page or background script context. Depending on the context, the way the cast instance is created happens differently. + +#### Page script + +In-page sender apps enable cast functionality by loading the remote Web Sender SDK script: +`https://www.gstatic.com/cv/js/sender/v1/cast_sender.js` + +This points to a loader script that checks the user agent string before injecting the proper SDK script into the page. In Chrome, the SDK script is actually hosted via a `chrome-extension://` URL as a [web accessible resource](https://developer.chrome.com/docs/extensions/mv3/manifest/web_accessible_resources/). + +For an instance created for a page script SDK: + +1. The [`contentInitial.ts`](./ext/src/cast/contentInitial.ts) content script is run at document start and handles some compatibility issues that can't be addressed via extension APIs (like SDK scripts directly loaded from `chrome-extension://` URLs). +2. The page loads the SDK via the usual Google-hosted `cast_sender.js` loader script. +3. The extension intercepts this script load, injects the [`contentBridge.ts`](./ext/src/cast/contentBridge.ts) script that creates a messaging connection to the Cast Manager (via extension messaging) that registers an instance for that context, and waits for a page messaging connection to forward messages through (as described [here](#communication)). The initial request is then transparently redirected to the extension-hosted SDK page script at [`src/cast/content.ts`](./src/cast/content.ts). +4. The SDK page script then creates the SDK objects ([`window.chrome.cast`](https://developers.google.com/cast/docs/reference/web_sender/chrome.cast)), handles loading the Framework API (if requested) and adds a page messaging listener for `cast:intitialized` events. +5. The Cast Manager sends a `cast:initialized` message to the SDK, which then calls the app's initialization handler ([`window.__onGCastApiAvailable`](https://developers.google.com/cast/docs/web_sender/integrate#initialization)). + +#### Extension script + +For an instance created for an extension script: + +1. The extension script imports the [`cast/export.ts`](./ext/src/cast/export.ts) module which creates an SDK instance. Page messaging is still used to communicate with the SDK, despite the lack of a script context boundary to avoid complicating the SDK implementation. +2. The extension script calls the exported `ensureInit` async function. + Depending on the extension script context: + - If **background**: The Cast Manager is called directly, registering a new cast instance, providing it with a port for a newly-created message channel (since extension messaging is only supported between contexts). Page messaging is hooked up such that messages from the SDK are sent to the Cast Manager through this channel and vice versa. + - If **content/extension page**: The `contentBridge.ts` script is imported as a module, with the usual side-effects of creating a messaging connection to the Cast Manager and hooking up page messaging (as described for page script instances). +3. Listeners are added for the `cast:initialized` message, so that the `ensureInit` function can resolve its promise and provide a Cast Manager port after initialization. + +#### All contexts + +The process now continues identically for all contexts: + +1. The page's now-active sender app calls the [`chrome.cast.initialize`](https://developers.google.com/cast/docs/reference/web_sender/chrome.cast#.initialize) API function, sending a `main:initializeCast` message to the Cast Manager, providing it with the [`chrome.cast.ApiConfig`](https://developers.google.com/cast/docs/reference/web_sender/chrome.cast.ApiConfig) data and prompting a receiver availability update. +2. The page is now free to request a session if receivers are available. + +### Sessions + +A sender app can request a session by calling the SDK's [`chrome.cast.requestSession`](https://developers.google.com/cast/docs/reference/web_sender/chrome.cast#.requestSession) method. This sends a `main:requestSession` message to the Cast Manager with a [`chrome.cast.SessionRequest`](https://developers.google.com/cast/docs/reference/web_sender/chrome.cast.SessionRequest?hl=en) object. This will trigger a receiver selection where the Cast Manager opens the popup UI and waits for the user to select a receiver device. + +If the selection is cancelled, a `cast:sessionRequestCancelled` message is sent to the SDK instance allowing. + +Otherwise, if a device is selected, the Cast Manager sends a `bridge:/createCastSession` message to the bridge instance which causes the bridge to launch the requested receiver app on the selected device. Once the app has launched and the cast session has been created, the bridge sends a `main:castSessionCreated` message and further `main:castSessionUpdated` messages back to the Cast Manager. + +Upon receiving the session created/updated messages, the Cast Manager forwards the message to the SDK instance which creates/updates the [`chrome.cast.Session`](https://developers.google.com/cast/docs/reference/web_sender/chrome.cast.Session) object and calls the relevant app listener functions. + +## Bridge + +The bridge is a Node.js-based [native messaging](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/Native_messaging) host application that is launched by Firefox when the extension requests a bridge instance. It receives messages from the extension and provides service discovery and Chromecast device messaging/session management since the WebExtension APIs are too limited to implement this functionality. + +### Daemon + +The bridge can also be run as a daemon by launching the executable with the `-d`/`--daemon` flag. Instead of running as a messaging host, the bridge starts a WebSocket server and listens for incoming connections. On the extension-side, daemon support can be enabled which will automatically connect to a specified WebSocket server address whenever the WebExtension native messaging connection fails. + +When an incoming connection is received the daemon acts as a native messaging server and spawns bridge instances as child processes. The daemon forwards incoming WebSocket messages to the bridge instances and sends responses back over `stdin`/`stdout` as usual. + +Since the daemon is just a WebSocket server, it can configured to be used remotely, so the bridge doesn't have to be running on the same machine as the extension. However, remote connections could cause performance issues due to increased latency and may be unstable or insecure. Local media casting will also be unavailable. + +## WebExtension Permissions + +| Permission | Description | Usage | +| ----------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | +| `browser.history` | Access browsing history | When opening receiver selection popup windows, the history log is polluted unless these entries are removed. | +| `menus` | N/A | Display context menus for casting on pages/media, and whitelist menus on the toolbar button. | +| `nativeMessaging` | Exchange messages with programs other than Firefox | Allows communciation with the bridge. | +| `notifications` | Display notifications to you | Show notifications if a bridge issue is found on startup. | +| `storage` | N/A | Store options data. | +| `tabs` | Access browser tabs | Execute scripts within a sender application's tab content script context (possibly unnecessary due to host permissions). | +| `webNavigation` | Access browser activity during navigation | Get URL of frame to determine available cast media types. | +| `webRequest` | N/A | Intercept and redirect Cast SDK requests. | +| `` | Acess your data for all websites | Wildcard host permission since the extension uses its own match pattern whitelist (may want to switch to optional host permissions in the future). | diff --git a/app/src/bridge/components/cast/Session.ts b/app/src/bridge/components/cast/Session.ts index de514b7..ba39138 100644 --- a/app/src/bridge/components/cast/Session.ts +++ b/app/src/bridge/components/cast/Session.ts @@ -140,7 +140,7 @@ export default class Session extends CastClient { messageData = JSON.stringify(messageData); messaging.sendMessage({ - subject: "cast:receivedSessionMessage", + subject: "cast:sessionMessageReceived", data: { sessionId: this.sessionId, namespace, diff --git a/app/src/bridge/messaging.ts b/app/src/bridge/messaging.ts index cac69cd..ecd2edc 100644 --- a/app/src/bridge/messaging.ts +++ b/app/src/bridge/messaging.ts @@ -144,7 +144,7 @@ type MessageDefinitions = { * Sent to cast API instance from bridge when session message * received from a receiver device. */ - "cast:receivedSessionMessage": { + "cast:sessionMessageReceived": { sessionId: string; namespace: string; messageData: string; diff --git a/ext/bin/build.js b/ext/bin/build.js index 9d78724..0669a4c 100644 --- a/ext/bin/build.js +++ b/ext/bin/build.js @@ -66,11 +66,11 @@ const buildOpts = { // Main path.join(srcPath, "background/background.ts"), // Cast - path.join(srcPath, "cast/index.ts"), path.join(srcPath, "cast/content.ts"), + path.join(srcPath, "cast/contentInitial.ts"), path.join(srcPath, "cast/contentBridge.ts"), // Media sender - path.join(srcPath, "cast/senders/media/index.ts"), + path.join(srcPath, "cast/senders/media.ts"), // Mirroring sender path.join(srcPath, "/cast/senders/mirroring.ts"), // UI diff --git a/ext/src/background/ReceiverSelector.ts b/ext/src/background/ReceiverSelector.ts index f26e302..c5cad5e 100644 --- a/ext/src/background/ReceiverSelector.ts +++ b/ext/src/background/ReceiverSelector.ts @@ -4,23 +4,15 @@ import logger from "../lib/logger"; import messaging, { Port, Message } from "../messaging"; import options from "../lib/options"; import { TypedEventTarget } from "../lib/TypedEventTarget"; -import { getMediaTypesForPageUrl } from "../lib/utils"; -import { +import type { SenderMediaMessage, SenderMessage } from "../cast/sdk/types"; +import type { ReceiverDevice, + ReceiverSelectorAppInfo, ReceiverSelectorMediaType, ReceiverSelectorPageInfo } from "../types"; -import deviceManager from "./deviceManager"; -import castManager from "./castManager"; - -import { BaseConfig, baseConfigStorage, getAppTag } from "../cast/googleApi"; -import type { SenderMediaMessage, SenderMessage } from "../cast/sdk/types"; -import type { SessionRequest } from "../cast/sdk/classes"; -import { ReceiverAction } from "../cast/sdk/enums"; -import { createReceiver } from "../cast/utils"; - const POPUP_URL = browser.runtime.getURL("ui/popup/index.html"); export interface ReceiverSelection { @@ -47,8 +39,6 @@ interface ReceiverSelectorEvents { mediaMessage: ReceiverSelectorMediaMessage; } -let baseConfig: BaseConfig; - /** * Manages the receiver selector popup window and communication with the * extension page hosted within. @@ -68,8 +58,7 @@ export default class ReceiverSelector extends TypedEventTarget { - let castInstance = castManager.getInstance( - contextTabId, - contextFrameId - ); - /** - * If the current context is running the mirroring app, pretend - * it doesn't exist because it shouldn't be launched like this. - */ - if ( - castInstance?.apiConfig?.sessionRequest.appId === - (await options.get("mirroringAppId")) - ) { - castInstance = undefined; - } - - let defaultMediaType = ReceiverSelectorMediaType.Tab; - let availableMediaTypes = ReceiverSelectorMediaType.None; - - let pageUrl: string | undefined; - try { - pageUrl = ( - await browser.webNavigation.getFrame({ - tabId: contextTabId, - frameId: contextFrameId - }) - ).url; - - availableMediaTypes = getMediaTypesForPageUrl(pageUrl); - } catch { - logger.error( - "Failed to locate frame, falling back to default available media types." - ); - } - - // Enable app media type if sender application is present - if (castInstance || selectionOpts?.withMediaSender) { - defaultMediaType = ReceiverSelectorMediaType.App; - availableMediaTypes |= ReceiverSelectorMediaType.App; - } - - const opts = await options.getAll(); - - // Disable mirroring media types if mirroring is not enabled - if (!opts.mirroringEnabled) { - availableMediaTypes &= ~( - ReceiverSelectorMediaType.Tab | ReceiverSelectorMediaType.Screen - ); - } - - // Remove file media type if local media is not enabled - if (!opts.mediaEnabled || !opts.localMediaEnabled) { - availableMediaTypes &= ~ReceiverSelectorMediaType.File; - } - - // Ensure status manager is initialized - await deviceManager.init(); - - let isRequestAppAudioCompatible: Optional; - if (castInstance?.apiConfig?.sessionRequest.appId) { - if (!baseConfig) { - try { - baseConfig = (await baseConfigStorage.get("baseConfig")) - .baseConfig; - } catch (err) { - throw logger.error("Failed to get Chromecast base config!"); - } - } - - isRequestAppAudioCompatible = getAppTag( - baseConfig, - castInstance.apiConfig?.sessionRequest.appId - )?.supports_audio_only; - } - - return new Promise(async (resolve, reject) => { - // Close an existing open selector - if (ReceiverSelector.sharedInstance.isOpen) { - await ReceiverSelector.sharedInstance.close(); - } - - const selector = createSelector(); - ReceiverSelector.sharedInstance = selector; - - // Handle selected return value - const onSelected = (ev: CustomEvent) => - resolve(ev.detail); - selector.addEventListener("selected", onSelected); - - // Handle cancelled return value - const onCancelled = () => resolve(null); - selector.addEventListener("cancelled", onCancelled); - - const onError = (ev: CustomEvent) => reject(ev.detail); - selector.addEventListener("error", onError); - - // Cleanup listeners - selector.addEventListener( - "close", - () => { - selector.removeEventListener("selected", onSelected); - selector.removeEventListener("cancelled", onCancelled); - selector.removeEventListener("error", onError); - }, - { once: true } - ); - - selector.open({ - receiverDevices: deviceManager.getDevices(), - defaultMediaType, - availableMediaTypes, - appId: castInstance?.apiConfig?.sessionRequest.appId, - // Create page info - pageInfo: pageUrl - ? { - url: pageUrl, - tabId: contextTabId, - frameId: contextFrameId, - sessionRequest: selectionOpts?.sessionRequest, - isRequestAppAudioCompatible - } - : undefined - }); - }); - } -} - -/** - * Creates new ReceiverSelector object and adds listeners for - * updates/messages. - */ -function createSelector() { - // Get a new selector for each selection - const selector = new ReceiverSelector(); - ReceiverSelector.sharedInstance = selector; - - /** - * Sends message to cast instance to trigger stopped receiver action - * (if applicable). - */ - const onStop = (ev: CustomEvent<{ deviceId: string }>) => { - const castInstance = castManager.getInstanceByDeviceId( - ev.detail.deviceId - ); - if (!castInstance) return; - - const device = deviceManager.getDeviceById(ev.detail.deviceId); - if (!device) return; - - castInstance.contentPort.postMessage({ - subject: "cast:sendReceiverAction", - data: { - receiver: createReceiver(device), - action: ReceiverAction.STOP - } - }); - }; - selector.addEventListener("stop", onStop); - - // Forward receiver messages - const onReceiverMessage = ( - ev: CustomEvent - ) => - deviceManager.sendReceiverMessage( - ev.detail.deviceId, - ev.detail.message - ); - selector.addEventListener("receiverMessage", onReceiverMessage); - - // Forward media messages - const onMediaMessage = (ev: CustomEvent) => - deviceManager.sendMediaMessage(ev.detail.deviceId, ev.detail.message); - selector.addEventListener("mediaMessage", onMediaMessage); - - // Update selector data whenever devices change/update - const onDeviceChange = () => selector.update(deviceManager.getDevices()); - - deviceManager.addEventListener("deviceUp", onDeviceChange); - deviceManager.addEventListener("deviceDown", onDeviceChange); - deviceManager.addEventListener("deviceUpdated", onDeviceChange); - deviceManager.addEventListener("deviceMediaUpdated", onDeviceChange); - - // Cleanup listeners - selector.addEventListener( - "close", - () => { - deviceManager.removeEventListener("deviceUp", onDeviceChange); - deviceManager.removeEventListener("deviceDown", onDeviceChange); - deviceManager.removeEventListener("deviceUpdated", onDeviceChange); - deviceManager.removeEventListener( - "deviceMediaUpdated", - onDeviceChange - ); - - selector.removeEventListener("stop", onStop); - selector.removeEventListener("receiverMessage", onReceiverMessage); - selector.removeEventListener("mediaMessage", onMediaMessage); - }, - { once: true } - ); - - return selector; } diff --git a/ext/src/background/background.ts b/ext/src/background/background.ts index 72f3884..ffb98e8 100755 --- a/ext/src/background/background.ts +++ b/ext/src/background/background.ts @@ -7,11 +7,10 @@ import bridge, { BridgeInfo } from "../lib/bridge"; import castManager from "./castManager"; import deviceManager from "./deviceManager"; -import ReceiverSelector from "./ReceiverSelector"; import { initMenus } from "./menus"; import { initWhitelist } from "./whitelist"; -import { baseConfigStorage, fetchBaseConfig } from "../cast/googleApi"; +import { baseConfigStorage, fetchBaseConfig } from "../lib/chromecastConfigApi"; const _ = browser.i18n.getMessage; @@ -133,26 +132,13 @@ async function init() { await initMenus(); await initWhitelist(); - /** - * When the browser action is clicked, open a receiver selector and - * load a sender for the response. The mirroring sender is loaded - * into the current tab at the - * top-level frame. - */ browser.browserAction.onClicked.addListener(async tab => { if (tab.id === undefined) { logger.error("Tab ID not found in browser action handler."); return; } - const selection = await ReceiverSelector.getSelection(tab.id); - if (selection) { - castManager.loadSender({ - tabId: tab.id, - frameId: 0, - selection - }); - } + castManager.triggerCast(tab.id); }); } diff --git a/ext/src/background/castManager.ts b/ext/src/background/castManager.ts index 511110d..4546125 100644 --- a/ext/src/background/castManager.ts +++ b/ext/src/background/castManager.ts @@ -1,32 +1,40 @@ "use strict"; import bridge from "../lib/bridge"; +import { + BaseConfig, + baseConfigStorage, + getAppTag +} from "../lib/chromecastConfigApi"; import logger from "../lib/logger"; import messaging, { Message, Port } from "../messaging"; import options from "../lib/options"; -import { stringify } from "../lib/utils"; +import { getMediaTypesForPageUrl, stringify } from "../lib/utils"; +import type { TypedMessagePort } from "../lib/TypedMessagePort"; -import { ReceiverSelectorMediaType } from "../types"; +import { + ReceiverSelectorAppInfo, + ReceiverSelectorMediaType, + ReceiverSelectorPageInfo +} from "../types"; import type { ApiConfig } from "../cast/sdk/classes"; import { ReceiverAction } from "../cast/sdk/enums"; import { createReceiver } from "../cast/utils"; import deviceManager from "./deviceManager"; -import ReceiverSelector, { ReceiverSelection } from "./ReceiverSelector"; -type AnyPort = Port | MessagePort; +import ReceiverSelector, { + ReceiverSelection, + ReceiverSelectorMediaMessage, + ReceiverSelectorReceiverMessage +} from "./ReceiverSelector"; -export interface CastInstance { - bridgePort: Port; - contentPort: AnyPort; - contentTabId?: number; - contentFrameId?: number; +type AnyPort = Port | TypedMessagePort; - /** ApiConfig provided on initialization. */ - apiConfig?: ApiConfig; - /** Established session details. */ - session?: CastSession; +export interface ContentContext { + tabId: number; + frameId: number; } interface CastSession { @@ -34,11 +42,73 @@ interface CastSession { deviceId: string; } +export interface CastInstance { + bridgePort: Port; + contentPort: AnyPort; + contentContext?: ContentContext; + + /** ApiConfig provided on initialization. */ + apiConfig?: ApiConfig; + /** Established session details. */ + session?: CastSession; +} + +/** Creates a cast instance object and associated bridge instance. */ +async function createCastInstance(opts: { + bridgePort?: Port; + contentPort: AnyPort; + contentContext?: { tabId: number; frameId?: number }; +}) { + const instance: CastInstance = { + bridgePort: opts.bridgePort ?? (await bridge.connect()), + contentPort: opts.contentPort + }; + + /** + * Set content context with fallback to extension message sender + * context for content scripts. + */ + if (opts.contentContext) { + instance.contentContext = { + tabId: opts.contentContext.tabId, + frameId: opts.contentContext.frameId ?? 0 + }; + } else if ( + !(opts.contentPort instanceof MessagePort) && + opts.contentPort.sender?.tab?.id + ) { + instance.contentContext = { + tabId: opts.contentPort.sender.tab.id, + frameId: opts.contentPort.sender.frameId ?? 0 + }; + } + + return instance; +} + +/** Disconnects either instance content port type. */ +function disconnectContentPort(port: AnyPort) { + if (port instanceof MessagePort) { + port.close(); + } else { + port.disconnect(); + } +} + +/** Checks if two content contexts match. */ +function isSameContext(ctx1?: ContentContext, ctx2?: ContentContext) { + if (!ctx1 || !ctx2) return false; + return ctx1?.tabId === ctx2?.tabId && ctx1?.frameId === ctx2?.frameId; +} + +let baseConfig: BaseConfig; +let receiverSelector: Optional; + /** Keeps track of cast API instances and provides bridge messaging. */ -export default new (class { +const castManager = new (class { private activeInstances = new Set(); - public async init() { + async init() { // Handle incoming instance connections messaging.onConnect.addListener(async port => { if (port.name === "cast") { @@ -52,7 +122,7 @@ export default new (class { for (const instance of this.activeInstances) { instance.contentPort.postMessage({ - subject: "cast:updateReceiverAvailability", + subject: "cast:receiverAvailabilityUpdated", data: { isAvailable } }); } @@ -68,11 +138,11 @@ export default new (class { /** * Finds a cast instance at the given tab (and optionally frame) ID. */ - public getInstance(tabId: number, frameId?: number) { + getInstanceAt(tabId: number, frameId?: number) { for (const instance of this.activeInstances) { - if (instance.contentTabId === tabId) { + if (instance.contentContext?.tabId === tabId) { // If frame ID doesn't match go to next instance - if (frameId && instance.contentFrameId !== frameId) { + if (frameId && instance.contentContext.frameId !== frameId) { continue; } @@ -81,7 +151,7 @@ export default new (class { } } - public getInstanceByDeviceId(deviceId: string) { + getInstanceByDeviceId(deviceId: string) { for (const instance of this.activeInstances) { if (instance.session?.deviceId === deviceId) return instance; } @@ -91,9 +161,9 @@ export default new (class { * Creates a cast instance with a given port and connects messaging * correctly depending on the type of port. */ - public async createInstance(port: AnyPort) { + async createInstance(port: AnyPort, contentContext?: ContentContext) { const instance = await (port instanceof MessagePort - ? this.createInstanceFromBackground(port) + ? this.createInstanceFromBackground(port, contentContext) : this.createInstanceFromContent(port)); this.activeInstances.add(instance); @@ -108,27 +178,41 @@ export default new (class { /** Creates a cast instance with a `MessagePort` content port. */ private async createInstanceFromBackground( - contentPort: MessagePort + contentPort: MessagePort, + contentContext?: ContentContext ): Promise { - const instance: CastInstance = { + const instance = await createCastInstance({ bridgePort: await bridge.connect(), - contentPort - }; + contentPort, + contentContext + }); + + // Ensure only one instance per context + if (contentContext) { + for (const instance of this.activeInstances) { + if (isSameContext(instance.contentContext, contentContext)) { + instance.bridgePort.disconnect(); + this.activeInstances.delete(instance); + break; + } + } + } instance.bridgePort.onDisconnect.addListener(() => { contentPort.close(); this.activeInstances.delete(instance); }); - // bridge -> content + // bridge -> cast instance instance.bridgePort.onMessage.addListener(message => { this.handleBridgeMessage(instance, message); }); - // content -> (any) + // cast instance -> (any) contentPort.addEventListener("message", ev => { this.handleContentMessage(instance, ev.data); }); + contentPort.start(); return instance; } @@ -148,33 +232,27 @@ export default new (class { ); } - /** - * If there's already an active instance for the sender - * tab/frame ID, disconnect it. - * - * TODO: Fix this behaviour! - */ + // Ensure only one instance per context for (const instance of this.activeInstances) { if ( - instance.contentTabId === contentPort.sender.tab.id && - instance.contentFrameId === contentPort.sender.frameId + isSameContext( + instance.contentContext, + contentPort.sender as ContentContext + ) ) { instance.bridgePort.disconnect(); + disconnectContentPort(instance.contentPort); + break; } } - const instance: CastInstance = { - bridgePort: await bridge.connect(), - contentPort, - contentTabId: contentPort.sender.tab.id, - contentFrameId: contentPort.sender.frameId - }; + const instance = await createCastInstance({ contentPort }); - // content -> (any) + // cast instance -> (any) const onContentPortMessage = (message: Message) => { this.handleContentMessage(instance, message); }; - // bridge -> content + // bridge -> cast instance const onBridgePortMessage = (message: Message) => { this.handleBridgeMessage(instance, message); }; @@ -206,16 +284,17 @@ export default new (class { switch (message.subject) { case "main:castSessionCreated": { // Close after session is created - const selector = ReceiverSelector.sharedInstance; if ( - selector.isOpen && + receiverSelector?.isOpen && // If selector context is the same as the instance context - selector.pageInfo?.tabId === instance.contentTabId && - selector.pageInfo?.frameId === instance.contentFrameId && + receiverSelector.pageInfo?.tabId === + instance.contentContext?.tabId && + receiverSelector.pageInfo?.frameId === + instance.contentContext?.frameId && // If selector is supposed to close (await options.get("receiverSelectorWaitForConnection")) ) { - selector.close(); + receiverSelector.close(); } const { receiverId: deviceId } = message.data; @@ -270,44 +349,30 @@ export default new (class { } switch (message.subject) { - // Cast API has been initialized - case "main:initializeCast": { + case "main:initializeCast": instance.apiConfig = message.data.apiConfig; - instance.contentPort.postMessage({ - subject: "cast:updateReceiverAvailability", + subject: "cast:receiverAvailabilityUpdated", data: { isAvailable: deviceManager.getDevices().length > 0 } }); break; - } // User has triggered receiver selection via the cast API - case "main:selectReceiver": { - if ( - instance.contentTabId === undefined || - instance.contentFrameId === undefined - ) { - throw logger.error( - "Cast instance associated with content sender missing tab/frame ID" - ); - } - + case "main:requestSession": { const { sessionRequest } = message.data; try { - const selection = await ReceiverSelector.getSelection( - instance.contentTabId, - instance.contentFrameId, - { sessionRequest } - ); + const selection = await getReceiverSelection({ + castInstance: instance + }); // Handle cancellation if (!selection) { instance.contentPort.postMessage({ - subject: "cast:selectReceiver/cancelled" + subject: "cast:sessionRequestCancelled" }); break; @@ -320,14 +385,13 @@ export default new (class { */ if (selection.mediaType !== ReceiverSelectorMediaType.App) { instance.contentPort.postMessage({ - subject: "cast:selectReceiver/cancelled" + subject: "cast:sessionRequestCancelled" }); - this.loadSender({ - tabId: instance.contentTabId, - frameId: instance.contentFrameId, - selection - }); + if (!instance.contentContext) { + throw logger.error("Missing content context"); + } + this.loadSender(selection, instance.contentContext); break; } @@ -342,7 +406,7 @@ export default new (class { } catch (err) { // TODO: Report errors properly instance.contentPort.postMessage({ - subject: "cast:selectReceiver/cancelled" + subject: "cast:sessionRequestCancelled" }); } @@ -352,25 +416,45 @@ export default new (class { } /** - * Loads the appropriate sender for a given receiver selector - * response. + * Gets a receiver selection and loads the appropriate sender for a + * given context. */ - public async loadSender(opts: { - tabId: number; - frameId?: number; - selection: ReceiverSelection; - }) { - // Cancelled - if (!opts.selection) { + async triggerCast(tabId: number, frameId = 0) { + let selection: Nullable; + try { + selection = await getReceiverSelection({ tabId, frameId }); + } catch (err) { + logger.error("Failed to get receiver selection (triggerCast)", err); return; } - switch (opts.selection.mediaType) { + if (!selection) return; + + this.loadSender(selection, { tabId, frameId }); + } + + /** + * Loads the appropriate sender for a given receiver selector + * response. + */ + private async loadSender( + selection: ReceiverSelection, + contentContext: ContentContext + ) { + // Cancelled + if (!selection) { + return; + } + + switch (selection.mediaType) { case ReceiverSelectorMediaType.App: { - const instance = this.getInstance(opts.tabId, opts.frameId); + const instance = this.getInstanceAt( + contentContext.tabId, + contentContext.frameId + ); if (!instance) { throw logger.error( - `Cast instance not found at tabId ${opts.tabId} / frameId ${opts.frameId}` + `Cast instance not found at tabId ${contentContext.tabId} / frameId ${contentContext.frameId}` ); } @@ -379,9 +463,9 @@ export default new (class { } instance.contentPort.postMessage({ - subject: "cast:sendReceiverAction", + subject: "cast:receiverAction", data: { - receiver: createReceiver(opts.selection.receiverDevice), + receiver: createReceiver(selection.receiverDevice), action: ReceiverAction.CAST } }); @@ -390,7 +474,7 @@ export default new (class { subject: "bridge:createCastSession", data: { appId: instance.apiConfig?.sessionRequest.appId, - receiverDevice: opts.selection.receiverDevice + receiverDevice: selection.receiverDevice } }); @@ -398,34 +482,239 @@ export default new (class { } case ReceiverSelectorMediaType.Tab: - case ReceiverSelectorMediaType.Screen: { - await browser.tabs.executeScript(opts.tabId, { + case ReceiverSelectorMediaType.Screen: + await browser.tabs.executeScript(contentContext.tabId, { code: stringify` - window.selectedMedia = ${opts.selection.mediaType}; - window.selectedReceiver = ${opts.selection.receiverDevice}; + window.selectedMedia = ${selection.mediaType}; + window.selectedReceiver = ${selection.receiverDevice}; `, - frameId: opts.frameId + frameId: contentContext.frameId }); - await browser.tabs.executeScript(opts.tabId, { + await browser.tabs.executeScript(contentContext.tabId, { file: "cast/senders/mirroring.js", - frameId: opts.frameId + frameId: contentContext.frameId }); break; - } - - case ReceiverSelectorMediaType.File: { - const fileUrl = new URL(`file://${opts.selection.filePath}`); - const { init } = await import("../cast/senders/media"); - - init({ - mediaUrl: fileUrl.href, - receiver: opts.selection.receiverDevice - }); - - break; - } } } })(); + +/** + * Opens a receiver selector with the specified default/available media + * types. + * + * Returns a promise that: + * - Resolves to a ReceiverSelection object if selection is + * successful. + * - Resolves to null if the selection is cancelled. + * - Rejects if the selection fails. + */ +async function getReceiverSelection(selectionOpts: { + tabId?: number; + frameId?: number; + castInstance?: CastInstance; +}): Promise { + /** + * If the current context is running the mirroring app, pretend + * it doesn't exist because it shouldn't be launched like this. + */ + if ( + selectionOpts.castInstance?.apiConfig?.sessionRequest.appId === + (await options.get("mirroringAppId")) + ) { + selectionOpts.castInstance = undefined; + } + + let defaultMediaType = ReceiverSelectorMediaType.Tab; + let availableMediaTypes = ReceiverSelectorMediaType.None; + + // Default frame ID + if (!selectionOpts.frameId) selectionOpts.frameId = 0; + + // Fallback to instance context + if (!selectionOpts.tabId && selectionOpts.castInstance?.contentContext) { + selectionOpts.tabId = selectionOpts.castInstance.contentContext.tabId; + selectionOpts.frameId = + selectionOpts.castInstance.contentContext.frameId; + } + + let pageInfo: Optional; + if (selectionOpts.tabId) { + try { + pageInfo = { + tabId: selectionOpts.tabId, + frameId: selectionOpts.frameId, + url: ( + await browser.webNavigation.getFrame({ + tabId: selectionOpts.tabId, + frameId: selectionOpts.frameId + }) + ).url + }; + + availableMediaTypes = getMediaTypesForPageUrl(pageInfo.url); + } catch { + logger.error( + "Failed to locate frame, falling back to default available media types." + ); + } + } + + // Enable app media type if sender application is present + if (selectionOpts.castInstance) { + defaultMediaType = ReceiverSelectorMediaType.App; + availableMediaTypes |= ReceiverSelectorMediaType.App; + } + + const opts = await options.getAll(); + + // Disable mirroring media types if mirroring is not enabled + if (!opts.mirroringEnabled) { + availableMediaTypes &= ~( + ReceiverSelectorMediaType.Tab | ReceiverSelectorMediaType.Screen + ); + } + + // Ensure status manager is initialized + await deviceManager.init(); + + let appInfo: Optional; + if (selectionOpts.castInstance?.apiConfig) { + if (!baseConfig) { + try { + baseConfig = (await baseConfigStorage.get("baseConfig")) + .baseConfig; + } catch (err) { + throw logger.error("Failed to get Chromecast base config!"); + } + } + + appInfo = { + sessionRequest: + selectionOpts.castInstance.apiConfig?.sessionRequest, + isRequestAppAudioCompatible: getAppTag( + baseConfig, + selectionOpts.castInstance.apiConfig?.sessionRequest.appId + )?.supports_audio_only + }; + } + + return new Promise(async (resolve, reject) => { + // Close an existing open selector + if (receiverSelector?.isOpen) { + await receiverSelector.close(); + } + receiverSelector = createSelector(); + + // Handle selected return value + const onSelected = (ev: CustomEvent) => + resolve(ev.detail); + receiverSelector.addEventListener("selected", onSelected); + + // Handle cancelled return value + const onCancelled = () => resolve(null); + receiverSelector.addEventListener("cancelled", onCancelled); + + const onError = (ev: CustomEvent) => reject(ev.detail); + receiverSelector.addEventListener("error", onError); + + // Cleanup listeners + receiverSelector.addEventListener( + "close", + () => { + receiverSelector?.removeEventListener("selected", onSelected); + receiverSelector?.removeEventListener("cancelled", onCancelled); + receiverSelector?.removeEventListener("error", onError); + }, + { once: true } + ); + + receiverSelector.open({ + receiverDevices: deviceManager.getDevices(), + defaultMediaType, + availableMediaTypes, + appInfo, + pageInfo + }); + }); +} + +/** + * Creates new ReceiverSelector object and adds listeners for + * updates/messages. + */ +function createSelector() { + // Get a new selector for each selection + const selector = new ReceiverSelector(); + + /** + * Sends message to cast instance to trigger stopped receiver action + * (if applicable). + */ + const onStop = (ev: CustomEvent<{ deviceId: string }>) => { + const castInstance = castManager.getInstanceByDeviceId( + ev.detail.deviceId + ); + if (!castInstance) return; + + const device = deviceManager.getDeviceById(ev.detail.deviceId); + if (!device) return; + + castInstance.contentPort.postMessage({ + subject: "cast:receiverAction", + data: { + receiver: createReceiver(device), + action: ReceiverAction.STOP + } + }); + }; + selector.addEventListener("stop", onStop); + + // Forward receiver messages + const onReceiverMessage = ( + ev: CustomEvent + ) => + deviceManager.sendReceiverMessage( + ev.detail.deviceId, + ev.detail.message + ); + selector.addEventListener("receiverMessage", onReceiverMessage); + + // Forward media messages + const onMediaMessage = (ev: CustomEvent) => + deviceManager.sendMediaMessage(ev.detail.deviceId, ev.detail.message); + selector.addEventListener("mediaMessage", onMediaMessage); + + // Update selector data whenever devices change/update + const onDeviceChange = () => selector.update(deviceManager.getDevices()); + + deviceManager.addEventListener("deviceUp", onDeviceChange); + deviceManager.addEventListener("deviceDown", onDeviceChange); + deviceManager.addEventListener("deviceUpdated", onDeviceChange); + deviceManager.addEventListener("deviceMediaUpdated", onDeviceChange); + + // Cleanup listeners + selector.addEventListener( + "close", + () => { + deviceManager.removeEventListener("deviceUp", onDeviceChange); + deviceManager.removeEventListener("deviceDown", onDeviceChange); + deviceManager.removeEventListener("deviceUpdated", onDeviceChange); + deviceManager.removeEventListener( + "deviceMediaUpdated", + onDeviceChange + ); + + selector.removeEventListener("stop", onStop); + selector.removeEventListener("receiverMessage", onReceiverMessage); + selector.removeEventListener("mediaMessage", onMediaMessage); + }, + { once: true } + ); + + return selector; +} + +export default castManager; diff --git a/ext/src/background/menus.ts b/ext/src/background/menus.ts index a9dc515..7e79d5b 100644 --- a/ext/src/background/menus.ts +++ b/ext/src/background/menus.ts @@ -4,13 +4,10 @@ import logger from "../lib/logger"; import options from "../lib/options"; import { stringify } from "../lib/utils"; -import { ReceiverSelectorMediaType } from "../types"; - -import ReceiverSelector, { ReceiverSelection } from "./ReceiverSelector"; -import castManager from "./castManager"; - import * as menuIds from "../menuIds"; +import castManager from "./castManager"; + const _ = browser.i18n.getMessage; const URL_PATTERN_HTTP = "http://*/*"; @@ -176,49 +173,21 @@ async function onMenuClicked( return; } - // Handle cast menus - const castMenuClicked = info.menuItemId === menuIdCast; - const castMediaMenuClicked = info.menuItemId === menuIdCastMedia; - if (castMenuClicked || castMediaMenuClicked) { - if (tab?.id === undefined) { - throw logger.error("Menu handler tab ID not found."); - } - if (!info.pageUrl) { - throw logger.error("Menu handler page URL not found."); + if (tab?.id === undefined) { + logger.error("Menu handler tab ID not found."); + return; + } + + switch (info.menuItemId) { + case menuIdCast: { + castManager.triggerCast(tab.id, info.frameId); + break; } - let selection: Nullable = null; - try { - selection = await ReceiverSelector.getSelection( - tab.id, - info.frameId, - { - withMediaSender: castMediaMenuClicked - } - ); - } catch (err) { - logger.error("Failed to get receiver selection (cast menu)", err); - return; - } - // Invalid selection result - if (!selection) return; - - if (castMenuClicked) { - castManager.loadSender({ - tabId: tab.id, - frameId: info.frameId, - selection - }); - } else if (castMediaMenuClicked) { - /** - * If the selected media type is App, that refers to - * the media sender in this context, so load media - * sender. - */ - if (selection.mediaType === ReceiverSelectorMediaType.App) { + case menuIdCastMedia: + if (info.srcUrl) { await browser.tabs.executeScript(tab.id, { code: stringify` - window.receiver = ${selection.receiverDevice}; window.mediaUrl = ${info.srcUrl}; window.targetElementId = ${info.targetElementId}; `, @@ -226,18 +195,11 @@ async function onMenuClicked( }); await browser.tabs.executeScript(tab.id, { - file: "cast/senders/media/index.js", + file: "cast/senders/media.js", frameId: info.frameId }); - } else { - // Handle other responses - castManager.loadSender({ - tabId: tab.id, - frameId: info.frameId, - selection - }); } - } + break; } } diff --git a/ext/src/background/whitelist.ts b/ext/src/background/whitelist.ts index 12ec9e4..72f9ab9 100644 --- a/ext/src/background/whitelist.ts +++ b/ext/src/background/whitelist.ts @@ -9,7 +9,7 @@ import { RemoteMatchPattern } from "../lib/matchPattern"; import { CAST_FRAMEWORK_LOADER_SCRIPT_URL, CAST_LOADER_SCRIPT_URL -} from "../cast/endpoints"; +} from "../cast/urls"; // Missing on @types/firefox-webext-browser type OnBeforeSendHeadersDetails = Parameters< @@ -207,7 +207,7 @@ async function onBeforeCastSDKRequest(details: OnBeforeRequestDetails) { }); return { - redirectUrl: browser.runtime.getURL("cast/index.js") + redirectUrl: browser.runtime.getURL("cast/content.js") }; } @@ -250,6 +250,13 @@ async function registerSiteWhitelist() { { urls: [""] }, ["blocking", "requestHeaders"] ); + + browser.contentScripts.register({ + matches: siteWhitelist.map(item => item.pattern), + js: [{ file: "cast/contentInitial.js" }], + runAt: "document_start", + allFrames: true + }); } function unregisterSiteWhitelist() { diff --git a/ext/src/cast/content.ts b/ext/src/cast/content.ts index 98b2110..e967d82 100644 --- a/ext/src/cast/content.ts +++ b/ext/src/cast/content.ts @@ -1,42 +1,48 @@ -"use strict"; - -import { CAST_LOADER_SCRIPT_URL, CAST_SCRIPT_URLS } from "./endpoints"; - -const _window = window.wrappedJSObject as any; - -_window.chrome = cloneInto({}, window); - /** - * YouTube won't load the cast SDK unless it thinks the - * presentation API exists. + * Cast Sender SDK page script loaded in place of remote cast_sender + * script. Handles API object creation and initializes sender apps. */ -if (window.location.host === "www.youtube.com") { - _window.navigator.presentation = cloneInto({}, window); + +import logger from "../lib/logger"; +import { loadScript } from "../lib/utils"; + +import pageMessenging from "./pageMessenging"; +import CastSDK from "./sdk"; +import { CAST_FRAMEWORK_SCRIPT_URL } from "./urls"; + +// Create page-accessible API object +window.chrome.cast = new CastSDK(); + +let frameworkScriptPromise: Promise | undefined; + +// Load remote CAF script if requested in script URL params. +if (document.currentScript) { + const currentScript = document.currentScript as HTMLScriptElement; + const currentScriptParams = new URLSearchParams( + new URL(currentScript.src).search + ); + + if (currentScriptParams.get("loadCastFramework") === "1") { + frameworkScriptPromise = loadScript(CAST_FRAMEWORK_SCRIPT_URL); + frameworkScriptPromise.catch(() => { + logger.error("Failed to load CAF script!"); + }); + } } -/** - * Replace the src property setter on