@wardby/cli 0.2.0 → 0.3.0

package/dist/providers/coding-proxy/registry/service.d.ts

@@ -0,0 +1,213 @@
+import { RegistryError, type Integrity, type RegistryAdapter, type UpstreamFetch } from "../../../coding/registry/types.js";
+import type { OsvAudit } from "./audit.js";
+import type { RegistryStore } from "./store.js";
+export declare const DEFAULT_MAX_GRAPH_PACKAGES = 3000;
+export declare const DEFAULT_GRAPH_TIMEOUT_MS = 180000;
+/** Graph-walk expansions in flight at once across every run, so one run's
+ *  walk cannot starve the others' upstream fetches -- or the proxy's event
+ *  loop: parsing packuments is CPU work on the same loop that carries model
+ *  traffic (per-walk 2 and global 3 since a live install at 4/6 on 500m
+ *  expired a ledger transaction). The walk is only the fallback now; lockfile
+ *  verification answers most installs without it. */
+export declare const DEFAULT_MAX_GRAPH_CONCURRENCY = 3;
+/** Lockfile plans read and verified at once across every run: with the
+ *  20 MiB body cap, this bounds the lockfile text held at once. */
+export declare const DEFAULT_PLAN_CONCURRENCY = 2;
+/** Lockfile plans one run may make (REGISTRY_PLAN_MAX_PER_RUN). */
+export declare const DEFAULT_PLAN_MAX_PER_RUN = 20;
+/** The `filename` of a refused RegistryFetch row a lockfile plan recorded
+ *  (the route it came from), which is how get_run tells plan refusals from
+ *  download refusals. */
+export declare const PLAN_FETCH_FILENAME = "-/plan";
+/** Largest lockfile a plan reads (the HTTP layer enforces it: 413). */
+export declare const MAX_PLAN_BODY_BYTES: number;
+export interface RegistryLimits {
+    maxFileBytes: number;
+    maxTotalBytes: number;
+    maxFiles: number;
+    idleTimeoutMs: number;
+    /** Refused RegistryFetch rows recorded per run (default 500). Further
+     *  refusals still get their normal error, but no row. */
+    maxRefusalRecords?: number;
+}
+export declare const DEFAULT_MAX_REFUSAL_RECORDS = 500;
+export type RegistryResponse = {
+    status: number;
+    contentType: string;
+    body: string;
+} | {
+    status: 200;
+    contentType: string;
+    stream: ReadableStream<Uint8Array>;
+};
+export interface RegistryRequest {
+    method: string;
+    ecosystem: string;
+    subpath: string;
+    token: string;
+    signal: AbortSignal;
+}
+export interface RegistryPlanRequest {
+    ecosystem: string;
+    token: string;
+    /** Reads the lockfile (at most MAX_PLAN_BODY_BYTES). Called only once the
+     *  token is authenticated and a plan slot is held, so an unauthenticated
+     *  or queued request never has its body buffered. Throws a RegistryError
+     *  (413 or 400) for a body it cannot read. */
+    readBody(): Promise<string>;
+    signal: AbortSignal;
+}
+export declare function errorResponse(error: RegistryError): RegistryResponse;
+export declare const DEFAULT_METADATA_CACHE_ENTRIES = 500;
+/** Byte budget of the metadata cache, by each entry's approximate retained
+ *  size. Entries are trimmed (an npm package's is a few MB at most, for
+ *  thousands of versions), but 500 of them could still add up. */
+export declare const DEFAULT_METADATA_CACHE_BYTES: number;
+/** The strongest supported hash of an SRI integrity string (`sha512-…`,
+ *  possibly several space-separated), or null when it has none. */
+export declare function parseSri(value: string): Integrity | null;
+export declare class RegistryService {
+    private readonly options;
+    /** Parsed, trimmed metadata (adapters keep only the fields the proxy
+     *  reads, never the upstream document), least recently used first.
+     *  Bounded to `metadataCacheEntries` and `metadataCacheBytes`; expired
+     *  entries are dropped on access and on insert. */
+    private readonly metadataCache;
+    /** Sum of the cached entries' `bytes`. */
+    private metadataCacheTotal;
+    /** Single-flight: concurrent misses for one package (and render need)
+     *  share one upstream fetch. */
+    private readonly metadataLoads;
+    private readonly now;
+    private readonly metadataTtlMs;
+    private readonly metadataCacheEntries;
+    private readonly metadataCacheBytes;
+    private readonly metadataUpstream;
+    /** Per-run in-flight download usage: files and bytes reserved by downloads
+     *  that are streaming right now but not yet recorded to the store. Without
+     *  this, `usage()` (which only counts already-served rows) is read once
+     *  per request, so concurrent downloads for the same run (e.g. npm's
+     *  parallel installs) count toward neither the file nor the byte limit
+     *  until each finishes, letting them overshoot both. This reservation is
+     *  in-process only — it holds per replica of the registry proxy, not
+     *  across replicas. */
+    private readonly inFlight;
+    private readonly tallies;
+    private readonly walkSlots;
+    private readonly planSlots;
+    private readonly versionUpstream;
+    constructor(options: {
+        adapters: ReadonlyMap<string, RegistryAdapter>;
+        store: RegistryStore;
+        audit: Pick<OsvAudit, "audit"> & Partial<Pick<OsvAudit, "auditVersions">>;
+        upstream: UpstreamFetch;
+        proxyBase: string;
+        limits: RegistryLimits;
+        now?: () => Date;
+        metadataTtlMs?: number;
+        metadataCacheEntries?: number;
+        /** Byte budget of the metadata cache (default 64 MiB), by each
+         *  entry's approximate retained size. */
+        metadataCacheBytes?: number;
+        /** Timeout for one metadata request, body included (default 30 s). */
+        metadataTimeoutMs?: number;
+        /** Largest metadata document read from upstream (default 64 MiB). */
+        maxMetadataBytes?: number;
+        /** Distinct packages an on-demand graph walk may expand per run and
+         *  ecosystem (default 3000). */
+        maxGraphPackages?: number;
+        /** Time one on-demand graph walk may take (default 180 s). */
+        graphTimeoutMs?: number;
+        /** Graph-walk expansions in flight at once across every run
+         *  (default 16). */
+        maxGraphConcurrency?: number;
+        /** Entries a lockfile plan may have (default 5000). */
+        planMaxEntries?: number;
+        /** Time one lockfile plan may take (default 120 s). */
+        planTimeoutMs?: number;
+        /** Lockfile plans read and verified at once across every run (default 2). */
+        planConcurrency?: number;
+        /** Lockfile plans one run may make (default 20). */
+        planMaxPerRun?: number;
+    });
+    /** `POST /registry/<ecosystem>/-/plan`: verifies a lockfile against the
+     *  registry and approves exactly its verified, reachable name@version
+     *  pairs for the run (plan.ts). Answers `{ approved, refused }`. */
+    plan(request: RegistryPlanRequest): Promise<RegistryResponse>;
+    private planLockfile;
+    private verifyPlan;
+    /** One refused row per plan refusal, within the run's refusal cap, and
+     *  once per run however often the same lockfile is planned. */
+    private recordPlanRefusals;
+    handle(request: RegistryRequest): Promise<RegistryResponse>;
+    private dispatch;
+    private hostAllowed;
+    /** Served usage for the run, seeded once from the store and then kept
+     *  current in-process as downloads complete. */
+    private servedUsage;
+    private authorize;
+    /** Whether `name` is in the run's approved graph for this ecosystem:
+     *  the allowlist's exact roots plus the dependencies of every kept
+     *  version (the same filter the metadata path applies: root range,
+     *  release age, advisories), transitively. Each newly found name is
+     *  recorded as an allowance as the walk goes, exactly as if its
+     *  parent's metadata had been served. A scoped wildcard root cannot be
+     *  enumerated, so it is never a starting point. */
+    private resolveInGraph;
+    /** The answer for a name the walk did not find: unavailable while any
+     *  node could not be expanded (the audit, if any failure was the
+     *  audit's), otherwise absent. */
+    private graphMiss;
+    private walkGraph;
+    /** The kept versions of one package inside the edge's range, and each
+     *  one's declared dependencies, through the same metadata cache and
+     *  `keptVersions` filter the metadata path uses (a root's allowlist range
+     *  applies there), within the process-wide walk concurrency cap. `"*"`
+     *  selects every kept version; a range no kept version satisfies selects
+     *  none. A package npm doesn't have, or whose metadata is too large,
+     *  definitively selects nothing; any other failure (upstream error or
+     *  timeout, audit unavailable) is transient and reported for retry. */
+    private graphNode;
+    /** A package's metadata, cached. `render` asks for the form
+     *  `renderMetadata` can serve; a cached entry fetched without it (by the
+     *  graph walk or a download) is fetched again with it, and replaces it. */
+    private metadata;
+    private dropCached;
+    private putCached;
+    /** Caches `meta`, least recently used evicted first, within both the entry
+     *  and the byte budget. An entry larger than the whole byte budget is not
+     *  cached at all. A live entry that can render is not replaced by one that
+     *  cannot. */
+    private cacheMetadata;
+    private keptVersions;
+    private tally;
+    /** Releases a run's in-process state when its deadline passes, whether or
+     *  not any other request ever arrives: the timer does not keep the process
+     *  alive. */
+    private scheduleRelease;
+    /** Drops a run's tally and graph walks, and stops any walk still running. */
+    private releaseRun;
+    /** Releases every run's in-process state (timers included), e.g. when the
+     *  server shuts down. */
+    close(): void;
+    /** Records a refused row, at most `maxRefusalRecords` per run so a worker
+     *  hammering refused names cannot grow the table (or get_run and the PR
+     *  body) without bound. Callers still return the refusal's error. */
+    private refuse;
+    private inFlightUsage;
+    /** Reserve one file slot for a download that is about to start, and its
+     *  declared size when known. An unknown size (`null`) reserves no bytes
+     *  up front; those are added incrementally as they stream, via
+     *  `trackStreamedBytes`. */
+    private reserveDownload;
+    /** Only called for downloads whose declared size was unknown at
+     *  reservation time; adds each chunk's bytes to the in-flight total as it
+     *  arrives, so the shared budget check sees them immediately. */
+    private trackStreamedBytes;
+    /** Release a download's reservation on every exit path (served, failed,
+     *  cancelled, or refused before it ever reserved streaming). Undoes
+     *  exactly what was reserved: the declared size when known, or the bytes
+     *  actually streamed when it was not. */
+    private releaseDownload;
+    private download;
+}