@fairfox/polly 0.67.0 → 0.70.0

package/dist/src/shared/lib/mesh-diagnostics.d.ts

@@ -0,0 +1,98 @@
+/**
+ * mesh-diagnostics — typed event stream for observable mesh failures and
+ * state transitions.
+ *
+ * The mesh network adapter's incoming path has seven branches that drop a
+ * message and return undefined: a malformed signed envelope, a revoked
+ * peer, an unknown peer, a bad signature, a malformed encrypted envelope,
+ * a missing document key, and a bad decryption. Each branch is correct —
+ * the adapter must not surface tampered or unidentifiable bytes to the
+ * Repo — but the drop is invisible to anything observing the application.
+ * The classic symptom is "the other peer typed something and nothing
+ * arrived" with no error anywhere.
+ *
+ * This module exposes a typed emit-and-subscribe stream that the adapter
+ * (and the pairing and revocation paths) write to. Tests subscribe to
+ * assert that exactly the expected diagnostics fired and no others;
+ * production code can attach an observability sink that turns the stream
+ * into telemetry or a user-visible diagnostic surface.
+ *
+ * The stream is module-level. Listeners are deduplicated by reference;
+ * subscribe returns an unsubscribe function. Listener exceptions are
+ * caught and dropped so a buggy observer cannot tear the network path.
+ */
+/** All diagnostic event kinds, discriminated by the `kind` field. */
+export type MeshDiagnostic = {
+    kind: "drop:malformed-signed-envelope";
+    reason?: string;
+} | {
+    kind: "drop:revoked-peer";
+    senderId: string;
+} | {
+    kind: "drop:unknown-peer";
+    senderId: string;
+} | {
+    kind: "drop:bad-signature";
+    senderId: string;
+    reason?: string;
+} | {
+    kind: "drop:malformed-encrypted-envelope";
+    senderId: string;
+    reason?: string;
+} | {
+    kind: "drop:missing-doc-key";
+    senderId: string;
+    documentId: string;
+} | {
+    kind: "drop:bad-decryption";
+    senderId: string;
+    documentId: string;
+    reason?: string;
+} | {
+    kind: "pair:invite-issued";
+    peerId: string;
+} | {
+    kind: "pair:invite-accepted";
+    peerId: string;
+    issuerId: string;
+} | {
+    kind: "revoke:issued";
+    revokedPeerId: string;
+    issuerId: string;
+} | {
+    kind: "revoke:applied";
+    revokedPeerId: string;
+};
+/** A diagnostic event with the wall-clock timestamp the emitter stamped. */
+export type MeshDiagnosticEvent = MeshDiagnostic & {
+    timestamp: number;
+};
+/** Callback shape for subscribers. */
+export type MeshDiagnosticListener = (event: MeshDiagnosticEvent) => void;
+/**
+ * Emit a diagnostic to every active subscriber. Synchronous. Listener
+ * exceptions are swallowed.
+ */
+export declare function emitMeshDiagnostic(diagnostic: MeshDiagnostic): void;
+/**
+ * Subscribe a listener. Returns an unsubscribe function. Idempotent on
+ * the same listener reference — subscribing the same function twice
+ * registers it once.
+ */
+export declare function subscribeToMeshDiagnostics(listener: MeshDiagnosticListener): () => void;
+/**
+ * Convenience for tests and trace recorders: subscribe, collect every
+ * event into an array, return the array and a stop function that
+ * unsubscribes. The returned array is the live capture buffer — reads
+ * see new events the moment they fire.
+ */
+export declare function recordMeshDiagnostics(): {
+    events: ReadonlyArray<MeshDiagnosticEvent>;
+    stop: () => void;
+};
+/**
+ * Test-only: drop every subscriber. Use in `afterEach` to guarantee
+ * isolation between tests when a stop function was missed. Not exported
+ * from the mesh subpath in production builds — tests reach in directly.
+ */
+export declare function clearMeshDiagnosticListeners(): void;

package/dist/src/shared/lib/mesh-network-adapter.d.ts

@@ -139,9 +139,5 @@ export declare class MeshNetworkAdapter extends NetworkAdapter {
      * and target ids and the crypto blob in the `data` field.
      */
     private wrap;
-    /**
-     * Try to unwrap an incoming crypto-wrapped message. Returns the original
-     * Message on success, undefined on verification or decryption failure.
-     */
     private tryUnwrap;
 }

package/dist/tools/test/src/e2e-mesh/console-allowlist.d.ts

@@ -0,0 +1,31 @@
+/**
+ * @fairfox/polly/test/e2e-mesh — canonical console-noise allowlist.
+ *
+ * Mesh runs emit a small number of benign console lines (Repo lifecycle,
+ * Automerge warmup, occasional sync diagnostics). E2e scripts watch the
+ * Puppeteer console stream and fail on anything unexpected; without an
+ * allowlist every run trips on the same benign noise.
+ *
+ * The allowlist is owned by polly because polly knows which lines its
+ * own code produces. Consumers extend it with their app-specific noise.
+ * Entries are tested as substrings against the rendered console message.
+ */
+/** Match a console line that contains the given substring. */
+export interface ConsolePattern {
+    /** Optional console level filter — "log" | "info" | "warn" | "error".
+     *  Undefined matches any level. */
+    level?: "log" | "info" | "warn" | "error";
+    /** Substring or RegExp the rendered console line must satisfy. */
+    match: string | RegExp;
+    /** Short reason — surfaces in failure messages when the allowlist
+     *  evolves and an entry should be removed. */
+    reason: string;
+}
+export declare const MESH_CONSOLE_ALLOWLIST: ReadonlyArray<ConsolePattern>;
+/**
+ * Return true when the console line matches any allowlist entry.
+ */
+export declare function isAllowedConsoleLine(line: {
+    level: string;
+    text: string;
+}, allowlist?: ReadonlyArray<ConsolePattern>): boolean;

package/dist/tools/test/src/e2e-mesh/index.d.ts

@@ -0,0 +1,27 @@
+/**
+ * @fairfox/polly/test/e2e-mesh — end-to-end test kit for the mesh.
+ *
+ * Centralises the patterns every consumer's e2e scripts reinvent today:
+ * pairing-ceremony driving, convergence polling, console-noise filtering,
+ * screenshot-on-failure, and an embedded signalling relay. Fairfox and
+ * lingua import from this subpath rather than reimplementing.
+ *
+ * The kit is opinionated about the shape of the consumer it drives —
+ * pairing UI exposes stable `data-e2e-*` attributes, the bootstrap path
+ * goes through `createMeshClient`, the document state is observable via
+ * a polled DOM predicate. Consumers that follow the conventions get the
+ * full kit for free; those that diverge supply their own driver per
+ * primitive.
+ *
+ * Diagnostic obligation runs by default through {@link startDiagnosticRecorder}:
+ * unexpected silent drops on the diagnostic stream fail the script. A
+ * scenario that legitimately exercises a drop branch (e.g. revocation)
+ * passes the expected kinds to `assertNoSilentDrops({ allow: [...] })`.
+ */
+export { type ConsolePattern, isAllowedConsoleLine, MESH_CONSOLE_ALLOWLIST, } from "./console-allowlist";
+export { knownPeersFor, type PrebakedKeyringPair, type PrebakedKeyringSet, type PrebakedPeer, prebakeKeyringPair, prebakeKeyringSet, } from "./keys";
+export { type CapturedConsoleLine, type LaunchedPeer, type LaunchPeerOptions, launchPeer, } from "./launch-peer";
+export { type DiagnosticRecorder, MeshAssertionError, type MeshAssertionFailure, startDiagnosticRecorder, } from "./mesh-assertions";
+export { type ServeConsumerOptions, type ServeConsumerResult, serveConsumer, } from "./serve-consumer";
+export { type ConvergencePredicate, type PeerSnapshot, type WaitForConvergenceOptions, waitForConvergence, waitForMeshConnected, } from "./wait-for-convergence";
+export { type WithRelayOptions, type WithRelayResult, withRelay } from "./with-relay";