@ibgib/space-gib 0.0.1 → 0.0.2

package/src/server/serve-gib/handlers/api/keystone/keystone-post.handler.mts

@@ -3,8 +3,7 @@
  */
 
 import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
-import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
+import { validateAndRegisterPostKeystones } from '@ibgib/core-gib/dist/sync/sync-peer/sync-peer-websocket-receiver/sync-websocket-peer-helpers.mjs';
 
 import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
 import { ServeGibHandlerBase } from '../../handler-base.mjs';
@@ -12,7 +11,7 @@ import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../typ
 import { API_PATH_REGEXES } from '../../../../path-constants.mjs';
 import { KeystoneParams } from './keystone-handler-types.mjs';
 
-const logalot = GLOBAL_LOG_A_LOT;
+const logalot = GLOBAL_LOG_A_LOT || true;
 
 /**
  * POST /api/keystone
@@ -33,30 +32,16 @@ export class KeystonePostHandler extends ServeGibHandlerBase<KeystoneParams, any
             const { ibGibs } = JSON.parse(reqCtx.body) as { ibGibs: any[] };
             if (!Array.isArray(ibGibs)) return this.error(400, 'ibGibs array required');
 
-            // 1. Intrinsic Validation
-            for (const ibGib of ibGibs) {
-                const errors = await validateIbGibIntrinsically({ ibGib });
-                if (errors) {
-                    return this.error(422, 'Intrinsic validation failed', { failedAddr: getIbGibAddr({ ibGib }), errors });
-                }
-            }
+            const space = await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) { throw new Error(`No local user space found`); }
 
-            // 2. Keystone-specific checks
-            for (const ibGib of ibGibs) {
-                if (ibGib.ib?.startsWith('keystone')) {
-                    if (!reqCtx.metaspace) { return this.error(500, 'Metaspace not initialized'); }
-                    // Registration handles genesis vs evolution internally via metastones
-                    await reqCtx.metaspace.registerNewIbGib({
-                        ibGib,
-                    });
-                }
-            }
+            // Delegate all intrinsic validation, keystone-specific checks, registration, and persistence to core-gib
+            await validateAndRegisterPostKeystones({
+                ibGibs,
+                metaspace,
+                space
+            });
 
-            // 3. Persistence
-            console.log(`[KeystoneHandler] Persisting ${ibGibs.length} ibGibs...`);
-            await metaspace.put({ ibGibs })
-            // await spaceSvc.putIbGibGraph(ibGibs);
-            console.log(`[KeystoneHandler] Persistence successful.`);
             return { status: 201, body: { success: true }, isJson: true };
 
         } catch (error) {

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

@@ -0,0 +1,201 @@
+/**
+ * @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-receiver/sync-peer-websocket-receiver-v1.mjs';
+import { validateUpfrontConnect } from '@ibgib/core-gib/dist/sync/sync-peer/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
+            });
+
+            // 6. Map standard Node.js Socket to platform-agnostic IWebSocketWrapper
+            const socketWrapper: IWebSocketWrapper = {
+                send(data: string): void {
+                    socket.write(encodeTextFrame(data));
+                },
+                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)}`); }
+                            socket.write(encodeCloseFrame());
+                            socket.end();
+                        }
+                    });
+                },
+                onClose(callback: () => void): void {
+                    socket.on('close', callback);
+                }
+            };
+
+            // 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');
+    }
+}