@wildo-ai/wildo-module-client 1.1.5 → 1.1.7

package/src/services/registry-server-client.ts

@@ -12,7 +12,8 @@
  * Auth (KD-11): if `authToken` is supplied, every request adds
  * `Authorization: Bearer <token>`. Public read paths work without
  * a token; restricted paths return 401/403, surfaced as
- * `RegistryAuthRequiredError` / `RegistryAuthForbiddenError`.
+ * `RegistryAuthRequiredError` (no key sent), `RegistryCredentialRejectedError` (a key sent and refused)
+ * or `RegistryAuthForbiddenError`; a 429 is `RegistryRateLimitedError`.
  */
 
 import { z } from 'zod';
@@ -23,16 +24,31 @@ import {
   RegistryArtifactIntegrityMismatchError,
   RegistryAuthForbiddenError,
   RegistryAuthRequiredError,
+  RegistryCredentialRejectedError,
   RegistryError,
+  RegistryRateLimitedError,
+  isRegistryError,
+  isRegistryReleaseStateConflictBody,
   RegistryMalformedPayloadError,
   RegistryModuleNotFoundError,
   RegistryUnexpectedStatusError,
   RegistryVersionNotFoundError,
+  RegistryYankNoticeSchema,
+  RegistryYankStateConflictError,
+  RegistryYankVerb,
+  REGISTRY_YANK_REASON_HEADER,
+  REGISTRY_YANKED_AT_HEADER,
   Sha256DigestSchema,
+  ModuleSearchHitSchema,
+  moduleSearchFilterQueryPairs,
+  moduleSearchHitMatchesFilter,
   type ModuleManifest,
+  type ModuleSearchFilter,
+  type ModuleSearchHit,
+  type RegistryYankNotice,
   type ModuleVersionRecord,
 } from '@wildo-ai/platform-config-lib';
-import { fetchJsonOk, fetchWithTimeout, joinUrl } from './_http-client';
+import { fetchJsonOk, fetchTransfer, fetchWithTimeout, joinUrl, readJsonBody } from './_http-client';
 
 /**
  * Zod schema for the `info()` response payload — mirrors
@@ -48,13 +64,7 @@ const RegistryInfoResponseSchema = z.object({
 });
 
 const RegistrySearchResponseSchema = z.object({
-  hits: z.array(
-    z.object({
-      moduleId: z.string().min(1),
-      description: z.string().optional(),
-      latestVersion: z.string(),
-    }),
-  ),
+  hits: z.array(ModuleSearchHitSchema),
 });
 
 const DIAGNOSTIC_LABEL = 'Registry';
@@ -72,10 +82,32 @@ function authHeaders(options: RegistryServerClientOptions): Record<string, strin
   return options.authToken ? { Authorization: `Bearer ${options.authToken}` } : {};
 }
 
-async function classifyAuthError(res: Response, registryUrl: string, action: string): Promise<RegistryError | null> {
-  if (res.status === 401) return new RegistryAuthRequiredError(registryUrl);
-  if (res.status === 403) return new RegistryAuthForbiddenError(action);
-  return null;
+/**
+ * Throw the typed error for a non-2xx response, after releasing its body (#1763 review: an unread body
+ * holds the connection until garbage collection). A 401 is told apart by whether a key was SENT — "log
+ * in" and "your key no longer works" are different remedies (#1759 review).
+ */
+async function refuseUnlessOk(
+  res: Response,
+  options: RegistryServerClientOptions,
+  action: string,
+  notFound?: () => RegistryError,
+): Promise<void> {
+  if (res.ok) return;
+  let error: RegistryError;
+  if (res.status === 404 && notFound) error = notFound();
+  else if (res.status === 401) error = options.authToken ? new RegistryCredentialRejectedError(options.baseUrl) : new RegistryAuthRequiredError(options.baseUrl);
+  else if (res.status === 403) error = new RegistryAuthForbiddenError(action);
+  else if (res.status === 429) error = new RegistryRateLimitedError(options.baseUrl, action, parseRetryAfterSeconds(res.headers.get('retry-after')));
+  else error = new RegistryUnexpectedStatusError(options.baseUrl, res.status, res.statusText, action);
+  await res.body?.cancel().catch(() => undefined);
+  throw error;
+}
+
+/** `Retry-After` in its delta-seconds form; the HTTP-date form is not produced by a Wildo backend. */
+function parseRetryAfterSeconds(value: string | null): number | undefined {
+  if (!value || !/^\d+$/.test(value.trim())) return undefined;
+  return Number(value.trim());
 }
 
 /**
@@ -90,10 +122,13 @@ async function parseJsonOrThrow(
   res: Response,
   registryUrl: string,
   action: string,
+  timeoutMs: number | undefined,
 ): Promise<unknown> {
   try {
-    return await res.json();
+    return await readJsonBody(res, registryUrl, action, timeoutMs);
   } catch (err) {
+    // A body cut short by the request budget is a timeout (#1763), not a malformed payload.
+    if (isRegistryError(err)) throw err;
     throw new RegistryMalformedPayloadError(
       registryUrl,
       action,
@@ -106,6 +141,11 @@ export interface RegistryResolveResult {
   /** Resolved exact version (matches `Sha256DigestSchema` for digest). */
   version: string;
   artifactDigest: string;
+  /**
+   * Present when the resolved release is yanked. Only an EXACT-version request can resolve to one
+   * (#1758) — ranges and tags never do — so the caller is pinned to it and should warn, not refuse.
+   */
+  yanked?: RegistryYankNotice;
 }
 
 export interface RegistryInfoResult {
@@ -116,11 +156,8 @@ export interface RegistryInfoResult {
   tags: Readonly<Record<string, string>>;
 }
 
-export interface RegistrySearchHit {
-  moduleId: string;
-  description?: string;
-  latestVersion: string;
-}
+/** One search hit: the module, its latest version, and (#2014) its kind and provider facts. */
+export type RegistrySearchHit = ModuleSearchHit;
 
 export const RegistryServerClient = {
   /**
@@ -162,19 +199,13 @@ export const RegistryServerClient = {
       timeoutMs: options.timeoutMs,
       diagnosticLabel: DIAGNOSTIC_LABEL,
     });
-    if (res.status === 404) {
-      throw new RegistryVersionNotFoundError(args.moduleId, args.range);
-    }
-    const authErr = await classifyAuthError(res, options.baseUrl, `resolve ${args.moduleId}`);
-    if (authErr) throw authErr;
-    if (!res.ok) {
-      throw new RegistryUnexpectedStatusError(options.baseUrl, res.status, res.statusText, `resolve ${args.moduleId}`);
-    }
+    await refuseUnlessOk(res, options, `resolve ${args.moduleId}`, () => new RegistryVersionNotFoundError(args.moduleId, args.range));
     // 6th-pass M3: typed JSON-parse (was bare `SyntaxError` for
     // malformed proxy responses).
-    const json = (await parseJsonOrThrow(res, options.baseUrl, `resolve ${args.moduleId}`)) as {
+    const json = (await parseJsonOrThrow(res, options.baseUrl, `resolve ${args.moduleId}`, options.timeoutMs)) as {
       version?: unknown;
       artifactDigest?: unknown;
+      yanked?: unknown;
     };
     const digest = String(json.artifactDigest ?? '');
     // 6th-pass M4: typed digest validation (was bare `ZodError`).
@@ -196,7 +227,15 @@ export const RegistryServerClient = {
         'response missing required `version` string',
       );
     }
-    return { version: json.version, artifactDigest: digest };
+    let yanked: RegistryYankNotice | undefined;
+    if (json.yanked !== undefined) {
+      const yankParse = RegistryYankNoticeSchema.safeParse(json.yanked);
+      if (!yankParse.success) {
+        throw new RegistryMalformedPayloadError(options.baseUrl, `resolve ${args.moduleId}`, `yanked: ${formatZodIssuesAsSingleLine(yankParse.error)}`);
+      }
+      yanked = yankParse.data;
+    }
+    return { version: json.version, artifactDigest: digest, ...(yanked ? { yanked } : {}) };
   },
 
   /**
@@ -217,14 +256,9 @@ export const RegistryServerClient = {
       timeoutMs: options.timeoutMs,
       diagnosticLabel: DIAGNOSTIC_LABEL,
     });
-    if (res.status === 404) throw new RegistryModuleNotFoundError(args.moduleId);
-    const authErr = await classifyAuthError(res, options.baseUrl, `info ${args.moduleId}`);
-    if (authErr) throw authErr;
-    if (!res.ok) {
-      throw new RegistryUnexpectedStatusError(options.baseUrl, res.status, res.statusText, `info ${args.moduleId}`);
-    }
+    await refuseUnlessOk(res, options, `info ${args.moduleId}`, () => new RegistryModuleNotFoundError(args.moduleId));
     // 6th-pass M3: typed JSON-parse.
-    const json = await parseJsonOrThrow(res, options.baseUrl, `info ${args.moduleId}`);
+    const json = await parseJsonOrThrow(res, options.baseUrl, `info ${args.moduleId}`, options.timeoutMs);
     const parsed = RegistryInfoResponseSchema.safeParse(json);
     if (!parsed.success) {
       throw new RegistryMalformedPayloadError(
@@ -237,16 +271,17 @@ export const RegistryServerClient = {
   },
 
   /**
-   * Search the registry's metadata index. The shape is
-   * intentionally narrow until Phase 4 designs the search UX.
+   * Search the registry's metadata index: a module-id substring, and (#2014) the manifest filters —
+   * kind, engine capability and provider maturity. The server refuses an unknown filter value.
    */
   async search(
     options: RegistryServerClientOptions,
-    args: { domain: string; query: string },
+    args: { domain: string; query: string; filter?: ModuleSearchFilter },
   ): Promise<readonly RegistrySearchHit[]> {
+    const params = new URLSearchParams([['q', args.query], ...moduleSearchFilterQueryPairs(args.filter ?? {})]);
     const url = joinUrl(
       options.baseUrl,
-      `/v1/registry/${encodeURIComponent(args.domain)}/modules?q=${encodeURIComponent(args.query)}`,
+      `/v1/registry/${encodeURIComponent(args.domain)}/modules?${params.toString()}`,
     );
     const res = await fetchWithTimeout(url, {
       method: 'GET',
@@ -254,13 +289,9 @@ export const RegistryServerClient = {
       timeoutMs: options.timeoutMs,
       diagnosticLabel: DIAGNOSTIC_LABEL,
     });
-    const authErr = await classifyAuthError(res, options.baseUrl, `search`);
-    if (authErr) throw authErr;
-    if (!res.ok) {
-      throw new RegistryUnexpectedStatusError(options.baseUrl, res.status, res.statusText, 'search');
-    }
+    await refuseUnlessOk(res, options, 'search');
     // 6th-pass M3: typed JSON-parse.
-    const json = await parseJsonOrThrow(res, options.baseUrl, 'search');
+    const json = await parseJsonOrThrow(res, options.baseUrl, 'search', options.timeoutMs);
     const parsed = RegistrySearchResponseSchema.safeParse(json);
     if (!parsed.success) {
       throw new RegistryMalformedPayloadError(
@@ -269,7 +300,8 @@ export const RegistryServerClient = {
         formatZodIssuesAsSingleLine(parsed.error),
       );
     }
-    return parsed.data.hits;
+    // Re-applied here: a server that predates the filters ignores them and answers every module (#2014 review F9).
+    return parsed.data.hits.filter((hit) => moduleSearchHitMatchesFilter(hit, args.filter ?? {}));
   },
 
   /**
@@ -286,7 +318,7 @@ export const RegistryServerClient = {
       version: string;
       expectedDigest: string;
     },
-  ): Promise<{ bytes: Uint8Array; integrity: string }> {
+  ): Promise<{ bytes: Uint8Array; integrity: string; yanked?: RegistryYankNotice }> {
     // 7th-pass C-M1: caller-supplied digest is a developer-contract
     // violation if malformed, not a registry-runtime condition.
     // Throw `TypeError` (matching `C-L3` precedent for
@@ -306,19 +338,16 @@ export const RegistryServerClient = {
       options.baseUrl,
       `/v1/registry/${encodeURIComponent(args.domain)}/modules/${encodeURIComponent(args.moduleId)}/${encodeURIComponent(args.version)}/artifact`,
     );
-    const res = await fetchWithTimeout(url, {
+    // A transfer, not a metadata call: the response is bounded by `timeoutMs`, the body by an IDLE budget
+    // reset on every chunk, so a large artifact over a slow link installs and a stalled one fails (#1763).
+    const { response: res, readAll } = await fetchTransfer(url, {
       method: 'GET',
       headers: authHeaders(options),
       timeoutMs: options.timeoutMs,
       diagnosticLabel: DIAGNOSTIC_LABEL,
     });
-    if (res.status === 404) throw new RegistryVersionNotFoundError(args.moduleId, args.version);
-    const authErr = await classifyAuthError(res, options.baseUrl, `download ${args.moduleId}@${args.version}`);
-    if (authErr) throw authErr;
-    if (!res.ok) {
-      throw new RegistryUnexpectedStatusError(options.baseUrl, res.status, res.statusText, `download ${args.moduleId}@${args.version}`);
-    }
-    const buf = new Uint8Array(await res.arrayBuffer());
+    await refuseUnlessOk(res, options, `download ${args.moduleId}@${args.version}`, () => new RegistryVersionNotFoundError(args.moduleId, args.version));
+    const buf = await readAll();
     const { createHash } = await import('node:crypto');
     const observed = `sha256:${createHash('sha256').update(buf).digest('hex')}`;
     if (observed !== args.expectedDigest) {
@@ -329,6 +358,67 @@ export const RegistryServerClient = {
         observed,
       );
     }
-    return { bytes: buf, integrity: observed };
+    // A yanked release is served by exact version (#1758) and says so in headers.
+    const yankedAt = res.headers.get(REGISTRY_YANKED_AT_HEADER);
+    const encodedReason = res.headers.get(REGISTRY_YANK_REASON_HEADER);
+    let reason: string | undefined;
+    if (encodedReason) {
+      try { reason = decodeURIComponent(encodedReason); } catch { reason = encodedReason; }
+    }
+    return { bytes: buf, integrity: observed, ...(yankedAt ? { yanked: { yankedAt, ...(reason ? { reason } : {}) } } : {}) };
+  },
+  /**
+   * Yank a release (#1758): ranges and `latest` stop selecting it, and `latest` moves to the highest
+   * live release; an exact pin still installs it, with a warning. Needs a key holding the version UPDATE
+   * role in the domain's owning organization. Returns where `latest` points afterwards.
+   */
+  async yank(
+    options: RegistryServerClientOptions,
+    args: { domain: string; moduleId: string; version: string; reason?: string },
+  ): Promise<{ latest: string | null }> {
+    return changeYankState(options, args, RegistryYankVerb.YANK);
+  },
+
+  /** Restore a yanked release (#1758); `latest` returns to it when it outranks the current target. */
+  async unyank(
+    options: RegistryServerClientOptions,
+    args: { domain: string; moduleId: string; version: string },
+  ): Promise<{ latest: string | null }> {
+    return changeYankState(options, args, RegistryYankVerb.UNYANK);
   },
 } as const;
+
+const RegistryYankResponseSchema = z.object({ ok: z.literal(true), latest: z.string().nullable().optional() });
+
+async function changeYankState(
+  options: RegistryServerClientOptions,
+  args: { domain: string; moduleId: string; version: string; reason?: string },
+  verb: RegistryYankVerb,
+): Promise<{ latest: string | null }> {
+  const url = joinUrl(
+    options.baseUrl,
+    `/v1/registry/${encodeURIComponent(args.domain)}/modules/${encodeURIComponent(args.moduleId)}/${verb}`,
+  );
+  const action = `${verb} ${args.moduleId}@${args.version}`;
+  const res = await fetchWithTimeout(url, {
+    method: 'POST',
+    headers: { ...authHeaders(options), 'content-type': 'application/json' },
+    body: JSON.stringify({ version: args.version, ...(args.reason !== undefined ? { reason: args.reason } : {}) }),
+    timeoutMs: options.timeoutMs,
+    diagnosticLabel: DIAGNOSTIC_LABEL,
+  });
+  if (res.status === 409) {
+    // Only the release-state refusal is the no-op; a 409 for anything else (the registry giving up after
+    // lost optimistic checks) is a FAILED yank and must not be reported as done (#1758 re-review R3).
+    const body = await res.json().catch(() => undefined);
+    if (isRegistryReleaseStateConflictBody(body)) throw new RegistryYankStateConflictError(args.moduleId, args.version, verb);
+    throw new RegistryUnexpectedStatusError(options.baseUrl, res.status, res.statusText, action);
+  }
+  // A 404 names the module or the version; the sanitized envelope does not say which.
+  await refuseUnlessOk(res, options, action, () => new RegistryVersionNotFoundError(args.moduleId, args.version));
+  const parsed = RegistryYankResponseSchema.safeParse(await parseJsonOrThrow(res, options.baseUrl, action, options.timeoutMs));
+  if (!parsed.success) {
+    throw new RegistryMalformedPayloadError(options.baseUrl, action, formatZodIssuesAsSingleLine(parsed.error));
+  }
+  return { latest: parsed.data.latest ?? null };
+}