@indigoai-us/hq-cloud 5.45.0 → 5.47.0

package/dist/object-io.d.ts

@@ -0,0 +1,218 @@
+/**
+ * ObjectIO — transport seam for vault object byte/metadata movement.
+ *
+ * s3.ts holds the *semantics* of sync (symlink-record encoding, mode/mtime
+ * stamping, created-at preservation, directory-marker filtering). Those never
+ * change. What CAN change is the *wire transport* underneath them:
+ *
+ *   - `S3SdkObjectIO` — the historical path. STS-vended credentials + the AWS
+ *     S3 SDK talking directly to the per-company bucket. No policy-size
+ *     ceiling concern for the BYTES, but the STS session policy that grants
+ *     access has the 2048-char IAM limit that motivated the presigned model.
+ *
+ *   - `PresignObjectIO` — the presigned-URL path. The vault-service decides
+ *     access as a runtime DDB check (no IAM policy ceiling) and hands back
+ *     short-lived presigned GET/PUT/DELETE URLs + (for PUT) the exact headers
+ *     to replay. The client never holds AWS credentials — it just `fetch`es
+ *     the signed URLs.
+ *
+ * The seam is a per-EntityContext factory resolved INSIDE s3.ts, so every
+ * existing call site (`uploadFile(ctx, …)`, `downloadFile(ctx, …)`, …) keeps
+ * its signature. `runRunner` selects the transport once per session via
+ * {@link setObjectIOFactory}; absent any selection the default is the S3 SDK,
+ * preserving today's behavior for every non-gated caller.
+ */
+import type { EntityContext } from "./types.js";
+import type { PresignOp, PresignKeyInput, PresignResultRow, VaultListedObject } from "./vault-client.js";
+/**
+ * The slice of {@link VaultClient} the presigned transport needs. Narrowed to
+ * just `presign` + `listFiles` so the factory accepts any caller that exposes
+ * those two (the real VaultClient, or a stub in tests) without depending on
+ * the full 20-method surface.
+ */
+export interface PresignTransportClient {
+    presign(input: {
+        companyUid: string;
+        op?: PresignOp;
+        expiresIn?: number;
+        keys: PresignKeyInput[];
+    }): Promise<{
+        results: PresignResultRow[];
+        expiresAt: string;
+    }>;
+    listFiles(companyUid: string, prefix?: string, cursor?: string): Promise<{
+        objects: VaultListedObject[];
+        cursor: string | null;
+        truncated: boolean;
+    }>;
+}
+export interface PutObjectInput {
+    key: string;
+    body: Buffer;
+    contentType: string;
+    /** S3 user metadata (x-amz-meta-*). Lowercased keys by convention. */
+    metadata?: Record<string, string>;
+}
+export interface GetObjectResult {
+    body: Buffer;
+    /** S3 user metadata (keys lowercased by S3). */
+    metadata?: Record<string, string>;
+}
+export interface ListObjectsInput {
+    prefix?: string;
+    continuationToken?: string;
+}
+export interface ListedRemoteObject {
+    key: string;
+    size: number;
+    lastModified: Date;
+    etag: string;
+}
+export interface ListObjectsResult {
+    objects: ListedRemoteObject[];
+    /** Opaque cursor for the next page; undefined when the listing is exhausted. */
+    nextContinuationToken?: string;
+}
+export interface HeadObjectResult {
+    lastModified: Date;
+    etag: string;
+    size: number;
+    metadata?: Record<string, string>;
+}
+/**
+ * The minimal byte/metadata transport s3.ts needs. Deliberately narrow — no
+ * symlink, mode, or created-at concepts leak in here; those live one layer up
+ * in s3.ts and compose on top of these five primitives.
+ */
+export interface ObjectIO {
+    putObject(input: PutObjectInput): Promise<{
+        etag: string;
+    }>;
+    getObject(key: string): Promise<GetObjectResult>;
+    listObjects(input: ListObjectsInput): Promise<ListObjectsResult>;
+    deleteObject(key: string): Promise<void>;
+    /** Null when the key does not exist (404 / 403-as-absent). */
+    headObject(key: string): Promise<HeadObjectResult | null>;
+    /**
+     * Optional batch pre-mint. Warms an internal URL cache for `keys` under `op`
+     * so subsequent per-key get/head (and, when primed, put/delete) calls reuse a
+     * pre-signed URL instead of issuing one presign request each. This is what
+     * turns an N-file sync from N presign calls into ceil(N/chunk) — the
+     * difference between staying under and blowing past the 100-req/hr limit on a
+     * bulk pull. The S3 SDK transport has no presign step and omits this (the
+     * per-call cost there is the SDK request itself, not a separate presign).
+     * Best-effort: a failed chunk or per-key denial simply leaves those keys
+     * uncached, and the per-key call falls back to a single presign.
+     */
+    prime?(op: PresignOp, keys: PresignKeyInput[]): Promise<void>;
+    /**
+     * True if a live primed PUT URL exists for `key`. Lets uploadFile/uploadSymlink
+     * skip recomputing metadata + the created-at HEAD when a `prime("put", …)`
+     * pre-pass already signed the metadata into the cached URL (the upload just
+     * sends the body, replaying the cached headers). Absent (undefined) on the S3
+     * SDK transport → callers take their normal compute-metadata path.
+     */
+    hasPrimedPut?(key: string): boolean;
+}
+/**
+ * Direct-to-S3 transport over STS-vended credentials. A fresh client per
+ * instance so the latest credentials from the EntityContext are always used
+ * (caching/refresh is the caller's concern, at the EntityContext level — see
+ * the original buildClient note in s3.ts).
+ */
+export declare class S3SdkObjectIO implements ObjectIO {
+    private readonly client;
+    private readonly bucket;
+    constructor(ctx: EntityContext);
+    putObject(input: PutObjectInput): Promise<{
+        etag: string;
+    }>;
+    getObject(key: string): Promise<GetObjectResult>;
+    listObjects(input: ListObjectsInput): Promise<ListObjectsResult>;
+    deleteObject(key: string): Promise<void>;
+    headObject(key: string): Promise<HeadObjectResult | null>;
+}
+/**
+ * Thrown when a presign mint is skipped because the per-user 100/hr vault rate
+ * budget is exhausted. Distinct name so callers can tell "deferred, retry next
+ * sync" apart from a real transfer failure. The key was NOT synced.
+ */
+export declare class RateLimitedError extends Error {
+    readonly key: string;
+    readonly op: PresignOp;
+    constructor(key: string, op: PresignOp, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * One-way circuit breaker shared across a run's per-company transports. The
+ * first 429 (vault rate budget exhausted) trips it; thereafter every UNCACHED
+ * presign fails fast with {@link RateLimitedError} instead of hitting the wire.
+ *
+ * Without this, an exhausted budget spirals: prime chunks 429 → keys uncached
+ * → per-file presign → each 429s (after VaultClient's own 3 retries +
+ * backoff) → an 86-minute storm of ~10k doomed calls (observed live). Tripping
+ * once and short-circuiting turns that into a clean fast finish: primed URLs
+ * still work, un-primed keys are deferred, and the run reports them so the next
+ * sync (after the rolling hour recovers) picks them up.
+ */
+export declare class RateLimitBreaker {
+    private tripped;
+    isTripped(): boolean;
+    trip(): void;
+}
+/**
+ * Transport that moves bytes over short-lived presigned URLs minted by the
+ * vault-service. Holds no AWS credentials. `companyUid` is the EntityContext's
+ * `uid` — the server resolves the per-company bucket from it, so cross-company
+ * reach is structurally impossible (same authority model as the list/presign
+ * handlers).
+ *
+ * URL cache: {@link prime} batch-mints URLs into `urlCache` (keyed by op+key)
+ * so the per-file get/head calls during a sync reuse them instead of issuing a
+ * presign request each. A single instance is shared across all s3.ts calls for
+ * one company within a run (see {@link presignObjectIOFactory} memoization), so
+ * a prime before the transfer loop warms the cache the loop then drains.
+ */
+export declare class PresignObjectIO implements ObjectIO {
+    private readonly vault;
+    private readonly companyUid;
+    private readonly breaker;
+    private readonly urlCache;
+    constructor(vault: PresignTransportClient, companyUid: string, breaker?: RateLimitBreaker);
+    private cacheKey;
+    hasPrimedPut(key: string): boolean;
+    /** A live (non-expiring) cached URL for op+key, or undefined. */
+    private cached;
+    /**
+     * Resolve a presigned URL (+ replay headers) for op+key: cache hit if primed,
+     * else a single presign. Throws on per-key denial (matches the SDK path's
+     * access error). `extra` carries PUT contentType/metadata on the miss path.
+     */
+    private resolveUrl;
+    prime(op: PresignOp, keys: PresignKeyInput[]): Promise<void>;
+    putObject(input: PutObjectInput): Promise<{
+        etag: string;
+    }>;
+    getObject(key: string): Promise<GetObjectResult>;
+    listObjects(input: ListObjectsInput): Promise<ListObjectsResult>;
+    deleteObject(key: string): Promise<void>;
+    headObject(key: string): Promise<HeadObjectResult | null>;
+}
+export type ObjectIOFactory = (ctx: EntityContext) => ObjectIO;
+/**
+ * Install the transport factory for the current process. Passing `null`
+ * resets to the default S3 SDK transport. Called once by `runRunner` after it
+ * resolves the caller's identity + feature-flag gate; every subsequent s3.ts
+ * call resolves its transport through this.
+ */
+export declare function setObjectIOFactory(factory: ObjectIOFactory | null): void;
+/** Resolve the transport for an EntityContext using the active factory. */
+export declare function resolveObjectIO(ctx: EntityContext): ObjectIO;
+/**
+ * Build a factory that routes every EntityContext through the presigned-URL
+ * transport, reusing the one already-authenticated VaultClient and deriving
+ * the per-company authority from `ctx.uid`.
+ */
+export declare function presignObjectIOFactory(vault: PresignTransportClient): ObjectIOFactory;
+//# sourceMappingURL=object-io.d.ts.map

package/dist/object-io.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"object-io.d.ts","sourceRoot":"","sources":["../src/object-io.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAUH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EACV,SAAS,EACT,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAG3B;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,KAAK,EAAE;QACb,UAAU,EAAE,MAAM,CAAC;QACnB,EAAE,CAAC,EAAE,SAAS,CAAC;QACf,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,IAAI,EAAE,eAAe,EAAE,CAAC;KACzB,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,gBAAgB,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChE,SAAS,CACP,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,EACf,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC;QACT,OAAO,EAAE,iBAAiB,EAAE,CAAC;QAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,SAAS,EAAE,OAAO,CAAC;KACpB,CAAC,CAAC;CACJ;AAMD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,gFAAgF;IAChF,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,IAAI,CAAC;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACjD,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACjE,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC,8DAA8D;IAC9D,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAC;IAC1D;;;;;;;;;;OAUG;IACH,KAAK,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D;;;;;;OAMG;IACH,YAAY,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACrC;AAqBD;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,QAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,GAAG,EAAE,aAAa;IAYxB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAe3D,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAWhD,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAwBhE,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;CAuBhE;AA6ED;;;;GAIG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAEvC,QAAQ,CAAC,GAAG,EAAE,MAAM;IACpB,QAAQ,CAAC,EAAE,EAAE,SAAS;gBADb,GAAG,EAAE,MAAM,EACX,EAAE,EAAE,SAAS,EACtB,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAQhC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,OAAO,CAAS;IACxB,SAAS,IAAI,OAAO;IAGpB,IAAI,IAAI,IAAI;CAGb;AAOD;;;;;;;;;;;;GAYG;AACH,qBAAa,eAAgB,YAAW,QAAQ;IAI5C,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAG3B,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;gBAGvC,KAAK,EAAE,sBAAsB,EAC7B,UAAU,EAAE,MAAM,EAGlB,OAAO,GAAE,gBAAyC;IAGrE,OAAO,CAAC,QAAQ;IAIhB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIlC,iEAAiE;IACjE,OAAO,CAAC,MAAM;IAUd;;;;OAIG;YACW,UAAU;IA4BlB,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,eAAe,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAgD5D,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IAwB3D,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAehD,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAiBhE,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAaxC,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;CAwDhE;AA0FD,MAAM,MAAM,eAAe,GAAG,CAAC,GAAG,EAAE,aAAa,KAAK,QAAQ,CAAC;AAM/D;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAExE;AAED,2EAA2E;AAC3E,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,GAAG,QAAQ,CAE5D;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,sBAAsB,GAC5B,eAAe,CA4BjB"}