@fairfox/polly 0.20.0 → 0.21.0

package/dist/src/elysia/peer-repo-plugin.d.ts

@@ -0,0 +1,79 @@
+/**
+ * peerRepo — Elysia plugin that runs a Polly peer-relay server alongside an
+ * Elysia application and exposes the server's Repo on the Elysia context.
+ *
+ * The Phase 1 plan originally framed the relay server as an Elysia plugin
+ * that registers a WebSocket route on Elysia's native socket layer. That
+ * design does not work directly: Automerge's WebSocketServerAdapter requires
+ * an `isomorphic-ws` WebSocketServer instance, and Elysia's WebSocket layer
+ * is built on Bun's native WebSocket API, which is a different shape. The
+ * realistic Phase 1 cut is therefore a *lifecycle* plugin: it runs
+ * createPeerRepoServer on its own port during Elysia startup, decorates the
+ * Elysia context so route handlers can reach the resulting Repo, and tears
+ * the server down during Elysia shutdown. Authenticated WebSocket upgrades
+ * via Elysia's hook system are a Phase 1.1 follow-up that requires either
+ * a custom Bun-native NetworkAdapter or an upgrade-time auth bridge.
+ *
+ * @example
+ * ```ts
+ * import { Elysia } from "elysia";
+ * import { peerRepo } from "@fairfox/polly/elysia";
+ *
+ * const app = new Elysia()
+ *   .use(peerRepo({ port: 3030, storagePath: "./data/polly-peer" }))
+ *   .get("/stats", ({ pollyPeerRepo }) => {
+ *     return { peers: pollyPeerRepo.peers.length };
+ *   })
+ *   .listen(8080);
+ * ```
+ */
+import { Elysia } from "elysia";
+import { type CreatePeerRepoServerOptions, type PeerRepoServer } from "../shared/lib/peer-repo-server";
+export interface PeerRepoPluginOptions extends CreatePeerRepoServerOptions {
+    /** Optional path for a health endpoint that returns peer count and storage
+     * id. Set to false to skip the health route entirely. Defaults to
+     * "/polly/peer/health". */
+    healthPath?: string | false;
+}
+/**
+ * Elysia plugin that boots a Polly peer-relay server alongside the host app
+ * and decorates the context with `pollyPeerRepo` (the Repo) and
+ * `pollyPeerServer` (the full {@link PeerRepoServer} for advanced use).
+ *
+ * The plugin starts the relay server during Elysia's onStart lifecycle and
+ * shuts it down during onStop, so route handlers and cron jobs can use the
+ * decorated Repo throughout the request lifetime without managing the
+ * underlying transport themselves.
+ */
+export declare function peerRepo(options: PeerRepoPluginOptions): Elysia<"", {
+    decorator: {
+        pollyPeerRepo: import("@automerge/automerge-repo").Repo | null;
+    } & {
+        pollyPeerServer: PeerRepoServer | null;
+    };
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/src/elysia/plugin.d.ts

@@ -60,10 +60,10 @@ export declare function polly(config?: PollyConfig): Elysia<"", {
 }, {
     [x: string]: {
         subscribe: {
-            body: unknown;
+            body: {};
             params: {};
-            query: unknown;
-            headers: unknown;
+            query: {};
+            headers: {};
             response: {};
         };
     };

package/dist/src/elysia/signaling-server-plugin.d.ts

@@ -0,0 +1,121 @@
+/**
+ * signalingServer — Phase 2 Elysia plugin that exposes a stateless
+ * WebSocket route for SDP/ICE relay between $meshState peers.
+ *
+ * The mesh transport is a star-of-data-channels: peers establish direct
+ * WebRTC connections to each other and exchange document operations
+ * peer-to-peer once those channels are open. WebRTC connection setup
+ * needs an out-of-band channel for SDP offer/answer and ICE candidate
+ * exchange, and that channel is what this plugin provides. The plugin
+ * does not own any document state, does not hold any encryption keys,
+ * and never inspects the contents of the messages it relays. It is a
+ * pure pub-sub by peer id.
+ *
+ * Once two peers have completed the SDP exchange and opened a direct
+ * data channel, the signalling server is no longer on the critical
+ * path — the peers talk directly. The signalling server's role is
+ * therefore intermittent: peers connect to it only during the brief
+ * windows when they are establishing or re-establishing connections.
+ *
+ * Wire protocol:
+ *
+ *   Client → server (join):
+ *     { type: "join", peerId: "peer-alice" }
+ *
+ *   Client → server (signal to another peer):
+ *     { type: "signal", peerId: "peer-alice", targetPeerId: "peer-bob",
+ *       payload: { ... } }
+ *
+ *   Server → client (delivered signal):
+ *     { type: "signal", peerId: "peer-alice", targetPeerId: "peer-bob",
+ *       payload: { ... } }
+ *
+ *   Server → client (notification of unknown target):
+ *     { type: "error", reason: "unknown-target", targetPeerId: "..." }
+ *
+ * The `payload` is opaque to the signalling server — typically it
+ * carries an SDP offer, SDP answer, or ICE candidate. Applications can
+ * also use the relay for any other peer-to-peer message that needs an
+ * intermediary, such as the initial handshake of a pairing flow.
+ *
+ * @example
+ * ```ts
+ * import { Elysia } from "elysia";
+ * import { signalingServer } from "@fairfox/polly/elysia";
+ *
+ * const app = new Elysia()
+ *   .use(signalingServer({ path: "/polly/signaling" }))
+ *   .listen(8080);
+ * ```
+ */
+import { Elysia } from "elysia";
+/** A signalling message. The `type` discriminates between join (peer
+ * registration), signal (relayed message), and error (server response). */
+export type SignalingMessage = {
+    type: "join";
+    /** The peer registering itself with the signalling server. */
+    peerId: string;
+} | {
+    type: "signal";
+    /** The peer sending the signal. */
+    peerId: string;
+    /** The peer the signal is being relayed to. */
+    targetPeerId: string;
+    /** Opaque payload, typically SDP or ICE. */
+    payload: unknown;
+} | {
+    type: "error";
+    reason: "unknown-target" | "not-joined" | "malformed";
+    targetPeerId?: string;
+};
+export interface SignalingServerOptions {
+    /** WebSocket route path. Defaults to "/polly/signaling". */
+    path?: string;
+}
+/**
+ * Construct the signalling-server Elysia plugin. The plugin keeps a
+ * per-instance map of peer id → WebSocket connection so that incoming
+ * "signal" messages can be routed to the right target socket. The map
+ * is local to the plugin instance, not shared across processes; for
+ * multi-instance deployments behind a load balancer, applications need
+ * sticky connection routing or a shared backplane (Redis pub-sub or
+ * similar). That is a follow-up.
+ */
+export declare function signalingServer(options?: SignalingServerOptions): Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {
+    [x: string]: {
+        subscribe: {
+            body: {};
+            params: {};
+            query: {};
+            headers: {};
+            response: {};
+        };
+    };
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/src/index.d.ts

@@ -6,14 +6,50 @@
  */
 export type { ExtensionAdapters } from "./shared/adapters";
 export { createChromeAdapters } from "./shared/adapters";
+export type { Access, AccessPredicate, PeerIdentity } from "./shared/lib/access";
+export { and, anyOfPeers, anyone, groupAccess, nobody, not, onlyPeer, or, ownerAccess, publicAccess, readOnlyExcept, } from "./shared/lib/access";
+export type { BlobRef, CreateBlobRefArgs } from "./shared/lib/blob-ref";
+export { computeBlobHash, createBlobRef, isBlobRef } from "./shared/lib/blob-ref";
 export { checkPostconditions, checkPreconditions, clearConstraints, isRuntimeConstraintsEnabled, registerConstraint, registerConstraints, } from "./shared/lib/constraints";
 export type { ContextConfig } from "./shared/lib/context-helpers";
 export { createContext, runInContext } from "./shared/lib/context-helpers";
 export type { BackgroundHelpers, ContentScriptHelpers, DevToolsHelpers, OptionsHelpers, PopupHelpers, SidePanelHelpers, } from "./shared/lib/context-specific-helpers";
+export type { CounterDoc, CrdtCounterOptions, CrdtListOptions, CrdtTextOptions, ListDoc, SpecialisedPrimitive, TextDoc, } from "./shared/lib/crdt-specialised";
+export { $crdtCounter, $crdtList, $crdtText } from "./shared/lib/crdt-specialised";
+export type { CrdtPrimitive, CrdtStateOptions } from "./shared/lib/crdt-state";
+export { $crdtState } from "./shared/lib/crdt-state";
+export type { EncryptedEnvelope, SealedBytes, } from "./shared/lib/encryption";
+export { decrypt, decryptOrThrow, EncryptionError, encrypt, generateDocumentKey, KEY_BYTES as ENCRYPTION_KEY_BYTES, NONCE_BYTES as ENCRYPTION_NONCE_BYTES, TAG_BYTES as ENCRYPTION_TAG_BYTES, } from "./shared/lib/encryption";
 export { ConnectionError, ErrorHandler, ExtensionError, HandlerError, TimeoutError, } from "./shared/lib/errors";
+export type { MeshKeyring, MeshNetworkAdapterOptions, } from "./shared/lib/mesh-network-adapter";
+export { DEFAULT_MESH_KEY_ID, MeshNetworkAdapter, } from "./shared/lib/mesh-network-adapter";
+export type { MeshSignalingClientOptions, SignalingMessage as MeshSignalingMessage, } from "./shared/lib/mesh-signaling-client";
+export { MeshSignalingClient } from "./shared/lib/mesh-signaling-client";
+export type { MeshStateOptions } from "./shared/lib/mesh-state";
+export { $meshCounter, $meshList, $meshState, $meshText, configureMeshState, resetMeshState, } from "./shared/lib/mesh-state";
+export type { MeshWebRTCAdapterOptions } from "./shared/lib/mesh-webrtc-adapter";
+export { DEFAULT_ICE_SERVERS, MeshWebRTCAdapter } from "./shared/lib/mesh-webrtc-adapter";
 export { getMessageBus, MessageBus } from "./shared/lib/message-bus";
+export type { MigratableState } from "./shared/lib/migrate-primitive";
+export { MigrationError, migratePrimitive } from "./shared/lib/migrate-primitive";
+export type { CreatePairingTokenOptions, PairingToken, } from "./shared/lib/pairing";
+export { applyPairingToken, createPairingToken, createPairingTokenWithFreshIdentity, DEFAULT_PAIRING_TTL_MS, decodePairingToken, encodePairingToken, isPairingTokenExpired, PAIRING_NONCE_BYTES, PAIRING_TOKEN_VERSION, PairingError, parsePairingToken, serialisePairingToken, } from "./shared/lib/pairing";
+export type { CreatePeerStateClientOptions, PeerRelayConnectionState, PeerStateClient, } from "./shared/lib/peer-relay-adapter";
+export { createPeerStateClient } from "./shared/lib/peer-relay-adapter";
+export type { CreatePeerRepoServerOptions, PeerRepoServer, } from "./shared/lib/peer-repo-server";
+export { createPeerRepoServer } from "./shared/lib/peer-repo-server";
+export type { PeerCounterOptions, PeerListOptions, PeerStateOptions, PeerTextOptions, } from "./shared/lib/peer-state";
+export { $peerCounter, $peerList, $peerState, $peerText, configurePeerState, resetPeerState, } from "./shared/lib/peer-state";
+export type { PrimitiveKind } from "./shared/lib/primitive-registry";
+export { PrimitiveCollisionError } from "./shared/lib/primitive-registry";
 export type { Resource, ResourceOptions, ResourceStatus } from "./shared/lib/resource";
 export { $resource } from "./shared/lib/resource";
+export type { CreateRevocationOptions, RevocationRecord, } from "./shared/lib/revocation";
+export { applyRevocation, createRevocation, decodeRevocation, encodeRevocation, REVOCATION_MAGIC, REVOCATION_RECORD_VERSION, RevocationError, revokePeerLocally, } from "./shared/lib/revocation";
+export type { Migration, Migrations, OpVersionCheck, VersionedDoc, } from "./shared/lib/schema-version";
+export { assertOpVersion, checkOpVersion, getDocVersion, SCHEMA_VERSION_FIELD, SchemaVersionError, } from "./shared/lib/schema-version";
+export type { SignedEnvelope, SigningKeyPair } from "./shared/lib/signing";
+export { generateSigningKeyPair, PUBLIC_KEY_BYTES as SIGNING_PUBLIC_KEY_BYTES, SECRET_KEY_BYTES as SIGNING_SECRET_KEY_BYTES, SIGNATURE_BYTES as SIGNING_SIGNATURE_BYTES, SigningError, sign, signingKeyPairFromSecret, verify, } from "./shared/lib/signing";
 export { $persistedState, $sharedState, $state, $syncedState } from "./shared/lib/state";
 export type { TestCase, TestSuite } from "./shared/lib/test-helpers";
 export { createTestSuite, quickTest, TestRunner } from "./shared/lib/test-helpers";