@dsbot-channel/p2p 0.0.0-stage → 0.7.0

package/dist/index.js

@@ -0,0 +1,142 @@
+import { makeAdapterPlugin } from '@dsbot-channel/core/adapter-plugin.js';
+import { ConfigError } from '@dsbot-channel/core/config.js';
+import { P2PAdapter } from './adapter.js';
+const FIELDS = new Set([
+    'peers',
+    'listen',
+    'dedupe',
+    'inflightTtlMs',
+    'sentAtWindowMs',
+    'maxBodyBytes',
+    'waitMs',
+]);
+function refuse(message, field) {
+    throw new ConfigError(message, field === undefined ? ['adapters', 'transport'] : ['adapters', 'transport', field]);
+}
+function record(value, field) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        refuse(`transport.${field} must be an object`, field);
+    return value;
+}
+function requiredText(value, field) {
+    if (typeof value !== 'string' || value.length === 0)
+        refuse(`transport.${field} must be a non-empty string`, field);
+    return value;
+}
+function optionalText(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.length === 0)
+        refuse(`transport.${field} must be a non-empty string`, field);
+    return value;
+}
+function optionalPort(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+        refuse(`transport.${field} must be a whole port number of at least 0`, field);
+    }
+    return value;
+}
+function optionalWhole(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 1) {
+        refuse(`transport.${field} must be a whole number of at least 1`, field);
+    }
+    return value;
+}
+function parsePeers(value) {
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            refuse('transport.peers must list at least one peer', 'peers');
+        const peers = value.map((entry, index) => {
+            const peer = record(entry, `peers[${index}]`);
+            if (peer.instance === undefined && peer.secret === undefined) {
+                refuse(`transport.peers mixes the list form and the mapping form: peers[${index}] is neither a peer nor a mapping`, 'peers');
+            }
+            return {
+                instance: requiredText(peer.instance, `peers[${index}].instance`),
+                secret: requiredText(peer.secret, `peers[${index}].secret`),
+                ...(optionalText(peer.url, `peers[${index}].url`) === undefined ? {} : { url: peer.url }),
+                ...(optionalText(peer.host, `peers[${index}].host`) === undefined ? {} : { host: peer.host }),
+                ...(optionalText(peer.botName, `peers[${index}].botName`) === undefined
+                    ? {}
+                    : { botName: peer.botName }),
+            };
+        });
+        const references = new Map();
+        for (const [index, peer] of peers.entries()) {
+            const seen = references.get(peer.instance) ?? new Set();
+            if (seen.has(peer.secret)) {
+                refuse(`transport.peers lists instance "${peer.instance}" twice with the same secret reference; ` +
+                    'entries for one instance must reference different secrets', `peers[${index}].secret`);
+            }
+            seen.add(peer.secret);
+            references.set(peer.instance, seen);
+        }
+        return peers;
+    }
+    if (value !== null && typeof value === 'object') {
+        const mapping = value;
+        if (Object.hasOwn(mapping, 'instance') && Object.hasOwn(mapping, 'secret')) {
+            refuse('transport.peers reads as one peer written without the list brackets; the list form is peers: [{ instance, secret }]', 'peers');
+        }
+        const entries = Object.entries(mapping);
+        if (entries.length === 0)
+            refuse('transport.peers must list at least one peer', 'peers');
+        return entries.map(([instance, secret]) => ({
+            instance: requiredText(instance, `peers.${instance}`),
+            secret: requiredText(secret, `peers.${instance}`),
+        }));
+    }
+    refuse('transport.peers must be a list of peers or a mapping of instance to secret reference', 'peers');
+}
+function parseListen(value) {
+    if (value === undefined)
+        return undefined;
+    const listen = record(value, 'listen');
+    return {
+        ...(optionalText(listen.host, 'listen.host') === undefined ? {} : { host: listen.host }),
+        ...(optionalPort(listen.port, 'listen.port') === undefined ? {} : { port: listen.port }),
+    };
+}
+function parseDedupe(value) {
+    if (value === undefined)
+        return undefined;
+    const dedupe = record(value, 'dedupe');
+    return {
+        ...(optionalPort(dedupe.ttlMs, 'dedupe.ttlMs') === undefined ? {} : { ttlMs: dedupe.ttlMs }),
+        ...(optionalWhole(dedupe.limit, 'dedupe.limit') === undefined ? {} : { limit: dedupe.limit }),
+    };
+}
+/** Reads the transport block a profile declared, refusing a field this adapter never reads. */
+export function parseP2PConfig(mount) {
+    const raw = mount.transport;
+    const unknown = Object.keys(raw).filter((key) => !FIELDS.has(key));
+    if (unknown.length > 0)
+        refuse(`transport names a field this adapter does not read: ${unknown.join(', ')}`);
+    return {
+        channel: mount.channel,
+        botName: mount.wireBotName ?? mount.botName,
+        ...(mount.status === undefined ? {} : { status: mount.status }),
+        peers: parsePeers(raw.peers),
+        ...(parseListen(raw.listen) === undefined ? {} : { listen: parseListen(raw.listen) }),
+        ...(parseDedupe(raw.dedupe) === undefined ? {} : { dedupe: parseDedupe(raw.dedupe) }),
+        ...(optionalWhole(raw.inflightTtlMs, 'inflightTtlMs') === undefined ? {} : { inflightTtlMs: raw.inflightTtlMs }),
+        ...(optionalWhole(raw.sentAtWindowMs, 'sentAtWindowMs') === undefined ? {} : { sentAtWindowMs: raw.sentAtWindowMs }),
+        ...(optionalWhole(raw.maxBodyBytes, 'maxBodyBytes') === undefined ? {} : { maxBodyBytes: raw.maxBodyBytes }),
+        ...(optionalWhole(raw.waitMs, 'waitMs') === undefined ? {} : { waitMs: raw.waitMs }),
+    };
+}
+export const createP2PAdapter = (mount, options) => new P2PAdapter(parseP2PConfig(mount), options);
+const adapter = makeAdapterPlugin({
+    name: 'dsbot-channel/p2p',
+    kind: 'p2p',
+    factory: createP2PAdapter,
+    check: parseP2PConfig,
+});
+export const Config = adapter.Config;
+export const apply = adapter.apply;
+export const plugin = adapter.plugin;
+export default adapter.plugin;

package/dist/p2p-auth.d.ts

@@ -0,0 +1,40 @@
+import type { P2PMediaItem } from './p2p-wire.js';
+export interface PeerSecret {
+    instance: string;
+    secret: string;
+}
+export interface AuthResult {
+    ok: boolean;
+    instance?: string | undefined;
+    status?: 401 | 403 | undefined;
+    reason?: string | undefined;
+}
+/** Everything the signature covers, in the order both sides build it. */
+export interface Envelope {
+    eventId: string;
+    /** The root event of the conversation this message belongs to; signed like eventId. */
+    chainId: string;
+    to: string;
+    sender: string;
+    instance: string;
+    body: string;
+    sentAt: number;
+    status?: string | undefined;
+    reason?: string | undefined;
+    final?: boolean | undefined;
+    inReplyTo?: string | undefined;
+    inReplyToExcerpt?: string | undefined;
+    /** Only present when the message carries media, so a text-only envelope keeps its old bytes. */
+    media?: readonly P2PMediaItem[] | undefined;
+}
+export interface AuthInput {
+    peers: readonly PeerSecret[];
+    signature?: string | null | undefined;
+    claimedInstance: string;
+    envelope?: Envelope | undefined;
+}
+/** The bytes a signature covers: every field of the envelope, in one fixed order. */
+export declare function canonicalEnvelope(envelope: Envelope): string;
+export declare function signEnvelope(secret: string, envelope: Envelope): string;
+/** Resolves the peer instance from the credential, never from the request body. */
+export declare function verifyRequest(input: AuthInput): AuthResult;

package/dist/p2p-auth.js

@@ -0,0 +1,44 @@
+import { createHash, timingSafeEqual } from 'node:crypto';
+function sameSecret(a, b) {
+    const left = createHash('sha256').update(a, 'utf8').digest();
+    const right = createHash('sha256').update(b, 'utf8').digest();
+    return timingSafeEqual(left, right);
+}
+/** The bytes a signature covers: every field of the envelope, in one fixed order. */
+export function canonicalEnvelope(envelope) {
+    return JSON.stringify({
+        eventId: envelope.eventId,
+        chainId: envelope.chainId,
+        to: envelope.to,
+        sender: envelope.sender,
+        instance: envelope.instance,
+        body: envelope.body,
+        sentAt: envelope.sentAt,
+        ...(envelope.status === undefined ? {} : { status: envelope.status }),
+        ...(envelope.reason === undefined ? {} : { reason: envelope.reason }),
+        ...(envelope.final === undefined ? {} : { final: envelope.final }),
+        ...(envelope.inReplyTo === undefined ? {} : { inReplyTo: envelope.inReplyTo }),
+        ...(envelope.inReplyToExcerpt === undefined ? {} : { inReplyToExcerpt: envelope.inReplyToExcerpt }),
+        ...(envelope.media === undefined || envelope.media.length === 0 ? {} : { media: envelope.media }),
+    });
+}
+export function signEnvelope(secret, envelope) {
+    return createHash('sha256').update(`${secret}.${canonicalEnvelope(envelope)}`, 'utf8').digest('base64');
+}
+/** Resolves the peer instance from the credential, never from the request body. */
+export function verifyRequest(input) {
+    if (!input.peers.length)
+        throw new Error('p2p: at least one peer secret is required to start');
+    if (!input.signature || input.envelope === undefined)
+        return { ok: false, status: 401, reason: 'missing signature' };
+    for (const peer of input.peers) {
+        const expected = signEnvelope(peer.secret, input.envelope);
+        if (sameSecret(expected, input.signature)) {
+            if (input.claimedInstance && input.claimedInstance !== peer.instance) {
+                return { ok: false, status: 403, reason: 'instance does not match the signing key' };
+            }
+            return { ok: true, instance: peer.instance };
+        }
+    }
+    return { ok: false, status: 401, reason: 'bad signature' };
+}

package/dist/p2p-dedupe.d.ts

@@ -0,0 +1,37 @@
+export interface DedupeOptions {
+    ttlMs: number;
+    limit: number;
+    inflightTtlMs?: number;
+    maxTurnMs?: number;
+    now?: () => number;
+}
+export interface DedupeEntry {
+    messageId: string;
+    at: number;
+}
+/** Dedupe table with single-flight: a concurrent duplicate waits instead of reprocessing. */
+export declare class DedupeTable {
+    private readonly options;
+    /** When this table started; a replay carried into a table with a newer epoch crossed a restart. */
+    readonly epoch: number;
+    private readonly done;
+    private readonly inflight;
+    private readonly now;
+    constructor(options: DedupeOptions);
+    has(key: string): DedupeEntry | undefined;
+    /** Claims the key. Returns the finished entry, or null when this call now owns the work. */
+    claim(key: string, waitMs: number): Promise<{
+        done: true;
+        entry: DedupeEntry | null;
+    } | {
+        done: false;
+    }>;
+    private expired;
+    /** Drops a reservation left by a crashed handler so the event can be retried. */
+    private reap;
+    commit(key: string, messageId: string): void;
+    abort(key: string): void;
+    private evict;
+    size(): number;
+    inflightSize(): number;
+}

package/dist/p2p-dedupe.js

@@ -0,0 +1,107 @@
+/** Dedupe table with single-flight: a concurrent duplicate waits instead of reprocessing. */
+export class DedupeTable {
+    options;
+    /** When this table started; a replay carried into a table with a newer epoch crossed a restart. */
+    epoch;
+    done = new Map();
+    inflight = new Map();
+    now;
+    constructor(options) {
+        this.options = options;
+        if (options.inflightTtlMs !== undefined && options.maxTurnMs !== undefined && options.inflightTtlMs <= options.maxTurnMs) {
+            throw new Error('inflightTtlMs must exceed maxTurnMs');
+        }
+        this.now = options.now ?? Date.now;
+        this.epoch = this.now();
+    }
+    has(key) {
+        const entry = this.done.get(key);
+        if (!entry)
+            return undefined;
+        if (this.now() - entry.at > this.options.ttlMs) {
+            this.done.delete(key);
+            return undefined;
+        }
+        return entry;
+    }
+    /** Claims the key. Returns the finished entry, or null when this call now owns the work. */
+    async claim(key, waitMs) {
+        const finished = this.has(key);
+        if (finished)
+            return { done: true, entry: finished };
+        const stale = this.inflight.get(key);
+        if (stale && this.expired(stale))
+            this.reap(key, stale);
+        const running = this.inflight.get(key);
+        if (running) {
+            const entry = await new Promise((resolve) => {
+                let settled = false;
+                const finish = (value) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    const index = running.waiters.indexOf(finish);
+                    if (index >= 0)
+                        running.waiters.splice(index, 1);
+                    resolve(value);
+                };
+                const timer = setTimeout(() => finish(null), waitMs);
+                running.waiters.push(finish);
+            });
+            return { done: true, entry };
+        }
+        this.inflight.set(key, { at: this.now(), waiters: [] });
+        return { done: false };
+    }
+    expired(entry) {
+        const ttl = this.options.inflightTtlMs;
+        return ttl !== undefined && this.now() - entry.at > ttl;
+    }
+    /** Drops a reservation left by a crashed handler so the event can be retried. */
+    reap(key, entry) {
+        this.inflight.delete(key);
+        for (const waiter of entry.waiters)
+            waiter(null);
+    }
+    commit(key, messageId) {
+        const entry = { messageId, at: this.now() };
+        this.done.set(key, entry);
+        this.evict();
+        const running = this.inflight.get(key);
+        if (running) {
+            this.inflight.delete(key);
+            for (const waiter of running.waiters)
+                waiter(entry);
+        }
+    }
+    abort(key) {
+        const running = this.inflight.get(key);
+        if (!running)
+            return;
+        this.inflight.delete(key);
+        for (const waiter of running.waiters)
+            waiter(null);
+    }
+    evict() {
+        if (this.done.size <= this.options.limit)
+            return;
+        const at = this.now();
+        for (const [key, entry] of this.done) {
+            if (at - entry.at > this.options.ttlMs)
+                this.done.delete(key);
+        }
+        while (this.done.size > this.options.limit) {
+            const oldest = this.done.keys().next();
+            if (oldest.done)
+                break;
+            this.done.delete(oldest.value);
+        }
+    }
+    size() {
+        return this.done.size;
+    }
+    inflightSize() {
+        return this.inflight.size;
+    }
+}

package/dist/p2p-listener.d.ts

@@ -0,0 +1,43 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { AddressInfo } from 'node:net';
+import type { DedupeTable } from './p2p-dedupe.js';
+import type { ChannelStats } from '@dsbot-channel/core/channel-stats.js';
+import type { AdapterStatus } from '@dsbot-channel/core/adapter-status.js';
+import type { P2PConfig } from './p2p-protocol.js';
+import type { InboundRequest } from './p2p-wire.js';
+export declare const DEFAULT_HOST = "127.0.0.1";
+export declare const DEFAULT_PORT = 7123;
+export declare const SIGNATURE_HEADER = "x-p2p-signature";
+export interface ListenerConfig extends P2PConfig {
+    listen: {
+        host?: string;
+        port?: number;
+    };
+}
+/** Checks the bind address before anything touches the network. */
+export declare function checkListenerConfig(config: ListenerConfig): string;
+export interface ListenerOptions {
+    config: ListenerConfig;
+    table: DedupeTable;
+    /** Runs after the dedupe claim and must return before the turn finishes.
+     * A 200 means accepted, not completed. */
+    onMessage?: (request: InboundRequest) => void | Promise<void>;
+    /** Receives a rejected asynchronous hand off so it never becomes a crash. */
+    onError?: (error: unknown, request: InboundRequest) => void;
+    /** Collects what this channel can report about itself. */
+    stats?: ChannelStats | undefined;
+    /** Answers a loopback only status read; absent means the route does not exist. */
+    status?: {
+        route?: string | undefined;
+        report: () => AdapterStatus;
+    } | undefined;
+}
+export interface Listener {
+    /** Bound address once listening. */
+    address(): AddressInfo;
+    /** Stops accepting connections and resolves once closed. */
+    close(): Promise<void>;
+    handle(request: IncomingMessage, response: ServerResponse): Promise<void>;
+}
+/** Starts the self hosted peer listener on the configured address. */
+export declare function startListener(options: ListenerOptions): Promise<Listener>;

package/dist/p2p-listener.js

@@ -0,0 +1,168 @@
+import { createServer } from 'node:http';
+import { assertBindHost } from '@dsbot-channel/core/config.js';
+import { STATUS_ROUTE } from './p2p-status.js';
+import { answerStatus } from '@dsbot-channel/core/adapters/shared/status-route.js';
+import { MAX_BODY_BYTES, P2P_ROUTE, handleMessage, parseRequest } from './p2p-protocol.js';
+export const DEFAULT_HOST = '127.0.0.1';
+export const DEFAULT_PORT = 7123;
+export const SIGNATURE_HEADER = 'x-p2p-signature';
+/** Checks the bind address before anything touches the network. */
+export function checkListenerConfig(config) {
+    const host = config.listen.host ?? DEFAULT_HOST;
+    assertBindHost(host, ['listen', 'host']);
+    if (!config.peers.length)
+        throw new Error('p2p: at least one peer secret is required to start');
+    return host;
+}
+function readBody(request, limit) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let size = 0;
+        let settled = false;
+        const settle = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(value);
+        };
+        request.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                chunks.length = 0;
+                settle({ ok: false });
+                return;
+            }
+            chunks.push(chunk);
+        });
+        request.on('end', () => settle({ ok: true, text: Buffer.concat(chunks).toString('utf8') }));
+        request.on('error', () => settle({ ok: false }));
+    });
+}
+function readSignature(request) {
+    const header = request.headers[SIGNATURE_HEADER];
+    const value = Array.isArray(header) ? header[0] : header;
+    return value ?? null;
+}
+function send(response, status, body) {
+    const text = JSON.stringify(body);
+    response.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(text) });
+    response.end(text);
+}
+/** Starts the self hosted peer listener on the configured address. */
+export async function startListener(options) {
+    const host = checkListenerConfig(options.config);
+    const port = options.config.listen.port ?? DEFAULT_PORT;
+    const limit = options.config.maxBodyBytes ?? MAX_BODY_BYTES;
+    const handle = async (request, response) => {
+        const status = options.status;
+        if (status !== undefined &&
+            answerStatus(request, response, {
+                route: status.route ?? STATUS_ROUTE,
+                report: status.report,
+                onRefused: () => options.stats?.unknownPath(),
+            })) {
+            return;
+        }
+        if (request.method !== 'POST' || request.url !== P2P_ROUTE) {
+            options.stats?.unknownPath();
+            send(response, 404, { error: 'not found' });
+            return;
+        }
+        const raw = await readBody(request, limit);
+        let payload;
+        if (!raw.ok) {
+            options.stats?.rejected('body exceeds the size limit');
+            send(response, 413, { error: 'body exceeds the size limit' });
+            return;
+        }
+        try {
+            payload = JSON.parse(raw.text);
+        }
+        catch {
+            options.stats?.rejected('body must be valid json');
+            send(response, 400, { error: 'body must be valid json' });
+            return;
+        }
+        const claimed = typeof payload.instance === 'string' ? payload.instance : '';
+        const onMessage = options.onMessage;
+        let result;
+        try {
+            result = await handleMessage({
+                config: options.config,
+                table: options.table,
+                auth: {
+                    signature: readSignature(request),
+                    claimedInstance: claimed,
+                },
+                payload,
+                ...(options.stats === undefined ? {} : { stats: options.stats }),
+                ...(onMessage === undefined
+                    ? {}
+                    : {
+                        process: (eventId) => {
+                            const parsed = parseRequest(payload, limit);
+                            if (parsed.ok && parsed.value.eventId === eventId) {
+                                const request = parsed.value;
+                                const report = (error) => {
+                                    const onError = options.onError;
+                                    if (onError === undefined)
+                                        return;
+                                    void Promise.resolve()
+                                        .then(() => onError(error, request))
+                                        .catch(() => undefined);
+                                };
+                                try {
+                                    const dispatched = onMessage(request);
+                                    if (dispatched instanceof Promise)
+                                        void dispatched.catch(report);
+                                }
+                                catch (error) {
+                                    report(error);
+                                }
+                            }
+                            return Promise.resolve(true);
+                        },
+                    }),
+            });
+        }
+        catch (error) {
+            options.stats?.rejected(error instanceof Error ? error.message : 'internal error');
+            send(response, 500, { error: error instanceof Error ? error.message : 'internal error' });
+            return;
+        }
+        if (result.status === 401)
+            options.stats?.authFailure();
+        if (result.status !== 200)
+            options.stats?.rejected(result.body.error);
+        send(response, result.status, result.body);
+    };
+    const server = createServer((request, response) => {
+        void handle(request, response);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, host, () => {
+            server.off('error', reject);
+            resolve();
+        });
+    }).catch((error) => {
+        options.stats?.failed(error instanceof Error ? error.message : String(error));
+        throw error;
+    });
+    options.stats?.listening(server.address().port);
+    return {
+        address: () => server.address(),
+        close: () => new Promise((resolve, reject) => {
+            server.close((error) => {
+                if (error) {
+                    options.stats?.failed(error.message);
+                    reject(error);
+                    return;
+                }
+                options.stats?.closed();
+                resolve();
+            });
+        }),
+        handle,
+    };
+}

package/dist/p2p-mapping.d.ts

@@ -0,0 +1,29 @@
+import type { P2PMediaItem } from './p2p-wire.js';
+import type { Event } from '@dsbot-channel/core/event-types.js';
+/** How much of the message being answered travels back with the reply. */
+export declare const EXCERPT_CHARS = 200;
+/** How much of a peer's own text reaches a line of ours. */
+export declare const PEER_TEXT_MAX = 200;
+/** How much of a wire name one log line keeps, escapes included. */
+export declare const LOG_NAME_MAX = 64;
+/** A wire name as one log-safe literal: control characters escaped, length bounded. */
+export declare function logName(value: string): string;
+/** A peer's own words for a line of ours: one line, bounded, nothing that breaks the line. */
+export declare function oneLine(text: unknown, limit?: number): string;
+/** Keeps a peer from shaping the header: no control characters, one line, no quotes. */
+export declare function cleanExcerpt(text: string, limit?: number): string;
+export interface P2PInbound {
+    instance: string;
+    sender: string;
+    messageId: string;
+    body: string;
+    media?: readonly P2PMediaItem[];
+    sentAt: number;
+    inReplyTo?: string;
+    inReplyToExcerpt?: string;
+    status?: 'declined';
+    reason?: string;
+    final?: boolean;
+}
+/** Maps a peer message onto the event model with the peer identity as the source. */
+export declare function toP2PEvent(inbound: P2PInbound): Event;