@interop/was-client 0.35.1 → 0.37.0

package/dist/internal/write.js

@@ -1,3 +1,4 @@
+import { isChunkedWrite } from '../codec.js';
 import { PreconditionFailedError, ValidationError } from '../errors.js';
 import { send } from './request.js';
 import { encodedPrecondition, writeHeaders } from './conditional.js';
@@ -31,11 +32,47 @@ export async function sendEncodedWrite(context, { path, method, encoded, capabil
     });
     return response;
 }
+/**
+ * Builds the {@link CodecRequestContext} core hands a codec that drives its own
+ * I/O: the signed-request primitive bound to this handle's capability, plus the
+ * handle's memoized backend-feature probe. The codec never sees the zcap
+ * machinery, and the raw `HttpResponse` it gets back matches the
+ * `was.request()` escape hatch, which is what `WasTransport` consumes.
+ *
+ * Requests go through the same mapped `send` path the core write paths use, so
+ * a codec-driven write fails with the typed `WasError` subclasses the calling
+ * method documents (a document `PUT` that 404s is a `NotFoundError`, not a raw
+ * ky/ezcap error). The typed errors carry the HTTP `status`, so a consumer that
+ * dispatches on status keeps working.
+ *
+ * @param context {ClientContext}
+ * @param options {object}
+ * @param options.features {FeatureProbe}   the handle's memoized backend-feature
+ *   probe
+ * @param [options.capability] {IZcap}     capability attached to each request
+ * @returns {CodecRequestContext}
+ */
+export function codecRequestContext(context, { features, capability }) {
+    return {
+        async request(input) {
+            // `send` only resolves `null` for the `read`/`idempotent` flags, which
+            // this surface never sets, so the response is always present.
+            const response = await send(context, { capability, ...input });
+            return response;
+        },
+        features
+    };
+}
 /**
  * Creates a resource with a codec-minted or server-minted id (insert) through
  * its codec, owning the create orchestration in one place: the encode, the
  * `PUT`-vs-`POST` branch, and the precondition selection.
  *
+ * A codec may also answer the encode with a multi-request plan (the EDV codec's
+ * chunked blob write). The plan is then executed over the handle's signed
+ * request context instead of being sent as one request; it owns its own
+ * preconditions and feature gating.
+ *
  * A codec that mints its own id (e.g. the encrypting codec's EDV id) writes it
  * by `PUT` to that id's path; a codec that mints none (the identity codec)
  * `POST`s to the items path and lets the server mint one. As in
@@ -55,14 +92,28 @@ export async function sendEncodedWrite(context, { path, method, encoded, capabil
  *   codec-minted id
  * @param options.codec {ResourceCodec}    the collection's resolved codec
  * @param options.data {ResourceData}      the plaintext value
+ * @param options.features {FeatureProbe}   the handle's shared backend-feature
+ *   probe, handed to a codec's multi-request plan so its affordance gate costs
+ *   no extra round trip
  * @param [options.contentType] {string}   caller-supplied content type
  * @param [options.capability] {IZcap}
  * @param [options.precondition] {WritePrecondition}   the caller's explicit
  *   precondition (used only for a non-conditional codec)
- * @returns {Promise<{ encoded: EncodedWrite; path: string; response: HttpResponse }>}
+ * @returns {Promise<InsertOutcome>}
  */
-export async function insertResource(context, { itemsPath, pathForId, codec, data, contentType, capability, precondition }) {
-    const encoded = await codec.encode({ data, contentType });
+export async function insertResource(context, { itemsPath, pathForId, codec, data, features, contentType, capability, precondition }) {
+    const write = await codec.encode({ data, contentType });
+    if (isChunkedWrite(write)) {
+        const { id, etag } = await write.execute(codecRequestContext(context, { features, capability }));
+        return {
+            chunked: true,
+            id,
+            path: pathForId(id),
+            contentType: write.resourceContentType,
+            ...(etag !== undefined && { etag })
+        };
+    }
+    const encoded = write;
     const chosen = codec.conditionalWrites
         ? encodedPrecondition(encoded)
         : precondition;
@@ -104,9 +155,9 @@ export async function insertResource(context, { itemsPath, pathForId, codec, dat
  * @param options.codec {ResourceCodec}          the collection's resolved codec
  * @param options.id {string}                    the resource id
  * @param options.data {ResourceData}            the plaintext value
- * @param options.features {function}            resolves the backend's
- *   advertised feature tokens (the handle's shared `BackendFeatures` probe);
- *   consulted only for a conditional codec's insert-after-null-pre-read
+ * @param options.features {FeatureProbe}         the handle's shared
+ *   `BackendFeatures` probe; consulted only for a conditional codec's
+ *   insert-after-null-pre-read
  * @param [options.contentType] {string}         caller-supplied content type
  * @param [options.capability] {IZcap}
  * @param [options.precondition] {WritePrecondition}   the caller's explicit
@@ -122,8 +173,7 @@ export async function upsertResource(context, { path, codec, id, data, features,
             capability,
             read: true
         });
-        if (current === null &&
-            !(await features()).includes('conditional-writes')) {
+        if (current === null && !(await features.has('conditional-writes'))) {
             // The write would be encoded as a fresh insert guarded only by
             // `If-None-Match: *`, which this backend ignores -- so if the document in
             // fact exists but is unreadable with this capability (the masked-404
@@ -140,7 +190,19 @@ export async function upsertResource(context, { path, codec, id, data, features,
                 'descriptor, or add() to mint a fresh document id.');
         }
     }
-    const encoded = await codec.encode({ id, data, contentType, current });
+    const write = await codec.encode({ id, data, contentType, current });
+    if (isChunkedWrite(write)) {
+        // Auto-routing is an insert-path affordance: a write by id would have to
+        // reconcile the existing stored parts (and the codec's sequence) with the
+        // new payload, which this path does not do. Refuse instead of
+        // half-performing the update. The codec supplies the scheme-specific
+        // recovery advice; this layer knows nothing about how it stores things.
+        throw new ValidationError(`Cannot write this payload to "${path}": the collection's codec ` +
+            'answered with a multi-request write plan, which is only auto-routed ' +
+            'on the insert path (add()). Add it as a new resource' +
+            (write.guidance === undefined ? '.' : `. ${write.guidance}`));
+    }
+    const encoded = write;
     // A conditional codec computes the precondition itself (from the sequence /
     // ETag); a plaintext codec defers to the caller's explicit options.
     const chosen = codec.conditionalWrites

package/dist/internal/write.js.map

@@ -1 +1 @@
-{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/internal/write.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAGvE,OAAO,EAAE,IAAI,EAAE,MAAM,cAAc,CAAA;AACnC,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAA;AAGpE;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,OAAsB,EACtB,EACE,IAAI,EACJ,MAAM,EACN,OAAO,EACP,UAAU,EACV,YAAY,EAOb;IAED,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE;QACnC,IAAI;QACJ,MAAM;QACN,UAAU;QACV,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO,EAAE,YAAY,CAAC;YACpB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,YAAY;YACZ,KAAK,EAAE,OAAO,CAAC,KAAK;SACrB,CAAC;KACH,CAAC,CAAA;IACF,OAAO,QAAwB,CAAA;AACjC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAsB,EACtB,EACE,SAAS,EACT,SAAS,EACT,KAAK,EACL,IAAI,EACJ,WAAW,EACX,UAAU,EACV,YAAY,EASb;IAED,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAA;IACzD,MAAM,MAAM,GAAG,KAAK,CAAC,iBAAiB;QACpC,CAAC,CAAC,mBAAmB,CAAC,OAAO,CAAC;QAC9B,CAAC,CAAC,YAAY,CAAA;IAChB,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAA;IACzE,MAAM,QAAQ,GAAG,MAAM,gBAAgB,CAAC,OAAO,EAAE;QAC/C,IAAI;QACJ,MAAM,EAAE,OAAO,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM;QACjD,UAAU;QACV,OAAO;QACP,YAAY,EAAE,MAAM;KACrB,CAAC,CAAA;IACF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAA;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAsB,EACtB,EACE,IAAI,EACJ,KAAK,EACL,EAAE,EACF,IAAI,EACJ,QAAQ,EACR,WAAW,EACX,UAAU,EACV,YAAY,EAUb;IAED,IAAI,OAAwC,CAAA;IAC5C,IAAI,KAAK,CAAC,iBAAiB,EAAE,CAAC;QAC5B,OAAO,GAAG,MAAM,IAAI,CAAC,OAAO,EAAE;YAC5B,IAAI;YACJ,MAAM,EAAE,KAAK;YACb,UAAU;YACV,IAAI,EAAE,IAAI;SACX,CAAC,CAAA;QACF,IACE,OAAO,KAAK,IAAI;YAChB,CAAC,CAAC,MAAM,QAAQ,EAAE,CAAC,CAAC,QAAQ,CAAC,oBAAoB,CAAC,EAClD,CAAC;YACD,+DAA+D;YAC/D,0EAA0E;YAC1E,qEAAqE;YACrE,yEAAyE;YACzE,eAAe;YACf,MAAM,IAAI,eAAe,CACvB,kCAAkC,IAAI,4BAA4B;gBAChE,iEAAiE;gBACjE,+DAA+D;gBAC/D,iEAAiE;gBACjE,8DAA8D;gBAC9D,6DAA6D;gBAC7D,iEAAiE;gBACjE,gEAAgE;gBAChE,mDAAmD,CACtD,CAAA;QACH,CAAC;IACH,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,CAAA;IACtE,4EAA4E;IAC5E,oEAAoE;IACpE,MAAM,MAAM,GAAG,KAAK,CAAC,iBAAiB;QACpC,CAAC,CAAC,mBAAmB,CAAC,OAAO,CAAC;QAC9B,CAAC,CAAC,YAAY,CAAA;IAChB,IAAI,CAAC;QACH,OAAO,MAAM,gBAAgB,CAAC,OAAO,EAAE;YACrC,IAAI;YACJ,MAAM,EAAE,KAAK;YACb,UAAU;YACV,OAAO;YACP,YAAY,EAAE,MAAM;SACrB,CAAC,CAAA;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IACE,GAAG,YAAY,uBAAuB;YACtC,KAAK,CAAC,iBAAiB;YACvB,OAAO,KAAK,IAAI,EAChB,CAAC;YACD,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,GAAG,GAAG,CAAA;YACxD,MAAM,IAAI,uBAAuB,CAC/B,kCAAkC,IAAI,gCAAgC;gBACpE,0DAA0D;gBAC1D,kEAAkE;gBAClE,gEAAgE;gBAChE,+DAA+D;gBAC/D,WAAW,EACb,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,GAAG,EAAE,CACzD,CAAA;QACH,CAAC;QACD,MAAM,GAAG,CAAA;IACX,CAAC;AACH,CAAC"}
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../../src/internal/write.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@interop/was-client",
   "description": "A developer-friendly client for Wallet Attached Storage (WAS) servers.",
-  "version": "0.35.1",
+  "version": "0.37.0",
   "type": "module",
   "scripts": {
     "build": "pnpm run clear && tsc",