@modelprofile.com/browser-runtime 5.2.0 → 5.3.0

package/ts/classes.runtime.ts

@@ -105,6 +105,7 @@ interface INormalizedRuntimeOptions {
   frameAcknowledgementTimeoutMs: number;
   screencast: INormalizedScreencastOptions;
   video: Required<plugins.smartpuppeteer.ILiveVideoOptions>;
+  devTools: boolean;
   egress: NonNullable<IBrowserRuntimeOptions['egress']>;
   ownership?: IBrowserRuntimeTestingOptions['ownership'];
   beforeLeasePublication?: IBrowserRuntimeTestingOptions['beforeLeasePublication'];
@@ -144,10 +145,25 @@ interface ILeaseRecord {
   videoPeerId: string;
   videoPeerMayExist: boolean;
   frameCaptureUsed: boolean;
+  devTools?: IDevToolsRecord;
   heldKeys: Map<string, plugins.smartpuppeteer.ILiveBrowserKeyInput>;
   heldButtons: Map<string, plugins.smartpuppeteer.ILiveBrowserMouseInput>;
 }
 
+interface IDevToolsRecord {
+  authority: TBrowserRuntimeLeaseAuthority;
+  session: ILiveBrowserSessionLike;
+  controller: AbortController;
+  connection?: plugins.smartpuppeteer.ILiveBrowserDevToolsConnection;
+  opening?: Promise<plugins.smartpuppeteer.ILiveBrowserDevToolsConnection>;
+  closePromise?: Promise<void>;
+  pending: Set<Promise<void>>;
+  commands: number;
+  interrupts: number;
+  closed: boolean;
+  removeAbortListener(): void;
+}
+
 export interface IBrowserRuntimeLeaseRenewalOptions {
   signal?: AbortSignal;
   /** Lifetime from successful reauthorization; defaults to the runtime capability lifetime. */
@@ -318,6 +334,9 @@ export class BrowserRuntime {
     if (options.beforeOperation !== undefined && typeof options.beforeOperation !== 'function') {
       throw new BrowserRuntimeError('INVALID_INPUT', 'beforeOperation must be a function');
     }
+    if (options.devTools !== undefined && typeof options.devTools !== 'boolean') {
+      throw new BrowserRuntimeError('INVALID_INPUT', 'devTools must be a boolean');
+    }
     const testingOptions = browserRuntimeTesting in options
       && options[browserRuntimeTesting] === true
       ? options as IBrowserRuntimeTestingOptions
@@ -570,6 +589,7 @@ export class BrowserRuntime {
       ),
       screencast,
       video: plugins.smartpuppeteer.normalizeLiveVideoOptions(options.video ?? {}),
+      devTools: options.devTools ?? false,
       egress: options.egress ?? {},
       ownership: testingOptions?.ownership,
       beforeLeasePublication: testingOptions?.beforeLeasePublication,
@@ -1374,6 +1394,148 @@ export class BrowserRuntime {
     });
   }
 
+  /** @internal */
+  public async leaseOpenDevTools(lease: ILeaseRecord, options: plugins.smartpuppeteer.ILiveBrowserDevToolsOptions,
+    operationOptions: IBrowserRuntimeOperationOptions = {}): Promise<plugins.smartpuppeteer.ILiveBrowserDevToolsConnection> {
+    this.requireHuman(lease);
+    if (!this.options.devTools) throw new BrowserRuntimeError('CAPABILITY_INVALID', 'DevTools is not enabled.');
+    if (!options || typeof options.onMessage !== 'function' || typeof options.onClose !== 'function') {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    const tabId = validateBoundedString(options.tabId, 'tabId', 1, 128);
+    let created: IDevToolsRecord | undefined;
+    try {
+      return await this.runOperation(lease, 'openDevTools', 'devtools', operationOptions, async (signal, session) => {
+        if (!session.openDevTools) throw new BrowserRuntimeError('CAPABILITY_INVALID', 'The browser adapter does not support DevTools.');
+        if (lease.devTools) await this.closeLeaseDevTools(lease, lease.devTools);
+        const controller = new AbortController();
+        const record: IDevToolsRecord = {
+          authority: this.createLeaseAuthority(lease), session, controller,
+          pending: new Set(), commands: 0, interrupts: 0, closed: false,
+          removeAbortListener: () => lease.controller.signal.removeEventListener('abort', abort),
+        };
+        const abort = (): void => { this.trackCleanup(this.closeLeaseDevTools(lease, record)); };
+        lease.controller.signal.addEventListener('abort', abort, { once: true });
+        created = record;
+        lease.devTools = record;
+        record.opening = session.openDevTools({ tabId,
+          onMessage: async message => {
+            this.requireDevToolsAuthority(lease, record);
+            await options.onMessage(message);
+            this.requireDevToolsAuthority(lease, record);
+          },
+          onClose: reason => {
+            record.closed = true;
+            controller.abort(new BrowserRuntimeError('ABORTED'));
+            record.removeAbortListener();
+            options.onClose(reason);
+          },
+        }, { signal });
+        const connection = await record.opening;
+        record.connection = connection;
+        try {
+          signal.throwIfAborted();
+          this.requireDevToolsAuthority(lease, record);
+        } catch (error) { await this.closeLeaseDevTools(lease, record); throw error; }
+        return {
+          tabId: connection.tabId,
+          browserVersion: connection.browserVersion,
+          send: message => this.sendLeaseDevTools(lease, record, message),
+          close: () => this.closeLeaseDevTools(lease, record),
+        };
+      });
+    } catch (error) {
+      if (created) await this.closeLeaseDevTools(lease, created);
+      throw error;
+    }
+  }
+
+  private requireDevToolsAuthority(lease: ILeaseRecord, record: IDevToolsRecord): void {
+    this.requireHuman(lease);
+    if (record.closed || record.controller.signal.aborted || lease.devTools !== record
+      || lease.slot.session !== record.session || !this.isLeaseAuthorityCurrent(lease, record.authority)) {
+      throw new BrowserRuntimeError('CAPABILITY_REVOKED');
+    }
+  }
+
+  private async sendLeaseDevTools(lease: ILeaseRecord, record: IDevToolsRecord, message: string): Promise<void> {
+    this.requireDevToolsAuthority(lease, record);
+    const limits = plugins.smartpuppeteer.liveBrowserDevToolsLimits;
+    if (typeof message !== 'string' || plugins.Buffer.byteLength(message) > limits.commandBytes) {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    let command: { method?: unknown };
+    try { command = JSON.parse(message); } catch { throw new BrowserRuntimeError('INVALID_INPUT'); }
+    if (!command || typeof command.method !== 'string' || !/^[A-Za-z]+\.[A-Za-z]+$/.test(command.method)) {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    const action = command.method;
+    const interrupt = limits.interruptMethods.includes(action);
+    if (interrupt ? record.interrupts >= limits.interruptCommands : record.commands >= limits.commands) {
+      throw new BrowserRuntimeError('QUOTA_EXCEEDED');
+    }
+    if (interrupt) record.interrupts++; else record.commands++;
+    const startedAt = Date.now();
+    const operation: IOperationRecord = {
+      operationId: randomId(), lease, controller: record.controller, action, startedAt,
+      session: record.session, incarnationGeneration: record.authority.incarnationGeneration,
+      promise: Promise.resolve(),
+    };
+    const identity = this.createOperationIdentity(lease, operation, action, 'devtools', startedAt);
+    const task = (async () => {
+      let failed = false;
+      let failure: unknown;
+      try {
+        await this.runBeforeOperation(identity, record.controller.signal);
+        this.requireDevToolsAuthority(lease, record);
+        await record.connection!.send(message);
+        this.requireDevToolsAuthority(lease, record);
+      } catch (error) { failed = true; failure = error; }
+      finally {
+        try {
+          await this.emitAudit(Object.freeze({ ...identity, phase: failed ? 'failed' : 'completed',
+            finishedAt: Date.now(), ...(failed ? { errorCode: this.operationErrorCode(failure) } : {}) }));
+        } finally {
+          if (interrupt) record.interrupts--; else record.commands--;
+        }
+      }
+      if (failed) throw failure;
+    })();
+    record.pending.add(task);
+    void task.then(() => record.pending.delete(task), () => record.pending.delete(task));
+    return task;
+  }
+
+  private closeLeaseDevTools(lease: ILeaseRecord, record: IDevToolsRecord): Promise<void> {
+    if (record.closePromise) return record.closePromise;
+    record.closed = true;
+    record.controller.abort(new BrowserRuntimeError('ABORTED'));
+    record.removeAbortListener();
+    const closing = (async () => {
+      try {
+        const detached = await waitBounded((async () => {
+          // Opening may still be completing when lease revocation arrives.
+          await Promise.resolve();
+          const connection = record.connection ?? await record.opening?.catch(() => undefined);
+          await connection?.close();
+        })(), this.options.quiescenceTimeoutMs + 3500);
+        if (!detached.settled) throw new BrowserRuntimeError('TIMEOUT');
+        const pending = await waitBounded(Promise.allSettled([...record.pending]),
+          this.options.quiescenceTimeoutMs + this.options.auditTimeoutMs + this.options.beforeOperationTimeoutMs);
+        if (!pending.settled) throw new BrowserRuntimeError('TIMEOUT');
+      } catch (error) {
+        await this.terminateRegisteredResourceInternal(lease.slot, false, {
+          session: record.session, incarnationGeneration: record.authority.incarnationGeneration,
+        });
+        throw error;
+      } finally {
+        if (lease.devTools === record) lease.devTools = undefined;
+      }
+    })();
+    record.closePromise = closing;
+    return closing;
+  }
+
   /** @internal */
   public async leaseAnswerVideoPeer(lease: ILeaseRecord, negotiationId: string,
     description: plugins.smartpuppeteer.ILiveVideoDescription, options: IBrowserRuntimeOperationOptions = {}): Promise<void> {
@@ -2013,6 +2175,7 @@ export class BrowserRuntime {
         usePipe: true,
         allowEvaluation: true,
         video: this.options.video,
+        allowDevTools: this.options.devTools,
         screencast: {
           enabled: false,          maxOutstandingFrames: this.options.maxOutstandingFrames,
           quality: this.options.screencast.quality,
@@ -3477,6 +3640,7 @@ export class BrowserRuntime {
       release();
     }
     await this.closeFrameSubscriptionIfLease(lease);
+    if (lease.devTools) await this.closeLeaseDevTools(lease, lease.devTools);
     if (operation) {
       const settled = await waitBounded(operation.promise, this.options.quiescenceTimeoutMs);
       if (!settled.settled) {
@@ -4381,6 +4545,11 @@ export class BrowserRuntimeLease {
     return this.runtime.leaseOpenVideoPeer(this.record, options);
   }
 
+  public openDevTools(options: plugins.smartpuppeteer.ILiveBrowserDevToolsOptions,
+    operationOptions?: IBrowserRuntimeOperationOptions): Promise<plugins.smartpuppeteer.ILiveBrowserDevToolsConnection> {
+    return this.runtime.leaseOpenDevTools(this.record, options, operationOptions);
+  }
+
   public answerVideoPeer(negotiationId: string, description: plugins.smartpuppeteer.ILiveVideoDescription,
     options?: IBrowserRuntimeOperationOptions): Promise<void> {
     return this.runtime.leaseAnswerVideoPeer(this.record, negotiationId, description, options);

package/ts/classes.runtimeownership.ts

@@ -1133,20 +1133,23 @@ export class BrowserRuntimeOwnership {
   }
 
   private async listOwnedProcessIds(): Promise<number[]> {
-    let entries: plugins.fs.Dirent[];
+    let entries: string[];
     try {
-      entries = await plugins.fsPromises.readdir(this.procRoot, { withFileTypes: true });
+      // /proc can report DT_UNKNOWN. Node's eager Dirent conversion then
+      // lstat()s every entry and rejects the entire scan if one process exits.
+      // Enumerate names; the per-PID inspection below owns disappearance checks.
+      entries = await plugins.fsPromises.readdir(this.procRoot);
     } catch {
       throw new BrowserRuntimeError('FENCED', 'process inspection is unavailable');
     }
     const processIds: number[] = [];
     let indeterminate = false;
     for (const entry of entries) {
-      if (!/^[1-9][0-9]{0,9}$/u.test(entry.name)) continue;
-      const pid = Number(entry.name);
+      if (!/^[1-9][0-9]{0,9}$/u.test(entry)) continue;
+      const pid = Number(entry);
       try {
         const stat = await plugins.fsPromises.lstat(
-          plugins.path.join(this.procRoot, entry.name),
+          plugins.path.join(this.procRoot, entry),
           { bigint: true },
         );
         if (!stat.isDirectory() || stat.isSymbolicLink()) {

package/ts/interfaces.ts

@@ -134,6 +134,7 @@ export type TBrowserRuntimeOperationClassification =
   | 'raw-input'
   | 'frame-stream'
   | 'video-peer'
+  | 'devtools'
   | 'viewport'
   | 'navigation'
   | 'tab'
@@ -160,6 +161,8 @@ export type TBrowserRuntimeAuditEvent = TBrowserRuntimeOperationIdentity & {
 };
 
 export interface ILiveBrowserSessionLike {
+  openDevTools?(options: plugins.smartpuppeteer.ILiveBrowserDevToolsOptions,
+    operationOptions?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<plugins.smartpuppeteer.ILiveBrowserDevToolsConnection>;
   start(options?: plugins.smartpuppeteer.ILiveBrowserOperationOptions): Promise<void>;
   stop(): Promise<void>;
   terminate(
@@ -300,6 +303,8 @@ export interface IBrowserRuntimeOptions {
   screencast?: IBrowserRuntimeScreencastOptions;
   /** Trusted host configuration; defaults to direct ICE and automatic GPU support. */
   video?: plugins.smartpuppeteer.ILiveVideoOptions;
+  /** Enables selected-tab DevTools for human leases only. Disabled by default. */
+  devTools?: boolean;
   egress?: Omit<IBrowserEgressProxyOptions, 'projectId' | 'browserResourceId'>;
   artifacts?: Omit<IBrowserArtifactStoreOptions, 'rootDirectory'>;
 }