dsh-cherry-bridge 0.2.1 → 0.2.3

package/src/AGENTS.md

@@ -36,6 +36,7 @@ in [`docs/e2e-checklist.md`](../docs/e2e-checklist.md).
 | `recordBytes` | 65,536 (64 KiB) | one JSON-RPC record above it **aborts the connection** — the transport answers by killing it, so every in-flight request fails |
 | `contentBytes` | 24,576 (24 KiB) | the slice size for one `agent.content.read` |
 | `pageItems` | 100 | the protocol's single-page hard cap; `hello` may negotiate smaller |
+| `unackedBytes` | 262,144 (256 KiB) | the peer HOLDS `agent.events` beyond this much un-acked delivery — terminal included; the layer acks at ¼ of it (hello value, else this) (issue #212) |
 
 Through 2.1.7 the desktop's `pageOf` pages by **count alone** (2.1.8's byte
 budget aside, still count-paged): `pageItems: 100` fat parts produced a record
@@ -187,8 +188,7 @@ projection. An unchanged message costs no repeat `agent.parts.list`
 RPC on send → wait → read rounds, while every read still re-fetches and
 sha256-verifies every `{ref}`'s bytes (a corrupted ref behind an unchanged
 revision fails with `ContentIntegrityError`; `toolsReadCache.test.ts` T1b pins
-this beside the cache). A hit is still not a zero-RPC read: 2.1.6+ externalizes
-every part over 4,096 characters.
+this beside the cache).
 
 - **Entry & key**: the `agent.parts.list` result — `{revision, page}` — keyed
   `<deviceId>\0<messageId>` (device-scoped: a message id is the peer's; two
@@ -654,8 +654,7 @@ one host; whole-replace `hosts` defaults new hosts to
 `ws`/port; a CHANGED `port` re-points EVERY final host, the current value a map
 no-op (the settings UI sends both on save). `GET /devices` reports both maps and
 `forgottenHosts` (addresses and intent, not credentials); tools/diagnostics show
-only `port`. The settings
-page shows the per-host ports only when they differ from the record-level one.
+only `port`.
 TLS trust is operator config (`wsTls`: FLAT `tls.connect` `rejectUnauthorized`/
 `ca` only), forwarded to both dial sites (pool, pairing). `resolveBridgeConfig`
 validates it: unknown key or unusable value warns by FIELD NAME, WHOLE object
@@ -785,9 +784,8 @@ that is not valid URL encoding) · `last-address` 400 (the action would leave no
 to dial; nothing written) · `invalid-device` 400 (the store refused) · `not-found`
 404 (unknown device OR action — also what a QUARANTINED archive answers, its view
 being empty) · `method-not-allowed` 405 (before the body) · `archive-quarantined`
-503 (`{file, corrupt, recovery}`; a damaged archive empties its view and 404s first,
-so this arm only covers a store that refuses after that read — unreachable for the
-shipped store, kept so the arm exists); anything else is the generic 500
+503 (`{file, corrupt, recovery}`; a damaged archive 404s first, so this arm covers
+only a store that refuses after that read); anything else is the generic 500
 `internal-error`.
 
 > The minimal `pairing-progress` frame shape is `{stage, detail?}`; this plugin
@@ -832,10 +830,11 @@ the error message).
 - **May be emitted** (`sanitizeDevice`): `deviceId`, `displayName`, `state`,
   `enabled`, `hosts`, `port`, a **12-char digest** of `desktopIdentity`, the
   hello-negotiated `limits` (`heartbeatMs`/`subscriptions`/`pageItems`/
-  `inFlightRequests` — **only with a live connection**; the endpoint never
-  dials and never wakes a device to fetch fallbacks), `messageSummaries` (the
-  hello capability bit, absent when not advertised), `sessionId` and session
-  cursors (unsubscribed sessions have none), the `stats` counters
+  `inFlightRequests` — **only with a live connection**; it never dials or wakes
+  a device for fallbacks), `messageSummaries` (the
+  hello capability bit, absent when not advertised), `sessionId`, session
+  cursors (none when unsubscribed) and their ledger (`deliveredBytes`/
+  `unackedBytes`/`acks`, #217), the `stats` counters
   (`connections`/`sockets`/`connectionsBuilt`/`subscriptions`), the two resolved
   `config` keys, and error `reason`/`message`.
 - **Never emitted**: `accessToken`, `tokenExpiresAt`, `invitationSecret`, the
@@ -844,9 +843,8 @@ the error message).
   construction**, not by a deny-list. `limits` is re-projected from its four
   keys: a whitelist inside the whitelist.
 - `stats.connectionsBuilt` counts connections built since the last `apply`, not
-  RPC requests — those belong to the transport; a same-named metric would be
-  misread. Counters and the error ring are zeroed on every `apply`: the
-  statistics describe **only** the current assembly.
+  RPC requests (those belong to the transport). Counters and the error ring are
+  zeroed on every `apply`: they describe **only** the current assembly.
 
 ### Logging: levels, identifiers, and what never appears
 
@@ -944,6 +942,4 @@ faces:
   answer is the byte-safe page **clamp**: never ask for a page that cannot fit.
 - Its read path refuses an unusable `byteLength`; we fall back to a slice bound
   plus the cumulative arm.
-- Its read path never replays a read; we replay reads **once** (deliberate
-  enhancement) while both sides keep commands receipt-recovered.
 

package/src/connection.ts

@@ -38,6 +38,17 @@ export interface EffectiveLimits {
   subscriptions: number
   pageItems: number
   inFlightRequests: number
+  /**
+   * The peer's hello-advertised UN-ACKED DELIVERY WINDOW (protocol
+   * `remoteLimits.unackedBytes`). Past this much delivered-but-unacknowledged
+   * traffic the desktop holds its event stream (issue #212), so the
+   * subscription layer sizes its own ack watermark from it.
+   *
+   * ABSENT, never defaulted — same rule as `messageSummaries` below: a hello
+   * that does not carry the key leaves the layer on the pinned protocol
+   * constant rather than on a guess about this peer.
+   */
+  unackedBytes?: number
   /**
    * The peer's hello-advertised `agentMessageSummariesVersion` (issue #105),
    * stored BESIDE the limits because it is re-read by that same handshake.
@@ -885,6 +896,29 @@ export class DeviceConnection {
   #pendingPings = new Set<{ nonce: string; sentAt: number }>()
   #token: string | undefined
   #tokenExpiresAt: number | undefined
+  /**
+   * Hosts whose LAST attempt failed for that ADDRESS's own reason (issue #220).
+   * A pass dials the hosts it has not failed yet FIRST, so a stale candidate
+   * sitting first in `record.hosts` cannot cost its dial timeout on every
+   * reconnect — the rule the official client states as "failed candidates
+   * rotate behind untried addresses across retries, so the round budget cannot
+   * permanently starve a later route"
+   * (`.scratch-csa/docs/references/remote-access/connectivity.md` §Connection
+   * lifetime; the tree is gitignored, and its remote-agent directory is the
+   * same `16e505fe` at app tags v0.5.2 and v0.5.3, so this is not a rule that
+   * arrived with a newer app).
+   *
+   * Demotion is ORDER, never exclusion: with every host marked the list falls
+   * back to record order, so a record whose only address is marked still dials
+   * it. A mark is cleared when that host itself connects, so a repaired address
+   * returns to the front on its own — no expiry timer, no persistence, no
+   * config key. A pairing-level verdict and a cancellation never mark (they are
+   * not this address's fault: the line `isPerHostFailure` draws for the
+   * handshake face, mirrored explicitly in the dial face, where only
+   * `IdentityMismatchError` can arise today), and `close()` keeps the marks
+   * because they describe addresses, not this lifecycle.
+   */
+  readonly #demotedHosts = new Set<string>()
 
   readonly #wsOptions: WsDialOptions | undefined
 
@@ -1244,7 +1278,7 @@ export class DeviceConnection {
     }
 
     let lastError: Error = new Error(`device ${this.record.deviceId}: all candidate hosts unreachable`)
-    for (const host of this.record.hosts) {
+    for (const host of this.#dialOrder()) {
       // CANCELLATION GATE, at the top of every candidate. `close()` bumps the
       // epoch and clears `#running`, so either check is enough — both are here
       // because they answer different halves of the same question ("is this
@@ -1268,7 +1302,15 @@ export class DeviceConnection {
         link = await this.#dial(host, port, epoch)
       } catch (error) {
         if (error instanceof IdentityMismatchError) throw error
+        // A cancellation is not this ADDRESS's fault, so it neither marks it
+        // nor continues the pass. UNREACHABLE today — `#dial`'s AbortController
+        // is aborted only through `#teardownLink`, which needs `#link`, and
+        // `#link` is not committed until the dial returns — so this is a
+        // DEFENSIVE arm, not a pinned one: it keeps the rule true if the dial
+        // ever grows a close path, at the cost of two lines and no behaviour.
+        if (error instanceof CancelledError) throw error
         lastError = error instanceof Error ? error : new Error(String(error))
+        this.#demotedHosts.add(host)
         continue
       }
       // Commit the link before the RPC handshake so every failure path below
@@ -1277,6 +1319,8 @@ export class DeviceConnection {
       this.#link = link
       try {
         await this.#handshake(link, epoch)
+        // This address works: any mark an earlier pass left on it is stale.
+        this.#demotedHosts.delete(host)
         return
       } catch (error) {
         // A close() that landed mid-handshake surfaces here as the failure of
@@ -1288,10 +1332,11 @@ export class DeviceConnection {
         // The terminal faces end the pass: they describe the PAIRING, not this
         // address, so trying the next candidate would only repeat them.
         if (!isPerHostFailure(error)) throw error
-        // A channel-level failure (socket dropped mid-handshake) is this
-        // ADDRESS's problem: tear the link down here, since the loop's next
-        // iteration would otherwise overwrite `#link` and leak this socket, and
-        // fall through to the next candidate.
+        // A peer that answers hello/authenticate with a per-address failure is
+        // this ADDRESS's problem too: demote it for the NEXT pass, tear the
+        // link down here (the loop's next iteration would otherwise overwrite
+        // `#link` and leak this socket), and fall through to the next candidate.
+        this.#demotedHosts.add(host)
         this.#teardownLink()
         lastError = error instanceof Error ? error : new Error(String(error))
         continue
@@ -1300,6 +1345,27 @@ export class DeviceConnection {
     throw new AllHostsUnreachableError(this.record.deviceId, this.record.hosts, lastError)
   }
 
+  /**
+   * The pass's dial order (issue #220): hosts this connection has NOT failed
+   * yet, in record order, then the demoted ones, in record order.
+   *
+   * Record order is preserved INSIDE each half, so an ordinary single-address
+   * record, a fresh record and an all-demoted record all dial exactly the list
+   * the record carries — the demotion can only move an address that failed
+   * behind addresses that did not, and can never drop one.
+   */
+  #dialOrder(): readonly string[] {
+    const hosts = this.record.hosts
+    if (this.#demotedHosts.size === 0) return hosts
+    const untried: string[] = []
+    const demoted: string[] = []
+    for (const host of hosts) {
+      if (this.#demotedHosts.has(host)) demoted.push(host)
+      else untried.push(host)
+    }
+    return [...untried, ...demoted]
+  }
+
   async #dial(host: string, port: number, epoch: number): Promise<LiveLink> {
     // (see {@link DeviceConnectionOptions.wsOptions} for TLS trust)
     // The URL comes from the SAME helper the pairing dial uses (issue #126):
@@ -1402,11 +1468,13 @@ export class DeviceConnection {
     // reconnect to a peer that no longer advertises the capability (or a
     // downgrade) cannot inherit a stale `messageSummaries` from the previous
     // link — the exact failure mode that would send `partsMode` to a 2.1.7 peer.
+    const unackedBytes = positive(hello.limits?.['unackedBytes'])
     this.#limits = {
       heartbeatMs: positive(hello.heartbeatMs) ?? FALLBACK_LIMITS.heartbeatMs,
       subscriptions: positive(hello.limits?.['subscriptions']) ?? FALLBACK_LIMITS.subscriptions,
       pageItems: positive(hello.limits?.['pageItems']) ?? FALLBACK_LIMITS.pageItems,
       inFlightRequests: positive(hello.limits?.['inFlightRequests']) ?? FALLBACK_LIMITS.inFlightRequests,
+      ...(unackedBytes === undefined ? {} : { unackedBytes }),
       ...(typeof hello.agentMessageSummariesVersion === 'number'
         ? { messageSummaries: hello.agentMessageSummariesVersion }
         : {}),

package/src/diagnostics.ts

@@ -199,7 +199,7 @@ export interface DiagnosticsDevice {
    * `partsMode: 'paged'`.
    *
    * Its own field, not a fifth key inside `limits`: it is a VERSION, not a
-   * count, and `limits` is documented as the four numeric caps. Present only
+   * count, and `limits` here is the four numeric caps this report CARRIES. Present only
    * when a LIVE connection reported it (the same rule as `limits`: the endpoint
    * never dials to find out). ABSENT therefore means "not advertised **or** not
    * connected" — every desktop through 2.1.7, and any device whose link is
@@ -216,6 +216,16 @@ export interface DiagnosticsSession {
   deviceId: string
   subscriptions: number
   cursor?: { sessionId: string; streamEpoch: string; seq: string }
+  /**
+   * Issue #217: the layer's own delivery ledger for THIS subscription — payload
+   * bytes received since it was installed, how many of them the peer may still
+   * count as un-acknowledged, and successful acks. Absent when the layer does
+   * not report it (an unsubscribed session has no ledger); counts describe the
+   * current subscription, so a re-subscribe restarts them.
+   */
+  deliveredBytes?: number
+  unackedBytes?: number
+  acks?: number
 }
 
 /** One recent error summary (spec §5: 「最近错误摘要」). */
@@ -324,6 +334,10 @@ export interface SubscriptionStat {
   sessionId: string
   subscriptions: number
   cursor?: { sessionId: string; streamEpoch: string; seq: string }
+  /** See {@link DiagnosticsSession.deliveredBytes} (issue #217). */
+  deliveredBytes?: number
+  unackedBytes?: number
+  acks?: number
 }
 
 /**
@@ -555,10 +569,11 @@ function projectMessageSummaries(raw: unknown): { messageSummaries?: number } {
 }
 
 /**
- * Re-projects the four numeric limit keys, dropping any foreign key that a
- * caller's `limits` object might carry. A whitelist inside the whitelist: the
- * shape is rebuilt field by field rather than spread, so a future addition to
- * `EffectiveLimits` cannot arrive here unvetted.
+ * Re-projects the four numeric limit keys this report carries, dropping any
+ * foreign key that a caller's `limits` object might carry — including
+ * `EffectiveLimits`' newer `unackedBytes`, which no diagnostics consumer needs.
+ * A whitelist inside the whitelist: the shape is rebuilt field by field rather
+ * than spread, so a future addition cannot arrive here unvetted.
  */
 function projectLimits(raw: unknown): { limits?: EffectiveLimits } {
   if (raw === null || typeof raw !== 'object') return {}
@@ -576,6 +591,17 @@ function numberOr(value: unknown, fallback: number): number {
   return typeof value === 'number' && Number.isFinite(value) ? value : fallback
 }
 
+/**
+ * A delivery-ledger counter (issue #217): a NON-NEGATIVE finite number, or
+ * nothing at all. Absence means "not reported"; a fabricated zero would read as
+ * "nothing was delivered", which is a claim this projection has no evidence for.
+ */
+function countEntry(key: 'deliveredBytes' | 'unackedBytes' | 'acks', raw: unknown): Partial<DiagnosticsSession> {
+  return typeof raw === 'number' && Number.isFinite(raw) && raw >= 0
+    ? ({ [key]: raw } as Partial<DiagnosticsSession>)
+    : {}
+}
+
 /** The loose-bag view every projection in this module takes of its input. */
 function bag(raw: unknown): Record<string, unknown> {
   return (raw ?? {}) as Record<string, unknown>
@@ -727,6 +753,9 @@ export function sanitizeDiagnostics(source: {
                 seq: typeof cursor['seq'] === 'string' ? cursor['seq'] : '',
               },
             }),
+        ...countEntry('deliveredBytes', value['deliveredBytes']),
+        ...countEntry('unackedBytes', value['unackedBytes']),
+        ...countEntry('acks', value['acks']),
       }
     }),
     recentErrors: (source.recentErrors ?? []).map((raw): DiagnosticsError => {
@@ -807,6 +836,9 @@ export function buildDiagnostics(
         deviceId: entry.deviceId,
         subscriptions: entry.subscriptions,
         ...(entry.cursor === undefined ? {} : { cursor: { ...entry.cursor } }),
+        ...(entry.deliveredBytes === undefined ? {} : { deliveredBytes: entry.deliveredBytes }),
+        ...(entry.unackedBytes === undefined ? {} : { unackedBytes: entry.unackedBytes }),
+        ...(entry.acks === undefined ? {} : { acks: entry.acks }),
       })
     }
   } catch {

package/src/index.ts

@@ -664,6 +664,11 @@ function subsFor(deviceId: string): SessionSubscriptions {
   const created = new SessionSubscriptions(connection.rpc, {
     subscriptionsLimit: connection.limits.subscriptions,
     perSessionCacheBytes: state.perSessionCacheBytes,
+    // The peer's OWN un-acked window when hello advertised it (protocol 0.7.0
+    // peers do); absent falls back to the pinned constant inside the layer.
+    // A PROVIDER, not a value: the layer outlives a reconnect, and `limits` is
+    // rebuilt by every hello — a pinned number would freeze the first answer.
+    unackedBytes: () => connection.limits.unackedBytes,
   })
   state.subscriptions.set(deviceId, created)
   // INFO (spec §5 「订阅建立」): the layer is announced with the cap it was
@@ -873,7 +878,16 @@ function assemblyDeps(): CherryHttpDeps & CherryToolsDeps {
       [...state.subscriptions.entries()].flatMap(([deviceId, layer]) =>
         layer.activeSessions().map((sessionId) => {
           const cursor = layer.cursorOf(sessionId)
-          return { deviceId, sessionId, subscriptions: 1, ...(cursor === undefined ? {} : { cursor }) }
+          // The layer's own delivery ledger (issue #217), beside the cursor it
+          // is measured against: both come from ONE session state read.
+          const delivery = layer.deliveryOf(sessionId)
+          return {
+            deviceId,
+            sessionId,
+            subscriptions: 1,
+            ...(cursor === undefined ? {} : { cursor }),
+            ...(delivery === undefined ? {} : delivery),
+          }
         }),
       ),
     diagnosticsErrors: () => [...state.recentErrors],