@ibgib/space-gib 0.0.9 → 0.0.13

package/src/server/serve-gib/handlers/ws/sync-upgrade-handler-base.mts

@@ -1,233 +0,0 @@
-/**
- * @module handlers/ws/sync-upgrade-handler-base
- *
- * Highly generic, reusable base class in serve-gib for handling WebSocket upgrades,
- * mapping socket streams to isomorphic SyncPeers, and checking upfront connect handshakes.
- */
-
-import { IncomingMessage } from 'node:http';
-import { Socket } from 'node:net';
-import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { getIbGibAddr, getIbAndGib } from '@ibgib/ts-gib/dist/helper.mjs';
-import { validateIbGibAddr } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
-import { parseKeystoneIb } from '@ibgib/core-gib/dist/keystone/keystone-helpers.mjs';
-import { SyncPeerWebSocketReceiver_V1, IWebSocketWrapper } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-websocket/sync-peer-websocket-receiver/sync-peer-websocket-receiver-v1.mjs';
-import { validateUpfrontConnect } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-websocket/sync-peer-websocket-receiver/sync-websocket-peer-helpers.mjs';
-import { SyncSagaCoordinator } from '@ibgib/core-gib/dist/sync/sync-saga-coordinator.mjs';
-
-import { GLOBAL_LOG_A_LOT } from '../../constants.mjs';
-import {
-    encodeTextFrame, decodeTextFrame, encodeCloseFrame, performConnect,
-    WebSocketFrameDecoder
-} from './ws-helper.mjs';
-import { ServeGibHandlerWithMetaspaceBase } from '../handler-base.mjs';
-import { ParamsWithDomain, RequestContext, ResponseResult, ServeGibHttpMethod } from '../../types.mjs';
-
-const logalot = GLOBAL_LOG_A_LOT;
-
-export interface SyncChannelQueryParams {
-    sAddr: string;
-    solution: string;
-}
-
-export interface SyncChannelRequestContext extends RequestContext<ParamsWithDomain, SyncChannelQueryParams> {
-}
-
-/**
- * Reusable server-side upgrade handler plumbing.
- * Binds raw node socket streams to platform-agnostic receiver peers.
- */
-export abstract class SyncUpgradeHandlerBase extends ServeGibHandlerWithMetaspaceBase<ParamsWithDomain, SyncChannelQueryParams> {
-    protected override lc: string = `[${SyncUpgradeHandlerBase.name}]`;
-    protected override method: ServeGibHttpMethod = 'GET';
-
-    /**
-     * Entry point for WebSocket upgrades.
-     * Orchestrates the upgrade, upfront validation, and registers the Receiver peer.
-     */
-    async handleUpgrade(reqCtx: RequestContext<ParamsWithDomain>, socket: Socket, head: Buffer): Promise<boolean> {
-        const lc_fn = `${this.lc}[handleUpgrade]`;
-        try {
-            if (logalot) { console.log(`${lc_fn} starting...`); }
-
-            // 1. Initial routing checks
-            if (!this.canHandleRoute(reqCtx)) {
-                return false;
-            }
-
-            const ctx = reqCtx as SyncChannelRequestContext;
-
-            // Extract route parameters & query parameters
-            ctx.params = await this.parseParams(ctx);
-            ctx.queryParams = await this.parseQueryParams(ctx);
-
-            // 2. Bootstrap multi-tenant domain metaspace context
-            await this.initConcreteContext(ctx);
-
-            const metaspace = ctx.metaspace!;
-            const space = await metaspace.getLocalUserSpace({ lock: false });
-            if (!space) { throw new Error("No default local user space found."); }
-
-            // 3. Upfront picket-fence pre-filter validation
-            const queryParams = ctx.queryParams!;
-            await validateUpfrontConnect({
-                sAddr: queryParams.sAddr,
-                solution: queryParams.solution,
-                space,
-                metaspace
-            });
-
-            // 4. Perform standard RFC 6455 Connect H andshake Upgrade
-            const ok = performConnect(ctx as any as IncomingMessage, socket);
-            if (!ok) { return true; }
-
-            // 5. Instantiate and initialize isomorphic WebSocket Receiver Peer
-            const receiverPeer = new SyncPeerWebSocketReceiver_V1({
-                classname: 'SyncPeerWebSocketReceiver_V1'
-            });
-
-            const localCoordinator = new SyncSagaCoordinator();
-            await receiverPeer.initializeOpts({
-                localCoordinator,
-                localMetaspace: metaspace,
-                localSpace: space,
-                sagaId: undefined, // Resolved dynamically inside runtime turns
-            });
-
-            // Handle raw socket errors to prevent unhandled 'error' crash (e.g. ECONNRESET)
-            socket.on('error', (err) => {
-                if (logalot) { console.warn(`[SyncUpgradeHandlerBase] Socket error: ${extractErrorMsg(err)}`); }
-                try {
-                    socket.destroy();
-                } catch (e) {
-                    // ignore
-                }
-            });
-
-            // 6. Map standard Node.js Socket to platform-agnostic IWebSocketWrapper
-            const socketWrapper: IWebSocketWrapper = {
-                send(data: string): void {
-                    if (socket.writable) {
-                        try {
-                            socket.write(encodeTextFrame(data));
-                        } catch (e) {
-                            if (logalot) { console.warn(`[SyncUpgradeHandlerBase] failed to write message frame: ${extractErrorMsg(e)}`); }
-                        }
-                    }
-                },
-                onMessage(callback: (data: string) => void): void {
-                    const decoder = new WebSocketFrameDecoder();
-                    socket.on('data', (buf) => {
-                        try {
-                            decoder.addChunk(buf);
-                            let frameText = decoder.nextFrame();
-                            while (frameText !== null) {
-                                callback(frameText);
-                                frameText = decoder.nextFrame();
-                            }
-                        } catch (error) {
-                            if (logalot) { console.warn(`[SyncUpgradeHandlerBase] closing connection due to decoder error: ${extractErrorMsg(error)}`); }
-                            if (socket.writable) {
-                                try {
-                                    socket.write(encodeCloseFrame());
-                                } catch (e) {
-                                    // ignore
-                                }
-                            }
-                            socket.end();
-                        }
-                    });
-                },
-                onClose(callback: () => void): void {
-                    socket.on('close', callback);
-                },
-                close(): void {
-                    if (socket.writable) {
-                        try {
-                            socket.write(encodeCloseFrame());
-                        } catch (e) {
-                            // ignore
-                        }
-                    }
-                    socket.end();
-                }
-            };
-
-            // Bind peer receiver to handle all socket messages (connect & runtime)
-            await receiverPeer.bindSocket(socketWrapper);
-
-            return true;
-        } catch (error) {
-            console.error(`${lc_fn} upgrade failure: ${extractErrorMsg(error)}`);
-            socket.destroy();
-            return true;
-        }
-    }
-
-    protected override async parseParamsImpl(reqCtx: RequestContext<ParamsWithDomain>): Promise<ParamsWithDomain | undefined> {
-        const match = reqCtx.pathname.match(this.regex);
-        if (!match) { return undefined; }
-        const domainIb = decodeURIComponent(match[1]);
-        const domainGib = decodeURIComponent(match[2]);
-        const domainAddr = getIbGibAddr({ ib: domainIb, gib: domainGib });
-
-        return {
-            domainInfo: this.getDomainInfo({ domainAddr })
-        };
-    }
-
-    protected override async parseQueryParams(
-        reqCtx: RequestContext<ParamsWithDomain, SyncChannelQueryParams>
-    ): Promise<SyncChannelQueryParams | undefined> {
-        const sAddrRaw = reqCtx.url.searchParams.get('sAddr');
-        const sAddr = sAddrRaw ? decodeURIComponent(sAddrRaw) : undefined;
-        const solution = reqCtx.url.searchParams.get('solution') ?? undefined;
-
-        const queryParams: Partial<SyncChannelQueryParams> = {};
-        if (sAddr !== undefined) { queryParams.sAddr = sAddr; }
-        if (solution !== undefined) { queryParams.solution = solution; }
-
-        if (Object.keys(queryParams).length > 0) {
-            const validationErrors = await this.validateQueryParams({ queryParams });
-            if (validationErrors.length === 0) {
-                return queryParams as SyncChannelQueryParams;
-            } else {
-                throw new Error(`invalid query params: ${validationErrors.join(', ')}`);
-            }
-        }
-        return undefined;
-    }
-
-    protected override async validateQueryParams({ queryParams }: { queryParams: any }): Promise<string[]> {
-        const errors: string[] = [];
-        if (!queryParams) {
-            return ["Missing query parameters: sAddr, solution"];
-        }
-
-        if (!queryParams.sAddr) {
-            errors.push("Missing sAddr");
-        } else {
-            try {
-                const decodedSAddr = queryParams.sAddr;
-                const addrErrors = validateIbGibAddr({ addr: decodedSAddr }) ?? [];
-                if (addrErrors.length > 0) {
-                    errors.push(`Invalid sAddr: ${addrErrors.join(', ')}`);
-                } else {
-                    const { ib } = getIbAndGib({ ibGibAddr: decodedSAddr });
-                    parseKeystoneIb({ ib });
-                }
-            } catch (error) {
-                errors.push(`Invalid sAddr: ${extractErrorMsg(error)}`);
-            }
-        }
-
-        if (!queryParams.solution) {
-            errors.push("Missing solution");
-        }
-        return errors;
-    }
-
-    protected override async handleRouteImpl(reqCtx: RequestContext<ParamsWithDomain>): Promise<ResponseResult | undefined> {
-        return this.error(400, 'WS endpoint requires upgrade');
-    }
-}

package/src/server/serve-gib/handlers/ws/sync-upgrade.handler.mts

@@ -1,24 +0,0 @@
-/**
- * @module handlers/ws/sync-upgrade.handler
- *
- * Concrete implementation of the serve-gib WebSocket Sync Peer wrapper.
- * Decoupled from core protocols by extending SyncUpgradeHandlerBase.
- */
-
-import { SyncUpgradeHandlerBase } from './sync-upgrade-handler-base.mjs';
-import { API_PATH_REGEXES } from '../../../path-constants.mjs';
-import { ServeGibHttpMethod } from '../../types.mjs';
-
-/**
- * SyncChannelHandler manages the WebSocket Connect and Transport channel.
- * Delegates 100% of connect handshake, signature verify, and sync turns to
- * SyncPeerWebSocketReceiver_V1.
- */
-export class SyncChannelHandler extends SyncUpgradeHandlerBase {
-    protected override lc: string = `[${SyncChannelHandler.name}]`;
-    protected override method: ServeGibHttpMethod = 'GET';
-    protected override regex: RegExp = API_PATH_REGEXES.SYNC_WS;
-}
-
-/** Keep naming backward-compatible for server registrations */
-export const SyncUpgradeHandler = SyncChannelHandler;

package/src/server/serve-gib/handlers/ws/ws-helper.mts

@@ -1,216 +0,0 @@
-import { createHash } from 'node:crypto';
-import { IncomingMessage } from 'node:http';
-import { Socket } from 'node:net';
-
-import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-
-const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
-
-/** Encodes a UTF-8 string as a minimal unmasked WebSocket text frame. */
-export function encodeTextFrame(text: string): Buffer {
-    const payload = Buffer.from(text, 'utf-8');
-    const payloadLen = payload.length;
-
-    let header: Buffer;
-    if (payloadLen < 126) {
-        header = Buffer.alloc(2);
-        header[0] = 0x81; // FIN + opcode 1 (text)
-        header[1] = payloadLen;
-    } else if (payloadLen < 65536) {
-        header = Buffer.alloc(4);
-        header[0] = 0x81;
-        header[1] = 126;
-        header.writeUInt16BE(payloadLen, 2);
-    } else {
-        header = Buffer.alloc(10);
-        header[0] = 0x81;
-        header[1] = 127;
-        header.writeBigUInt64BE(BigInt(payloadLen), 2);
-    }
-
-    return Buffer.concat([header, payload]);
-}
-
-/** Decodes a masked client WebSocket text frame. Returns null for non-text or incomplete frames. */
-export function decodeTextFrame(data: Buffer): string | null {
-    try {
-        if (data.length < 2) { return null; }
-
-        const opcode = data[0] & 0x0f;
-        if (opcode === 0x8) { return null; } // Close
-        if (opcode !== 0x1) { return null; } // Text only
-
-        const masked = (data[1] & 0x80) !== 0;
-        let payloadStart = 2;
-        let payloadLen = data[1] & 0x7f;
-
-        if (payloadLen === 126) {
-            payloadLen = data.readUInt16BE(2);
-            payloadStart = 4;
-        } else if (payloadLen === 127) {
-            payloadLen = Number(data.readBigUInt64BE(2));
-            payloadStart = 10;
-        }
-
-        if (masked) {
-            const maskStart = payloadStart;
-            payloadStart += 4;
-            const mask = data.slice(maskStart, maskStart + 4);
-            const payload = data.slice(payloadStart, payloadStart + payloadLen);
-            for (let i = 0; i < payload.length; i++) {
-                payload[i] ^= mask[i % 4];
-            }
-            return payload.toString('utf-8');
-        }
-
-        return data.slice(payloadStart, payloadStart + payloadLen).toString('utf-8');
-    } catch (error) {
-        console.error(`[ws-helper] decode error: ${extractErrorMsg(error)}`);
-        return null;
-    }
-}
-
-/** Encodes a WebSocket close frame (opcode 0x8) with optional status code. */
-export function encodeCloseFrame(code = 1000): Buffer {
-    const frame = Buffer.alloc(4);
-    frame[0] = 0x88;
-    frame[1] = 2;
-    frame.writeUInt16BE(code, 2);
-    return frame;
-}
-
-/** Performs the RFC 6455 opening connect handshake. */
-export function performConnect(req: IncomingMessage, socket: Socket): boolean {
-    try {
-        const key = req.headers['sec-websocket-key'];
-        if (!key) {
-            socket.write('HTTP/1.1 400 Bad Request\r\n\r\nMissing Sec-WebSocket-Key');
-            socket.destroy();
-            return false;
-        }
-
-        const acceptKey = createHash('sha1')
-            .update(key + WS_MAGIC)
-            .digest('base64');
-
-        const response = [
-            'HTTP/1.1 101 Switching Protocols',
-            'Upgrade: websocket',
-            'Connection: Upgrade',
-            `Sec-WebSocket-Accept: ${acceptKey}`,
-            '\r\n',
-        ].join('\r\n');
-
-        socket.write(response);
-        return true;
-    } catch (error) {
-        console.error(`[ws-helper] connect error: ${extractErrorMsg(error)}`);
-        socket.destroy();
-        return false;
-    }
-}
-
-/**
- * Stateful WebSocket text frame decoder that aggregates incoming TCP chunks
- * and decodes full RFC 6455 frames.
- */
-export class WebSocketFrameDecoder {
-    private buffer: Buffer = Buffer.alloc(0);
-    private fragments: Buffer[] = [];
-
-    /** Adds new data chunk from TCP socket. */
-    addChunk(chunk: Buffer): void {
-        this.buffer = Buffer.concat([this.buffer, chunk]);
-    }
-
-    /**
-     * Parses the next complete text message, assembling fragments if necessary.
-     * Returns:
-     * - `string` if a complete text message was assembled/decoded (and consumes those bytes).
-     * - `null` if the buffer is incomplete or we need more data.
-     * - `throws Error` on protocol errors or close frames.
-     */
-    nextFrame(): string | null {
-        while (true) {
-            if (this.buffer.length < 2) {
-                return null;
-            }
-
-            const firstByte = this.buffer[0];
-            const fin = (firstByte & 0x80) !== 0;
-            const opcode = firstByte & 0x0f;
-
-            if (opcode === 0x8) {
-                throw new Error('Close frame received');
-            }
-
-            const isContinuation = opcode === 0x0;
-            const isText = opcode === 0x1;
-
-            if (!isContinuation && !isText) {
-                throw new Error(`Unsupported WebSocket opcode: 0x${opcode.toString(16)}`);
-            }
-
-            // Protocol checks
-            if (isContinuation && this.fragments.length === 0) {
-                throw new Error('Continuation frame received without an active message.');
-            }
-            if (isText && this.fragments.length > 0) {
-                throw new Error('New message frame received before previous one completed.');
-            }
-
-            const secondByte = this.buffer[1];
-            const masked = (secondByte & 0x80) !== 0;
-            let payloadLen = secondByte & 0x7f;
-            let headerLen = 2;
-
-            if (payloadLen === 126) {
-                if (this.buffer.length < 4) {
-                    return null;
-                }
-                payloadLen = this.buffer.readUInt16BE(2);
-                headerLen = 4;
-            } else if (payloadLen === 127) {
-                if (this.buffer.length < 10) {
-                    return null;
-                }
-                payloadLen = Number(this.buffer.readBigUInt64BE(2));
-                headerLen = 10;
-            }
-
-            const maskLen = masked ? 4 : 0;
-            const totalFrameLen = headerLen + maskLen + payloadLen;
-
-            if (this.buffer.length < totalFrameLen) {
-                return null;
-            }
-
-            // Consume frame from buffer
-            const frameData = this.buffer.subarray(0, totalFrameLen);
-            this.buffer = this.buffer.subarray(totalFrameLen);
-
-            let payloadStart = headerLen;
-            let payload: Buffer;
-            if (masked) {
-                const mask = frameData.subarray(payloadStart, payloadStart + 4);
-                payloadStart += 4;
-                payload = Buffer.from(frameData.subarray(payloadStart));
-                for (let i = 0; i < payload.length; i++) {
-                    payload[i] ^= mask[i % 4];
-                }
-            } else {
-                payload = Buffer.from(frameData.subarray(payloadStart));
-            }
-
-            this.fragments.push(payload);
-
-            if (fin) {
-                const completePayload = Buffer.concat(this.fragments);
-                this.fragments = [];
-                return completePayload.toString('utf-8');
-            }
-            
-            // Loop again to process any subsequent frames already inside the TCP buffer
-        }
-    }
-}

package/src/server/serve-gib/handlers/ws/ws-types.mts

@@ -1,53 +0,0 @@
-import { KeystoneIbGib_V1 } from "@ibgib/core-gib/dist/keystone/keystone-types.mjs";
-
-export type HandshakeMessageType =
-    'auth-challenge-init' |
-    'auth-init' |
-    'auth-challenge' |
-    'auth-proof' |
-    'auth-ok' |
-    'auth-fail';
-
-export interface HandshakeMessageBase {
-    type: HandshakeMessageType;
-}
-
-export interface AuthChallengeInitMessage extends HandshakeMessageBase {
-    type: 'auth-challenge-init';
-    challengeUuid: string;
-}
-
-export interface AuthInitMessage extends HandshakeMessageBase {
-    type: 'auth-init';
-    sAddr: string;
-}
-
-export interface AuthChallengeMessage extends HandshakeMessageBase {
-    type: 'auth-challenge';
-    challengeUuid: string;
-    demandedIds: string[];
-}
-
-export interface AuthProofMessage extends HandshakeMessageBase {
-    type: 'auth-proof';
-    proofFrame: KeystoneIbGib_V1;
-}
-
-export interface AuthOkMessage extends HandshakeMessageBase {
-    type: 'auth-ok';
-}
-
-export interface AuthFailMessage extends HandshakeMessageBase {
-    type: 'auth-fail';
-    message: string;
-    errors?: string[];
-}
-
-export type HandshakeMessage =
-    AuthChallengeInitMessage |
-    AuthInitMessage |
-    AuthChallengeMessage |
-    AuthProofMessage |
-    AuthOkMessage |
-    AuthFailMessage;
-

package/src/server/serve-gib/serve-gib-helpers.mts

@@ -1,32 +0,0 @@
-/**
- * @module serve-gib/serve-gib-helpers
- * 
- * General purpose helper functions for the serve-gib framework.
- */
-
-/**
- * Validates and coerces a boolean query parameter in place on the queryParams object.
- * 
- * @param queryParams The parsed query parameters object
- * @param key The specific key to validate and coerce
- * @param errors Array to push error messages into if validation fails
- */
-export function validateAndCoerceBooleanQueryParam(
-    queryParams: any,
-    key: string,
-    errors: string[]
-): void {
-    const rawVal = queryParams[key];
-    if (typeof rawVal === 'string' &&
-        (rawVal.toLowerCase() === 'true' || rawVal.toLowerCase() === 'false')
-    ) {
-        queryParams[key] = rawVal.toLowerCase() === 'true';
-    } else if (typeof rawVal === 'boolean') {
-        // do nothing, it's already a boolean
-    } else if (rawVal !== undefined) {
-        errors.push(`invalid value for "${key}". typeof should either be string or boolean. (E: c28ef87a2d4b4a6faef9a2c8db05b637)`);
-    } else {
-        // It's undefined, which means it wasn't provided in the URL.
-        // We do not error here because default parameters apply later or it may be optional.
-    }
-}