@modelprofile.com/browser-runtime 1.0.1 → 2.1.0

package/ts/classes.framed.ts

@@ -2,8 +2,15 @@ import * as plugins from './plugins.js';
 import { validateAgentAction, validateAgentActionResult } from './actions.js';
 import type { BrowserRuntime, BrowserRuntimeLease } from './classes.runtime.js';
 import { BrowserRuntimeError, type TBrowserRuntimeErrorCode } from './errors.js';
+import {
+  browserRuntimeTesting,
+  type IBrowserRuntimeFramedClientTestingOptions,
+} from './internal.testing.js';
 import type {
   IAttachTrustedFramedPeerOptions,
+  TBrowserCapabilityAuthorizationRequest,
+  IBrowserFlexCapabilityBinding,
+  IBrowserFlexSessionId,
   IBrowserRuntimeFramedClientOptions,
   IBrowserRuntimeOperationOptions,
   TBrowserAgentAction,
@@ -190,12 +197,24 @@ class JsonFramedChannel {
 }
 
 export class BrowserRuntimeFramedServerPeer {
+  private readonly trustedProjectId: string;
+  private readonly trustedBrowserResourceId: string;
+  private readonly trustedAttachmentAuthorityId: string;
+  private readonly trustedAttachmentRevision: number;
+  private readonly trustedActorId: string;
   private readonly trustedPeerId: string;
+  private readonly trustedRole: 'agent';
+  private readonly trustedSource: 'flex';
   private readonly trustedScopeId: string;
-  private readonly trustedSessionId: string;
+  private readonly trustedChannelId: string;
+  private readonly trustedSessionId: IBrowserFlexSessionId;
   private readonly channel: JsonFramedChannel;
   private readonly activeRequests = new Map<string, AbortController>();
   private lease?: BrowserRuntimeLease;
+  private capabilityId?: string;
+  private pendingCapabilityId?: string;
+  private pendingReleasedLeaseId?: string;
+  private runtimeReleasedLease = false;
   private started = false;
   private closePromise?: Promise<void>;
   private closing = false;
@@ -206,9 +225,39 @@ export class BrowserRuntimeFramedServerPeer {
     options: IAttachTrustedFramedPeerOptions,
     private readonly onClosed: () => void = () => undefined,
   ) {
-    this.trustedPeerId = validateBoundedString(options.peerId, 'peerId', 1, 128);
-    this.trustedScopeId = validateBoundedString(options.scopeId, 'scopeId', 1, 128);
-    this.trustedSessionId = validateBoundedString(options.sessionId, 'sessionId', 1, 128);
+    this.trustedProjectId = validateBoundedString(options.projectId, 'projectId', 1, 256);
+    this.trustedBrowserResourceId = validateBoundedString(
+      options.browserResourceId,
+      'browserResourceId',
+      16,
+      256,
+    );
+    this.trustedAttachmentAuthorityId = validateBoundedString(
+      options.attachmentAuthorityId,
+      'attachmentAuthorityId',
+      1,
+      256,
+    );
+    this.trustedAttachmentRevision = validateInteger(
+      options.attachmentRevision,
+      'attachmentRevision',
+      0,
+      Number.MAX_SAFE_INTEGER,
+    );
+    this.trustedActorId = validateBoundedString(options.actorId, 'actorId', 1, 256);
+    this.trustedPeerId = validateBoundedString(options.peerId, 'peerId', 1, 256);
+    if (options.role !== 'agent' || options.source !== 'flex') {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    this.trustedRole = options.role;
+    this.trustedSource = options.source;
+    this.trustedScopeId = validateBoundedString(options.scopeId, 'scopeId', 1, 256);
+    this.trustedChannelId = validateBoundedString(options.channelId, 'channelId', 1, 256);
+    if (options.sessionId?.harnessId !== 'flex') throw new BrowserRuntimeError('INVALID_INPUT');
+    this.trustedSessionId = {
+      harnessId: 'flex',
+      nativeId: validateBoundedString(options.sessionId.nativeId, 'sessionId.nativeId', 1, 256),
+    };
     if (
       !(options.readable instanceof plugins.stream.Readable)
       || !(options.writable instanceof plugins.stream.Writable)
@@ -229,6 +278,42 @@ export class BrowserRuntimeFramedServerPeer {
     return this.trustedPeerId;
   }
 
+  public get projectId(): string {
+    return this.trustedProjectId;
+  }
+
+  public get browserResourceId(): string {
+    return this.trustedBrowserResourceId;
+  }
+
+  public get channelId(): string {
+    return this.trustedChannelId;
+  }
+
+  /** @internal */
+  public get activeCapabilityId(): string | undefined {
+    return this.capabilityId ?? this.pendingCapabilityId;
+  }
+
+  /** @internal */
+  public releaseLeaseFromRuntime(capabilityId: string, leaseId: string): void {
+    if (
+      this.pendingCapabilityId === capabilityId
+      && !this.lease
+    ) {
+      this.pendingReleasedLeaseId = leaseId;
+      return;
+    }
+    if (
+      this.capabilityId !== capabilityId
+      || this.lease?.capabilityId !== capabilityId
+      || this.lease.leaseId !== leaseId
+    ) return;
+    this.lease = undefined;
+    this.capabilityId = undefined;
+    this.runtimeReleasedLease = true;
+  }
+
   public start(): void {
     if (this.started) return;
     this.started = true;
@@ -237,7 +322,17 @@ export class BrowserRuntimeFramedServerPeer {
 
   public close(): Promise<void> {
     if (this.closePromise) return this.closePromise;
-    this.closePromise = this.closeInternal().catch((error) => {
+    this.closePromise = this.closeInternal(true).catch((error) => {
+      this.closePromise = undefined;
+      throw error;
+    });
+    return this.closePromise;
+  }
+
+  /** @internal */
+  public closeFromRuntime(): Promise<void> {
+    if (this.closePromise) return this.closePromise;
+    this.closePromise = this.closeInternal(false).catch((error) => {
       this.closePromise = undefined;
       throw error;
     });
@@ -281,36 +376,77 @@ export class BrowserRuntimeFramedServerPeer {
     request: Record<string, unknown>,
     controller: AbortController,
   ): Promise<void> {
+    let acquisitionCapabilityId: string | undefined;
     try {
       let result: unknown;
       if (method === 'acquire') {
         validateExactKeys(request, ['version', 'id', 'method', 'capabilityToken'], 'acquire request');
-        if (this.lease) throw new BrowserRuntimeError('BUSY');
+        if (this.lease || this.pendingCapabilityId) throw new BrowserRuntimeError('BUSY');
         const capabilityToken = validateBoundedString(
           request.capabilityToken,
           'capabilityToken',
           16,
           512,
         );
-        this.lease = await this.runtime.acquireLease({
-          capabilityToken,
+        const authority = {
+          projectId: this.trustedProjectId,
+          browserResourceId: this.trustedBrowserResourceId,
+          attachmentAuthorityId: this.trustedAttachmentAuthorityId,
+          attachmentRevision: this.trustedAttachmentRevision,
+          actorId: this.trustedActorId,
           peerId: this.trustedPeerId,
-          expectedRole: 'agent',
-          expectedSource: 'flex',
+          role: this.trustedRole,
+          source: this.trustedSource,
           scopeId: this.trustedScopeId,
+          channelId: this.trustedChannelId,
           sessionId: this.trustedSessionId,
+        } as const;
+        const descriptor = this.runtime.authorizeCapability(capabilityToken, authority);
+        this.pendingCapabilityId = descriptor.capabilityId;
+        acquisitionCapabilityId = descriptor.capabilityId;
+        this.pendingReleasedLeaseId = undefined;
+        const acquiredLease = await this.runtime.acquireLease({
+          capabilityToken,
+          ...authority,
           signal: controller.signal,
         });
+        await this.runtime.beforeFramedPeerLeasePublication();
+        this.lease = acquiredLease;
+        this.capabilityId = acquiredLease.capabilityId;
+        this.runtimeReleasedLease = false;
+        const releasedBeforePublication = this.pendingReleasedLeaseId === acquiredLease.leaseId;
+        this.pendingCapabilityId = undefined;
+        this.pendingReleasedLeaseId = undefined;
+        if (releasedBeforePublication) {
+          this.lease = undefined;
+          this.capabilityId = undefined;
+          this.runtimeReleasedLease = true;
+          throw new BrowserRuntimeError('CAPABILITY_REVOKED');
+        }
         if (this.closing || controller.signal.aborted) {
-          await this.lease.release();
+          await this.runtime.revokeFramedCapability(acquiredLease.capabilityId);
           this.lease = undefined;
+          this.capabilityId = undefined;
           throw new BrowserRuntimeError('ABORTED');
         }
+        try {
+          acquiredLease.getState();
+        } catch {
+          this.lease = undefined;
+          this.capabilityId = undefined;
+          this.runtimeReleasedLease = true;
+          throw new BrowserRuntimeError('CAPABILITY_REVOKED');
+        }
         result = {
-          leaseId: this.lease.leaseId,
-          role: this.lease.role,
+          leaseId: acquiredLease.leaseId,
+          role: acquiredLease.role,
+          projectId: this.trustedProjectId,
+          browserResourceId: this.trustedBrowserResourceId,
+          attachmentAuthorityId: this.trustedAttachmentAuthorityId,
+          attachmentRevision: this.trustedAttachmentRevision,
           scopeId: this.trustedScopeId,
-          sessionId: this.trustedSessionId,
+          channelId: this.trustedChannelId,
+          sessionId: { ...this.trustedSessionId },
         };
       } else if (method === 'execute') {
         validateExactKeys(request, ['version', 'id', 'method', 'action'], 'execute request');
@@ -335,9 +471,14 @@ export class BrowserRuntimeFramedServerPeer {
         result = { cancelled };
       } else if (method === 'release') {
         validateExactKeys(request, ['version', 'id', 'method'], 'release request');
-        const lease = this.requireLease();
-        await lease.release();
+        if (!this.lease) {
+          if (!this.runtimeReleasedLease) throw new BrowserRuntimeError('CAPABILITY_INVALID');
+        } else {
+          await this.runtime.revokeFramedCapability(this.capabilityId!);
+        }
         this.lease = undefined;
+        this.capabilityId = undefined;
+        this.runtimeReleasedLease = false;
         result = { released: true };
       } else {
         throw new BrowserRuntimeError('PROTOCOL_ERROR');
@@ -345,6 +486,10 @@ export class BrowserRuntimeFramedServerPeer {
       assertJsonWithoutBytes(result, hardMaxFrameBytes);
       await this.channel.send({ version: protocolVersion, id, ok: true, result });
     } catch (error) {
+      if (acquisitionCapabilityId && this.pendingCapabilityId === acquisitionCapabilityId) {
+        this.pendingCapabilityId = undefined;
+        this.pendingReleasedLeaseId = undefined;
+      }
       await this.sendError(id, error);
     }
   }
@@ -366,21 +511,23 @@ export class BrowserRuntimeFramedServerPeer {
     } satisfies IFramedErrorResponse).catch(() => undefined);
   }
 
-  private async closeInternal(): Promise<void> {
+  private async closeInternal(revokeCapability: boolean): Promise<void> {
     this.closing = true;
     for (const controller of this.activeRequests.values()) {
       controller.abort(new BrowserRuntimeError('ABORTED'));
     }
-    const dispatchResult = await waitBounded(
-      Promise.allSettled([...this.dispatches]).then(() => undefined),
-      hardRequestTimeoutMs,
-    );
-    if (!dispatchResult.settled) {
-      await this.runtime.disconnectPeer(this.trustedPeerId);
+    const capabilityId = this.capabilityId;
+    if (revokeCapability && capabilityId) {
+      await this.runtime.revokeFramedCapability(capabilityId);
     }
-    await this.lease?.release();
     this.lease = undefined;
-    await this.runtime.disconnectPeer(this.trustedPeerId);
+    this.capabilityId = undefined;
+    if (revokeCapability) {
+      await waitBounded(
+        Promise.allSettled([...this.dispatches]).then(() => undefined),
+        hardRequestTimeoutMs,
+      );
+    }
     await this.channel.close();
     this.onClosed();
   }
@@ -392,13 +539,10 @@ export class BrowserRuntimeFramedServerPeer {
       for (const controller of this.activeRequests.values()) {
         controller.abort(new BrowserRuntimeError('ABORTED'));
       }
-      await waitBounded(
-        Promise.allSettled([...this.dispatches]).then(() => undefined),
-        hardRequestTimeoutMs,
-      );
-      await this.lease?.release();
+      const capabilityId = this.capabilityId;
+      if (capabilityId) await this.runtime.revokeFramedCapability(capabilityId);
       this.lease = undefined;
-      await this.runtime.disconnectPeer(this.trustedPeerId);
+      this.capabilityId = undefined;
       this.onClosed();
     })().catch((error) => {
       this.closePromise = undefined;
@@ -417,11 +561,48 @@ export class BrowserRuntimeFramedClient {
   private started = false;
   private closePromise?: Promise<void>;
   private readonly scopeIdValue: string;
-  private readonly sessionIdValue: string;
+  private readonly channelIdValue: string;
+  private readonly sessionIdValue: IBrowserFlexSessionId;
+  private readonly authority: TBrowserCapabilityAuthorizationRequest;
+  private readonly afterAcquireResponse?: IBrowserRuntimeFramedClientTestingOptions['afterAcquireResponse'];
 
-  constructor(options: IBrowserRuntimeFramedClientOptions) {
-    this.scopeIdValue = validateBoundedString(options.scopeId, 'scopeId', 1, 128);
-    this.sessionIdValue = validateBoundedString(options.sessionId, 'sessionId', 1, 128);
+  constructor(options: IBrowserRuntimeFramedClientOptions | IBrowserRuntimeFramedClientTestingOptions) {
+    if (options.role !== 'agent' || options.source !== 'flex' || options.sessionId?.harnessId !== 'flex') {
+      throw new BrowserRuntimeError('INVALID_INPUT');
+    }
+    this.scopeIdValue = validateBoundedString(options.scopeId, 'scopeId', 1, 256);
+    this.channelIdValue = validateBoundedString(options.channelId, 'channelId', 1, 256);
+    this.sessionIdValue = {
+      harnessId: 'flex',
+      nativeId: validateBoundedString(options.sessionId.nativeId, 'sessionId.nativeId', 1, 256),
+    };
+    this.authority = {
+      projectId: validateBoundedString(options.projectId, 'projectId', 1, 256),
+      browserResourceId: validateBoundedString(options.browserResourceId, 'browserResourceId', 16, 256),
+      attachmentAuthorityId: validateBoundedString(
+        options.attachmentAuthorityId,
+        'attachmentAuthorityId',
+        1,
+        256,
+      ),
+      attachmentRevision: validateInteger(
+        options.attachmentRevision,
+        'attachmentRevision',
+        0,
+        Number.MAX_SAFE_INTEGER,
+      ),
+      actorId: validateBoundedString(options.actorId, 'actorId', 1, 256),
+      role: 'agent',
+      peerId: validateBoundedString(options.peerId, 'peerId', 1, 256),
+      source: 'flex',
+      scopeId: this.scopeIdValue,
+      channelId: this.channelIdValue,
+      sessionId: this.sessionIdValue,
+    };
+    this.afterAcquireResponse = browserRuntimeTesting in options
+      && options[browserRuntimeTesting] === true
+      ? options.afterAcquireResponse
+      : undefined;
     if (
       !(options.readable instanceof plugins.stream.Readable)
       || !(options.writable instanceof plugins.stream.Writable)
@@ -462,12 +643,22 @@ export class BrowserRuntimeFramedClient {
     return this.scopeIdValue;
   }
 
-  public get sessionId(): string {
-    return this.sessionIdValue;
+  public get channelId(): string {
+    return this.channelIdValue;
+  }
+
+  public get sessionId(): IBrowserFlexSessionId {
+    return { ...this.sessionIdValue };
+  }
+
+  public get authorityBinding(): TBrowserCapabilityAuthorizationRequest {
+    return {
+      ...(this.authority as IBrowserFlexCapabilityBinding),
+      sessionId: { ...this.sessionIdValue },
+    };
   }
 
   public async acquire(capabilityTokenArg: string, signal?: AbortSignal): Promise<void> {
-    if (this.acquired) throw new BrowserRuntimeError('BUSY');
     signal?.throwIfAborted();
     const capabilityToken = validateBoundedString(
       capabilityTokenArg,
@@ -482,10 +673,27 @@ export class BrowserRuntimeFramedClient {
       void this.request('cancel', { targetRequestId: id }).catch(() => undefined);
     };
     signal?.addEventListener('abort', onAbort, { once: true });
+    let acquiredRemotely = false;
     try {
       await acquisition;
+      acquiredRemotely = true;
+      await this.afterAcquireResponse?.();
       signal?.throwIfAborted();
       this.acquired = true;
+    } catch (error) {
+      if (acquiredRemotely) {
+        let cleanupError: unknown;
+        await this.request('release', {}).catch(async (releaseError) => {
+          cleanupError = releaseError;
+          await this.channel.close().catch(() => undefined);
+          this.handleClose();
+        });
+        this.acquired = false;
+        if (cleanupError) {
+          throw new AggregateError([error, cleanupError], 'Framed acquisition cleanup is incomplete');
+        }
+      }
+      throw error;
     } finally {
       signal?.removeEventListener('abort', onAbort);
     }