@ai-matrx/desktop-protocol 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 0.7.0
+
+- `CLOSE_RULES` / `closeRule(code)` / `isTerminalClose(code)` (`src/close-policy.ts`): the one table
+  of what a dialer does after each close — `reconnect_now`, `reconnect`, `reauth` (one retry with a
+  fresh token; a second refusal before any welcome is terminal, outcome `signed_out`), or `stop`
+  with an `outcome` (`not_owned` 4003, `removed` 4004, `replaced` 4009, `revoked` 4010,
+  `upgrade_required` 4426). A CloseCode without a rule fails to compile; unknown codes reconnect.
+- The client reads that table (its private terminal list is gone) and reports
+  `DesktopClientState.outcome` when it stops; 4001/4008 no longer redial forever.
+
+Consumer action: never keep a local list of terminal close codes; branch on `closeRule(code)` and
+show `state.outcome`.
+
+## 0.6.0
+
+- `RelayDeviceStatusEvent.since_ms` is `null` for a device that has never connected (protocol 1.1;
+  `NULL_SINCE`): a 1.0 reader is sent `0`, its old meaning (`statusForPeer`).
+- A WebSocket client may announce its minor at connect by also offering
+  `versionSubprotocol(PROTOCOL_VERSION)` (e.g. `matrx.v1.1`) beside `SUBPROTOCOL`;
+  `announcedVersion(offered)` reads it (servers still answer `SUBPROTOCOL`).
+- The versioning test also refuses a 1.0 field changing type, except a widening to null listed in
+  `NULL_SINCE`.
+
+Consumer action: treat `since_ms: null` as "never connected"; offer the version subprotocol.
+
 ## 0.5.0
 
 Version skew is the normal state, so a minor protocol addition must never make an older peer

package/dist/client.cjs

@@ -311,6 +311,29 @@ var CloseCode = {
 };
 var CloseCodeValue = import_zod3.z.literal([1e3, 1001, 1006, 1012, 1013, 4001, 4003, 4004, 4008, 4009, 4010, 4400, 4426]);
 
+// src/close-policy.ts
+var CLOSE_RULES = {
+  [CloseCode.NORMAL]: { action: "reconnect", error: ["DEVICE_OFFLINE", "Connection closed"] },
+  [CloseCode.GOING_AWAY]: { action: "reconnect_now", error: ["DEVICE_OFFLINE", "Connection lost"] },
+  [CloseCode.ABNORMAL]: { action: "reconnect_now", error: ["DEVICE_OFFLINE", "Connection lost"] },
+  [CloseCode.DEVICE_RECONNECTED]: { action: "reconnect_now", error: ["DEVICE_OFFLINE", "Device reconnected"] },
+  [CloseCode.TRY_AGAIN_LATER]: { action: "reconnect", error: ["DEVICE_OFFLINE", "Relay busy; retrying"] },
+  [CloseCode.AUTH_INVALID]: { action: "reauth", outcome: "signed_out", error: ["AUTH_INVALID", "Sign-in was not accepted"] },
+  [CloseCode.AUTH_FORBIDDEN]: { action: "stop", outcome: "not_owned", error: ["AUTH_FORBIDDEN", "Not this device's owner"] },
+  [CloseCode.DEVICE_NOT_FOUND]: { action: "stop", outcome: "removed", error: ["NOT_FOUND", "Device not found"] },
+  [CloseCode.AUTH_EXPIRED]: { action: "reauth", outcome: "signed_out", error: ["AUTH_EXPIRED", "Sign-in expired"] },
+  [CloseCode.REPLACED]: { action: "stop", outcome: "replaced", error: ["CONFLICT", "Replaced by a newer connection"] },
+  [CloseCode.DEVICE_REVOKED]: { action: "stop", outcome: "revoked", error: ["AUTH_DEVICE_REVOKED", "This device was revoked"] },
+  // A malformed message, or a connection the relay lost track of: a fresh socket starts clean.
+  [CloseCode.PROTOCOL_ERROR]: { action: "reconnect", error: ["PROTOCOL_ERROR", "Connection reset by the relay"] },
+  [CloseCode.UPGRADE_REQUIRED]: { action: "stop", outcome: "upgrade_required", error: ["PROTOCOL_VERSION_UNSUPPORTED", "Protocol upgrade required"] }
+};
+var UNKNOWN = { action: "reconnect", error: ["DEVICE_OFFLINE", "Connection lost"] };
+function closeRule(code) {
+  if (code === null || code === void 0) return CLOSE_RULES[CloseCode.ABNORMAL];
+  return CLOSE_RULES[code] ?? UNKNOWN;
+}
+
 // src/schema/frame.ts
 var import_zod4 = require("zod");
 var FrameHeader = import_zod4.z.strictObject({
@@ -646,7 +669,11 @@ var SessionControlChangedEvent = import_zod8.z.strictObject({ controller_client_
 var import_zod9 = require("zod");
 var RelayDeviceStatusEvent = import_zod9.z.strictObject({
   online: import_zod9.z.boolean(),
-  since_ms: epochMs,
+  /**
+   * When the device last went online/offline; null = it has never connected (since 1.1 —
+   * NULL_SINCE: a 1.0 reader is sent 0, its old meaning).
+   */
+  since_ms: epochMs.nullable(),
   app_version: import_zod9.z.string().max(32).nullable(),
   protocol_version: ProtocolVersion.nullable()
 });
@@ -728,13 +755,6 @@ var EVENTS = {
 
 // src/client/client.ts
 var WS_OPEN = 1;
-var TERMINAL_CLOSE = /* @__PURE__ */ new Map([
-  [CloseCode.DEVICE_REVOKED, ["AUTH_DEVICE_REVOKED", "This device was revoked"]],
-  [CloseCode.AUTH_FORBIDDEN, ["AUTH_FORBIDDEN", "Not this device's owner"]],
-  [CloseCode.DEVICE_NOT_FOUND, ["NOT_FOUND", "Device not found"]],
-  [CloseCode.REPLACED, ["CONFLICT", "Replaced by a newer connection"]],
-  [CloseCode.UPGRADE_REQUIRED, ["PROTOCOL_VERSION_UNSUPPORTED", "Protocol upgrade required"]]
-]);
 var defaultTimers = {
   setTimeout: (fn, ms) => globalThis.setTimeout(fn, ms),
   clearTimeout: (handle) => globalThis.clearTimeout(handle),
@@ -777,8 +797,10 @@ function createDesktopClient(options) {
     attempts: 0,
     retryInMs: null,
     lastError: null,
-    lastCloseCode: null
+    lastCloseCode: null,
+    outcome: null
   };
+  let authRefusals = 0;
   const listeners = /* @__PURE__ */ new Set();
   const readyWaiters = /* @__PURE__ */ new Set();
   const pending = /* @__PURE__ */ new Map();
@@ -813,6 +835,7 @@ function createDesktopClient(options) {
   }
   function connect() {
     if (state.status === "connecting" || state.status === "handshaking" || state.status === "open") return;
+    if (state.status === "closed" || state.status === "idle") authRefusals = 0;
     closedByUser = false;
     if (reconnectTimer !== null) {
       timers.clearTimeout(reconnectTimer);
@@ -894,8 +917,11 @@ function createDesktopClient(options) {
       timers.clearTimeout(probeTimer);
       probeTimer = null;
     }
-    const terminal = code === null ? void 0 : TERMINAL_CLOSE.get(code);
-    const lost = error ?? (terminal ? new DesktopProtocolError(terminal[0], terminal[1]) : new DesktopProtocolError("DEVICE_OFFLINE", "Connection lost", { retryable: true }));
+    const rule = code === null ? null : closeRule(code);
+    if (rule?.action === "reauth") authRefusals++;
+    const stopped = rule !== null && (rule.action === "stop" || rule.action === "reauth" && authRefusals >= 2);
+    const terminal = stopped && rule ? rule : void 0;
+    const lost = error ?? (terminal ? new DesktopProtocolError(terminal.error[0], terminal.error[1]) : rule && rule.action === "reauth" ? new DesktopProtocolError(rule.error[0], rule.error[1], { retryable: true }) : new DesktopProtocolError("DEVICE_OFFLINE", "Connection lost", { retryable: true }));
     for (const [id, p] of pending) {
       pending.delete(id);
       p.cleanup();
@@ -912,7 +938,14 @@ function createDesktopClient(options) {
       endStream(s, null, lost);
     }
     if (closedByUser || terminal) {
-      setState({ status: "closed", welcome: null, lastError: closedByUser ? state.lastError : lost, lastCloseCode: code, retryInMs: null });
+      setState({
+        status: "closed",
+        welcome: null,
+        lastError: closedByUser ? state.lastError : lost,
+        lastCloseCode: code,
+        retryInMs: null,
+        outcome: closedByUser ? null : terminal?.outcome ?? null
+      });
       rejectReadyWaiters(lost);
       return;
     }
@@ -1066,7 +1099,8 @@ function createDesktopClient(options) {
     }
     helloId = null;
     backoff.markConnected();
-    setState({ status: "open", welcome: welcome.data, attempts: 0, retryInMs: null, lastError: null });
+    authRefusals = 0;
+    setState({ status: "open", welcome: welcome.data, attempts: 0, retryInMs: null, lastError: null, outcome: null });
     for (const w of [...readyWaiters]) {
       readyWaiters.delete(w);
       w.resolve(welcome.data);