@pipelex/sdk 0.49.0 → 0.50.0

package/dist/upload-grant.d.ts

@@ -1,21 +1,93 @@
 /**
- * `uploadWithGrant` — send one file straight to Pipelex storage with an upload
- * grant (`PipelexApiClient.requestUploadGrant`, `POST /v1/upload/grant`). The
- * side that holds the credential requests the grant; the side that holds the
- * bytes, typically a browser page, sends them with this. See
+ * `describeUpload` and `uploadWithGrant` — the two halves of an upload grant
+ * (`PipelexApiClient.requestUploadGrant`, `POST /v1/upload/grant`) that the side
+ * holding the bytes runs, typically a browser page. That side describes the file,
+ * its SHA-256 included, with `describeUpload`; the side that holds the credential
+ * requests the grant for that description; and the bytes go to storage with
+ * `uploadWithGrant`, unless the grant says the organization already holds them. See
  * `docs/input-preparation.md`.
  *
  * **This module is the browser-safe entry, `@pipelex/sdk/upload`.** Its runtime
  * import graph must never reach a Node builtin, `undici` or the client: a page
  * bundles it as is, with nothing marked external. It imports the error classes,
- * the timer bound in `timers.ts` and the wire types only, and
- * `tests/upload-grant.test.ts` bundles it for the browser with esbuild to hold it
- * to that.
+ * the timer bound in `timers.ts` and the wire types only, hashes with Web Crypto,
+ * and `tests/upload-grant.test.ts` bundles it for the browser with esbuild to hold
+ * it to that.
  */
 import type { UploadGrant } from "./product-models.js";
-export type { UploadGrant, UploadGrantInput } from "./product-models.js";
+export type { UploadGrant, UploadGrantInput, UploadKind } from "./product-models.js";
 export { InputPreparationError, RejectedAssetError, UploadTransportError } from "./errors.js";
 export type { RejectedAssetCode, UploadTransportCode } from "./errors.js";
+/** Per-call options for {@link describeUpload}. */
+export interface DescribeUploadOptions {
+    /** The file's name, replacing a `File`'s own; required for a nameless `Blob`. */
+    filename?: string;
+    /**
+     * The largest file to hash, in bytes, 52428800 (50 MiB, the platform's default limit on
+     * one upload) when omitted. Hashing reads the whole file into memory, so a larger file
+     * is described without its SHA-256 and never read. Where the deployment's limit is no
+     * larger, its grant request then meets the grant route's own `413`. On a deployment
+     * whose grants report a larger `max_bytes`, a file between the two is granted without
+     * a hash: it is uploaded under a fresh name, with no deduplication and no checksum for
+     * storage to hold the body to, and the description's absent `sha256` is how a caller
+     * sees it. Pass that `max_bytes` to hash up to it. It must be a positive number.
+     */
+    maxBytes?: number;
+}
+/**
+ * A file described for `requestUploadGrant`, as {@link describeUpload} reads it: every
+ * field the grant request takes to describe a file, ready to send as is.
+ */
+export interface UploadDescription {
+    /** The file's name: the `File`'s own, or the `filename` option for a nameless `Blob`. */
+    filename: string;
+    /** The type the runtime gives the file, `Blob.type`: empty when it knows none. */
+    content_type: string;
+    /** The file's exact size in bytes. */
+    size: number;
+    /**
+     * The SHA-256 of the file's bytes, 64 lowercase hexadecimal digits. Absent in two
+     * cases, where the grant then names a new object and asks for the bytes, as it does
+     * for every request with no hash: where the runtime offers no Web Crypto digest, which
+     * a browser withholds from a page served over plain `http` from any host but the local
+     * one, and for a file larger than `describeUpload`'s `maxBytes`, which is never read.
+     * The grant route refuses such a file's size with its own `413` only where the
+     * deployment's limit is no larger than `maxBytes`; under a larger limit the file is
+     * granted and uploaded without its hash, so without deduplication.
+     */
+    sha256?: string;
+}
+/**
+ * Describe a file for `requestUploadGrant`: its name, its type, its size and the
+ * SHA-256 of its bytes, computed with Web Crypto. A grant asked for with the hash
+ * names the object after the bytes, so a file the organization already holds is
+ * answered `stored: true` and never sent again, and storage refuses a body whose
+ * bytes differ from the ones described.
+ *
+ * The side holding the bytes runs this, so a page describes the file and hands the
+ * description to the server that holds the key, which passes it to
+ * `requestUploadGrant` unchanged; the bytes never cross that server. A nameless
+ * `Blob` takes its name from `options.filename`, which also replaces a `File`'s own.
+ *
+ * The whole file is read into memory once to hash it, so only a file no larger than
+ * `options.maxBytes` is, 50 MiB by default: a larger one, such as a video of several
+ * gigabytes picked by mistake, would freeze or crash a browser tab before the grant
+ * route could refuse its size. It is described without `sha256` and never read. Where
+ * the deployment's limit is no larger than `maxBytes`, as with the default on a
+ * deployment at the platform's default limit, the grant route's `413` refuses it with its
+ * own message. On a deployment whose grants report a larger `max_bytes`, a file between
+ * the two is granted without the hash and uploaded under a fresh name, with no
+ * deduplication and no checksum for storage to hold the body to: the absent `sha256` on
+ * the description is how the caller sees it, and passing that `max_bytes` as `maxBytes`
+ * hashes up to it. Where the runtime offers no Web
+ * Crypto digest, the file is described without `sha256` too, and the upload goes on
+ * without the hash.
+ *
+ * A file that cannot be read, such as one changed on disk since it was picked, throws an
+ * `InputPreparationError` whose `cause` is the runtime's error; a file with no name and a
+ * `maxBytes` that is not a positive number throw one before anything is read.
+ */
+export declare function describeUpload(file: Blob, options?: DescribeUploadOptions): Promise<UploadDescription>;
 /** Per-call options for {@link uploadWithGrant}. */
 export interface UploadWithGrantOptions {
     /**
@@ -33,56 +105,78 @@ export interface UploadWithGrantOptions {
      */
     timeoutMs?: number;
 }
-/** What a successful {@link uploadWithGrant} stored. */
+/** What a successful {@link uploadWithGrant} leaves in storage. */
 export interface GrantedUpload {
-    /** The grant's `pipelex-storage://` reference, which now names the stored object. */
+    /** The grant's `pipelex-storage://` reference, which now names the stored file. */
     uri: string;
+    /**
+     * The file's record, the grant's `file_id`. Absent when the grant carried none, as from a
+     * deployment that predates file records.
+     */
+    file_id?: string;
 }
 /**
- * `PUT` a file to storage with an upload grant, and return the reference it now
- * carries. The file goes as the raw body with the grant's signed headers
- * unchanged; the body sets `Content-Length`, which the grant signed, so the file
- * must be exactly the size the grant was requested for.
+ * Store a file with an upload grant, and return the reference it now carries.
+ *
+ * **A grant that says `stored: true` sends nothing**: the organization already holds
+ * these bytes, so the call returns the grant's `uri` and `file_id` at once, without
+ * reading the file or reaching storage. Otherwise the file goes to the grant's `url` as
+ * the raw body of a `PUT`, with the grant's signed headers unchanged; the body sets
+ * `Content-Length`, which the grant signed, so the file must be exactly the size the
+ * grant was requested for, and when the grant was requested with the file's SHA-256,
+ * storage holds the body to it.
+ *
+ * Two answers from storage are no failure. A `412` refuses the create-only `PUT`
+ * because the object already exists: when the grant names the file by its bytes (it
+ * signs `x-amz-checksum-sha256`), that object can only hold those bytes, stored
+ * meanwhile by another upload of them or by the platform's own copy of a run's file
+ * that holds them, so the call succeeds with the grant's `uri` and `file_id`, the answer
+ * a `stored: true` grant gives. A `409 ConditionalRequestConflict`
+ * says another write of the object was in flight, so the `PUT` is sent again after a
+ * short pause, a few times at most.
  *
  * Storage's refusals map onto the input-preparation errors, so a caller that
  * already handles `uploadFile` needs no new case:
  *
- * - `RejectedAssetError` (`status` is storage's, `code` says why) — a `412` when
- *   the grant was already used (`grant_used`: a grant writes one object, once); a
- *   `403` when the file's size, type or metadata differ from what the grant signed
- *   (`signature_mismatch`), when the request carried a header the grant did not sign
- *   (`unsigned_header`), or when the grant has expired (`grant_expired`); any other
- *   `4xx` but a `408` or a `429` (`store_refused`). Each asks for a new grant, or for
- *   the file the grant was requested for.
+ * - `RejectedAssetError` (`status` is storage's, `code` says why) — a `412` for a
+ *   grant that names no bytes, when the grant was already used (`grant_used`: such a
+ *   grant writes one object, once); a `403` when the file's size, type or metadata
+ *   differ from what the grant signed (`signature_mismatch`), when the request carried
+ *   a header the grant did not sign (`unsigned_header`), or when the grant has expired
+ *   (`grant_expired`); any other `4xx` but a `408` or a `429` (`store_refused`), a
+ *   `400 BadDigest` among them, for bytes other than the ones whose SHA-256 the grant
+ *   was requested with. Each asks for a new grant, or for the file the grant was
+ *   requested for.
  * - `UploadTransportError` (`status` is storage's when it answered, `code` says
  *   which) — the time limit running out (`timeout`), storage unreachable
  *   (`unreachable`), a `5xx` (`server_error`), storage timing out on the body
- *   (`storage_timeout`, a `400 RequestTimeout`, which wrote nothing), another upload
- *   with the same grant still in progress (`conflict`, a `409
+ *   (`storage_timeout`, a `400 RequestTimeout`, which wrote nothing), another write of
+ *   the object still in progress after every attempt (`conflict`, a `409
  *   ConditionalRequestConflict`), storage timing out or throttling the request
  *   (`unexpected`, a `408` or a `429`, refused for its timing rather than for the
  *   file), or a redirect, which is refused rather than followed (`redirected`). In a
  *   browser a refused cross-origin request looks like an unreachable host, so the
- *   message names that too. A grant whose `url` is not an absolute `http(s)` URL free
- *   of user info is refused the same way, before anything is sent
- *   (`invalid_grant_url`).
+ *   message names that too. A grant that is not stored and whose `url` is not an
+ *   absolute `http(s)` URL free of user info is refused the same way, before anything
+ *   is sent (`invalid_grant_url`).
  *
- * The whole exchange runs under a time limit: `timeoutMs` when given, else 60 s plus
- * 1 s for every started 128 KiB of the file. A caller's `signal` can end it sooner,
- * and its abort propagates as the signal's own reason, unwrapped, even when the time
- * limit ran out too. Only the first 16 KiB of storage's error body are read, and when
- * the limit runs out while that body is still arriving, storage has already answered:
- * the call settles as that answer, classified from its status and whatever part of the
- * body arrived.
+ * The whole exchange runs under a time limit, the pauses after a conflict included:
+ * `timeoutMs` when given, else 60 s plus 1 s for every started 128 KiB of the file. A
+ * caller's `signal` can end it sooner, and its abort propagates as the signal's own
+ * reason, unwrapped, even when the time limit ran out too. Only the first 16 KiB of
+ * storage's error body are read, and when the limit runs out while that body is still
+ * arriving, or during the pause after a conflict, storage has already answered: the
+ * call settles as that answer, classified from its status and whatever part of the body
+ * arrived.
  *
  * A timeout, a `5xx`, a conflict and a connection lost after the file went out leave
  * it unknown whether the object was written: retrying with the same grant before it
- * expires either stores it or answers the `412` of a used grant, and then the
- * grant's `uri` already names the file. After a `408` or a `429` the same retry
- * applies, later, since storage refused the request for its timing. A `501` is the
- * exception: storage does not implement the request it was sent, stored nothing, and
- * answers a retry the same way, so its error is not retryable. The grant is a bearer
- * capability: nothing here logs it, and no error this throws carries its URL,
- * storage's error body or a runtime error that could hold either.
+ * expires either stores it or finds it stored, and then the grant's `uri` names the
+ * file. After a `408` or a `429` the same retry applies, later, since storage refused
+ * the request for its timing. A `501` is the exception: storage does not implement the
+ * request it was sent, stored nothing, and answers a retry the same way, so its error
+ * is not retryable. The grant is a bearer capability: nothing here logs it, and no
+ * error this throws carries its URL, storage's error body or a runtime error that
+ * could hold either.
  */
 export declare function uploadWithGrant(grant: UploadGrant, file: Blob, options?: UploadWithGrantOptions): Promise<GrantedUpload>;