@spexcode/session-topology 0.6.8

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export type TopologyErrorCode = 'TOPOLOGY_EDGE_ID_INVALID' | 'TOPOLOGY_EDGE_UNKNOWN' | 'TOPOLOGY_EDGE_EXISTS' | 'TOPOLOGY_CYCLE_REFUSED' | 'TOPOLOGY_RELATION_TYPE_INVALID' | 'TOPOLOGY_SESSION_ID_INVALID' | 'TOPOLOGY_SESSION_UNKNOWN' | 'TOPOLOGY_SELF_EDGE' | 'TOPOLOGY_TRANSACTION_INVALID' | 'TOPOLOGY_STORAGE_ERROR';
+export declare class TopologyError extends Error {
+    readonly code: TopologyErrorCode;
+    constructor(code: TopologyErrorCode, message: string, cause?: unknown);
+}
+export declare function failTopology(code: TopologyErrorCode, message: string, cause?: unknown): never;

package/dist/errors.js

@@ -0,0 +1,11 @@
+export class TopologyError extends Error {
+    code;
+    constructor(code, message, cause) {
+        super(message, { cause });
+        this.name = 'TopologyError';
+        this.code = code;
+    }
+}
+export function failTopology(code, message, cause) {
+    throw new TopologyError(code, message, cause);
+}

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import type { ProtocolTransaction, SessionProtocol } from '@spexcode/session-protocol';
+import { TopologyError } from './errors.js';
+export interface TopologyEdge {
+    edgeId: string;
+    fromSessionId: string;
+    toSessionId: string;
+    relationType: string;
+    createdAtMs: number;
+    removedAtMs: number | null;
+}
+export interface SessionTopology {
+    attach(tx: ProtocolTransaction, fromSessionId: string, toSessionId: string, relationType: string): TopologyEdge;
+    detach(tx: ProtocolTransaction, edgeId: string): TopologyEdge;
+    reparent(tx: ProtocolTransaction, subjectSessionId: string, nextFromSessionId: string, relationType: string): TopologyEdge;
+    subscribe(tx: ProtocolTransaction, watcherSessionId: string, subjectSessionId: string, channel: string): TopologyEdge;
+    unsubscribe(tx: ProtocolTransaction, watcherSessionId: string, subjectSessionId: string, channel: string): TopologyEdge;
+    parents(sessionId: string, relationType?: string, tx?: ProtocolTransaction): TopologyEdge[];
+    children(sessionId: string, relationType?: string, tx?: ProtocolTransaction): TopologyEdge[];
+    subscriptions(sessionId: string, tx?: ProtocolTransaction): TopologyEdge[];
+    recipients(subjectSessionId: string, tx?: ProtocolTransaction): string[];
+}
+export declare function openTopology(protocol: SessionProtocol): SessionTopology;
+export { TopologyError };
+export type { TopologyErrorCode } from './errors.js';

package/dist/index.js

@@ -0,0 +1,173 @@
+import { randomBytes } from 'node:crypto';
+import { applyComponentMigrations } from '@spexcode/session-protocol';
+import { failTopology, TopologyError } from './errors.js';
+import { TOPOLOGY_MIGRATIONS } from './schema.js';
+const EDGE_ID = /^[0-9a-f]{32}$/;
+const RELATION_TYPE = /^[0-9A-Za-z._:-]{1,64}$/;
+const SESSION_ID = /^(?!-)[0-9A-Za-z_-]{1,256}$/;
+const EDGE_COLUMNS = `edge_id, from_session_id, to_session_id, relation_type, created_at_ms, removed_at_ms`;
+export function openTopology(protocol) {
+    applyComponentMigrations(protocol, 'session-topology', TOPOLOGY_MIGRATIONS);
+    const requireTransaction = (tx) => {
+        if (!tx
+            || typeof tx.exec !== 'function'
+            || typeof tx.query !== 'function'
+            || typeof tx.enqueue !== 'function') {
+            failTopology('TOPOLOGY_TRANSACTION_INVALID', 'a live protocol transaction context is required');
+        }
+        return tx;
+    };
+    const requireSessionId = (sessionId) => {
+        if (typeof sessionId !== 'string' || !SESSION_ID.test(sessionId)) {
+            failTopology('TOPOLOGY_SESSION_ID_INVALID', 'session id must match the protocol address grammar');
+        }
+    };
+    const requireRelationType = (relationType) => {
+        if (typeof relationType !== 'string' || !RELATION_TYPE.test(relationType)) {
+            failTopology('TOPOLOGY_RELATION_TYPE_INVALID', 'relation type must match [0-9A-Za-z._:-]{1,64}');
+        }
+    };
+    const requireEdgeId = (edgeId) => {
+        if (typeof edgeId !== 'string' || !EDGE_ID.test(edgeId)) {
+            failTopology('TOPOLOGY_EDGE_ID_INVALID', 'edge id must be 32 lowercase hexadecimal characters');
+        }
+    };
+    const toEdge = (row) => ({
+        edgeId: String(row.edge_id),
+        fromSessionId: String(row.from_session_id),
+        toSessionId: String(row.to_session_id),
+        relationType: String(row.relation_type),
+        createdAtMs: Number(row.created_at_ms),
+        removedAtMs: row.removed_at_ms === null ? null : Number(row.removed_at_ms),
+    });
+    const asEdgeRows = (rows) => rows;
+    const requireAddresses = (tx, fromSessionId, toSessionId) => {
+        const rows = tx.query('SELECT session_id FROM protocol_sessions WHERE session_id IN (?,?) ORDER BY session_id', fromSessionId, toSessionId);
+        const found = new Set(rows.map(row => String(row.session_id)));
+        if (!found.has(fromSessionId) || !found.has(toSessionId)) {
+            failTopology('TOPOLOGY_SESSION_UNKNOWN', 'one or more topology session addresses are unknown');
+        }
+    };
+    const cycleExists = (tx, fromSessionId, toSessionId, relationType) => tx.query(`WITH RECURSIVE reachable(session_id) AS (
+       VALUES (?)
+       UNION
+       SELECT edge.to_session_id
+       FROM topology_edges AS edge INDEXED BY topology_active_edge
+       JOIN reachable ON edge.from_session_id=reachable.session_id
+       WHERE edge.relation_type=? AND edge.removed_at_ms IS NULL
+     )
+     SELECT 1 AS present FROM reachable WHERE session_id=? LIMIT 1`, toSessionId, relationType, fromSessionId).length > 0;
+    const validateNewEdge = (tx, fromSessionId, toSessionId, relationType) => {
+        requireTransaction(tx);
+        requireSessionId(fromSessionId);
+        requireSessionId(toSessionId);
+        requireRelationType(relationType);
+        if (fromSessionId === toSessionId) {
+            failTopology('TOPOLOGY_SELF_EDGE', 'an edge cannot point from a session to itself');
+        }
+        requireAddresses(tx, fromSessionId, toSessionId);
+        if (cycleExists(tx, fromSessionId, toSessionId, relationType)) {
+            failTopology('TOPOLOGY_CYCLE_REFUSED', 'the edge would create a relation cycle');
+        }
+    };
+    const activeEdge = (tx, fromSessionId, toSessionId, relationType) => asEdgeRows(tx.query(`SELECT ${EDGE_COLUMNS} FROM topology_edges INDEXED BY topology_active_edge
+     WHERE from_session_id=? AND to_session_id=? AND relation_type=? AND removed_at_ms IS NULL`, fromSessionId, toSessionId, relationType))[0];
+    const insertEdge = (tx, fromSessionId, toSessionId, relationType) => {
+        const edgeId = randomBytes(16).toString('hex');
+        const createdAtMs = Date.now();
+        try {
+            tx.exec(`INSERT INTO topology_edges
+         (edge_id, from_session_id, to_session_id, relation_type, created_at_ms, removed_at_ms)
+         VALUES (?,?,?,?,?,NULL)`, edgeId, fromSessionId, toSessionId, relationType, createdAtMs);
+        }
+        catch (error) {
+            const code = String(error?.code ?? '');
+            if (code.includes('UNIQUE') || code.includes('PRIMARYKEY')) {
+                failTopology('TOPOLOGY_EDGE_EXISTS', 'the active topology edge already exists', error);
+            }
+            if (code.includes('FOREIGNKEY')) {
+                failTopology('TOPOLOGY_SESSION_UNKNOWN', 'one or more topology session addresses are unknown', error);
+            }
+            failTopology('TOPOLOGY_STORAGE_ERROR', 'the topology edge could not be stored', error);
+        }
+        return { edgeId, fromSessionId, toSessionId, relationType, createdAtMs, removedAtMs: null };
+    };
+    const attach = (tx, fromSessionId, toSessionId, relationType) => {
+        validateNewEdge(tx, fromSessionId, toSessionId, relationType);
+        if (activeEdge(tx, fromSessionId, toSessionId, relationType)) {
+            failTopology('TOPOLOGY_EDGE_EXISTS', 'the active topology edge already exists');
+        }
+        return insertEdge(tx, fromSessionId, toSessionId, relationType);
+    };
+    const detach = (tx, edgeId) => {
+        requireTransaction(tx);
+        requireEdgeId(edgeId);
+        const row = asEdgeRows(tx.query(`SELECT ${EDGE_COLUMNS} FROM topology_edges WHERE edge_id=? AND removed_at_ms IS NULL`, edgeId))[0];
+        if (!row)
+            failTopology('TOPOLOGY_EDGE_UNKNOWN', 'the active topology edge does not exist');
+        const removedAtMs = Date.now();
+        const result = tx.exec('UPDATE topology_edges SET removed_at_ms=? WHERE edge_id=? AND removed_at_ms IS NULL', removedAtMs, edgeId);
+        if (result.changes !== 1) {
+            failTopology('TOPOLOGY_EDGE_UNKNOWN', 'the active topology edge does not exist');
+        }
+        return { ...toEdge(row), removedAtMs };
+    };
+    const withRead = (tx, query) => {
+        if (tx !== undefined)
+            return query(requireTransaction(tx));
+        return protocol.withTransaction(query);
+    };
+    const queryEdges = (sessionId, relationType, tx, direction) => {
+        requireSessionId(sessionId);
+        if (relationType !== undefined)
+            requireRelationType(relationType);
+        return withRead(tx, active => {
+            const index = direction === 'from' ? 'topology_active_edge' : 'topology_active_to';
+            const column = direction === 'from' ? 'from_session_id' : 'to_session_id';
+            const relation = relationType === undefined ? '' : ' AND relation_type=?';
+            const params = relationType === undefined ? [sessionId] : [sessionId, relationType];
+            return asEdgeRows(active.query(`SELECT ${EDGE_COLUMNS} FROM topology_edges INDEXED BY ${index}
+         WHERE ${column}=? AND removed_at_ms IS NULL${relation}
+         ORDER BY relation_type, from_session_id, to_session_id, created_at_ms, edge_id`, ...params)).map(toEdge);
+        });
+    };
+    return {
+        attach,
+        detach,
+        reparent(tx, subjectSessionId, nextFromSessionId, relationType) {
+            validateNewEdge(tx, nextFromSessionId, subjectSessionId, relationType);
+            const removedAtMs = Date.now();
+            tx.exec(`UPDATE topology_edges SET removed_at_ms=?
+         WHERE to_session_id=? AND relation_type=? AND removed_at_ms IS NULL`, removedAtMs, subjectSessionId, relationType);
+            return insertEdge(tx, nextFromSessionId, subjectSessionId, relationType);
+        },
+        subscribe(tx, watcherSessionId, subjectSessionId, channel) {
+            return attach(tx, watcherSessionId, subjectSessionId, channel);
+        },
+        unsubscribe(tx, watcherSessionId, subjectSessionId, channel) {
+            requireTransaction(tx);
+            requireSessionId(watcherSessionId);
+            requireSessionId(subjectSessionId);
+            requireRelationType(channel);
+            const row = activeEdge(tx, watcherSessionId, subjectSessionId, channel);
+            if (!row)
+                failTopology('TOPOLOGY_EDGE_UNKNOWN', 'the active topology edge does not exist');
+            return detach(tx, String(row.edge_id));
+        },
+        parents(sessionId, relationType, tx) {
+            return queryEdges(sessionId, relationType, tx, 'to');
+        },
+        children(sessionId, relationType, tx) {
+            return queryEdges(sessionId, relationType, tx, 'from');
+        },
+        subscriptions(sessionId, tx) {
+            return queryEdges(sessionId, undefined, tx, 'from');
+        },
+        recipients(subjectSessionId, tx) {
+            requireSessionId(subjectSessionId);
+            return withRead(tx, active => active.query(`SELECT DISTINCT from_session_id FROM topology_edges INDEXED BY topology_active_to
+         WHERE to_session_id=? AND removed_at_ms IS NULL ORDER BY from_session_id`, subjectSessionId).map(row => String(row.from_session_id)));
+        },
+    };
+}
+export { TopologyError };

package/dist/schema.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentMigration } from '@spexcode/session-protocol';
+export declare const TOPOLOGY_MIGRATION_SQL = "\nCREATE TABLE topology_edges (\n  edge_id          TEXT    NOT NULL PRIMARY KEY,\n  from_session_id  TEXT    NOT NULL REFERENCES protocol_sessions(session_id),\n  to_session_id    TEXT    NOT NULL REFERENCES protocol_sessions(session_id),\n  relation_type    TEXT    NOT NULL,\n  created_at_ms    INTEGER NOT NULL,\n  removed_at_ms    INTEGER,\n  CHECK (length(edge_id) = 32 AND edge_id NOT GLOB '*[^0-9a-f]*'),\n  CHECK (from_session_id <> to_session_id),\n  CHECK (length(relation_type) BETWEEN 1 AND 64),\n  CHECK (relation_type NOT GLOB '*[^0-9A-Za-z._:-]*'),\n  CHECK (created_at_ms >= 0),\n  CHECK (removed_at_ms IS NULL OR removed_at_ms >= 0)\n) STRICT;\n\nCREATE UNIQUE INDEX topology_active_edge\n  ON topology_edges (from_session_id, to_session_id, relation_type)\n  WHERE removed_at_ms IS NULL;\n\nCREATE INDEX topology_active_to\n  ON topology_edges (to_session_id, relation_type, from_session_id)\n  WHERE removed_at_ms IS NULL;\n";
+export declare const TOPOLOGY_MIGRATIONS: readonly ComponentMigration[];

package/dist/schema.js

@@ -0,0 +1,27 @@
+export const TOPOLOGY_MIGRATION_SQL = `
+CREATE TABLE topology_edges (
+  edge_id          TEXT    NOT NULL PRIMARY KEY,
+  from_session_id  TEXT    NOT NULL REFERENCES protocol_sessions(session_id),
+  to_session_id    TEXT    NOT NULL REFERENCES protocol_sessions(session_id),
+  relation_type    TEXT    NOT NULL,
+  created_at_ms    INTEGER NOT NULL,
+  removed_at_ms    INTEGER,
+  CHECK (length(edge_id) = 32 AND edge_id NOT GLOB '*[^0-9a-f]*'),
+  CHECK (from_session_id <> to_session_id),
+  CHECK (length(relation_type) BETWEEN 1 AND 64),
+  CHECK (relation_type NOT GLOB '*[^0-9A-Za-z._:-]*'),
+  CHECK (created_at_ms >= 0),
+  CHECK (removed_at_ms IS NULL OR removed_at_ms >= 0)
+) STRICT;
+
+CREATE UNIQUE INDEX topology_active_edge
+  ON topology_edges (from_session_id, to_session_id, relation_type)
+  WHERE removed_at_ms IS NULL;
+
+CREATE INDEX topology_active_to
+  ON topology_edges (to_session_id, relation_type, from_session_id)
+  WHERE removed_at_ms IS NULL;
+`;
+export const TOPOLOGY_MIGRATIONS = [
+    { version: 1, sql: TOPOLOGY_MIGRATION_SQL },
+];

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@spexcode/session-topology",
+  "version": "0.6.8",
+  "publishConfig": { "access": "public" },
+  "type": "module",
+  "description": "A neutral SQLite relation model for session addresses.",
+  "files": ["dist"],
+  "exports": {
+    ".": "./dist/index.js",
+    "./package.json": "./package.json"
+  },
+  "engines": { "node": ">=22" },
+  "scripts": {
+    "build": "node ../../scripts/build-dist.mjs",
+    "prepublishOnly": "node ../../scripts/release-publish.mjs --from-package-publish",
+    "test": "npm run build && tsx --import ../../scripts/test-home.mjs --test src/*.test.ts"
+  },
+  "dependencies": { "@spexcode/session-protocol": "0.6.8" },
+  "devDependencies": {
+    "@types/node": "^20.16.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.6.3"
+  }
+}