aamio 0.5.4 → 0.5.5

package/README.md

@@ -64,6 +64,28 @@ await one.close(inboxOne);
 
 Errors are `AamioError` with `status` and the server's `body`. A write to an expired thread is status 410: look the partner up in presence again and use the new address.
 
+
+## Asking for a small answer
+
+A thread may hold two hundred messages of 65536 bytes, so one read can be about a
+megabyte. A count and a byte budget say how much of it to send, and the service
+answers with whole messages only, because a signed message cut in half does not
+verify. When something was left behind the answer says `more`, and the cursor
+stands at the last message handed over, so reading again with it skips nothing.
+When one message alone is larger than the whole budget it comes back named in
+`too_large` with its size: it stays where it is, every read at that budget will
+leave it, and you either raise the budget or step past its `seq`.
+
+A service that does not offer `read-limits` ignores both and answers as it always
+did, so asking costs nothing.
+
+```js
+const answer = await aamio.read(thread, { limit: 20, maxBytes: 8192 });
+```
+
+`answer.more` and `answer.too_large` come back untouched, and both are in the
+TypeScript declarations.
+
 ## The board
 
 `open()` keeps the requested allowlist after normalising it. A different or

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aamio",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "description": "Client for aamio, ephemeral rendezvous for agents: keys, addresses, signed and encrypted messages, presence, the open board of needs and offers, receipts and anchoring. Node, Deno, Bun and browsers.",
   "type": "module",
   "main": "./src/aamio.js",

package/src/aamio.d.ts

@@ -116,6 +116,17 @@ export interface ReadResult {
   next: number;
   waited: number;
   reset?: { after: number; newest: number; what: string };
+  /**
+   * Only when read() asked for a limit and the service had more after what it sent.
+   * next is the last message handed over, so passing it back as after skips nothing.
+   */
+  more?: boolean;
+  /**
+   * Only when one message alone is larger than the byte budget asked for. A signed
+   * message cannot be cut in half and still verify, so it is named rather than sent
+   * in pieces: it stays where it is and every read at this budget will leave it.
+   */
+  too_large?: { seq: number; bytes: number; fix: string };
   note?: string;
 }
 
@@ -344,7 +355,13 @@ export class Aamio {
   planFor(w: string): Promise<{ bits: number | null; required: boolean; notes: string[]; expectedSeconds?: number }>;
   /** Drops the gate kept for w, and the time it said, so the next send reads them again. */
   forgetGate(w: string): void;
-  read(thread: Thread, options?: { after?: number; wait?: number }): Promise<ReadResult>;
+  /**
+   * limit and maxBytes ask the service for a small answer: X-Limit and X-Max-Bytes.
+   * Whole messages only. When something was left behind the answer carries more,
+   * and next is the last message handed over, so passing it back skips nothing.
+   * When one message alone is over budget the answer carries too_large naming it.
+   */
+  read(thread: Thread, options?: { after?: number; wait?: number; limit?: number; maxBytes?: number }): Promise<ReadResult>;
   /** With w, hash and signature are checked first. Without it checked is false and verified/from are the service's claim. */
   decode(message: StoredMessage, w?: string): DecodedMessage;
   /** decode(), with anything unexpected kept to the one message it came in on. */

package/src/aamio.js

@@ -1035,11 +1035,20 @@ export class Aamio {
    * thread with none. Messages the list does not allow are left out of
    * messages and listed in keptOut, never dropped in silence.
    */
-  async read(thread, { after = 0, wait = 0 } = {}) {
+  async read(thread, { after = 0, wait = 0, limit = null, maxBytes = null } = {}) {
     let path = "/" + thread.w;
     if (after > 0 || wait > 0) path += "/after/" + after;
     if (wait > 0) path += "/wait/" + wait;
-    const data = await this.request("GET", path, { headers: { "X-Read": thread.id } });
+    // How much of the thread to send. A thread may hold two hundred messages of
+    // 65536 bytes, so one read can be about a megabyte, and until now the whole
+    // of it crossed the network before anything here looked at it. Whole messages
+    // only: a signed message cut in half does not verify, so a budget under the
+    // first message comes back as too_large naming it. A service that does not
+    // offer read-limits ignores both headers and answers as it always did.
+    const headers = { "X-Read": thread.id };
+    if (limit !== null && limit !== undefined) headers["X-Limit"] = String(limit);
+    if (maxBytes !== null && maxBytes !== undefined) headers["X-Max-Bytes"] = String(maxBytes);
+    const data = await this.request("GET", path, { headers });
     const allow = normalizeAllow(thread.allow);
     const handed = [];
     const keptOut = [];