@nelsonlongxiang/dsh-open-a2a-net 0.6.28 → 0.6.30

package/lib/faces/canvas-notify.js

@@ -0,0 +1,138 @@
+/** Coalesce a burst of store writes (a drag that adds three members) into one ping. */
+export const CANVAS_NOTIFY_DEBOUNCE_MS = 400;
+/** A peer's pings refresh its card at most this often. */
+export const CANVAS_REFRESH_MIN_GAP_MS = 1_000;
+const SEND_TIMEOUT_MS = 5_000;
+/**
+ * Re-read one peer's card now. Each pass pre-stales the entry (the literal
+ * carries no missAt) so it is a GENUINE refetch: pass 1 may join a flight
+ * that started before the peer's change; pass 2 always starts after the
+ * first settled — that one is the answer. A miss keeps the last good card
+ * inside cachedCardFetch itself (the missAt window); there is nothing to
+ * restore here.
+ * @param d - the card cache and its single-flight fetch.
+ * @param url - the tracked peer URL.
+ */
+export async function refreshPeerCard(d, url) {
+    for (let pass = 0; pass < 2; pass += 1) {
+        const hit = d.cardCache.get(url);
+        if (hit !== undefined)
+            d.cardCache.set(url, { at: 0, card: hit.card });
+        await d.cachedCardFetch(url);
+    }
+}
+/**
+ * Register the receive face and subscribe the send side to the canvas store.
+ * @param webServer - the settled host web server.
+ * @param d - the captures listed on {@link CanvasNotifyDeps}.
+ */
+export function registerCanvasNotify(webServer, d) {
+    const { ctx, logger, peerStore, canvasStore, originClaimHeaders, verifyOriginClaim, callerLinkedToThisHost } = d;
+    // ── send ──
+    let timer;
+    const recipients = () => peerStore.list().filter(url => {
+        const card = d.cardCache.get(url)?.card;
+        // The card face's own predicate (bare-zone caller, as originClaimHeaders
+        // signs it): only a peer that is served the full card ever sees canvasOrg.
+        return card !== undefined && callerLinkedToThisHost(card.team, url, card);
+    });
+    const flush = () => {
+        timer = undefined;
+        for (const url of recipients()) {
+            void globalThis.fetch(url.replace(/\/$/, '') + '/a2a/canvas-changed', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json', ...originClaimHeaders() },
+                body: '{}',
+                signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+            }).then(async (reply) => {
+                const out = await reply.json().catch(() => undefined);
+                if (out?.ok !== true)
+                    logger.debug(`a2a: canvas-changed ping to ${url} not taken: ${String(out?.error ?? `HTTP ${String(reply.status)}`)}`);
+            }, (error) => {
+                // A down peer re-reads the card on its own TTL once it is back.
+                logger.debug(`a2a: canvas-changed ping to ${url} failed: ${error instanceof Error ? error.message : String(error)}`);
+            });
+        }
+    };
+    ctx.effect(() => canvasStore.onChange(() => {
+        if (timer === undefined)
+            timer = setTimeout(flush, CANVAS_NOTIFY_DEBOUNCE_MS);
+    }), 'a2a: canvas change notifier');
+    ctx.effect(() => () => {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+    }, 'a2a: canvas change notifier timer');
+    // ── receive ──
+    const lastRefresh = new Map();
+    const trailing = new Map();
+    const refresh = (url) => {
+        lastRefresh.set(url, Date.now());
+        void refreshPeerCard(d, url);
+    };
+    let disposed = false;
+    ctx.effect(() => () => {
+        disposed = true;
+        for (const handle of trailing.values())
+            clearTimeout(handle);
+        trailing.clear();
+    }, 'a2a: canvas-changed trailing refreshes');
+    ctx.effect(() => webServer.register({
+        kind: 'exact',
+        path: '/a2a/canvas-changed',
+        handler: (req, res) => {
+            const send = (payload) => {
+                const text = JSON.stringify(payload);
+                res.writeHead(200, { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(text) });
+                res.end(text);
+            };
+            // The ping has no content: drain a small body without buffering it,
+            // and cut off anything larger.
+            let size = 0;
+            req.on('data', (chunk) => { size += chunk.length; if (size > 4 * 1024)
+                req.destroy(); });
+            req.on('end', () => {
+                void (async () => {
+                    if (req.method !== 'POST') {
+                        send({ ok: false, error: 'POST required' });
+                        return;
+                    }
+                    // Tracked first, from the claimed URL: it must BE a tracked peer URL
+                    // whose card is already cached, so verifying the claim never fetches
+                    // anything a caller chose (no stranger host, no path on a peer).
+                    const claimed = String(req.headers['x-a2a-caller-url'] ?? '').replace(/\/$/, '');
+                    const tracked = claimed === '' ? [] : peerStore.list().filter(url => url.replace(/\/$/, '') === claimed && d.cardCache.get(url)?.card !== undefined);
+                    if (tracked.length === 0) {
+                        send({ ok: false, error: 'caller is not a tracked peer of this host' });
+                        return;
+                    }
+                    const claim = await verifyOriginClaim(req);
+                    if (!claim.ok) {
+                        send({ ok: false, error: `untrusted-origin: OriginClaim verification failed (${claim.reason})` });
+                        return;
+                    }
+                    if (disposed) {
+                        send({ ok: false, error: 'host is shutting down' });
+                        return;
+                    }
+                    // Rate limit without losing an update: a ping inside the gap is
+                    // deferred to one trailing refresh at the gap's end, never dropped.
+                    let refreshed = 0;
+                    let deferred = 0;
+                    for (const url of tracked) {
+                        const wait = CANVAS_REFRESH_MIN_GAP_MS - (Date.now() - (lastRefresh.get(url) ?? 0));
+                        if (wait <= 0) {
+                            refresh(url);
+                            refreshed += 1;
+                            continue;
+                        }
+                        deferred += 1;
+                        if (!trailing.has(url))
+                            trailing.set(url, setTimeout(() => { trailing.delete(url); refresh(url); }, wait));
+                    }
+                    send({ ok: true, refreshed, deferred });
+                })();
+            });
+        },
+    }), 'a2a: canvas-changed peer route');
+}