@tapflowio/relay 0.19.0 → 0.20.0

package/dist/RelayServer.d.ts

@@ -3,6 +3,10 @@ export declare function isExternalAddress(addr: string): boolean;
  *  a test carrying its own copy of the number passes when the constant moves, which is the drift the
  *  wire-contract work keeps finding. Not re-exported from the package index. */
 export declare const IDR_REQUEST_THROTTLE_MS = 500;
+/** The same window for `network:request-state`, and a **separate constant on purpose**: the two share
+ *  a number today and not a policy. IDR drops inside the window; this one coalesces onto its trailing
+ *  edge (see `networkStateRequester`). Sharing the constant would mean tuning one tunes the other. */
+export declare const NETWORK_STATE_REQUEST_THROTTLE_MS = 500;
 /**
  * The owner key a connection speaks for, from the authenticated user and the client id it claimed.
  *
@@ -72,6 +76,9 @@ export declare class RelayServer {
     private audioDropHandlers;
     private droppers;
     private idrRequesters;
+    /** Unlike `idrRequesters` these hold a timer, which is why the value is not a bare closure — see
+     *  `forgetSessionState`. */
+    private networkStateRequesters;
     private wsRoles;
     /** Per-socket throttle state for `logInboundRejection`. A `WeakMap` so a closed socket's entry goes
      *  with the socket — there is no cleanup to forget, unlike the maps keyed by session id nearby. */
@@ -134,8 +141,17 @@ export declare class RelayServer {
      * Pre-existing, and this slice is what makes it worth fixing here rather than filing: `idrRequesters`
      * used to be populated only by the binary drop path, i.e. only under backpressure, and a re-join now
      * creates an entry for any streaming session (#515). The leak went from rare to ordinary.
+     *
+     * **Now five maps, and the fifth is not dropped the same way.** `networkStateRequesters` holds a
+     * *coalescing* requester, so its closure owns a pending `setTimeout` — and deleting a map entry does
+     * not cancel a timer. Leaving it armed is not a leak but a double send: `session:leave` followed by a
+     * re-join inside the window fires the orphaned trailing edge *and* the new requester's leading edge,
+     * which is the second budget for one session that this map exists to prevent. Hence `dispose()`
+     * rather than `delete` alone. It was named `forgetSessionStreamState` while all four were stream
+     * records; the network requester is not one, so the name lost the word rather than the entry
+     * lost the function.
      */
-    private forgetSessionStreamState;
+    private forgetSessionState;
     /**
      * Throttled callback asking the session's agent for an on-demand IDR (fast drop recovery); ignored by
      * agents that don't support it.
@@ -148,6 +164,26 @@ export declare class RelayServer {
      * past the map. Measured: calling it directly from one caller left every test green.
      */
     private idrRequester;
+    /**
+     * Throttled callback asking the session's agent to re-read and report the device's network
+     * condition (#614); ignored by agents that don't support it.
+     *
+     * **Coalescing, where `idrRequester` above drops — and the difference is not a preference.** A
+     * dropped IDR request costs nothing: the next periodic keyframe repairs it. Nothing re-produces a
+     * `network:state`, so a request dropped inside the window leaves that viewer rendering "unknown"
+     * for the life of the session. The trailing edge fires after the last join in a burst, and the
+     * relay addresses the reply to whichever socket holds the session *when it arrives* — so the
+     * viewer that ends up watching is the one served, which a leading edge cannot promise.
+     *
+     * The burst this is for is the dirty blip, not two people: `join()` refuses a live holder, and a
+     * clean `session:leave` runs `forgetSessionState` and builds a fresh requester. A browser socket
+     * that dies in its close handler does neither, so `lastAt` survives into the re-join — which is
+     * the very path this slice exists to serve.
+     *
+     * One per session, constructed here, for the reason written on `idrRequester`: the throttle lives
+     * in the closure, so a second requester is a second budget.
+     */
+    private networkStateRequester;
     private remoteAddressOf;
     private warnProxyMisconfigOnce;
     private handleConnection;

package/dist/RelayServer.d.ts.map

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

package/dist/RelayServer.js

@@ -14,6 +14,7 @@ import { resolveClientAddress } from './lib/clientAddress.js';
 import { resolveCorsHeaders } from './lib/cors.js';
 import { isCsrfBlocked } from './lib/csrf.js';
 import { pickLanAddress } from './lib/lanAddress.js';
+import { createTrailingRequester, systemTimerScheduler } from './lib/trailingRequester.js';
 import { getDb } from './db.js';
 import { handleLogin, handleLogout, handleMe, handleChangePassword, handleInit, handleAuthStatus } from './api/auth.js';
 import { handleVerify, handleAccept } from './api/invitations.js';
@@ -43,6 +44,10 @@ export function isExternalAddress(addr) {
  *  a test carrying its own copy of the number passes when the constant moves, which is the drift the
  *  wire-contract work keeps finding. Not re-exported from the package index. */
 export const IDR_REQUEST_THROTTLE_MS = 500;
+/** The same window for `network:request-state`, and a **separate constant on purpose**: the two share
+ *  a number today and not a policy. IDR drops inside the window; this one coalesces onto its trailing
+ *  edge (see `networkStateRequester`). Sharing the constant would mean tuning one tunes the other. */
+export const NETWORK_STATE_REQUEST_THROTTLE_MS = 500;
 // Ping every socket each interval; a missed pong window (~2× this) terminates the dead socket.
 const HEARTBEAT_MS = 30_000;
 // How long a session outlives its agent's socket, waiting for that agent to come back (#426).
@@ -198,6 +203,9 @@ export class RelayServer {
     droppers = new Map();
     // Per-session throttled "request an IDR from the agent" callbacks (drop recovery).
     idrRequesters = new Map();
+    /** Unlike `idrRequesters` these hold a timer, which is why the value is not a bare closure — see
+     *  `forgetSessionState`. */
+    networkStateRequesters = new Map();
     wsRoles = new Map();
     /** Per-socket throttle state for `logInboundRejection`. A `WeakMap` so a closed socket's entry goes
      *  with the socket — there is no cleanup to forget, unlike the maps keyed by session id nearby. */
@@ -409,6 +417,14 @@ export class RelayServer {
         for (const timer of this.agentHolds.values())
             clearTimeout(timer);
         this.agentHolds.clear();
+        // Same argument one line up. **Not** because the send would land — `sendTo` drops a socket that is
+        // not OPEN, which is why `fire` carries no check of its own — but because `unref()` only excuses a
+        // timer from keeping the process alive, and the test runner's process outlives the server anyway.
+        // An armed edge therefore still runs, holding a closure over the session map of a relay that has
+        // already stopped.
+        for (const requester of this.networkStateRequesters.values())
+            requester.dispose();
+        this.networkStateRequesters.clear();
         return new Promise((resolve, reject) => {
             this.wss.clients.forEach((ws) => ws.terminate());
             this.wss.close(() => {
@@ -467,12 +483,23 @@ export class RelayServer {
      * Pre-existing, and this slice is what makes it worth fixing here rather than filing: `idrRequesters`
      * used to be populated only by the binary drop path, i.e. only under backpressure, and a re-join now
      * creates an entry for any streaming session (#515). The leak went from rare to ordinary.
+     *
+     * **Now five maps, and the fifth is not dropped the same way.** `networkStateRequesters` holds a
+     * *coalescing* requester, so its closure owns a pending `setTimeout` — and deleting a map entry does
+     * not cancel a timer. Leaving it armed is not a leak but a double send: `session:leave` followed by a
+     * re-join inside the window fires the orphaned trailing edge *and* the new requester's leading edge,
+     * which is the second budget for one session that this map exists to prevent. Hence `dispose()`
+     * rather than `delete` alone. It was named `forgetSessionStreamState` while all four were stream
+     * records; the network requester is not one, so the name lost the word rather than the entry
+     * lost the function.
      */
-    forgetSessionStreamState(sessionId) {
+    forgetSessionState(sessionId) {
         this.dropHandlers.delete(sessionId);
         this.audioDropHandlers.delete(sessionId);
         this.droppers.delete(sessionId);
         this.idrRequesters.delete(sessionId);
+        this.networkStateRequesters.get(sessionId)?.dispose();
+        this.networkStateRequesters.delete(sessionId);
     }
     /**
      * Throttled callback asking the session's agent for an on-demand IDR (fast drop recovery); ignored by
@@ -503,6 +530,48 @@ export class RelayServer {
         this.idrRequesters.set(sessionId, requester);
         return requester;
     }
+    /**
+     * Throttled callback asking the session's agent to re-read and report the device's network
+     * condition (#614); ignored by agents that don't support it.
+     *
+     * **Coalescing, where `idrRequester` above drops — and the difference is not a preference.** A
+     * dropped IDR request costs nothing: the next periodic keyframe repairs it. Nothing re-produces a
+     * `network:state`, so a request dropped inside the window leaves that viewer rendering "unknown"
+     * for the life of the session. The trailing edge fires after the last join in a burst, and the
+     * relay addresses the reply to whichever socket holds the session *when it arrives* — so the
+     * viewer that ends up watching is the one served, which a leading edge cannot promise.
+     *
+     * The burst this is for is the dirty blip, not two people: `join()` refuses a live holder, and a
+     * clean `session:leave` runs `forgetSessionState` and builds a fresh requester. A browser socket
+     * that dies in its close handler does neither, so `lastAt` survives into the re-join — which is
+     * the very path this slice exists to serve.
+     *
+     * One per session, constructed here, for the reason written on `idrRequester`: the throttle lives
+     * in the closure, so a second requester is a second budget.
+     */
+    networkStateRequester(sessionId) {
+        const existing = this.networkStateRequesters.get(sessionId);
+        if (existing)
+            return existing;
+        const requester = createTrailingRequester({
+            scheduler: systemTimerScheduler,
+            windowMs: NETWORK_STATE_REQUEST_THROTTLE_MS,
+            fire: () => {
+                const session = this.sessions.get(sessionId);
+                // `sendTo` already drops a socket that is not OPEN, so a closed agent needs no check here —
+                // an earlier draft duplicated it and no mutation could tell the copy from the original.
+                //
+                // The lookup is the guard that remains, and it should be unreachable: **every path that removes
+                // a session runs `forgetSessionState`, which disposes this timer.** It is kept as the cheap half
+                // of that pair rather than as a live case — a trailing edge is the one call here that outlives
+                // the statement scheduling it, so the invariant holding is worth not assuming.
+                if (session)
+                    this.sendTo(session.agentSocket, { type: 'network:request-state', sessionId });
+            },
+        });
+        this.networkStateRequesters.set(sessionId, requester);
+        return requester;
+    }
     // Extracted so tests can simulate non-loopback origins (all test traffic is loopback).
     remoteAddressOf(request) {
         return request.socket.remoteAddress ?? '';
@@ -705,7 +774,7 @@ export class RelayServer {
      */
     settleRole(ws, inbound) {
         // Every reason that carries a type, which is all of them but the two that have none to carry.
-        // Missing `bad-payload` here returned `false` before the caller could answer, so the twelve
+        // Missing `bad-payload` here returned `false` before the caller could answer, so the thirteen
         // answerable requests were classified correctly and then dropped anyway — the regression this
         // whole path exists to prevent, reintroduced one line above it.
         const type = inbound.ok ? inbound.msg.type
@@ -842,14 +911,14 @@ export class RelayServer {
             case 'session:end': {
                 if (this.ownsSession(ws, this.sessions.get(msg.sessionId))) {
                     this.sessions.remove(msg.sessionId);
-                    this.forgetSessionStreamState(msg.sessionId);
+                    this.forgetSessionState(msg.sessionId);
                 }
                 break;
             }
             case 'session:leave': {
                 if (this.ownsSession(ws, this.sessions.get(msg.sessionId))) {
                     this.sessions.clearBrowser(msg.sessionId);
-                    this.forgetSessionStreamState(msg.sessionId);
+                    this.forgetSessionState(msg.sessionId);
                 }
                 break;
             }
@@ -962,6 +1031,11 @@ export class RelayServer {
             // Bound to the session's own agent socket, unlike the replies above: this payload
             // lands on the viewer's host OS clipboard, so a second agent (another Mac on the
             // same relay) must not be able to address someone else's session.
+            // Bound to the session's own agent socket for the same reason clipboard is: this reply says
+            // whether a **specific tester's** device is on the network, and a second agent must not be
+            // able to tell that tester's viewer something about it.
+            case 'network:state':
+            case 'network:error':
             case 'clipboard:data':
             case 'clipboard:write-done':
             case 'clipboard:error': {
@@ -1183,6 +1257,22 @@ export class RelayServer {
                 }
                 break;
             }
+            // Ownership is not decoration here: taking a device off the network is the most disruptive
+            // thing a non-holder could do to someone else's session short of shutting it down, and unlike
+            // a shutdown it leaves the device *looking* fine. `dispatchTarget` rather than the weaker
+            // `reachableTarget` `device:shutdown` uses — there is no teardown race to accommodate.
+            case 'network:set': {
+                const net = this.dispatchTarget(ws, msg.sessionId);
+                if (net.ok) {
+                    net.session.agentSocket.send(JSON.stringify(msg));
+                }
+                else if (ws.readyState === WebSocket.OPEN) {
+                    this.sendTo(ws, {
+                        type: 'network:error', sessionId: msg.sessionId, requestId: msg.requestId, message: net.message,
+                    });
+                }
+                break;
+            }
         }
     }
     handleAgentResources(ws, msg) {
@@ -1313,7 +1403,7 @@ export class RelayServer {
         }
         for (const s of agentSessions) {
             this.sessions.remove(s.id);
-            this.forgetSessionStreamState(s.id);
+            this.forgetSessionState(s.id);
         }
         this.sessions.removeResources(ws);
         logger.info(cause === 'replaced'
@@ -1389,7 +1479,7 @@ export class RelayServer {
                     this.sendTo(s.browserSocket, { type: 'session:terminated', sessionId: s.id, reason: 'agent-disconnected' });
                 }
                 this.sessions.remove(s.id);
-                this.forgetSessionStreamState(s.id);
+                this.forgetSessionState(s.id);
             }
         }
         // Only devices without a surviving session get a new one. Passing all of them here is what
@@ -1535,6 +1625,27 @@ export class RelayServer {
             // backpressure path already throttles this exact message per session; sharing that requester is
             // what keeps the two callers from having two policies.
             this.idrRequester(session.id)();
+            // And ask what the device's network is doing (#614). `NetworkState` is agent-produced and is not
+            // among the three replayed above, so without this a viewer that reconnects has no way to learn
+            // whether the device is offline and its control renders in a guessed position.
+            //
+            // **Gated on the capability, unlike the IDR request beside it.** That one is safe to send blind
+            // because an agent without it loses nothing — the next periodic keyframe arrives anyway. This one
+            // has no such repair, so an agent that never answers is indistinguishable from one that failed to
+            // read; a viewer arming a deadline would then render "could not read" on every re-join, for an
+            // agent that already said it cannot do this at all. iOS is exactly that agent until #607's last
+            // slice. Fifty lines up, `session:joined` carries these capabilities for the stated reason that a
+            // consumer must not infer support from a timeout — asking anyway would make the relay do it.
+            //
+            // **Inside `readySent` too, and there as an optimisation rather than a correctness condition.**
+            // `readySent` is the *stream's* readiness: `clearStreamSocket` lowers it while `deviceStatus`
+            // stays `'booted'`, so a booted, genuinely offline device with a dead stream socket is not asked
+            // about here — and the agent would have answered, since it still holds that serial. What makes
+            // skipping safe is not the agent's silence but the viewer's: with `readySent` false the
+            // `device:ready` above is not replayed either, so nothing is rendering a live device to be wrong
+            // about. `deviceStatus` is not the fix — the comment on `device:ready` says why (#440).
+            if (session.agentCapabilities?.includes('network-control'))
+                this.networkStateRequester(session.id)();
         }
     }
     /** Shut the device down because nobody is watching it any more. The idle timer's payload, hoisted out
@@ -1775,8 +1886,11 @@ export class RelayServer {
             case 'clipboard:write':
                 this.sendTo(ws, { type: 'clipboard:error', sessionId, requestId, message });
                 break;
+            case 'network:set':
+                this.sendTo(ws, { type: 'network:error', sessionId, requestId, message });
+                break;
             // The four remaining acked inputs. A `default` rather than four labels because the union is
-            // closed and exhaustive: adding a thirteenth answerable request without a case here would land
+            // closed and exhaustive: adding a fourteenth answerable request without a case here would land
             // it on `input:error`, which `answerableRequestsAnswered` is what stops.
             default:
                 this.sendTo(ws, { type: 'input:error', sessionId, requestId, message, reason: 'malformed' });