@the-open-engine/zeroshot 6.28.0 → 6.29.1

package/src/hosted-target/zero-cloud-v1-adapter.ts

@@ -1,21 +1,18 @@
-import { MAX_ERROR_BODY_BYTES, MAX_RESPONSE_BYTES, MAX_RETRY_ELAPSED_MS, IDEMPOTENCY_KEY_PATTERN } from './bounds.ts';
+import { IDEMPOTENCY_KEY_PATTERN, MAX_RESPONSE_BYTES } from './bounds.js';
 import {
+  TargetAdapterError,
   TargetAuthError,
-  TargetConflictError,
-  TargetNotFoundError,
   TargetProtocolError,
-  TargetRateLimitError,
   TargetTransportError,
-} from './errors.ts';
-import { TargetAdapterError } from './errors.ts';
-import { DefaultRetryPolicy, parseRetryAfter } from './retry.ts';
+} from './errors.js';
+import { DefaultRetryPolicy } from './retry.js';
 import {
   assertCapsule,
   assertCapsuleAccess,
   assertCapsuleLimits,
   assertCapsuleListPage,
-} from './response-validation.ts';
-import type { TargetAdapter } from './target-adapter.ts';
+} from './response-validation.js';
+import type { TargetAdapter, CreateTargetAdapterOptions } from './adapter-types.js';
 import type {
   AllocateRequest,
   Capsule,
@@ -24,363 +21,279 @@ import type {
   CapsuleListPage,
   Clock,
   HttpTransport,
+  ListRequest,
   RetryPolicy,
   TargetAccessTokenProvider,
-  TargetDiscovery,
-} from './types.ts';
-
-interface ZeroCloudV1Options {
-  readonly discovery: TargetDiscovery;
-  readonly organization: string;
-  readonly tokenProvider: TargetAccessTokenProvider;
-  readonly transport?: HttpTransport;
-  readonly clock?: Clock;
-  readonly retryPolicy?: RetryPolicy;
-}
+} from './types.js';
+import type { TargetDiscoveryDescriptor } from '../target/discovery.js';
+import { readBoundedResponseJson } from '../target/bounded-response.js';
+import { throwCapsuleServerError } from './capsule-error-response.js';
+import { validateAccessUrl } from './access-url.js';
+import { withTargetRetry } from './retry-executor.js';
+import {
+  requestUrl,
+  type AdapterRequest,
+  type ExecuteArguments,
+} from './adapter-request.js';
 
 const DEFAULT_TRANSPORT: HttpTransport = {
-  fetch(url: string, init: RequestInit & { redirect: 'error' }): Promise<Response> {
+  fetch(url, init) {
     return globalThis.fetch(url, init);
   },
 };
-
 const DEFAULT_CLOCK: Clock = { now: () => Date.now() };
 
 function throwIfAborted(signal?: AbortSignal): void {
-  if (signal?.aborted) {
-    throw signal.reason === undefined
-      ? new DOMException('The operation was aborted', 'AbortError')
-      : signal.reason;
-  }
+  if (signal?.aborted)
+    throw signal.reason ?? new globalThis.DOMException('The operation was aborted', 'AbortError');
 }
 
-async function waitForRetryDelay(delayMs: number, signal?: AbortSignal): Promise<void> {
-  throwIfAborted(signal);
-  if (delayMs <= 0) return;
-
-  await new Promise<void>((resolve, reject) => {
-    const onAbort = (): void => {
-      clearTimeout(timer);
-      reject(
-        signal!.reason === undefined
-          ? new DOMException('The operation was aborted', 'AbortError')
-          : signal!.reason,
-      );
-    };
-    const timer = setTimeout(() => {
-      signal?.removeEventListener('abort', onAbort);
-      resolve();
-    }, delayMs);
-    signal?.addEventListener('abort', onAbort, { once: true });
-  });
+function validOpaque(value: string, field: string): void {
+  if (value.length === 0 || value.length > 1024)
+    throw new TargetProtocolError(`${field} is invalid`);
 }
 
-function originOf(url: string): string {
-  try {
-    const u = new URL(url);
-    return u.origin;
-  } catch {
-    throw new TargetProtocolError(`Invalid URL: ${url}`);
-  }
+function jsonRequest(body: unknown): string {
+  return JSON.stringify(body);
 }
 
+
 export class ZeroCloudV1TargetAdapter implements TargetAdapter {
-  private readonly discovery: TargetDiscovery;
-  private readonly organization: string;
-  private readonly tokenProvider: TargetAccessTokenProvider;
-  private readonly transport: HttpTransport;
-  private readonly clock: Clock;
-  private readonly retryPolicy: RetryPolicy;
-  private readonly expectedOrigin: string;
+  readonly #descriptor: TargetDiscoveryDescriptor;
+  readonly #organizationId: string;
+  readonly #tokenProvider: TargetAccessTokenProvider;
+  readonly #transport: HttpTransport;
+  readonly #clock: Clock;
+  readonly #retryPolicy: RetryPolicy;
+
+  constructor(options: CreateTargetAdapterOptions) {
+    this.#descriptor = options.descriptor;
+    this.#organizationId = options.organization.id;
+    validOpaque(this.#organizationId, 'organization id');
+    this.#tokenProvider = options.tokenProvider;
+    this.#transport = options.transport ?? DEFAULT_TRANSPORT;
+    this.#clock = options.clock ?? DEFAULT_CLOCK;
+    this.#retryPolicy = options.retryPolicy ?? new DefaultRetryPolicy();
+  }
 
-  constructor(opts: ZeroCloudV1Options) {
-    this.discovery = opts.discovery;
-    this.organization = opts.organization;
-    this.tokenProvider = opts.tokenProvider;
-    this.transport = opts.transport ?? DEFAULT_TRANSPORT;
-    this.clock = opts.clock ?? DEFAULT_CLOCK;
-    this.retryPolicy = opts.retryPolicy ?? new DefaultRetryPolicy();
-    this.expectedOrigin = originOf(opts.discovery.capsuleV1);
+  get credentialInstall(): TargetAdapter['credentialInstall'] {
+    const descriptor = this.#descriptor.credentialInstall;
+    return descriptor === null
+      ? Object.freeze({ supported: false as const })
+      : Object.freeze({ supported: true as const, descriptor });
   }
 
-  async allocate(req: AllocateRequest, signal?: AbortSignal): Promise<Capsule> {
-    if (!IDEMPOTENCY_KEY_PATTERN.test(req.idempotencyKey)) {
-      throw new TargetProtocolError(
-        `Invalid idempotency key: must match ${IDEMPOTENCY_KEY_PATTERN}`,
+  allocate(request: AllocateRequest, signal?: AbortSignal): Promise<Capsule> {
+    try {
+      if (!IDEMPOTENCY_KEY_PATTERN.test(request.idempotencyKey))
+        throw new TargetProtocolError('Idempotency key is invalid');
+      if (request.label !== undefined && (request.label.length < 1 || request.label.length > 100)) {
+        throw new TargetProtocolError('Capsule label is outside the supported bounds');
+      }
+      if (request.size !== undefined && !this.#descriptor.sizes.catalog.includes(request.size)) {
+        throw new TargetProtocolError('Capsule size is not advertised by the target');
+      }
+      const body = {
+        ...(request.label === undefined ? {} : { label: request.label }),
+        ...(request.size === undefined ? {} : { size: request.size }),
+      };
+      return this.#execute(
+        'allocate',
+        'POST',
+        this.#descriptor.capsule.routes.allocate,
+        { org_id: this.#organizationId },
+        201,
+        assertCapsule,
+        signal,
+        {
+          body: jsonRequest(body),
+          headers: { 'Idempotency-Key': request.idempotencyKey },
+        }
       );
+    } catch (error) {
+      return Promise.reject(error);
     }
-
-    const body = JSON.stringify({ profile: req.profile, organization: this.organization });
-
-    return this._withRetry(async () => {
-      const resp = await this._request('POST', '/capsules', {
-        signal,
-        body,
-        headers: { 'Idempotency-Key': req.idempotencyKey },
-      });
-      const json = await this._readJson(resp);
-      return assertCapsule(json);
-    }, signal);
   }
 
-  async list(cursor?: string, signal?: AbortSignal): Promise<CapsuleListPage> {
-    return this._withRetry(async () => {
-      const params = new URLSearchParams({ organization: this.organization });
-      if (cursor) params.set('cursor', cursor);
-      const resp = await this._request('GET', `/capsules?${params.toString()}`, { signal });
-      const json = await this._readJson(resp);
-      const page = assertCapsuleListPage(json);
-      if (page.cursor !== undefined && page.cursor === cursor) {
-        throw new TargetProtocolError(
-          `Pagination loop detected: server returned the same cursor "${cursor}"`,
-        );
-      }
-      return page;
-    }, signal);
+  async list(request: ListRequest = {}, signal?: AbortSignal): Promise<CapsuleListPage> {
+    if (request.cursor !== undefined) validOpaque(request.cursor, 'cursor');
+    if (
+      request.limit !== undefined &&
+      (!Number.isSafeInteger(request.limit) ||
+        request.limit < 1 ||
+        request.limit > this.#descriptor.pagination.maxPageSize)
+    ) {
+      throw new TargetProtocolError('Pagination limit is outside the advertised bounds');
+    }
+    const page = await this.#execute(
+      'list',
+      'GET',
+      this.#descriptor.capsule.routes.list,
+      {
+        org_id: this.#organizationId,
+        cursor: request.cursor,
+        limit: request.limit,
+      },
+      200,
+      assertCapsuleListPage,
+      signal
+    );
+    if (request.cursor !== undefined && page.nextCursor === request.cursor)
+      throw new TargetProtocolError('Target returned a pagination loop');
+    return page;
   }
 
-  async inspect(capsuleId: string, signal?: AbortSignal): Promise<Capsule> {
-    return this._withRetry(async () => {
-      const resp = await this._request('GET', `/capsules/${encodeURIComponent(capsuleId)}`, {
-        signal,
-      });
-      const json = await this._readJson(resp);
-      return assertCapsule(json);
-    }, signal);
+  inspect(capsuleId: string, signal?: AbortSignal): Promise<Capsule> {
+    validOpaque(capsuleId, 'capsule id');
+    return this.#execute(
+      'inspect',
+      'GET',
+      this.#descriptor.capsule.routes.inspect,
+      { org_id: this.#organizationId, capsule_id: capsuleId },
+      200,
+      assertCapsule,
+      signal
+    );
   }
 
-  async terminate(capsuleId: string, signal?: AbortSignal): Promise<void> {
-    await this._withRetry(async () => {
-      const resp = await this._request(
-        'DELETE',
-        `/capsules/${encodeURIComponent(capsuleId)}`,
-        { signal },
-      );
-      if (resp.status !== 204) {
-        const json = await this._readJson(resp);
-        throw new TargetProtocolError(`Unexpected terminate response: ${JSON.stringify(json)}`);
-      }
-    }, signal);
+  terminate(capsuleId: string, signal?: AbortSignal): Promise<Capsule> {
+    validOpaque(capsuleId, 'capsule id');
+    return this.#execute(
+      'terminate',
+      'DELETE',
+      this.#descriptor.capsule.routes.terminate,
+      { org_id: this.#organizationId, capsule_id: capsuleId },
+      202,
+      assertCapsule,
+      signal
+    );
   }
 
-  async limits(signal?: AbortSignal): Promise<CapsuleLimits> {
-    return this._withRetry(async () => {
-      const params = new URLSearchParams({ organization: this.organization });
-      const resp = await this._request('GET', `/limits?${params.toString()}`, { signal });
-      const json = await this._readJson(resp);
-      return assertCapsuleLimits(json);
-    }, signal);
+  limits(signal?: AbortSignal): Promise<CapsuleLimits> {
+    return this.#execute(
+      'limits',
+      'GET',
+      this.#descriptor.capsule.routes.limits,
+      { org_id: this.#organizationId },
+      200,
+      assertCapsuleLimits,
+      signal
+    );
   }
 
   async access(capsuleId: string, signal?: AbortSignal): Promise<CapsuleAccess> {
-    return this._withRetry(async () => {
-      const resp = await this._request(
-        'POST',
-        `/capsules/${encodeURIComponent(capsuleId)}/access`,
-        { signal },
-      );
-      const json = await this._readJson(resp);
-      return assertCapsuleAccess(json);
-    }, signal);
+    validOpaque(capsuleId, 'capsule id');
+    const result = await this.#execute(
+      'access',
+      'POST',
+      this.#descriptor.capsule.routes.access,
+      { capsule_id: capsuleId },
+      200,
+      assertCapsuleAccess,
+      signal,
+      {
+        body: jsonRequest({ protocol: 'openengine.cluster/v1' }),
+      }
+    );
+    validateAccessUrl(result.websocketUrl, capsuleId, this.#descriptor);
+    return result;
   }
 
-  private async _request(
-    method: string,
-    path: string,
-    opts: { signal?: AbortSignal | undefined; body?: string | undefined; headers?: Record<string, string> | undefined },
-  ): Promise<Response> {
-    const url = `${this.discovery.capsuleV1}${path}`;
-
-    const responseOrigin = originOf(url);
-    if (responseOrigin !== this.expectedOrigin) {
-      throw new TargetProtocolError(
-        `Origin mismatch: expected ${this.expectedOrigin}, got ${responseOrigin}`,
-      );
-    }
-
-    let token: string;
-    try {
-      token = await this.tokenProvider.getAccessToken(opts.signal);
-    } catch (err) {
-      throw new TargetTransportError('Failed to acquire access token', err);
-    }
-
-    const headers: Record<string, string> = {
-      'Authorization': `Bearer ${token}`,
-      'Content-Type': 'application/json',
-      'Accept': 'application/json',
-      ...opts.headers,
-    };
+  #execute<T>(...args: ExecuteArguments<T>): Promise<T> {
+    return Promise.resolve().then(() => this.#executeExpanded(args));
+  }
 
-    let response: Response;
-    const fetchInit: RequestInit & { redirect: 'error' } = {
+  #executeExpanded<T>(args: ExecuteArguments<T>): Promise<T> {
+    const [
+      operation,
       method,
-      headers,
-      redirect: 'error',
-    };
-    if (opts.body !== undefined) fetchInit.body = opts.body;
-    if (opts.signal !== undefined) fetchInit.signal = opts.signal;
-
+      template,
+      values,
+      expectedStatus,
+      validate,
+      signal,
+      request = {},
+    ] = args;
+    let path: string;
     try {
-      response = await this.transport.fetch(url, fetchInit);
-    } catch (err) {
-      if (err instanceof TargetAdapterError) throw err;
-      const msg = err instanceof Error ? err.message : String(err);
-      if (msg.includes('redirect')) {
-        throw new TargetProtocolError(`Redirect rejected for ${method} ${path}`, err);
-      }
-      throw new TargetTransportError(`Network error during ${method} ${path}`, err);
-    }
-
-    if (response.status < 200 || response.status >= 300) {
-      await this._mapStatusError(response, method, path, opts.headers);
+      path = template.expand(values);
+    } catch {
+      throw new TargetProtocolError('Capsule route expansion is unsafe');
     }
-
-    return response;
+    return withTargetRetry(
+      operation,
+      async () => {
+        const response = await this.#request(method, path, signal, request);
+        if (response.status >= 300 && response.status < 400) {
+          await response.body?.cancel().catch(() => undefined);
+          throw new TargetProtocolError('Capsule redirects are forbidden');
+        }
+        if (response.status !== expectedStatus) {
+          if (response.status >= 200 && response.status < 300) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new TargetProtocolError('Target returned an unexpected success status');
+          }
+          await throwCapsuleServerError(
+            response,
+            (errorResponse) => this.#readJson(errorResponse),
+            this.#clock,
+          );
+        }
+        return validate(await this.#readJson(response));
+      },
+      signal,
+      { clock: this.#clock, policy: this.#retryPolicy },
+    );
   }
 
-  private async _mapStatusError(
-    response: Response,
+  async #request(
     method: string,
     path: string,
-    headers?: Record<string, string>,
-  ): Promise<never> {
-    const status = response.status;
-    const errorBody = await this._readErrorBody(response);
-    const context = `${status} ${method} ${path}: ${errorBody}`;
-
-    if (status === 401 || status === 403) throw new TargetAuthError(context);
-    if (status === 404) throw new TargetNotFoundError(context);
-    if (status === 409) {
-      const idempotencyKey = headers?.['Idempotency-Key'] ?? 'unknown';
-      throw new TargetConflictError(idempotencyKey, context);
-    }
-    if (status === 429) {
-      const retryAfterMs = parseRetryAfter(response.headers.get('Retry-After'), this.clock);
-      throw new TargetRateLimitError(context, retryAfterMs ?? undefined);
-    }
-    if (status >= 500) throw new TargetTransportError(context);
-    throw new TargetProtocolError(`Unexpected status ${context}`);
-  }
-
-  private async _readJson(response: Response): Promise<unknown> {
-    const contentLength = response.headers.get('Content-Length');
-    if (contentLength !== null) {
-      const len = parseInt(contentLength, 10);
-      if (Number.isFinite(len) && len > MAX_RESPONSE_BYTES) {
-        throw new TargetProtocolError(
-          `Response too large: ${len} bytes exceeds limit of ${MAX_RESPONSE_BYTES}`,
-        );
-      }
-    }
-
-    let text: string;
-    try {
-      const reader = response.body?.getReader();
-      if (!reader) {
-        text = await response.text();
-      } else {
-        const chunks: Uint8Array[] = [];
-        let totalBytes = 0;
-        while (true) {
-          const { done, value } = await reader.read();
-          if (done) break;
-          totalBytes += value.byteLength;
-          if (totalBytes > MAX_RESPONSE_BYTES) {
-            reader.cancel();
-            throw new TargetProtocolError(
-              `Response body exceeds limit of ${MAX_RESPONSE_BYTES} bytes`,
-            );
-          }
-          chunks.push(value);
-        }
-        const combined = new Uint8Array(totalBytes);
-        let offset = 0;
-        for (const chunk of chunks) {
-          combined.set(chunk, offset);
-          offset += chunk.byteLength;
-        }
-        text = new TextDecoder().decode(combined);
-      }
-    } catch (err) {
-      if (err instanceof TargetProtocolError) throw err;
-      throw new TargetProtocolError('Failed to read response body', err);
-    }
-
+    signal: AbortSignal | undefined,
+    request: AdapterRequest,
+  ): Promise<Response> {
+    throwIfAborted(signal);
+    const url = requestUrl(path, this.#descriptor);
+    let token: string;
     try {
-      return JSON.parse(text);
-    } catch (err) {
-      throw new TargetProtocolError('Invalid JSON in response body', err);
+      token = await this.#tokenProvider.getAccessToken(signal);
+    } catch {
+      throw new TargetAuthError('Target access authorization failed');
     }
-  }
-
-  private async _readErrorBody(response: Response): Promise<string> {
-    const reader = response.body?.getReader();
-    if (!reader) return '';
-
-    const chunks: Uint8Array[] = [];
-    let totalBytes = 0;
+    const init: RequestInit & { redirect: 'manual' } = {
+      method,
+      headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${token}`,
+        ...(request.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+        ...request.headers,
+      },
+      redirect: 'manual',
+    };
+    if (request.body !== undefined) init.body = request.body;
+    if (signal !== undefined) init.signal = signal;
     try {
-      while (totalBytes < MAX_ERROR_BODY_BYTES) {
-        const { done, value } = await reader.read();
-        if (done) break;
-
-        const remaining = MAX_ERROR_BODY_BYTES - totalBytes;
-        const retained = value.byteLength > remaining ? value.slice(0, remaining) : value;
-        chunks.push(retained);
-        totalBytes += retained.byteLength;
-        if (retained.byteLength !== value.byteLength || totalBytes === MAX_ERROR_BODY_BYTES) {
-          void reader.cancel().catch(() => undefined);
-          break;
-        }
+      const response = await this.#transport.fetch(url.href, init);
+      if (response.url && new globalThis.URL(response.url).href !== url.href) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new TargetProtocolError('Capsule response changed target route');
       }
-    } catch {
-      void reader.cancel().catch(() => undefined);
-      return '<unreadable>';
-    }
-
-    const combined = new Uint8Array(totalBytes);
-    let offset = 0;
-    for (const chunk of chunks) {
-      combined.set(chunk, offset);
-      offset += chunk.byteLength;
+      return response;
+    } catch (error) {
+      if (error instanceof TargetAdapterError) throw error;
+      throwIfAborted(signal);
+      throw new TargetTransportError('Capsule transport failed');
     }
-    return new TextDecoder().decode(combined);
   }
 
-  private async _withRetry<T>(
-    fn: () => Promise<T>,
-    signal?: AbortSignal,
-  ): Promise<T> {
-    const startTime = this.clock.now();
-    let attempt = 0;
-
-    while (true) {
-      throwIfAborted(signal);
-      try {
-        return await fn();
-      } catch (err) {
-        throwIfAborted(signal);
-        if (!(err instanceof TargetAdapterError)) throw err;
-        if (err instanceof TargetAuthError) throw err;
-
-        attempt++;
-        const elapsed = this.clock.now() - startTime;
-        const decision = this.retryPolicy.shouldRetry(attempt, elapsed, err);
-        const remaining = MAX_RETRY_ELAPSED_MS - elapsed;
-
-        if (
-          !decision.retry ||
-          !Number.isFinite(decision.delayMs) ||
-          decision.delayMs < 0 ||
-          decision.delayMs >= remaining
-        ) {
-          throw err;
-        }
 
-        await waitForRetryDelay(decision.delayMs, signal);
-        if (this.clock.now() - startTime >= MAX_RETRY_ELAPSED_MS) throw err;
-      }
-    }
+  #readJson(response: Response): Promise<unknown> {
+    return readBoundedResponseJson(response, MAX_RESPONSE_BYTES, (kind) =>
+      new TargetProtocolError(
+        kind === 'size'
+          ? 'Capsule response exceeds the size limit'
+          : 'Capsule response is not valid UTF-8 JSON',
+      ),
+    );
   }
 }