@serfab/cadre-core 0.6.0 → 0.8.1

package/src/push-fanout.ts

@@ -0,0 +1,272 @@
+/**
+ * push-fanout.ts — the server-side push-wake **trigger policy + fan-out**.
+ *
+ * The delivery half (`push-notifier.ts`) knows *how* to send one strand-wake to
+ * one device; this module owns *who* to wake and *when*. On strand activity it
+ * enumerates the cadre's hibernating mobile members, prefers a direct
+ * control-network `pushWake`, falls back to FCM/APNs platform push only when the
+ * direct dial cannot reach the (suspended) peer, and dedups/cooldowns per
+ * `(peer, strand)` so a chatty strand cannot spam wakes.
+ *
+ * It owns no transport and no DB access: every node primitive (member
+ * enumeration, participation check, direct dial, token resolve, stale-token
+ * expiry) and the `PushNotifier` are injected, so the whole policy is unit-tested
+ * with fakes and never throws to its trigger (a dropped wake is recoverable — the
+ * hibernation check-in wake is the backstop).
+ *
+ * Cross-platform-clean by construction: it imports only the `PushNotifier`
+ * *type* (erased at emit) and the dependency-free `STRAND_WAKE_TYPE` value, so it
+ * carries no `node:http2`/`node:crypto` edge. The Node-only notifier is built by
+ * `CadreNode` (via a guarded dynamic import) and injected here.
+ */
+
+import debug from 'debug';
+import type { StrandInstance, WakeAck, DeviceTokenRecord } from './types.js';
+import type { PushNotifier } from './push-notifier.js';
+import { STRAND_WAKE_TYPE } from './strand-wake-payload.js';
+
+const log = debug('sereus:cadre:push-fanout');
+
+/** Default per-`(peer, strand)` minimum gap between wakes. */
+export const DEFAULT_PUSH_COOLDOWN_MS = 5 * 60_000;
+/** Default per-strand burst-coalescing window. */
+export const DEFAULT_PUSH_DEBOUNCE_MS = 10_000;
+
+/** A cadre member as returned by {@link CadreNode.listMembers}. */
+export interface FanoutMember {
+  peerId: string;
+  multiaddr: string | null;
+}
+
+/**
+ * Everything {@link PushFanoutService} needs, injected so the policy is pure and
+ * testable. The node-bound implementations live on {@link CadreNode}; the
+ * `notifier` is a {@link PushNotifier} built from `config.push`.
+ */
+export interface PushFanoutOptions {
+  /** Enumerate the cadre's `CadrePeer` membership (every party node). */
+  listMembers: () => Promise<FanoutMember[]>;
+  /**
+   * The local strand instance for `strandId`, or `undefined` when this node does
+   * not participate — the participation gate (never push for a strand we cannot
+   * vouch for).
+   */
+  getStrand: (strandId: string) => StrandInstance | undefined;
+  /** This node's own peerId, excluded from every fan-out (never wake self). */
+  selfPeerId: () => string | undefined;
+  /**
+   * Direct control-network push-wake. Resolves to a {@link WakeAck} when the dial
+   * REACHED the peer (whatever the peer then decided); REJECTS only on a
+   * dial/transport failure (no dialable address / timeout ⇒ the phone is
+   * suspended), which is what triggers the platform-push fallback.
+   */
+  pushWake: (peerId: string, strandId: string, reason?: string) => Promise<WakeAck>;
+  /** Resolve a peer's FCM/APNs token; `null` ⇒ not a registered mobile peer. */
+  resolveDeviceToken: (peerId: string) => Promise<DeviceTokenRecord | null>;
+  /**
+   * Expire a peer's stale `DeviceToken` after a platform reports it unregistered.
+   * Authority nodes delete the row; non-authority nodes only log (the in-memory
+   * dead-token set below is what actually stops re-pushing this process).
+   */
+  expireDeviceToken: (peerId: string) => Promise<void>;
+  /** Platform-push delivery seam (FCM/APNs router). */
+  notifier: PushNotifier;
+  /** Monotonic clock (epoch ms); injectable for deterministic cooldown/debounce tests. */
+  now?: () => number;
+  /** Per-`(peer, strand)` minimum gap. Default {@link DEFAULT_PUSH_COOLDOWN_MS}. */
+  cooldownMs?: number;
+  /** Per-strand burst coalescing. Default {@link DEFAULT_PUSH_DEBOUNCE_MS}. */
+  debounceMs?: number;
+}
+
+/**
+ * Server-side push-wake fan-out (see module header). One per participating
+ * {@link CadreNode}, constructed only when push credentials are configured.
+ */
+export class PushFanoutService {
+  private readonly deps: PushFanoutOptions;
+  private readonly now: () => number;
+  private readonly cooldownMs: number;
+  private readonly debounceMs: number;
+
+  /** Per-strand leading-edge debounce: last fan-out start time (epoch ms). */
+  private readonly lastFanoutAt = new Map<string, number>();
+  /** Per-strand in-flight pass, so two near-simultaneous triggers coalesce into one. */
+  private readonly inFlight = new Map<string, Promise<void>>();
+  /** Per-`(peer, strand)` last-wake time (epoch ms); the anti-spam cooldown. */
+  private readonly cooldownAt = new Map<string, number>();
+  /**
+   * Peers whose `DeviceToken` a platform reported unregistered. Consulted before
+   * every resolve→send so we stop pushing to a dead token. In-memory and
+   * acceptably lossy: a restart re-learns staleness on the next failed send.
+   */
+  private readonly deadTokens = new Set<string>();
+
+  constructor(options: PushFanoutOptions) {
+    this.deps = options;
+    this.now = options.now ?? (() => Date.now());
+    this.cooldownMs = options.cooldownMs ?? DEFAULT_PUSH_COOLDOWN_MS;
+    this.debounceMs = options.debounceMs ?? DEFAULT_PUSH_DEBOUNCE_MS;
+  }
+
+  /**
+   * Fan a wake out to the cadre's hibernating mobile members for a strand that
+   * just saw activity. Best-effort: never throws to the trigger (the check-in
+   * wake is the backstop). No-ops when this node does not participate in the
+   * strand, when the strand was already fanned out within `debounceMs`, or — by
+   * joining — when a pass for the strand is already in flight.
+   *
+   * @param strandId - the strand whose activity should wake hibernating peers.
+   * @param reason - free-form cause hint carried in the wake (default `activity`).
+   */
+  async notify(strandId: string, reason = 'activity'): Promise<void> {
+    try {
+      // 1. Participation gate — never push for a strand we do not participate in.
+      if (!this.deps.getStrand(strandId)) {
+        log('notify: not participating in strand %s; no-op', strandId);
+        return;
+      }
+
+      // Concurrent trigger coalescing: a second near-simultaneous notify joins the
+      // in-flight pass rather than enumerating + sending again (mirrors
+      // CadreNode.serviceWakePromises). The stored promise is guarded (see below),
+      // so a joiner that adopts it via `return inflight` never observes a rejection
+      // — the "never throws to the trigger" guarantee holds on the join path too
+      // (a rejection here would otherwise escape this try/catch, since the returned
+      // promise settles in the caller's `void notify(...)` context).
+      const inflight = this.inFlight.get(strandId);
+      if (inflight) {
+        log('notify: joining in-flight fan-out for strand %s', strandId);
+        return inflight;
+      }
+
+      // 2. Per-strand debounce — coalesce bursts after a pass has completed.
+      const now = this.now();
+      const last = this.lastFanoutAt.get(strandId);
+      if (last !== undefined && now - last < this.debounceMs) {
+        log('notify: debounced fan-out for strand %s', strandId);
+        return;
+      }
+
+      this.lastFanoutAt.set(strandId, now);
+      // Guard the pass so neither the originator nor a concurrent joiner can see a
+      // rejection (e.g. listMembers throwing on a control-DB hiccup): a dropped
+      // fan-out is recoverable via the check-in wake backstop.
+      const op = this.runFanout(strandId, reason).catch((error) => {
+        log('notify: fan-out pass for strand %s failed (best-effort): %o', strandId, error);
+      });
+      this.inFlight.set(strandId, op);
+      try {
+        await op;
+      } finally {
+        this.inFlight.delete(strandId);
+      }
+    } catch (error) {
+      // The trigger must never see a throw — failures are logged best-effort.
+      log('notify: fan-out for strand %s failed (best-effort): %o', strandId, error);
+    }
+  }
+
+  /** Release the notifier's transport resources (e.g. the APNs HTTP/2 session). */
+  async close(): Promise<void> {
+    await this.deps.notifier.close();
+  }
+
+  /**
+   * One fan-out pass: enumerate members, drop self and any peer still cooling
+   * down for this strand, and wake the survivors concurrently. Each
+   * {@link wakePeer} is self-contained (never rejects), so one peer's failure
+   * never aborts the others.
+   */
+  private async runFanout(strandId: string, reason: string): Promise<void> {
+    const members = await this.deps.listMembers();
+    const self = this.deps.selfPeerId();
+    const targets = members.filter(
+      (m) => m.peerId !== self && !this.isCoolingDown(m.peerId, strandId)
+    );
+    log('fanout: strand %s — %d candidate(s) after self/cooldown filter', strandId, targets.length);
+    await Promise.all(targets.map((m) => this.wakePeer(m.peerId, strandId, reason)));
+  }
+
+  /**
+   * Wake one candidate: try the direct control-network dial first, falling back
+   * to a platform push only when the dial cannot reach the (suspended) peer.
+   *
+   * A resolved {@link WakeAck} means the control path REACHED the peer — even an
+   * ack with `accepted:false` (the receiver declined, e.g. non-member/unknown
+   * strand) counts as reached, so we do NOT also send a platform push (that would
+   * double-wake). Only a dial/transport REJECTION means the phone is suspended
+   * and unreachable over the control network, which is the one case that falls
+   * through to FCM/APNs.
+   */
+  private async wakePeer(peerId: string, strandId: string, reason: string): Promise<void> {
+    // A wake of either kind is now being attempted → arm the cooldown up front.
+    this.markCooldown(peerId, strandId);
+
+    try {
+      const ack = await this.deps.pushWake(peerId, strandId, reason);
+      log(
+        'wakePeer: direct pushWake reached %s for strand %s (accepted=%s); no platform fallback',
+        peerId, strandId, ack.accepted
+      );
+      return;
+    } catch (error) {
+      // Dial/transport failure ⇒ suspended phone ⇒ fall through to platform push.
+      log('wakePeer: direct pushWake could not reach %s; trying platform push: %o', peerId, error);
+    }
+
+    try {
+      await this.platformPush(peerId, strandId, reason);
+    } catch (error) {
+      log('wakePeer: platform push for %s failed (best-effort): %o', peerId, error);
+    }
+  }
+
+  /**
+   * Deliver a platform push (FCM/APNs) to a suspended peer. Skips a peer with a
+   * known-dead token, no-ops for a non-mobile peer (`resolveDeviceToken` → null),
+   * and — on an `unregistered` send — marks the token dead and expires the row.
+   */
+  private async platformPush(peerId: string, strandId: string, reason: string): Promise<void> {
+    if (this.deadTokens.has(peerId)) {
+      log('platformPush: %s has a known-stale token; skipping resolve→send', peerId);
+      return;
+    }
+
+    const record = await this.deps.resolveDeviceToken(peerId);
+    if (!record) {
+      log('platformPush: %s is not a registered mobile peer; no platform push', peerId);
+      return;
+    }
+
+    const result = await this.deps.notifier.send({
+      token: record.token,
+      platform: record.platform,
+      payload: { type: STRAND_WAKE_TYPE, strandId, reason },
+    });
+
+    if (!result.ok && result.unregistered) {
+      // Permanently-invalid token: stop pushing to it this process (the set), and
+      // expire the row (authority delete; non-authority logs re-registration).
+      this.deadTokens.add(peerId);
+      await this.deps.expireDeviceToken(peerId);
+      log('platformPush: expired stale token for %s (platform=%s)', peerId, record.platform);
+    }
+  }
+
+  /** Whether `peerId` was woken for `strandId` within `cooldownMs`. */
+  private isCoolingDown(peerId: string, strandId: string): boolean {
+    const last = this.cooldownAt.get(cooldownKey(peerId, strandId));
+    return last !== undefined && this.now() - last < this.cooldownMs;
+  }
+
+  /** Arm the per-`(peer, strand)` cooldown at the current clock time. */
+  private markCooldown(peerId: string, strandId: string): void {
+    this.cooldownAt.set(cooldownKey(peerId, strandId), this.now());
+  }
+}
+
+/** Composite key for the per-`(peer, strand)` cooldown map. */
+function cooldownKey(peerId: string, strandId: string): string {
+  return `${peerId}${strandId}`;
+}

package/src/push-notifier-apns.ts

@@ -0,0 +1,243 @@
+/**
+ * push-notifier-apns.ts — APNs HTTP/2 strand-wake delivery.
+ *
+ * Server-only: signs a provider JWT (ES256, JOSE raw r‖s via `node:crypto`) and
+ * sends a background data push over an HTTP/2 session to Apple's gateway.
+ *
+ * The HTTP/2 call is behind an injected `Http2Requester` seam (bundled with a
+ * `close` into an {@link ApnsTransport}) so unit tests assert the request shape
+ * and map every documented response code with no real network and no credentials.
+ * The default transport owns a single lazily-(re)established `node:http2` session.
+ *
+ * Two single-shot retries guard transient failure without a retry storm: a
+ * thrown transport error (session death / GOAWAY mid-send) re-establishes the
+ * session and retries the one request once; a 403 `ExpiredProviderToken`
+ * re-mints the provider JWT and retries once. A second failure is returned as-is.
+ *
+ * Secret hygiene: the `.p8` `privateKey`, the minted JWT, and full device tokens
+ * are never logged — failure log lines carry only a status/reason and a redacted
+ * token prefix.
+ */
+
+// Namespace import (not `import { sign }`): a *named* import of the
+// browser-externalized `node:crypto` hard-fails the web build, whereas a
+// namespace import only warns — same reasoning as the `node:http2` import below
+// and the matching note in push-notifier-fcm.ts. Server-only; never run in browser.
+import * as nodeCrypto from 'node:crypto';
+import * as http2 from 'node:http2';
+import debug from 'debug';
+import type { ApnsCredentials } from './types.js';
+import type { PushMessage, PushNotifier, PushSendResult } from './push-notifier.js';
+import { MAX_REASON_LEN, b64urlJson, errText, redact } from './push-notifier-shared.js';
+
+const APNS_PROD_HOST = 'https://api.push.apple.com';
+const APNS_SANDBOX_HOST = 'https://api.sandbox.push.apple.com';
+/** Apple requires the provider token be 20–60 min old; refresh well inside that. */
+const PROVIDER_TOKEN_TTL_MS = 45 * 60_000;
+
+const debugApns = debug('sereus:cadre:push:apns');
+
+/** Raw HTTP/2 response: APNs `:status` and the (possibly empty) JSON body. */
+export interface ApnsResponse {
+  status: number;
+  body: string;
+}
+
+/** A single APNs HTTP/2 request — `:path`, headers, and the JSON body. */
+export interface ApnsRequest {
+  /** `:path`, e.g. `/3/device/{token}`. */
+  path: string;
+  headers: Record<string, string>;
+  body: string;
+}
+
+/**
+ * Low-level HTTP/2 request seam. Resolves with the `(status, body)` pair; rejects
+ * (throws) on a session/transport failure so the caller can re-establish + retry.
+ */
+export type Http2Requester = (req: ApnsRequest) => Promise<ApnsResponse>;
+
+/** The HTTP/2 request seam plus its session-teardown. */
+export interface ApnsTransport {
+  request: Http2Requester;
+  close(): Promise<void>;
+}
+
+export interface ApnsPushDeps {
+  /** HTTP/2 transport. Defaults to a real `node:http2` session manager. */
+  transport?: ApnsTransport;
+  /** Monotonic clock (ms). Defaults to `Date.now`. Injected for token-cache tests. */
+  now?: () => number;
+  /** Failure log seam (default: `debug('sereus:cadre:push:apns')`). */
+  log?: (line: string) => void;
+}
+
+/** A cached provider JWT and the wall-clock ms after which to refresh it. */
+interface CachedProviderToken {
+  value: string;
+  expiresAt: number;
+}
+
+export function createApnsPushNotifier(creds: ApnsCredentials, deps: ApnsPushDeps = {}): PushNotifier {
+  const host = creds.production ? APNS_PROD_HOST : APNS_SANDBOX_HOST;
+  const transport = deps.transport ?? createHttp2Transport(host);
+  const now = deps.now ?? (() => Date.now());
+  const log = deps.log ?? ((line: string) => debugApns(line));
+
+  let cached: CachedProviderToken | null = null;
+
+  async function send(msg: PushMessage): Promise<PushSendResult> {
+    let jwt: string;
+    try {
+      jwt = providerToken(false);
+    } catch (err) {
+      log(`provider-token mint failed: ${errText(err)}`);
+      return { ok: false, unregistered: false, error: `apns jwt mint failed: ${errText(err)}` };
+    }
+
+    let res = await tryRequest(msg, jwt);
+    if (!res) return { ok: false, unregistered: false, error: `apns transport failed (token=${redact(msg.token)})` };
+
+    // Provider token expired mid-flight — re-mint once and retry the single send.
+    if (res.status === 403 && /ExpiredProviderToken/i.test(res.body)) {
+      try {
+        jwt = providerToken(true);
+      } catch (err) {
+        log(`provider-token re-mint failed: ${errText(err)}`);
+        return { ok: false, unregistered: false, error: `apns jwt re-mint failed: ${errText(err)}` };
+      }
+      res = await tryRequest(msg, jwt);
+      if (!res) return { ok: false, unregistered: false, error: `apns transport failed (token=${redact(msg.token)})` };
+    }
+    return mapResult(res, msg.token);
+  }
+
+  /**
+   * Send one request with a single re-establish-on-throw retry. A thrown error is
+   * a session death / GOAWAY; the default transport recreates its session lazily
+   * on the next call, so a second attempt rides a fresh session. Returns `null`
+   * when both attempts throw.
+   */
+  async function tryRequest(msg: PushMessage, jwt: string): Promise<ApnsResponse | null> {
+    const req = buildRequest(msg, jwt);
+    try {
+      return await transport.request(req);
+    } catch (err1) {
+      log(`http2 request failed, re-establishing once: ${errText(err1)}`);
+      try {
+        return await transport.request(req);
+      } catch (err2) {
+        log(`http2 request failed after re-establish: ${errText(err2)}`);
+        return null;
+      }
+    }
+  }
+
+  function mapResult(res: ApnsResponse, deviceToken: string): PushSendResult {
+    if (res.status === 200) return { ok: true };
+    const reason = apnsReason(res.body);
+    const summary = `apns ${res.status}${reason ? ` ${reason}` : ''}`;
+    if (res.status === 410 || reason === 'Unregistered' || (res.status === 400 && reason === 'BadDeviceToken')) {
+      log(`unregistered token=${redact(deviceToken)} (${summary})`);
+      return { ok: false, unregistered: true, error: summary };
+    }
+    log(`send failed token=${redact(deviceToken)} (${summary})`);
+    return { ok: false, unregistered: false, error: summary };
+  }
+
+  function buildRequest(msg: PushMessage, jwt: string): ApnsRequest {
+    const body = JSON.stringify({
+      aps: { 'content-available': 1 },
+      type: msg.payload.type,
+      strandId: msg.payload.strandId,
+      reason: msg.payload.reason.slice(0, MAX_REASON_LEN),
+    });
+    return {
+      path: `/3/device/${msg.token}`,
+      headers: {
+        authorization: `bearer ${jwt}`,
+        'apns-topic': creds.bundleId,
+        'apns-push-type': 'background',
+        'apns-priority': '5',
+        'apns-expiration': '0',
+      },
+      body,
+    };
+  }
+
+  function providerToken(forceRefresh: boolean): string {
+    if (!forceRefresh && cached && cached.expiresAt > now()) return cached.value;
+    const iat = Math.floor(now() / 1000);
+    const header = { alg: 'ES256', kid: creds.keyId };
+    const claims = { iss: creds.teamId, iat };
+    const signingInput = `${b64urlJson(header)}.${b64urlJson(claims)}`;
+    const sig = nodeCrypto.sign('SHA256', Buffer.from(signingInput), {
+      key: creds.privateKey,
+      dsaEncoding: 'ieee-p1363',
+    }).toString('base64url');
+    const jwt = `${signingInput}.${sig}`;
+    cached = { value: jwt, expiresAt: now() + PROVIDER_TOKEN_TTL_MS };
+    return jwt;
+  }
+
+  async function close(): Promise<void> {
+    cached = null;
+    await transport.close();
+  }
+
+  return { send, close };
+}
+
+/**
+ * Default {@link ApnsTransport}: a single lazily-(re)established `node:http2`
+ * session to Apple's gateway. A session that errors / receives GOAWAY / closes is
+ * dropped so the next request re-establishes it. Not exercised by unit tests (no
+ * network) — tests inject a fake transport; the real path is validated out-of-band.
+ */
+function createHttp2Transport(host: string): ApnsTransport {
+  let session: http2.ClientHttp2Session | null = null;
+
+  function ensureSession(): http2.ClientHttp2Session {
+    if (session && !session.closed && !session.destroyed) return session;
+    const s = http2.connect(host);
+    // Drop a dead session so ensureSession recreates it on the next request.
+    s.on('error', () => { if (session === s) session = null; });
+    s.on('goaway', () => { s.destroy(); });
+    s.on('close', () => { if (session === s) session = null; });
+    session = s;
+    return s;
+  }
+
+  async function request(req: ApnsRequest): Promise<ApnsResponse> {
+    const s = ensureSession();
+    return await new Promise<ApnsResponse>((resolve, reject) => {
+      const stream = s.request({ ':method': 'POST', ':path': req.path, ...req.headers });
+      const chunks: Buffer[] = [];
+      let status = 0;
+      stream.on('response', (headers) => { status = Number(headers[':status'] ?? 0); });
+      stream.on('data', (chunk: Buffer) => chunks.push(chunk));
+      stream.on('end', () => resolve({ status, body: Buffer.concat(chunks).toString('utf8') }));
+      stream.on('error', (err) => reject(err));
+      stream.end(req.body);
+    });
+  }
+
+  async function close(): Promise<void> {
+    const s = session;
+    session = null;
+    if (s) await new Promise<void>((resolve) => s.close(() => resolve()));
+  }
+
+  return { request, close };
+}
+
+/** Extract the APNs error `reason` field from a response body, if present. */
+function apnsReason(body: string): string | null {
+  if (!body) return null;
+  try {
+    const parsed = JSON.parse(body) as { reason?: unknown };
+    return typeof parsed.reason === 'string' ? parsed.reason : null;
+  } catch {
+    return null;
+  }
+}