@the-open-engine/zeroshot 6.29.0 → 6.29.1

package/src/hosted-target/response-validation.ts

@@ -1,86 +1,194 @@
-import { TargetProtocolError } from './errors.ts';
-import { KNOWN_CAPSULE_STATES } from './types.ts';
-import type { Capsule, CapsuleAccess, CapsuleLimits, CapsuleListPage } from './types.ts';
-
-export function assertRequiredFields(
-  body: unknown,
-  fields: readonly string[],
-  context: string,
-): asserts body is Record<string, unknown> {
-  if (body === null || typeof body !== 'object') {
-    throw new TargetProtocolError(`${context}: expected object, got ${typeof body}`);
+import { TargetProtocolError } from './errors.js';
+import { KNOWN_CAPSULE_STATES } from './types.js';
+import type { Capsule, CapsuleAccess, CapsuleLimits, CapsuleListPage } from './types.js';
+
+function closedObject(body: unknown, fields: readonly string[], context: string): Record<string, unknown> {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    throw new TargetProtocolError(`${context} response is malformed`);
   }
   const record = body as Record<string, unknown>;
-  for (const field of fields) {
-    if (record[field] === undefined || record[field] === null) {
-      throw new TargetProtocolError(`${context}: missing required field "${field}"`);
-    }
+  if (Object.keys(record).length !== fields.length || fields.some((field) => !(field in record))) {
+    throw new TargetProtocolError(`${context} response is malformed`);
   }
+  return record;
+}
+
+function nonempty(value: unknown): value is string {
+  return typeof value === 'string' && value.length > 0;
 }
 
-export function assertKnownEnum(value: string, known: readonly string[], field: string): void {
-  if (!known.includes(value)) {
-    // eslint-disable-next-line no-console
-    console.warn(`Unknown ${field} value: "${value}". Known values: ${known.join(', ')}`);
+type TimestampParts = {
+  readonly year: number;
+  readonly month: number;
+  readonly day: number;
+  readonly hour: number;
+  readonly minute: number;
+  readonly second: number;
+  readonly offsetHour: number;
+  readonly offsetMinute: number;
+};
+
+function decimal(value: string, length: number): number | null {
+  if (value.length !== length) return null;
+  for (const character of value) {
+    if (character < '0' || character > '9') return null;
   }
+  return Number(value);
 }
 
-export function assertCapsule(body: unknown): Capsule {
-  assertRequiredFields(body, ['id', 'state', 'createdAt'], 'Capsule');
-  const record = body as Record<string, unknown>;
-  if (typeof record['id'] !== 'string') {
-    throw new TargetProtocolError('Capsule: "id" must be a string');
+function parseDate(value: string): Pick<TimestampParts, 'year' | 'month' | 'day'> | null {
+  const fields = value.split('-');
+  if (fields.length !== 3) return null;
+  const year = decimal(fields[0] ?? '', 4);
+  const month = decimal(fields[1] ?? '', 2);
+  const day = decimal(fields[2] ?? '', 2);
+  if (year === null || month === null || day === null) return null;
+  return { year, month, day };
+}
+
+function parseZone(value: string): {
+  readonly clock: string;
+  readonly offsetHour: number;
+  readonly offsetMinute: number;
+} | null {
+  if (value.endsWith('Z')) {
+    return { clock: value.slice(0, -1), offsetHour: 0, offsetMinute: 0 };
   }
-  if (typeof record['state'] !== 'string') {
-    throw new TargetProtocolError('Capsule: "state" must be a string');
+  const marker = value.at(-6);
+  if ((marker !== '+' && marker !== '-') || value.at(-3) !== ':') return null;
+  const offsetHour = decimal(value.slice(-5, -3), 2);
+  const offsetMinute = decimal(value.slice(-2), 2);
+  if (offsetHour === null || offsetMinute === null) return null;
+  return { clock: value.slice(0, -6), offsetHour, offsetMinute };
+}
+
+function parseFractionalClock(value: string): string | null {
+  const fields = value.split('.');
+  if (fields.length > 2) return null;
+  const fraction = fields[1];
+  if (fraction !== undefined &&
+      (fraction.length === 0 || decimal(fraction, fraction.length) === null)) {
+    return null;
   }
-  if (typeof record['createdAt'] !== 'string') {
-    throw new TargetProtocolError('Capsule: "createdAt" must be a string');
+  return fields[0] ?? null;
+}
+
+function parseHms(value: string): {
+  readonly hour: number;
+  readonly minute: number;
+  readonly second: number;
+} | null {
+  const fields = value.split(':');
+  if (fields.length !== 3) return null;
+  const hour = decimal(fields[0] ?? '', 2);
+  const minute = decimal(fields[1] ?? '', 2);
+  const second = decimal(fields[2] ?? '', 2);
+  return hour === null || minute === null || second === null ? null : { hour, minute, second };
+}
+
+function parseClock(value: string): Omit<TimestampParts, 'year' | 'month' | 'day'> | null {
+  const zone = parseZone(value);
+  if (zone === null) return null;
+  const clock = parseFractionalClock(zone.clock);
+  if (clock === null) return null;
+  const parts = parseHms(clock);
+  if (parts === null) return null;
+  return { ...parts, offsetHour: zone.offsetHour, offsetMinute: zone.offsetMinute };
+}
+
+function parseTimestamp(value: string): TimestampParts | null {
+  if (value.at(10) !== 'T') return null;
+  const date = parseDate(value.slice(0, 10));
+  const clock = parseClock(value.slice(11));
+  return date === null || clock === null ? null : { ...date, ...clock };
+}
+
+function validClock(parts: TimestampParts): boolean {
+  return parts.hour <= 23 && parts.minute <= 59 && parts.second <= 59 &&
+    parts.offsetHour <= 23 && parts.offsetMinute <= 59;
+}
+
+function validCalendar(parts: TimestampParts): boolean {
+  if (parts.month < 1 || parts.month > 12) return false;
+  const leap = parts.year % 4 === 0 && (parts.year % 100 !== 0 || parts.year % 400 === 0);
+  const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+  return parts.day >= 1 && parts.day <= (days[parts.month - 1] ?? 0);
+}
+
+function timestamp(value: unknown): value is string {
+  if (!nonempty(value)) return false;
+  const parts = parseTimestamp(value);
+  return parts !== null &&
+    validClock(parts) &&
+    validCalendar(parts) &&
+    Number.isFinite(Date.parse(value));
+}
+
+function uint(value: unknown): value is number {
+  return Number.isSafeInteger(value) && (value as number) >= 0;
+}
+
+export function assertCapsule(body: unknown): Capsule {
+  const value = closedObject(body, ['capsule_id', 'state', 'label', 'created_at'], 'Capsule');
+  if (
+    !nonempty(value.capsule_id) ||
+    typeof value.state !== 'string' ||
+    !KNOWN_CAPSULE_STATES.includes(value.state as Capsule['state']) ||
+    (value.label !== null && typeof value.label !== 'string') ||
+    !timestamp(value.created_at)
+  ) {
+    throw new TargetProtocolError('Capsule response is malformed');
   }
-  assertKnownEnum(record['state'] as string, KNOWN_CAPSULE_STATES, 'CapsuleState');
-  return record as unknown as Capsule;
+  return Object.freeze({
+    id: value.capsule_id,
+    state: value.state as Capsule['state'],
+    label: value.label as string | null,
+    createdAt: value.created_at,
+  });
 }
 
 export function assertCapsuleAccess(body: unknown): CapsuleAccess {
-  assertRequiredFields(body, ['endpoint', 'token', 'expiresAt'], 'CapsuleAccess');
-  const record = body as Record<string, unknown>;
-  if (typeof record['endpoint'] !== 'string') {
-    throw new TargetProtocolError('CapsuleAccess: "endpoint" must be a string');
-  }
-  if (typeof record['token'] !== 'string') {
-    throw new TargetProtocolError('CapsuleAccess: "token" must be a string');
+  const value = closedObject(
+    body,
+    ['protocol', 'websocket_url', 'access_token', 'token_type', 'expires_at'],
+    'CapsuleAccess',
+  );
+  if (
+    value.protocol !== 'openengine.cluster/v1' ||
+    !nonempty(value.websocket_url) ||
+    !nonempty(value.access_token) ||
+    value.token_type !== 'Bearer' ||
+    !timestamp(value.expires_at)
+  ) {
+    throw new TargetProtocolError('CapsuleAccess response is malformed');
   }
-  if (typeof record['expiresAt'] !== 'string') {
-    throw new TargetProtocolError('CapsuleAccess: "expiresAt" must be a string');
-  }
-  return record as unknown as CapsuleAccess;
+  return Object.freeze({
+    protocol: 'openengine.cluster/v1',
+    websocketUrl: value.websocket_url,
+    accessToken: value.access_token,
+    tokenType: 'Bearer',
+    expiresAt: value.expires_at,
+  });
 }
 
 export function assertCapsuleLimits(body: unknown): CapsuleLimits {
-  assertRequiredFields(body, ['maxConcurrent', 'maxPerHour'], 'CapsuleLimits');
-  const record = body as Record<string, unknown>;
-  if (typeof record['maxConcurrent'] !== 'number') {
-    throw new TargetProtocolError('CapsuleLimits: "maxConcurrent" must be a number');
+  const value = closedObject(body, ['active_capsules', 'max_active_capsules'], 'CapsuleLimits');
+  if (!uint(value.active_capsules) || (value.max_active_capsules !== null && !uint(value.max_active_capsules))) {
+    throw new TargetProtocolError('CapsuleLimits response is malformed');
   }
-  if (typeof record['maxPerHour'] !== 'number') {
-    throw new TargetProtocolError('CapsuleLimits: "maxPerHour" must be a number');
-  }
-  return record as unknown as CapsuleLimits;
+  return Object.freeze({
+    activeCapsules: value.active_capsules,
+    maxActiveCapsules: value.max_active_capsules as number | null,
+  });
 }
 
 export function assertCapsuleListPage(body: unknown): CapsuleListPage {
-  assertRequiredFields(body, ['items'], 'CapsuleListPage');
-  const record = body as Record<string, unknown>;
-  if (!Array.isArray(record['items'])) {
-    throw new TargetProtocolError('CapsuleListPage: "items" must be an array');
-  }
-  const items = (record['items'] as unknown[]).map((item) => assertCapsule(item));
-  const cursor = record['cursor'];
-  if (cursor !== undefined && cursor !== null && typeof cursor !== 'string') {
-    throw new TargetProtocolError('CapsuleListPage: "cursor" must be a string if present');
-  }
-  if (typeof cursor === 'string') {
-    return { items, cursor };
+  const value = closedObject(body, ['capsules', 'next_cursor'], 'CapsulePage');
+  if (!Array.isArray(value.capsules) || (value.next_cursor !== null && typeof value.next_cursor !== 'string')) {
+    throw new TargetProtocolError('CapsulePage response is malformed');
   }
-  return { items };
+  return Object.freeze({
+    capsules: Object.freeze(value.capsules.map((item) => assertCapsule(item))),
+    nextCursor: value.next_cursor as string | null,
+  });
 }

package/src/hosted-target/retry-executor.ts

@@ -0,0 +1,62 @@
+import { MAX_RETRY_ELAPSED_MS } from './bounds.js';
+import { TargetAdapterError } from './errors.js';
+import type { Clock, RetryPolicy } from './types.js';
+
+export type TargetOperation = 'allocate' | 'list' | 'inspect' | 'terminate' | 'limits' | 'access';
+
+function throwIfAborted(signal?: AbortSignal): void {
+  if (signal?.aborted) {
+    throw signal.reason ?? new globalThis.DOMException('The operation was aborted', 'AbortError');
+  }
+}
+
+async function wait(delayMs: number, signal?: AbortSignal): Promise<void> {
+  throwIfAborted(signal);
+  if (delayMs <= 0) return;
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(resolve, delayMs);
+    signal?.addEventListener('abort', () => {
+      clearTimeout(timer);
+      reject(signal.reason ?? new globalThis.DOMException('The operation was aborted', 'AbortError'));
+    }, { once: true });
+  });
+}
+
+type RetryContext = {
+  readonly clock: Clock;
+  readonly policy: RetryPolicy;
+};
+function retryableError(value: unknown): value is TargetAdapterError {
+  return value instanceof TargetAdapterError && value.retryable;
+}
+
+function validRetryDelay(retry: boolean, delayMs: number, remaining: number): boolean {
+  return retry && Number.isFinite(delayMs) && delayMs >= 0 && delayMs < remaining;
+}
+
+
+export async function withTargetRetry<T>(
+  operation: TargetOperation,
+  effect: () => Promise<T>,
+  signal: AbortSignal | undefined,
+  context: RetryContext,
+): Promise<T> {
+  const retrySafe = operation !== 'access';
+  const started = context.clock.now();
+  let attempt = 0;
+  while (true) {
+    throwIfAborted(signal);
+    try {
+      return await effect();
+    } catch (error) {
+      throwIfAborted(signal);
+      if (!retrySafe || !retryableError(error)) throw error;
+      attempt += 1;
+      const elapsed = context.clock.now() - started;
+      const decision = context.policy.shouldRetry(attempt, elapsed, error);
+      const remaining = MAX_RETRY_ELAPSED_MS - elapsed;
+      if (!validRetryDelay(decision.retry, decision.delayMs, remaining)) throw error;
+      await wait(decision.delayMs, signal);
+    }
+  }
+}

package/src/hosted-target/retry.ts

@@ -1,13 +1,45 @@
-import { MAX_RETRY_ATTEMPTS, MAX_RETRY_ELAPSED_MS } from './bounds.ts';
-import type { TargetAdapterError } from './errors.ts';
-import { TargetAuthError, TargetRateLimitError } from './errors.ts';
-import type { Clock, RetryPolicy } from './types.ts';
+import { MAX_RETRY_ATTEMPTS, MAX_RETRY_ELAPSED_MS } from './bounds.js';
+import type { TargetAdapterError } from './errors.js';
+import { TargetAuthError, TargetRateLimitError, TargetServerError } from './errors.js';
+import type { Clock, RetryPolicy } from './types.js';
+const IMF_WEEKDAYS = new Set(['Mon,', 'Tue,', 'Wed,', 'Thu,', 'Fri,', 'Sat,', 'Sun,']);
+const IMF_MONTHS = new Set([
+  'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+]);
+
+function fixedDigits(value: string, length: number): boolean {
+  if (value.length !== length) return false;
+  for (const character of value) {
+    if (character < '0' || character > '9') return false;
+  }
+  return true;
+}
+
+function validImfDate(weekday: string, day: string, month: string, year: string): boolean {
+  return IMF_WEEKDAYS.has(weekday) &&
+    fixedDigits(day, 2) &&
+    IMF_MONTHS.has(month) &&
+    fixedDigits(year, 4);
+}
+
+function validImfTime(value: string): boolean {
+  const parts = value.split(':');
+  return parts.length === 3 && parts.every((part) => fixedDigits(part, 2));
+}
+
+function isImfFixdate(value: string): boolean {
+  const parts = value.split(' ');
+  if (parts.length !== 6) return false;
+  const [weekday = '', day = '', month = '', year = '', time = '', zone = ''] = parts;
+  return validImfDate(weekday, day, month, year) && validImfTime(time) && zone === 'GMT';
+}
 
 export class DefaultRetryPolicy implements RetryPolicy {
   shouldRetry(
     attempt: number,
     elapsed: number,
-    error: TargetAdapterError,
+    error: TargetAdapterError
   ): { retry: boolean; delayMs: number } {
     if (error instanceof TargetAuthError) return { retry: false, delayMs: 0 };
     if (!error.retryable) return { retry: false, delayMs: 0 };
@@ -15,7 +47,8 @@ export class DefaultRetryPolicy implements RetryPolicy {
     if (elapsed >= MAX_RETRY_ELAPSED_MS) return { retry: false, delayMs: 0 };
 
     const requestedDelay =
-      error instanceof TargetRateLimitError && error.retryAfterMs !== undefined
+      (error instanceof TargetRateLimitError || error instanceof TargetServerError) &&
+      error.retryAfterMs !== undefined
         ? Math.max(0, error.retryAfterMs)
         : Math.min(1000 * Math.pow(2, attempt), 10_000);
     const remaining = MAX_RETRY_ELAPSED_MS - elapsed;
@@ -33,14 +66,17 @@ export function parseRetryAfter(header: string | null, clock: Clock): number | n
   const trimmed = header.trim();
   if (trimmed.length === 0) return null;
 
-  const numericSeconds = Number(trimmed);
-  if (Number.isFinite(numericSeconds) && numericSeconds >= 0) {
-    return Math.ceil(numericSeconds * 1000);
+  if (/^\d+$/.test(trimmed)) {
+    const delayMs = Number(trimmed) * 1000;
+    return Number.isSafeInteger(delayMs) ? delayMs : null;
   }
 
+  if (!isImfFixdate(trimmed)) {
+    return null;
+  }
   const date = Date.parse(trimmed);
-  if (Number.isNaN(date)) return null;
+  if (!Number.isFinite(date) || new Date(date).toUTCString() !== trimmed) return null;
 
   const delayMs = date - clock.now();
-  return delayMs > 0 ? Math.ceil(delayMs) : 0;
+  return delayMs > 0 ? delayMs : 0;
 }

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

@@ -1,10 +1,14 @@
-import type { AllocateRequest, Capsule, CapsuleAccess, CapsuleLimits, CapsuleListPage } from './types.ts';
+import { ZeroCloudV1TargetAdapter } from './zero-cloud-v1-adapter.js';
+import type { CreateTargetAdapterOptions, TargetAdapter } from './adapter-types.js';
+export type {
+  CreateTargetAdapterOptions,
+  CredentialInstallCapability,
+  TargetAdapter,
+} from './adapter-types.js';
 
-export interface TargetAdapter {
-  allocate(req: AllocateRequest, signal?: AbortSignal): Promise<Capsule>;
-  list(cursor?: string, signal?: AbortSignal): Promise<CapsuleListPage>;
-  inspect(capsuleId: string, signal?: AbortSignal): Promise<Capsule>;
-  terminate(capsuleId: string, signal?: AbortSignal): Promise<void>;
-  limits(signal?: AbortSignal): Promise<CapsuleLimits>;
-  access(capsuleId: string, signal?: AbortSignal): Promise<CapsuleAccess>;
+export function createTargetAdapter(options: CreateTargetAdapterOptions): TargetAdapter {
+  if (options.descriptor.adapter.majorVersion !== 1) {
+    throw new Error('Unsupported hosted target adapter version');
+  }
+  return new ZeroCloudV1TargetAdapter(options);
 }

package/src/hosted-target/types.ts

@@ -1,44 +1,49 @@
-import type { TargetAdapterError } from './errors.ts';
+import type { TargetAdapterError } from './errors.js';
 
 export interface TargetAccessTokenProvider {
   getAccessToken(signal?: AbortSignal): Promise<string>;
 }
 
-export type CapsuleState = 'provisioning' | 'running' | 'stopping' | 'terminated' | 'failed' | (string & {});
-
-export const KNOWN_CAPSULE_STATES = ['provisioning', 'running', 'stopping', 'terminated', 'failed'] as const;
+export type CapsuleState = 'provisioning' | 'ready' | 'terminating' | 'terminated' | 'failed';
+export const KNOWN_CAPSULE_STATES = ['provisioning', 'ready', 'terminating', 'terminated', 'failed'] as const;
 
 export interface Capsule {
   readonly id: string;
   readonly state: CapsuleState;
+  readonly label: string | null;
   readonly createdAt: string;
-  readonly [key: string]: unknown;
 }
 
 export interface CapsuleAccess {
-  readonly endpoint: string;
-  readonly token: string;
+  readonly protocol: 'openengine.cluster/v1';
+  readonly websocketUrl: string;
+  readonly accessToken: string;
+  readonly tokenType: 'Bearer';
   readonly expiresAt: string;
 }
 
 export interface CapsuleListPage {
-  readonly items: readonly Capsule[];
-  readonly cursor?: string;
+  readonly capsules: readonly Capsule[];
+  readonly nextCursor: string | null;
 }
 
 export interface CapsuleLimits {
-  readonly maxConcurrent: number;
-  readonly maxPerHour: number;
-  readonly [key: string]: unknown;
+  readonly activeCapsules: number;
+  readonly maxActiveCapsules: number | null;
 }
 
 export interface AllocateRequest {
   readonly idempotencyKey: string;
-  readonly profile: string;
+  readonly label?: string;
+  readonly size?: 'tiny' | 'small' | 'standard' | 'large';
+}
+export interface ListRequest {
+  readonly cursor?: string;
+  readonly limit?: number;
 }
 
 export interface HttpTransport {
-  fetch(url: string, init: RequestInit & { redirect: 'error' }): Promise<Response>;
+  fetch(url: string, init: RequestInit & { redirect: 'manual' }): Promise<Response>;
 }
 
 export interface Clock {
@@ -52,7 +57,3 @@ export interface RetryPolicy {
     error: TargetAdapterError,
   ): { retry: boolean; delayMs: number };
 }
-
-export interface TargetDiscovery {
-  readonly capsuleV1: string;
-}