@interop/was-client 0.92.0 → 0.93.1

package/README.md

@@ -26,6 +26,7 @@
   - [Conditional writes (optimistic concurrency)](#conditional-writes-optimistic-concurrency)
   - [Storage introspection: backends and quotas](#storage-introspection-backends-and-quotas)
   - [Registering a Bring-Your-Own-Storage backend](#registering-a-bring-your-own-storage-backend)
+  - [Replica registration](#replica-registration)
   - [Encrypted collections (EDV-over-WAS): pass-through encryption via the WAS client (recommended)](#encrypted-collections-edv-over-was-pass-through-encryption-via-the-was-client-recommended)
   - [Cross-replica sync](#cross-replica-sync)
   - [Resource logs (co-managed key resources)](#resource-logs-co-managed-key-resources)
@@ -432,7 +433,12 @@ await collection.resource('vc-1').delete() // idempotent
 
 Writes detect the payload: a plain object/array is sent as JSON; a
 `Blob`/`Uint8Array`/`Buffer` is sent as binary, with the content-type taken from
-`options.contentType`, the `Blob.type`, or `application/octet-stream`.
+`options.contentType`, the `Blob.type`, or `application/octet-stream`. A
+`ReadableStream<Uint8Array>` is accepted only by an encrypted collection (see
+[Encrypted collections](#encrypted-collections-edv-over-was-pass-through-encryption-via-the-was-client-recommended)).
+A plaintext collection refuses it with `ValidationError`. A plaintext resource
+has no chunked representation, and a signed request carries a `Digest` of its
+whole body. Buffer the stream into a `Blob` there.
 
 ```ts
 // JSON
@@ -452,13 +458,17 @@ Reads auto-parse: `get()` returns a parsed object for a JSON content-type and a
 `Blob` otherwise; `getText()` / `getBytes()` are explicit escape hatches.
 `getWithEtag()` pairs the decoded value with its ETag validator, and
 `getWithEtag({ as: 'text' })` projects it to text (decrypting where `getText()`
-would not).
-
-A write value is a JSON object/array or binary (`Blob`/`Uint8Array`) -- the
-`ResourceData` type. A top-level JSON primitive (a bare `string`, `number`,
-`boolean`, or `null`) is **not** accepted; it is a compile-time error. To store
-one, either wrap it in an object (`put('greeting', { value: 'hello' })`) or
-write it as binary via a `Blob`:
+would not). `getStream()` resolves `{ stream, contentType?, etag? }`, or `null`
+on a miss. It runs the codec like `get()`, so it decrypts on an encrypted
+collection. A JSON body is re-serialized, so it is semantically identical JSON
+but not guaranteed byte-identical.
+
+A write value is a JSON object/array or binary (`Blob`/`Uint8Array`, or a
+`ReadableStream<Uint8Array>` on an encrypted collection) -- the `ResourceData`
+type. A top-level JSON primitive (a bare `string`, `number`, `boolean`, or
+`null`) is **not** accepted; it is a compile-time error. To store one, either
+wrap it in an object (`put('greeting', { value: 'hello' })`) or write it as
+binary via a `Blob`:
 
 ```ts
 await collection.put('greeting', new Blob(['hello'], { type: 'text/plain' }))
@@ -627,11 +637,12 @@ collection listings; updating one updates the other.
 A Collection's configuration (`name`, `backend`, `encryption`, `generator`, read
 by [`describe()`](#collections)) and its annotations live in one object at the
 Collection's reserved `/meta` path: server-managed properties (`createdAt` /
-`updatedAt` / `createdBy`) plus a user-writable `custom` object (`name` and
-`tags`), under one `ETag` validator. `meta()` is that same object with `custom`
-decoded through the codec; `describe()` does not resolve the codec at all, so on
-an encrypted collection it reports `custom` as the opaque envelope. A server
-without the endpoint surfaces its 501 as `NotImplementedError`.
+`updatedAt` / `createdBy` / `created`) plus a user-writable `custom` object
+(`name` and `tags`), under one `ETag` validator. `meta()` is that same object
+with `custom` decoded through the codec; `describe()` does not resolve the codec
+at all, so on an encrypted collection it reports `custom` as the opaque
+envelope. A server without the endpoint surfaces its 501 as
+`NotImplementedError`.
 
 ```ts
 const meta = await collection.meta() // CollectionMetadata | null (null on a miss)
@@ -649,6 +660,12 @@ await collection.setMeta({ custom: { name: 'Vault' } }, { ifMatch: meta?.etag })
 await collection.setMeta({ custom: { name: 'Vault' } }, { ifNoneMatch: true })
 ```
 
+`created` is the write stamp of the write that created the Collection
+(`{ updatedAt, updatedAtCounter, originId }`), kept for the Collection's life. A
+Collection deleted and created again carries the stamp of the later create. No
+write sends it back. A Collection created before the server supported the stamp
+may lack it.
+
 A failed precondition throws `PreconditionFailedError` (412). This `/meta` ETag
 is independent of every Resource's versions, but not of the configuration
 members: one validator covers the whole Collection Metadata object, so
@@ -844,6 +861,125 @@ sends no body on an in-place replace).
 > can actually serve bytes depends on the server having a live provider adapter
 > for it. Until then it is registered but inert (`status: 'registered'`).
 
+### Replica registration
+
+A Space can pull from a copy of itself on another server. The Space controller
+registers that peer Space with this server, and this server then runs a pull
+loop against the peer. Replication is one-way. The peer receives nothing unless
+its own server holds a registration pointing back.
+
+A registration is a directed edge. `fromSpace` is the peer Space's canonical
+trailing-slash URL, and `toSpace` is this Space's. `role` is always `source`.
+`capability` is the pull capability: a zcap the controller delegates to this
+server's DID, rooted in the peer Space, with `allowedAction` within `GET` and
+`HEAD`. `collections` lists the Collections to pull. Leave it out to pull every
+Collection.
+
+```ts
+// The DID of the server that will pull: the reference server discloses it
+// as `instance.serverDid` in its service description. `instance` is an
+// operator disclosure, so a deployment may leave it out; ask the operator
+// for the DID then.
+const { description } = await was.service()
+const serverDid = description.instance?.serverDid
+if (serverDid === undefined) {
+  throw new Error('This server does not disclose its DID.')
+}
+
+// The pull capability: GET-only, rooted in the peer Space, delegated to that
+// DID.
+const capability = await peerWas.space(peerSpaceId).grant({
+  to: serverDid,
+  actions: ['GET']
+})
+
+const registration = await space.registerReplica({
+  id: 'peer-1', // client-chosen and URL-safe
+  fromSpace: `https://peer.example/space/${peerSpaceId}/`,
+  toSpace: `https://was.example/space/${space.id}/`,
+  capability,
+  collections: [{ id: 'credentials' }], // omit to pull every Collection
+  role: 'source'
+}) // the stored ReplicaRegistration
+
+const listing = await space.replicas() // { url, totalItems, items } | null
+const one = await space.replica('peer-1') // ReplicaRegistration | null
+
+const status = await space.replicaStatus('peer-1') // ReplicaStatus | null
+// status.state: 'idle' | 'pulling' | 'backing-off' | 'stalled'
+for (const entry of status?.collections ?? []) {
+  if (entry.state === 'stalled') {
+    // entry.stall: { reason, since, detail? }
+  }
+}
+
+// The data already pulled under the registration stays. 'not-found' is the
+// server's masked 404: absent, or the caller is not the controller.
+const { outcome } = await space.deregisterReplica('peer-1') // 'deleted' | 'not-found'
+```
+
+`replicaStatus()` reports the pull loop's runtime state. The response is
+uncacheable and is not part of the registration record. Each Collection entry
+has its own `state` (`synced`, `syncing`, `stalled`, or `skipped`). A stalled
+Collection keeps its checkpoint until the cause is removed, and the other
+Collections continue. Its `stall.reason` is one of:
+
+- `clock-bound` -- a received write stamp is dated further ahead of local time
+  than the server allows. It clears as local time catches up.
+- `fork` -- a history log or an immutable Collection member differs from the
+  local one in a way no write order resolves.
+- `quota-exceeded` -- applying the change would exceed a local quota.
+- `unsupported-backend` -- the Collection names a `backend` this server has no
+  registration for.
+- `container-refused` -- the local Space or Collection refused the write.
+
+Every replica method is controller-only on the server, the reads included, since
+a registration holds the pull capability. A delegated capability gets the
+masked 404. `replicas()`, `replica()`, and `replicaStatus()` then return `null`,
+and `registerReplica()` throws `NotFoundError`. `deregisterReplica()` reports it
+as `{ outcome: 'not-found' }` rather than swallowing it, so a delegated caller
+can tell that nothing was removed. The three reads reserve `null` for that 404.
+A 2xx with no JSON body is a server fault and throws `WasServerError`.
+
+`registerReplica()` throws `ValidationError` (400 `invalid-request-body`) for a
+malformed body. Each entry of the error's `problems` carries a `pointer` naming
+the offending member. It throws `ConflictError` (409) for two refusals, told
+apart by the error's `type` URI:
+
+- `replica-refused` (`ProblemTypes.REPLICA_REFUSED`) -- the server refuses the
+  peer. For example, the peer Space's `controller` or `type` differs from this
+  one, the peer advertises no replication, the capability's controller is not
+  this server, or a listed Collection's immutable members differ. The cause is
+  in the error's `details`.
+- `id-conflict` (`ProblemTypes.ID_CONFLICT`) -- a registration with this `id`
+  already exists.
+
+```ts
+import { ProblemTypes } from '@interop/was-client'
+
+try {
+  await space.registerReplica(registration)
+} catch (err) {
+  if (err instanceof ConflictError && err.type === ProblemTypes.ID_CONFLICT) {
+    // already registered under this id
+  } else {
+    throw err
+  }
+}
+```
+
+`deregisterReplica()` throws `ConflictError` (`replica-refused`) when the
+registration is the one that maps this Space's did:webvh controller. Removing it
+would leave the Space with no way to follow its controller's log.
+
+A peer advertises replication in its service description, under
+`specs['https://w3id.org/pws/replication']` (version `0.1` on the reference
+server). A registration is per-server state. It is not replicated, it is not
+part of an export, and deleting the Space removes it. `space.describe()`
+surfaces the Space's registrations as the read-only `replicas` member, one
+`{ fromSpace, toSpace, role }` summary per peer, with no registration id and no
+capability. The server ignores `replicas` in a write body.
+
 ### Encrypted collections (EDV-over-WAS): pass-through encryption via the WAS client (recommended)
 
 This is the recommended way to use encrypted collections. For the low-level
@@ -966,6 +1102,21 @@ scope for now):
   `isPendingStub` recognizes it, and `delete()` removes it with its chunks. Tune
   the threshold and the chunk size with
   `createEdvEncryption({ maxBlobBytes, chunkSize })`.
+- **Streams.** A `ReadableStream<Uint8Array>` has no known size, so `add()`
+  always routes it to the chunked-stream path, however short it is. It is
+  encrypted and written as it is read, without buffering. `put(id, stream)`
+  takes the same route where no document is stored at `id` yet. Over an existing
+  document it is refused with `ValidationError` before the stream is read. A
+  content-addressed collection refuses a stream for the reason it refuses a
+  large blob. A write that fails midway cancels the stream, so the source behind
+  it is released. The content type is `options.contentType`, then a guess from
+  the id's extension, then `application/octet-stream`. To read without
+  buffering, call `resource.getStream()` or `collection.getStream(id)`. Its
+  `contentType` is the bare media type, with no parameters, on every collection.
+  For a chunked document the stream fetches and decrypts each chunk as it is
+  read. A missing chunk therefore errors the stream, with `NotFoundError`,
+  rather than the `getStream()` call; a tampered one errors it with
+  `EncryptionError`. `get()` still returns a `Blob`.
 - **Raw reads.** `get()` decrypts; the `getText()` / `getBytes()` escape hatches
   do not (they return the stored representation).
 
@@ -1224,6 +1375,17 @@ carries a blinded-index key, pass the cipher the stored `/meta` value
 Collection-handle write does; a cipher built without it writes documents
 `find()` cannot see until they are rewritten.
 
+`collection.changes()` reads one page of the raw feed, and sends the query as a
+`POST` by default. Pass `method: 'GET'` for the read-only form,
+`GET .../query?profile=changes&checkpoint=...&limit=...`. The server verifies it
+under the `GET` action and answers the same `ChangesPage`. A caller holding a
+GET-only capability, such as a pull capability, reads the feed this way. The
+`POST` form refuses that capability with `NotFoundError`.
+
+```ts
+const page = await collection.changes({ method: 'GET', checkpoint, limit: 100 })
+```
+
 ### Resource logs (co-managed key resources)
 
 The opt-in `@interop/was-client/log` subpath is the WAS binding of
@@ -1303,6 +1465,7 @@ not exist". Write/delete methods throw a typed error instead.
 | 400    | `ValidationError`      | `ValidationError`      |
 | 401    | `AuthRequiredError`    | `AuthRequiredError`    |
 | 409    | `ConflictError`        | `ConflictError`        |
+| 422    | `ValidationError`      | `ValidationError`      |
 | 413    | `PayloadTooLargeError` | `PayloadTooLargeError` |
 | 501    | `NotImplementedError`  | `NotImplementedError`  |
 | 507    | `QuotaExceededError`   | `QuotaExceededError`   |

package/dist/Collection.d.ts

@@ -1,6 +1,6 @@
 import type { ClientContext } from './internal/request.js';
 import type { WritePrecondition } from './internal/conditional.js';
-import type { CodecRequestContext, IndexDeclaration, IndexSchema } from './codec.js';
+import type { CodecRequestContext, DecodedStream, IndexDeclaration, IndexSchema } from './codec.js';
 import { Resource } from './Resource.js';
 import type { ChangesCheckpoint, ChangesPage, ResourceChangeDocument } from '@interop/storage-core';
 import type { AddResult, BackendDescriptor, BackendUsage, CollectionMetadata, CollectionWritableFields, EncryptionOverride, FindPage, GrantOptions, HandleOptions, IDelegatedZcap, IZcap, Json, ResourceData, LinkSet, PolicyDocument, CollectionResourcesList, ResourceMetadataCustomInput, ResourceSummary } from './types.js';
@@ -458,12 +458,21 @@ export declare class Collection {
     resource(resourceId: string, options?: HandleOptions): Resource;
     /**
      * Adds a resource with a server-generated id. JSON for plain objects/arrays,
-     * binary for `Blob`/`Uint8Array`. Throws `NotFoundError` if the collection
-     * does not exist (WAS does not auto-create parents).
+     * binary for `Blob`/`Uint8Array` or `ReadableStream<Uint8Array>`. Throws
+     * `NotFoundError` if the collection does not exist (WAS does not
+     * auto-create parents).
      *
      * On an encrypted collection a binary payload above the codec's
      * single-document threshold is auto-routed to the chunked-stream path, which
-     * a server that does not serve the chunk endpoints answers with `501`.
+     * a server that does not serve the chunk endpoints answers with `501`. A
+     * `ReadableStream<Uint8Array>` is always written through that path, without
+     * buffering, since its size is unknown. A content-addressed collection
+     * (`idDerivation: 'content'`) cannot store a chunked payload, so it refuses
+     * a stream with `ValidationError` before reading it.
+     *
+     * On a plaintext collection a stream is refused with `ValidationError`: a
+     * plaintext resource has no chunked representation, and a signed request
+     * carries a `Digest` of its whole body. Buffer it into a `Blob` there.
      *
      * @param data {ResourceData}
      * @param options {object}
@@ -482,11 +491,25 @@ export declare class Collection {
      * @returns {Promise<Json | Blob | null>}
      */
     get(resourceId: string): Promise<Json | Blob | null>;
+    /**
+     * Reads a resource by id as a byte stream, decrypting on an encrypted
+     * collection -- the read for a caller that cannot buffer a large chunked
+     * blob. Delegates to `Resource.getStream`; see it for the details. The
+     * ordinary {@link get} still returns a `Blob`. Returns `null` on a
+     * missing/unauthorized resource (404 conflation caveat).
+     *
+     * @param resourceId {string}
+     * @returns {Promise<(DecodedStream & { etag?: string }) | null>}
+     */
+    getStream(resourceId: string): Promise<(DecodedStream & {
+        etag?: string;
+    }) | null>;
     /**
      * Creates or replaces a resource by id (upsert). Forwards the
      * conditional-write options (`ifMatch` / `ifNoneMatch`) to `Resource.put`;
-     * see it for the conditional-write semantics. Returns the stored
-     * resource's new `etag`.
+     * see it for the conditional-write semantics and for which payloads
+     * (including a `ReadableStream<Uint8Array>`) each kind of collection
+     * accepts. Returns the stored resource's new `etag`.
      *
      * @param resourceId {string}
      * @param data {ResourceData}
@@ -579,14 +602,25 @@ export declare class Collection {
      * parse that resource's body). Entries of any other kind pass through
      * unchecked.
      *
+     * The query is sent as a `POST` whose body carries the parameters, or in
+     * the read-only `GET` form with the parameters in the query string, which
+     * the server verifies under the `GET` action and answers with the same page.
+     * A capability whose `allowedAction` excludes `POST` (a GET-only pull
+     * capability, say) reads the feed with `GET`, since the `POST` form refuses
+     * it with `NotFoundError`; every other handle sends `POST`. `method`
+     * overrides the derived form.
+     *
      * @param [options] {object}
      * @param [options.checkpoint] {ChangesCheckpoint}   opaque checkpoint from a prior page; resume strictly after it
      * @param [options.limit] {number}   max documents; the server reduces it to its own maximum
+     * @param [options.method] {'POST' | 'GET'}   the request form; derived from
+     *   the bound capability by default
      * @returns {Promise<ChangesPage>}
      */
     changes(options?: {
         checkpoint?: ChangesCheckpoint;
         limit?: number;
+        method?: 'POST' | 'GET';
     }): Promise<ChangesPage>;
     /**
      * Walks the `changes` feed page by page from `checkpoint` (or the beginning)
@@ -608,11 +642,14 @@ export declare class Collection {
      * @param [options] {object}
      * @param [options.checkpoint] {ChangesCheckpoint}   resume strictly after it
      * @param [options.limit] {number}   max entries per request, every kind counted
+     * @param [options.method] {'POST' | 'GET'}   the request form of each page,
+     *   as for {@link changes}
      * @returns {AsyncGenerator<{ documents: ResourceChangeDocument[], checkpoint: ChangesCheckpoint | null }>}
      */
     resourceChanges(options?: {
         checkpoint?: ChangesCheckpoint;
         limit?: number;
+        method?: 'POST' | 'GET';
     }): AsyncGenerator<{
         documents: ResourceChangeDocument[];
         checkpoint: ChangesCheckpoint | null;

package/dist/Collection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Collection.d.ts","sourceRoot":"","sources":["../src/Collection.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Collection.d.ts","sourceRoot":"","sources":["../src/Collection.ts"],"names":[],"mappings":"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"}

package/dist/Collection.js

@@ -71,6 +71,47 @@ function mergedConfiguration(desc, current) {
         plaintext: desc.plaintext ?? current?.plaintext
     });
 }
+/**
+ * The request form of the `changes` query a bound capability admits: `GET`
+ * when the capability's `allowedAction` is stated and excludes `POST` (a
+ * GET-only pull capability), `POST` otherwise (no capability, a root one, or
+ * one whose actions are unrestricted or include `POST`).
+ */
+function changesMethodFor(capability) {
+    const allowed = capability?.allowedAction ?? 'POST';
+    const actions = Array.isArray(allowed) ? allowed : [allowed];
+    return actions.some(action => action.toUpperCase() === 'POST')
+        ? 'POST'
+        : 'GET';
+}
+/**
+ * The path and body of a `changes` query in the given form. The `POST` form
+ * carries the parameters in its JSON body; the read-only `GET` form carries
+ * them in the query string, each percent-encoded by `URLSearchParams` so an
+ * opaque checkpoint never breaks the URL.
+ *
+ * @param options {object}
+ * @param options.queryPath {string}   the collection's `/query` path
+ * @param options.method {'POST' | 'GET'}
+ * @param [options.checkpoint] {ChangesCheckpoint}
+ * @param [options.limit] {number}
+ * @returns {{ path: string, method: 'POST' | 'GET', json?: object }}
+ */
+function changesRequest({ queryPath, method, checkpoint, limit }) {
+    const params = {
+        profile: 'changes',
+        ...(checkpoint !== undefined && { checkpoint }),
+        ...(limit !== undefined && { limit })
+    };
+    if (method === 'POST') {
+        return { path: queryPath, method, json: params };
+    }
+    const search = new URLSearchParams();
+    for (const [name, value] of Object.entries(params)) {
+        search.set(name, String(value));
+    }
+    return { path: `${queryPath}?${search.toString()}`, method };
+}
 export class Collection {
     spaceId;
     id;
@@ -1208,12 +1249,21 @@ export class Collection {
     }
     /**
      * Adds a resource with a server-generated id. JSON for plain objects/arrays,
-     * binary for `Blob`/`Uint8Array`. Throws `NotFoundError` if the collection
-     * does not exist (WAS does not auto-create parents).
+     * binary for `Blob`/`Uint8Array` or `ReadableStream<Uint8Array>`. Throws
+     * `NotFoundError` if the collection does not exist (WAS does not
+     * auto-create parents).
      *
      * On an encrypted collection a binary payload above the codec's
      * single-document threshold is auto-routed to the chunked-stream path, which
-     * a server that does not serve the chunk endpoints answers with `501`.
+     * a server that does not serve the chunk endpoints answers with `501`. A
+     * `ReadableStream<Uint8Array>` is always written through that path, without
+     * buffering, since its size is unknown. A content-addressed collection
+     * (`idDerivation: 'content'`) cannot store a chunked payload, so it refuses
+     * a stream with `ValidationError` before reading it.
+     *
+     * On a plaintext collection a stream is refused with `ValidationError`: a
+     * plaintext resource has no chunked representation, and a signed request
+     * carries a `Digest` of its whole body. Buffer it into a `Blob` there.
      *
      * @param data {ResourceData}
      * @param options {object}
@@ -1292,11 +1342,25 @@ export class Collection {
         // guard in the `Resource` constructor applies to reads and writes alike.
         return this.resource(resourceId).get();
     }
+    /**
+     * Reads a resource by id as a byte stream, decrypting on an encrypted
+     * collection -- the read for a caller that cannot buffer a large chunked
+     * blob. Delegates to `Resource.getStream`; see it for the details. The
+     * ordinary {@link get} still returns a `Blob`. Returns `null` on a
+     * missing/unauthorized resource (404 conflation caveat).
+     *
+     * @param resourceId {string}
+     * @returns {Promise<(DecodedStream & { etag?: string }) | null>}
+     */
+    async getStream(resourceId) {
+        return this.resource(resourceId).getStream();
+    }
     /**
      * Creates or replaces a resource by id (upsert). Forwards the
      * conditional-write options (`ifMatch` / `ifNoneMatch`) to `Resource.put`;
-     * see it for the conditional-write semantics. Returns the stored
-     * resource's new `etag`.
+     * see it for the conditional-write semantics and for which payloads
+     * (including a `ReadableStream<Uint8Array>`) each kind of collection
+     * accepts. Returns the stored resource's new `etag`.
      *
      * @param resourceId {string}
      * @param data {ResourceData}
@@ -1407,28 +1471,37 @@ export class Collection {
      * parse that resource's body). Entries of any other kind pass through
      * unchecked.
      *
+     * The query is sent as a `POST` whose body carries the parameters, or in
+     * the read-only `GET` form with the parameters in the query string, which
+     * the server verifies under the `GET` action and answers with the same page.
+     * A capability whose `allowedAction` excludes `POST` (a GET-only pull
+     * capability, say) reads the feed with `GET`, since the `POST` form refuses
+     * it with `NotFoundError`; every other handle sends `POST`. `method`
+     * overrides the derived form.
+     *
      * @param [options] {object}
      * @param [options.checkpoint] {ChangesCheckpoint}   opaque checkpoint from a prior page; resume strictly after it
      * @param [options.limit] {number}   max documents; the server reduces it to its own maximum
+     * @param [options.method] {'POST' | 'GET'}   the request form; derived from
+     *   the bound capability by default
      * @returns {Promise<ChangesPage>}
      */
     async changes(options = {}) {
-        const { checkpoint, limit } = options;
+        const { checkpoint, limit, method = changesMethodFor(this.#capability) } = options;
         const response = await send(this.#context, {
-            path: collectionQuery(this.spaceId, this.id),
-            method: 'POST',
-            capability: this.#capability,
-            json: {
-                profile: 'changes',
-                ...(checkpoint !== undefined && { checkpoint }),
-                ...(limit !== undefined && { limit })
-            }
+            ...changesRequest({
+                queryPath: collectionQuery(this.spaceId, this.id),
+                method,
+                checkpoint,
+                limit
+            }),
+            capability: this.#capability
         });
-        // A `changes` query is a POST, so it never carries the null-on-404 `read`
-        // flag: a missing or unauthorized collection throws, as every other write
-        // -shaped call on this handle does. A `null` here is therefore a 2xx whose
-        // body did not parse as JSON, which must not masquerade as the end-of-feed
-        // page `{ documents: [], checkpoint: null }`.
+        // Neither form carries the null-on-404 `read` flag: a missing or
+        // unauthorized collection throws, as every other write-shaped call on this
+        // handle does. A `null` here is therefore a 2xx whose body did not parse
+        // as JSON, which must not masquerade as the end-of-feed page
+        // `{ documents: [], checkpoint: null }`.
         const page = dataOrNull(response);
         if (page === null) {
             throw new WasServerError(`The changes feed of collection "${this.id}" answered with no JSON ` +
@@ -1487,14 +1560,16 @@ export class Collection {
      * @param [options] {object}
      * @param [options.checkpoint] {ChangesCheckpoint}   resume strictly after it
      * @param [options.limit] {number}   max entries per request, every kind counted
+     * @param [options.method] {'POST' | 'GET'}   the request form of each page,
+     *   as for {@link changes}
      * @returns {AsyncGenerator<{ documents: ResourceChangeDocument[], checkpoint: ChangesCheckpoint | null }>}
      */
     async *resourceChanges(options = {}) {
-        const { limit } = options;
+        const { limit, method } = options;
         let checkpoint = options.checkpoint;
         const seen = new Set(checkpoint === undefined ? [] : [checkpoint]);
         for (;;) {
-            const page = await this.changes({ checkpoint, limit });
+            const page = await this.changes({ checkpoint, limit, method });
             yield {
                 documents: page.documents.filter(isResourceChange),
                 checkpoint: page.checkpoint ?? null