@the-open-engine/zeroshot 6.29.0 → 6.29.1

package/src/hosted-session/reconnecting-watch.ts

@@ -0,0 +1,148 @@
+import type {
+  WatchSubscription,
+  WatchSubscriptionItem,
+} from '../cluster/index.js';
+import {
+  HostedAuthorizationError,
+  HostedTransportUncertainError,
+} from './errors.js';
+import type { HostedWatch, InitializedSession } from './types.js';
+
+type ReplaceSession = (signal: AbortSignal) => Promise<InitializedSession>;
+
+export class ReconnectingHostedWatch implements HostedWatch {
+  readonly #replace: ReplaceSession;
+  readonly #ownedController = new AbortController();
+  readonly #signal: AbortSignal;
+  #session: InitializedSession;
+  #subscription: WatchSubscription;
+  #tail: Promise<void> = Promise.resolve();
+  #replacementPromise: Promise<InitializedSession> | undefined;
+  #cancelPromise: Promise<void> | undefined;
+  #reconnected = false;
+  #cancelled = false;
+
+  constructor(
+    replace: ReplaceSession,
+    session: InitializedSession,
+    subscription: WatchSubscription,
+    signal?: AbortSignal,
+  ) {
+    this.#replace = replace;
+    this.#session = session;
+    this.#subscription = subscription;
+    this.#signal = signal === undefined
+      ? this.#ownedController.signal
+      : AbortSignal.any([signal, this.#ownedController.signal]);
+  }
+
+  [Symbol.asyncIterator](): this {
+    return this;
+  }
+
+  next(): Promise<IteratorResult<WatchSubscriptionItem>> {
+    const result = this.#tail.then(() => this.#readNext());
+    this.#tail = result.then(() => undefined, () => undefined);
+    return result;
+  }
+
+  async #readNext(): Promise<IteratorResult<WatchSubscriptionItem>> {
+    while (!this.#cancelled) {
+      const item = await this.#subscription.stream.next();
+      if (this.#cancelled) return { done: true, value: undefined };
+      if (!item.done) return item;
+      return this.#handleClosed(item);
+    }
+    return { done: true, value: undefined };
+  }
+
+  async #handleClosed(
+    item: IteratorResult<WatchSubscriptionItem>,
+  ): Promise<IteratorResult<WatchSubscriptionItem>> {
+    if (this.#session.connection.state === 'OPEN') {
+      await this.#session.connection.close();
+      return item;
+    }
+    const { code } = await this.#session.connection.closed;
+    if (code === 4401) return this.#reconnect();
+    if (code === 4403) throw new HostedAuthorizationError();
+    if (code === 1000) return item;
+    throw new HostedTransportUncertainError();
+  }
+
+  async #reconnect(): Promise<IteratorResult<WatchSubscriptionItem>> {
+    if (this.#reconnected) throw new HostedTransportUncertainError();
+    this.#reconnected = true;
+    const replacementPromise = this.#replace(this.#signal);
+    this.#replacementPromise = replacementPromise;
+    let replacement: InitializedSession;
+    try {
+      replacement = await replacementPromise;
+    } catch (error) {
+      if (this.#cancelled) return { done: true, value: undefined };
+      throw error;
+    } finally {
+      if (this.#replacementPromise === replacementPromise) {
+        this.#replacementPromise = undefined;
+      }
+    }
+    return this.#installReplacement(replacement);
+  }
+
+  async #installReplacement(
+    replacement: InitializedSession,
+  ): Promise<IteratorResult<WatchSubscriptionItem>> {
+    if (this.#cancelled) {
+      await replacement.connection.close();
+      return { done: true, value: undefined };
+    }
+    try {
+      const subscription = await this.#subscription.stream.reconnect(replacement.connection);
+      if (this.#cancelled) {
+        await subscription.stream.cancel();
+        await replacement.connection.close();
+        return { done: true, value: undefined };
+      }
+      this.#subscription = subscription;
+      this.#session = replacement;
+      return this.#readNext();
+    } catch (error) {
+      await replacement.connection.close();
+      if (this.#cancelled) return { done: true, value: undefined };
+      throw error;
+    }
+  }
+
+  async return(): Promise<IteratorResult<WatchSubscriptionItem>> {
+    await this.cancel();
+    return { done: true, value: undefined };
+  }
+
+  async throw(error?: unknown): Promise<IteratorResult<WatchSubscriptionItem>> {
+    await this.cancel();
+    throw error;
+  }
+
+  cancel(): Promise<void> {
+    this.#cancelPromise ??= this.#cancelOwned();
+    return this.#cancelPromise;
+  }
+
+  async #cancelOwned(): Promise<void> {
+    this.#cancelled = true;
+    this.#ownedController.abort(new DOMException('hosted watch cancelled', 'AbortError'));
+    const replacement = this.#replacementPromise;
+    const outcomes = await Promise.allSettled([
+      this.#subscription.stream.cancel(),
+      this.#session.connection.close(),
+      ...(replacement === undefined
+        ? []
+        : [replacement.then(() => undefined, () => undefined)]),
+    ]);
+    await this.#tail;
+    const failure = outcomes.find(
+      (outcome): outcome is PromiseRejectedResult => outcome.status === 'rejected',
+    );
+    if (failure !== undefined) throw failure.reason;
+  }
+}

package/src/hosted-session/types.ts

@@ -1,15 +1,20 @@
-import type { Connection } from '../cluster/index.js';
-import type { ClusterClient, ConnectOptions } from '../cluster/index.js';
-import type { InitializeResult } from '../cluster/index.js';
-
-export interface AccessResponse {
-  readonly endpoint: string;
-  readonly token: string;
+import type { Connection, ClusterClient, ConnectOptions, InitializeResult, WatchParams, WatchSubscriptionItem } from '../cluster/index.js';
+export interface HostedAccess {
+  readonly protocol: 'openengine.cluster/v1';
+  readonly websocketUrl: string;
+  readonly accessToken: string;
+  readonly tokenType: 'Bearer';
   readonly expiresAt: string;
 }
 
+export interface HostedAccessAdapter {
+  access(capsuleId: string, signal?: AbortSignal): Promise<HostedAccess>;
+}
+
 export interface HostedSessionInit {
-  readonly getAccess: (signal?: AbortSignal) => Promise<AccessResponse>;
+  readonly adapter: HostedAccessAdapter;
+  readonly capsuleId: string;
+  readonly targetAuthority: string;
   readonly connectOptions?: Omit<ConnectOptions, 'headers' | 'signal'>;
   readonly clock?: { now(): number };
 }
@@ -19,3 +24,12 @@ export interface InitializedSession {
   readonly client: ClusterClient;
   readonly initializeResult: InitializeResult;
 }
+
+export interface HostedWatch extends AsyncIterator<WatchSubscriptionItem>, AsyncIterable<WatchSubscriptionItem> {
+  cancel(): Promise<void>;
+}
+
+export interface HostedWatchOptions {
+  readonly params: WatchParams;
+  readonly signal?: AbortSignal;
+}

package/src/hosted-target/access-url.ts

@@ -0,0 +1,46 @@
+import type { TargetDiscoveryDescriptor } from '../target/discovery.js';
+import { TargetProtocolError } from './errors.js';
+
+function hasForbiddenCodePoint(value: string): boolean {
+  for (const character of value) {
+    const codePoint = character.codePointAt(0)!;
+    if (codePoint <= 0x20 || codePoint === 0x7f) return true;
+  }
+  return false;
+}
+
+function parseAccessUrl(value: string): URL {
+  try {
+    if (hasForbiddenCodePoint(value)) throw new TypeError('unsafe URL code point');
+    const url = new globalThis.URL(value);
+    if (url.href !== value) throw new TypeError('non-canonical URL');
+    return url;
+  } catch {
+    throw new TargetProtocolError('Capsule access WebSocket URL is invalid');
+  }
+}
+
+function matchesAccessRoute(url: URL, target: URL, expectedPath: string): boolean {
+  const expectedProtocol = target.protocol === 'http:' ? 'ws:' : 'wss:';
+  return url.protocol === expectedProtocol &&
+    url.host === target.host &&
+    !url.username &&
+    !url.password &&
+    !url.search &&
+    !url.hash &&
+    url.pathname === expectedPath;
+}
+
+export function validateAccessUrl(
+  value: string,
+  capsuleId: string,
+  descriptor: TargetDiscoveryDescriptor,
+): void {
+  const url = parseAccessUrl(value);
+  const expectedPath = descriptor.transport.websocketRouteTemplate.expand({
+    capsule_id: capsuleId,
+  });
+  if (!matchesAccessRoute(url, new globalThis.URL(descriptor.origin), expectedPath)) {
+    throw new TargetProtocolError('Capsule access WebSocket URL does not match discovery');
+  }
+}

package/src/hosted-target/adapter-request.ts

@@ -0,0 +1,28 @@
+import type { RouteTemplate, TargetDiscoveryDescriptor } from '../target/discovery.js';
+import { TargetProtocolError } from './errors.js';
+import type { TargetOperation } from './retry-executor.js';
+
+export type AdapterRequest = {
+  readonly body?: string;
+  readonly headers?: Readonly<Record<string, string>>;
+};
+
+export type ExecuteArguments<T> = [
+  operation: TargetOperation,
+  method: string,
+  template: RouteTemplate,
+  values: Readonly<Record<string, string | number | undefined>>,
+  expectedStatus: number,
+  validate: (body: unknown) => T,
+  signal?: AbortSignal,
+  request?: AdapterRequest,
+];
+
+export function requestUrl(path: string, descriptor: TargetDiscoveryDescriptor): URL {
+  const url = new globalThis.URL(path, descriptor.capsule.baseUrl);
+  if (url.origin !== descriptor.origin || url.hash ||
+      `${url.pathname}${url.search}` !== path) {
+    throw new TargetProtocolError('Capsule route changed during URL canonicalization');
+  }
+  return url;
+}

package/src/hosted-target/adapter-types.ts

@@ -0,0 +1,39 @@
+import type { TargetDiscoveryDescriptor } from '../target/discovery.js';
+import type {
+  AllocateRequest,
+  Capsule,
+  CapsuleAccess,
+  CapsuleLimits,
+  CapsuleListPage,
+  Clock,
+  HttpTransport,
+  ListRequest,
+  RetryPolicy,
+  TargetAccessTokenProvider,
+} from './types.js';
+
+export type CredentialInstallCapability =
+  | { readonly supported: false }
+  | {
+      readonly supported: true;
+      readonly descriptor: NonNullable<TargetDiscoveryDescriptor['credentialInstall']>;
+    };
+
+export interface TargetAdapter {
+  allocate(req: AllocateRequest, signal?: AbortSignal): Promise<Capsule>;
+  list(req?: ListRequest, signal?: AbortSignal): Promise<CapsuleListPage>;
+  inspect(capsuleId: string, signal?: AbortSignal): Promise<Capsule>;
+  terminate(capsuleId: string, signal?: AbortSignal): Promise<Capsule>;
+  limits(signal?: AbortSignal): Promise<CapsuleLimits>;
+  access(capsuleId: string, signal?: AbortSignal): Promise<CapsuleAccess>;
+  readonly credentialInstall: CredentialInstallCapability;
+}
+
+export interface CreateTargetAdapterOptions {
+  readonly descriptor: TargetDiscoveryDescriptor;
+  readonly organization: { readonly id: string };
+  readonly tokenProvider: TargetAccessTokenProvider;
+  readonly transport?: HttpTransport;
+  readonly clock?: Clock;
+  readonly retryPolicy?: RetryPolicy;
+}

package/src/hosted-target/bounds.ts

@@ -1,3 +1,4 @@
+/** Shared wire limits for every hosted-target response and retry path. */
 export const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
 export const MAX_PAGINATION_PAGES = 100;
 export const MAX_RETRY_ATTEMPTS = 3;

package/src/hosted-target/capsule-error-response.ts

@@ -0,0 +1,107 @@
+import { TargetProtocolError, TargetServerError } from './errors.js';
+import { parseRetryAfter } from './retry.js';
+import type { Clock } from './types.js';
+
+const ERROR_CODES = Object.freeze({
+  unauthorized: { statuses: [401], retryable: false },
+  invalid_request: { statuses: [400], retryable: false },
+  not_found: { statuses: [404], retryable: false },
+  forbidden: { statuses: [402, 403], retryable: false },
+  idempotency_conflict: { statuses: [409], retryable: false },
+  run_conflict: { statuses: [409], retryable: true },
+  rate_limited: { statuses: [429], retryable: true },
+  temporarily_unavailable: { statuses: [503], retryable: true },
+  internal_error: { statuses: [500], retryable: false },
+});
+type ErrorCode = keyof typeof ERROR_CODES;
+
+type CapsuleErrorBody = {
+  readonly code: ErrorCode;
+  readonly capsuleId: string | null;
+  readonly retryable: boolean;
+};
+
+function isErrorCode(value: unknown): value is ErrorCode {
+  return typeof value === 'string' && value in ERROR_CODES;
+}
+
+function isRecordBody(body: unknown): body is Record<string, unknown> {
+  return body !== null && typeof body === 'object' && !Array.isArray(body);
+}
+
+function hasExactErrorFields(value: Record<string, unknown>): boolean {
+  const fields = Object.keys(value);
+  const exactFields = ['code', 'message', 'capsule_id', 'retryable'];
+  return fields.length === exactFields.length &&
+    exactFields.every((field) => field in value);
+}
+
+function hasValidErrorValues(value: Record<string, unknown>): value is Record<string, unknown> & {
+  readonly code: ErrorCode;
+  readonly capsule_id: string | null;
+  readonly retryable: boolean;
+} {
+  return isErrorCode(value.code) &&
+    typeof value.message === 'string' &&
+    (value.capsule_id === null || typeof value.capsule_id === 'string') &&
+    typeof value.retryable === 'boolean';
+}
+
+function parseErrorBody(body: unknown): CapsuleErrorBody {
+  if (!isRecordBody(body) || !hasExactErrorFields(body) || !hasValidErrorValues(body)) {
+    throw new TargetProtocolError('Capsule error response is malformed');
+  }
+  const value = body;
+  return {
+    code: value.code,
+    capsuleId: value.capsule_id,
+    retryable: value.retryable,
+  };
+}
+
+function validateChallenge(response: Response): void {
+  if (response.status !== 401) return;
+  if (response.headers.get('WWW-Authenticate') !== 'Bearer error="invalid_token"') {
+    throw new TargetProtocolError('Capsule authentication challenge is malformed');
+  }
+}
+
+function validatedRetryAfter(
+  response: Response,
+  retryable: boolean,
+  clock: Clock,
+): number | undefined {
+  const header = response.headers.get('Retry-After');
+  const retryAfter = parseRetryAfter(header, clock) ?? undefined;
+  if (header !== null && retryAfter === undefined) {
+    throw new TargetProtocolError('Capsule Retry-After header is malformed');
+  }
+  if (retryable && retryAfter === undefined) {
+    throw new TargetProtocolError('Retryable capsule error omitted Retry-After');
+  }
+  if (!retryable && retryAfter !== undefined) {
+    throw new TargetProtocolError('Permanent capsule error advertised Retry-After');
+  }
+  return retryAfter;
+}
+
+export async function throwCapsuleServerError(
+  response: Response,
+  readJson: (response: Response) => Promise<unknown>,
+  clock: Clock,
+): Promise<never> {
+  const value = parseErrorBody(await readJson(response));
+  const contract = ERROR_CODES[value.code];
+  if (!contract.statuses.includes(response.status) || contract.retryable !== value.retryable) {
+    throw new TargetProtocolError('Capsule error response contradicts its status contract');
+  }
+  validateChallenge(response);
+  const retryAfter = validatedRetryAfter(response, contract.retryable, clock);
+  throw new TargetServerError(
+    response.status,
+    value.code,
+    contract.retryable,
+    value.capsuleId,
+    retryAfter,
+  );
+}

package/src/hosted-target/errors.ts

@@ -1,37 +1,38 @@
-function sanitize(text: string): string {
-  return text
-    .replace(/Authorization:\s*Bearer\s+\S+/gi, 'Authorization: Bearer [REDACTED]')
-    .replace(/token["']?\s*[:=]\s*["'][^"']+["']/gi, 'token: "[REDACTED]"')
-    .replace(/https?:\/\/[^\s]*(?:token|key|secret|credential|auth)[^\s]*/gi, '[REDACTED_URL]');
-}
-
-function sanitizeCause(cause: unknown): unknown {
-  if (!cause) return cause;
-  if (cause instanceof Error) {
-    const cleaned = new Error(sanitize(cause.message));
-    cleaned.name = cause.name;
-    if (cause.cause) cleaned.cause = sanitizeCause(cause.cause);
-    return cleaned;
-  }
-  if (typeof cause === 'string') return sanitize(cause);
-  return cause;
-}
-
 export class TargetAdapterError extends Error {
   readonly code: string;
   readonly retryable: boolean;
 
-  constructor(code: string, message: string, retryable: boolean, cause?: unknown) {
-    super(sanitize(message), { cause: sanitizeCause(cause) });
+  constructor(code: string, message: string, retryable: boolean) {
+    super(message);
     this.name = 'TargetAdapterError';
     this.code = code;
     this.retryable = retryable;
   }
 }
+export class TargetServerError extends TargetAdapterError {
+  readonly status: number;
+  readonly serverCode: string;
+  readonly capsuleId: string | null;
+  readonly retryAfterMs: number | undefined;
 
+  constructor(
+    status: number,
+    serverCode: string,
+    retryable: boolean,
+    capsuleId: string | null,
+    retryAfterMs?: number
+  ) {
+    super('SERVER_REJECTED', `Capsule request failed (${serverCode})`, retryable);
+    this.name = 'TargetServerError';
+    this.status = status;
+    this.serverCode = serverCode;
+    this.capsuleId = capsuleId;
+    this.retryAfterMs = retryAfterMs;
+  }
+}
 export class TargetAuthError extends TargetAdapterError {
-  constructor(message: string, cause?: unknown) {
-    super('AUTH_FAILED', message, false, cause);
+  constructor(message: string) {
+    super('AUTH_FAILED', message, false);
     this.name = 'TargetAuthError';
   }
 }
@@ -39,8 +40,8 @@ export class TargetAuthError extends TargetAdapterError {
 export class TargetConflictError extends TargetAdapterError {
   readonly idempotencyKey: string;
 
-  constructor(idempotencyKey: string, message: string, cause?: unknown) {
-    super('CONFLICT', message, true, cause);
+  constructor(idempotencyKey: string, message: string) {
+    super('CONFLICT', message, true);
     this.name = 'TargetConflictError';
     this.idempotencyKey = idempotencyKey;
   }
@@ -49,37 +50,37 @@ export class TargetConflictError extends TargetAdapterError {
 export class TargetRateLimitError extends TargetAdapterError {
   readonly retryAfterMs: number | undefined;
 
-  constructor(message: string, retryAfterMs?: number, cause?: unknown) {
-    super('RATE_LIMITED', message, true, cause);
+  constructor(message: string, retryAfterMs?: number) {
+    super('RATE_LIMITED', message, true);
     this.name = 'TargetRateLimitError';
     this.retryAfterMs = retryAfterMs;
   }
 }
 
 export class TargetTransportError extends TargetAdapterError {
-  constructor(message: string, cause?: unknown) {
-    super('TRANSPORT', message, true, cause);
+  constructor(message: string) {
+    super('TRANSPORT', message, true);
     this.name = 'TargetTransportError';
   }
 }
 
 export class TargetProtocolError extends TargetAdapterError {
-  constructor(message: string, cause?: unknown) {
-    super('PROTOCOL', message, false, cause);
+  constructor(message: string) {
+    super('PROTOCOL', message, false);
     this.name = 'TargetProtocolError';
   }
 }
 
 export class TargetCapacityError extends TargetAdapterError {
-  constructor(message: string, cause?: unknown) {
-    super('CAPACITY', message, false, cause);
+  constructor(message: string) {
+    super('CAPACITY', message, false);
     this.name = 'TargetCapacityError';
   }
 }
 
 export class TargetNotFoundError extends TargetAdapterError {
-  constructor(message: string, cause?: unknown) {
-    super('NOT_FOUND', message, false, cause);
+  constructor(message: string) {
+    super('NOT_FOUND', message, false);
     this.name = 'TargetNotFoundError';
   }
 }

package/src/hosted-target/index.ts

@@ -1,5 +1,9 @@
-export type { TargetAdapter } from './target-adapter.ts';
-export { ZeroCloudV1TargetAdapter } from './zero-cloud-v1-adapter.ts';
+export {
+  createTargetAdapter,
+  type TargetAdapter,
+  type CreateTargetAdapterOptions,
+  type CredentialInstallCapability,
+} from './target-adapter.js';
 export {
   TargetAdapterError,
   TargetAuthError,
@@ -9,8 +13,9 @@ export {
   TargetProtocolError,
   TargetCapacityError,
   TargetNotFoundError,
+  TargetServerError,
   isRetryable,
-} from './errors.ts';
+} from './errors.js';
 export type {
   TargetAccessTokenProvider,
   CapsuleState,
@@ -19,26 +24,8 @@ export type {
   CapsuleListPage,
   CapsuleLimits,
   AllocateRequest,
+  ListRequest,
   HttpTransport,
   Clock,
   RetryPolicy,
-  TargetDiscovery,
-} from './types.ts';
-export { KNOWN_CAPSULE_STATES } from './types.ts';
-export {
-  MAX_RESPONSE_BYTES,
-  MAX_PAGINATION_PAGES,
-  MAX_RETRY_ATTEMPTS,
-  MAX_RETRY_ELAPSED_MS,
-  MAX_ERROR_BODY_BYTES,
-  IDEMPOTENCY_KEY_PATTERN,
-} from './bounds.ts';
-export { DefaultRetryPolicy, parseRetryAfter } from './retry.ts';
-export {
-  assertRequiredFields,
-  assertKnownEnum,
-  assertCapsule,
-  assertCapsuleAccess,
-  assertCapsuleLimits,
-  assertCapsuleListPage,
-} from './response-validation.ts';
+} from './types.js';