tor-browser

The Tor Browser
git clone https://git.dasho.dev/tor-browser.git
Log | Files | Refs | README | LICENSE

CDPSession.ts (3584B)

      1 /**
      2 * @license
      3 * Copyright 2024 Google Inc.
      4 * SPDX-License-Identifier: Apache-2.0
      5 */
      6 import type {ProtocolMapping} from 'devtools-protocol/types/protocol-mapping.js';
      7 
      8 import type {Connection} from '../cdp/Connection.js';
      9 import {EventEmitter, type EventType} from '../common/EventEmitter.js';
     10 
     11 /**
     12 * @public
     13 */
     14 export type CDPEvents = {
     15  [Property in keyof ProtocolMapping.Events]: ProtocolMapping.Events[Property][0];
     16 };
     17 
     18 /**
     19 * Events that the CDPSession class emits.
     20 *
     21 * @public
     22 */
     23 // eslint-disable-next-line @typescript-eslint/no-namespace
     24 export namespace CDPSessionEvent {
     25  /** @internal */
     26  export const Disconnected = Symbol('CDPSession.Disconnected');
     27  /** @internal */
     28  export const Swapped = Symbol('CDPSession.Swapped');
     29  /**
     30   * Emitted when the session is ready to be configured during the auto-attach
     31   * process. Right after the event is handled, the session will be resumed.
     32   *
     33   * @internal
     34   */
     35  export const Ready = Symbol('CDPSession.Ready');
     36  export const SessionAttached = 'sessionattached' as const;
     37  export const SessionDetached = 'sessiondetached' as const;
     38 }
     39 
     40 /**
     41 * @public
     42 */
     43 export interface CDPSessionEvents
     44  extends CDPEvents,
     45    Record<EventType, unknown> {
     46  /** @internal */
     47  [CDPSessionEvent.Disconnected]: undefined;
     48  /** @internal */
     49  [CDPSessionEvent.Swapped]: CDPSession;
     50  /** @internal */
     51  [CDPSessionEvent.Ready]: CDPSession;
     52  [CDPSessionEvent.SessionAttached]: CDPSession;
     53  [CDPSessionEvent.SessionDetached]: CDPSession;
     54 }
     55 
     56 /**
     57 * @public
     58 */
     59 export interface CommandOptions {
     60  timeout: number;
     61 }
     62 
     63 /**
     64 * The `CDPSession` instances are used to talk raw Chrome Devtools Protocol.
     65 *
     66 * @remarks
     67 *
     68 * Protocol methods can be called with {@link CDPSession.send} method and protocol
     69 * events can be subscribed to with `CDPSession.on` method.
     70 *
     71 * Useful links: {@link https://chromedevtools.github.io/devtools-protocol/ | DevTools Protocol Viewer}
     72 * and {@link https://github.com/aslushnikov/getting-started-with-cdp/blob/HEAD/README.md | Getting Started with DevTools Protocol}.
     73 *
     74 * @example
     75 *
     76 * ```ts
     77 * const client = await page.createCDPSession();
     78 * await client.send('Animation.enable');
     79 * client.on('Animation.animationCreated', () =>
     80 *   console.log('Animation created!'),
     81 * );
     82 * const response = await client.send('Animation.getPlaybackRate');
     83 * console.log('playback rate is ' + response.playbackRate);
     84 * await client.send('Animation.setPlaybackRate', {
     85 *   playbackRate: response.playbackRate / 2,
     86 * });
     87 * ```
     88 *
     89 * @public
     90 */
     91 export abstract class CDPSession extends EventEmitter<CDPSessionEvents> {
     92  /**
     93   * @internal
     94   */
     95  constructor() {
     96    super();
     97  }
     98 
     99  /**
    100   * The underlying connection for this session, if any.
    101   *
    102   * @public
    103   */
    104  abstract connection(): Connection | undefined;
    105 
    106  /**
    107   * True if the session has been detached, false otherwise.
    108   *
    109   * @public
    110   */
    111  abstract get detached(): boolean;
    112 
    113  /**
    114   * Parent session in terms of CDP's auto-attach mechanism.
    115   *
    116   * @internal
    117   */
    118  parentSession(): CDPSession | undefined {
    119    return undefined;
    120  }
    121 
    122  abstract send<T extends keyof ProtocolMapping.Commands>(
    123    method: T,
    124    params?: ProtocolMapping.Commands[T]['paramsType'][0],
    125    options?: CommandOptions,
    126  ): Promise<ProtocolMapping.Commands[T]['returnType']>;
    127 
    128  /**
    129   * Detaches the cdpSession from the target. Once detached, the cdpSession object
    130   * won't emit any events and can't be used to send messages.
    131   */
    132  abstract detach(): Promise<void>;
    133 
    134  /**
    135   * Returns the session's id.
    136   */
    137  abstract id(): string;
    138 }