@smthrs/artifacts 0.0.0-stage → 1.0.0-rc.12

package/dist/esm/RemoteArtifacts.d.ts

@@ -0,0 +1,237 @@
+/**
+ * The shared artifact tier: an {@link ArtifactStore.Service} spoken over HTTP.
+ *
+ * The wire protocol mirrors Bazel's dumb-HTTP remote cache, class
+ * `HttpCacheClient` in `com.google.devtools.build.lib.remote.http`, which
+ * documents it as: "CAS (Content Addressable Storage) blobs are stored under
+ * the path `/cas/base16-key`", uploaded with `PUT`, downloaded with `GET`. We add
+ * `HEAD /cas/{digest}` for a single existence probe and
+ * `POST /cas/findMissing` for the batched one, because Bazel's HTTP client has
+ * no `findMissingDigests` at all — it answers "everything is missing" and
+ * re-uploads — and a batched probe is the whole reason
+ * `MissingDigestsFinder` exists in the gRPC client.
+ *
+ * Transport is Effect's own `HttpClient` tag. There is no lower transport in
+ * this repository, and there does not need to be one: the kernel already
+ * decorates that tag with `net:get`/`net:post` capability checks, so a remote
+ * artifact fetch is permission-checked like every other egress.
+ *
+ * ## Chunked uploads
+ *
+ * With `chunkBytes` set, a blob past that size travels as a sequence of
+ * `PUT /cas/{digest}` requests carrying `Content-Range: bytes {a}-{b}/{total}`,
+ * preceded by a `HEAD /cas/{digest}` existence probe and a
+ * `Content-Range: bytes *\/{total}` probe with an empty body. This is the
+ * resumable-upload shape HTTP already has: the range probe asks what prefix
+ * the tier holds and `308` means "keep going", with a `Range: bytes=0-{last}`
+ * header on the probe or on a chunk answer moving the offset.
+ *
+ * Only a `308` continues the sequence, and the completing chunk's `2xx` is
+ * confirmed with `HEAD` before `put` reports the digest as published. A `2xx`
+ * anywhere else, to the empty probe or to a chunk the tier is still owed bytes
+ * after, reads as a tier that ignored `Content-Range` and stored the body it
+ * was handed, which is what plain WebDAV `PUT` does. That tier, the one that
+ * answers `400`, `411`, or `416`, and the one whose `HEAD` will not confirm
+ * the stored length all get the same treatment: one whole-blob `PUT`, which
+ * overwrites the partial body the sequence left behind. So the blob always
+ * lands whole, and the cost of turning the dial on against a server that
+ * never learned about it is round trips, never a digest published over bytes
+ * the server does not hold.
+ *
+ * This repository's own hosted and self-hosted cache services are such
+ * servers: neither implements the resumable sequence, and both refuse a
+ * ranged `PUT` with `400`, RFC 9110 section 14.5's answer from a resource
+ * that does not support partial `PUT`. Against them `chunkBytes` costs the
+ * probe round trip and the blob travels whole, and both cap one request body
+ * at 16 MiB, so a blob past that cap is refused with `413` in either mode.
+ *
+ * The endpoint and its credentials arrive as **layer construction options**.
+ * They are capabilities, never step inputs: they are not hashed into a step
+ * key, journaled, or returned in a recorded result. Invalid endpoint errors are
+ * sanitized before they cross the boundary.
+ *
+ * @since 1.0.0-rc.0
+ */
+import * as Duration from "effect/Duration";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as ArtifactStore from "./ArtifactStore.ts";
+/**
+ * How eagerly a composition materializes shared blobs into its local store.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const DownloadPolicy: Schema.Literals<readonly ["all", "toplevel", "minimal"]>;
+/**
+ * How eagerly a composition materializes remote blobs.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export type DownloadPolicy = typeof DownloadPolicy.Type;
+/**
+ * Every download policy, in materialization order.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export declare const downloadPolicies: ReadonlyArray<DownloadPolicy>;
+/**
+ * A remote artifact tier, which is an ordinary store that also states how
+ * eagerly a composition reading through it should materialize blobs locally.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ */
+export interface Service extends ArtifactStore.Service {
+    readonly downloadPolicy: DownloadPolicy;
+}
+/**
+ * Reads the download policy a store declares, or `undefined` for a store that
+ * declares none — every local store, and any foreign implementation.
+ *
+ * @category getters
+ * @since 1.0.0-rc.0
+ */
+export declare const downloadPolicyOf: (store: ArtifactStore.Service) => DownloadPolicy | undefined;
+/**
+ * How to reach the shared artifact tier.
+ *
+ * @category models
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export interface Options {
+    /**
+     * The cache root, e.g. `https://cache.example.com`. `/cas/{digest}` and
+     * `/cas/findMissing` are resolved beneath it. A trailing slash is ignored.
+     *
+     * Four shapes are refused at construction as `invalid_configuration`, before
+     * any request leaves and therefore before `headers` can reach a wire: a value
+     * that is not a string, one no `URL` parser accepts, a scheme other than
+     * `https:` (plain `http:` is accepted only for the literal loopback hosts
+     * `localhost`, `127.0.0.1`, and `[::1]`), and an endpoint carrying
+     * userinfo, a query, or a fragment. The
+     * last rule keeps a credential out of a place nothing here would redact: an
+     * endpoint is interpolated into every request path and into span attributes.
+     *
+     * The refusal message names only the violated rule and never echoes the
+     * endpoint, so a rejected `https://user:secret@host` cannot leak its
+     * credential into a log line or a durable error.
+     */
+    readonly endpoint: string;
+    /**
+     * Headers sent with every request — an `Authorization` bearer token, a
+     * tenant header, whatever the deployment's gateway wants. This is the
+     * credential seam, and it is deliberately construction-time: a credential
+     * that arrived as a step input would be hashed into a step key and persisted
+     * everywhere the journal goes.
+     *
+     * The protocol wins every collision. These headers are applied to a request
+     * first. Configured `content-type`, `content-length`, and `content-range`
+     * are removed, then computed only where the protocol needs them. Whole-blob
+     * uploads, including fallbacks, never carry `content-range`.
+     * All configured header names are redacted in HTTP spans, in addition to
+     * the host's existing redaction rules.
+     *
+     * A name that is not an HTTP token, or a value longer than 16 KiB or
+     * carrying a control character (CR and LF included), is refused at
+     * construction as `invalid_configuration`.
+     */
+    readonly headers?: Record<string, string> | undefined;
+    /**
+     * The deadline on a single download, from the request leaving to the last
+     * body byte arriving. A shared tier that stops answering must fail the read
+     * rather than park it forever. `CombinedArtifacts.get` propagates a remote
+     * `ArtifactStoreError`, including a download timeout. Only opportunistic
+     * uploads from `CombinedArtifacts.put` ignore remote failures;
+     * `ArtifactSync.hydrate` separately turns a failure into replay rejection.
+     * Defaults to 60 seconds, Bazel's `--remote_timeout`
+     * default for the same REST protocol (its `RemoteOptions`: "For the REST
+     * cache, this is both the connect and the read timeout").
+     */
+    readonly downloadTimeout?: Duration.Input | undefined;
+    /**
+     * Deadline for an upload, including every resume probe and chunk. Defaults
+     * to 60 seconds.
+     */
+    readonly uploadTimeout?: Duration.Input | undefined;
+    /**
+     * Deadline for an existence probe or one `findMissing` batch, including its
+     * response body. Defaults to 60 seconds.
+     */
+    readonly requestTimeout?: Duration.Input | undefined;
+    /**
+     * The largest download this client will buffer, in bytes. The body is read
+     * incrementally and abandoned the moment it exceeds the bound — and refused
+     * outright when `Content-Length` already declares the excess — so a
+     * mis-serving or hostile cache cannot make this process buffer and hash an
+     * arbitrarily large body before the digest check refuses it. Defaults to
+     * 256 MiB.
+     */
+    readonly maxDownloadBytes?: number | undefined;
+    /**
+     * Largest `findMissing` response body accepted. Defaults to the protocol's
+     * 256 KiB request/response bound and may only lower that bound.
+     */
+    readonly maxFindMissingResponseBytes?: number | undefined;
+    /**
+     * Above this many bytes an upload travels as a sequence of `Content-Range`
+     * `PUT`s instead of one whole-blob body, and a transfer that died partway
+     * resumes from the prefix the tier kept rather than starting over. See
+     * {@link module:RemoteArtifacts | the chunked upload protocol} below.
+     *
+     * Absent by default: every upload is one whole-blob `PUT`, which is what
+     * Bazel's dumb-HTTP client does and what every deployment already serving
+     * this protocol expects. Set it when a proxy caps request bodies, or when
+     * artifacts are large enough that losing a transfer is expensive.
+     *
+     * The repository's own hosted and self-hosted cache services answer the
+     * ranged probe with `400`, so against them this dial degrades to one
+     * whole-blob `PUT`, and their 16 MiB body cap refuses a larger blob with
+     * `413` in either mode.
+     */
+    readonly chunkBytes?: number | undefined;
+    /**
+     * How eagerly a composition reading through this tier materializes blobs
+     * into its local store. This is Bazel's `--remote_download_{all,toplevel,
+     * minimal}` dial (`RemoteOutputChecker`), and it lives here because the
+     * shared tier is the thing being conserved.
+     *
+     * - `all` (the default) prefetches every referenced blob when a replay is
+     *   admitted, so the replay reads local bytes.
+     * - `toplevel` prefetches nothing and materializes a blob into the local
+     *   store on the first read that actually needs it.
+     * - `minimal` prefetches nothing and materializes nothing: a read is served
+     *   straight from the shared tier and the local store never grows.
+     *
+     * `CombinedArtifacts.get` honors the last two; `@smthrs/engine-store`'s
+     * `ArtifactSync.hydrate` honors the first.
+     */
+    readonly downloadPolicy?: DownloadPolicy | undefined;
+}
+/**
+ * Builds a remote artifact store over Effect's `HttpClient`.
+ *
+ * @category constructors
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const make: (options: Options) => Effect.Effect<Service, ArtifactStore.ArtifactStoreError, HttpClient.HttpClient>;
+/**
+ * Provides a remote artifact store as the `ArtifactStore` tag.
+ *
+ * Composing this *alone* makes every artifact read and write a network round
+ * trip. The intended production shape is
+ * {@link CombinedArtifacts.layer | CombinedArtifacts}, with this as its remote
+ * tier.
+ *
+ * @category layers
+ * @since 1.0.0-rc.0
+ * @slop
+ */
+export declare const layer: (options: Options) => Layer.Layer<ArtifactStore.ArtifactStore, ArtifactStore.ArtifactStoreError, HttpClient.HttpClient>;
+//# sourceMappingURL=RemoteArtifacts.d.ts.map

package/dist/esm/RemoteArtifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RemoteArtifacts.d.ts","sourceRoot":"","sources":["../../src/RemoteArtifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,KAAK,QAAQ,MAAM,iBAAiB,CAAA;AAC3C,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAGvC,OAAO,KAAK,UAAU,MAAM,wBAAwB,CAAA;AAGpD,OAAO,KAAK,KAAK,MAAM,cAAc,CAAA;AAErC,OAAO,KAAK,MAAM,MAAM,eAAe,CAAA;AAEvC,OAAO,KAAK,aAAa,MAAM,oBAAoB,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,cAAc,0DAA2D,CAAA;AAEtF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC,IAAI,CAAA;AAEvD;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,aAAa,CAAC,cAAc,CAAiD,CAAA;AAE5G;;;;;;GAMG;AACH,MAAM,WAAW,OAAQ,SAAQ,aAAa,CAAC,OAAO;IACpD,QAAQ,CAAC,cAAc,EAAE,cAAc,CAAA;CACxC;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,aAAa,CAAC,OAAO,KAAG,cAAc,GAAG,SAGhF,CAAA;AAED;;;;;;GAMG;AACH,MAAM,WAAW,OAAO;IACtB;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAA;IACrD;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;IACrD;;;OAGG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;IACnD;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,QAAQ,CAAC,KAAK,GAAG,SAAS,CAAA;IACpD;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC9C;;;OAGG;IACH,QAAQ,CAAC,2BAA2B,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACzD;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACxC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,cAAc,GAAG,SAAS,CAAA;CACrD;AA4FD;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,GACf,SAAS,OAAO,KACf,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,kBAAkB,EAAE,UAAU,CAAC,UAAU,CAid7E,CAAA;AAEJ;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,KAAK,GAChB,SAAS,OAAO,KACf,KAAK,CAAC,KAAK,CAAC,aAAa,CAAC,aAAa,EAAE,aAAa,CAAC,kBAAkB,EAAE,UAAU,CAAC,UAAU,CACzC,CAAA"}