@ibgib/space-gib 0.0.1

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

@@ -0,0 +1,172 @@
+/**
+ * @module serve-gib/serve-gib-v1
+ *
+ * The main entry point for processing incoming requests in the serve-gib
+ * framework.
+ */
+
+import { IncomingMessage, ServerResponse } from 'node:http';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from './constants.mjs';
+import { RequestContext, ResponseResult, ServeGibHandler, ServeGibHttpMethod } from './types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface ServeGibOptions {
+    /** Pipeline of handlers to check in order. */
+    handlers: ServeGibHandler<any, any>[];
+    /** Dedicated handler for errors (404, 500, etc.). */
+    errorHandler: ServeGibHandler<any, any>;
+    /** Port the server is listening on. */
+    port: number;
+    /**
+     * Root data directory for the server. We will use this as the root dir for
+     * all spaces that house multitenant ibgib data.
+     */
+    dataDir: string;
+}
+
+export class ServeGib_V1 {
+    private lc = `[${ServeGib_V1.name}]`;
+
+    constructor(private options: ServeGibOptions) { }
+
+    /**
+     * Entry point for all incoming HTTP requests.
+     */
+    async handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+        const lc = `${this.lc}[${this.handleRequest.name}]`;
+        const start = Date.now();
+        let reqCtx: RequestContext | undefined;
+
+        try {
+            // Contextualize the request
+            reqCtx = await this.prepareContext(req);
+            if (!reqCtx) { throw new Error(`(UNEXPECTED) reqCtx falsy? couldn't prepare context? (E: 401888c0f649dfdf0e2d21f86b3ff826)`); }
+
+            // Execute pipeline
+            let result: ResponseResult | undefined;
+            for (const handler of this.options.handlers) {
+                result = await handler.handleRoute(reqCtx);
+                if (result) { break; }
+            }
+
+            // Fallback if no handler matched
+            if (!result) {
+                result = await this.options.errorHandler.handleRoute(reqCtx);
+            }
+
+            // Final output
+            if (result) {
+                this.sendResponse(res, result);
+            } else {
+                // If even the error handler didn't produce a result
+                this.sendResponse(res, { status: 404, body: 'Not Found' });
+            }
+
+        } catch (error) {
+            console.error(`${lc} Fatal error handling ${req.method} ${req.url}: ${extractErrorMsg(error)}`);
+            try {
+                // Try to use the error handler for the fatal error
+                if (reqCtx) {
+                    const errorResult = await this.options.errorHandler.handleRoute(reqCtx);
+                    this.sendResponse(res, errorResult ?? { status: 500, body: 'Internal Server Error' });
+                } else {
+                    throw new Error(`errored before reqCtx could be set. (E: d77ab84b4f8874e188cfa8e9895f1226)`);
+                }
+            } catch (innerError) {
+                // Total collapse fallback
+                console.error(`${lc} Collapse in error handler: ${extractErrorMsg(innerError)}`);
+                res.writeHead(500);
+                res.end('Critical Server Error');
+            }
+        } finally {
+            const duration = Date.now() - start;
+            // Standard access logging
+            console.log(`${lc} ${req.method} ${req.url} -> ${res.statusCode} (${duration}ms)`);
+        }
+    }
+
+    /**
+     * Builds request context (e.g. extracting/decoding URL, path segments, body
+     * content, etc.), and initializes the request's metaspace if applicable.
+     */
+    public async prepareContext(req: IncomingMessage): Promise<RequestContext> {
+        const lc = `${this.lc}[${this.prepareContext.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: ad9e9c678d0538c2d1e16ca8063d4426)`); }
+
+            /**
+             * These are NOT all of the validation we do on the context, rather,
+             * it is just simple initial validation.
+             */
+            const initialValidationErrors: string[] = [];
+
+            const rawUrl = req.url ?? '/';
+            const protocol = (req.headers['x-forwarded-proto'] as string) || 'http'; // todo: who owns the req.headers? Can an attacker manipulate this?
+            const url = new URL(rawUrl, `${protocol}://localhost:${this.options.port}`); // todo: wth?? Why are we hard-coding localhost? in the URL object?
+
+            const pathname = url.pathname;
+            const rawPathSegments = pathname.split('/');
+            const decodedPathSegments = rawPathSegments.map(s => decodeURIComponent(s));
+
+            const body = await this.readBody(req);
+
+            const reqCtx: RequestContext = {
+                rawUrl,
+                pathname,
+                method: req.method?.toUpperCase() as ServeGibHttpMethod ?? 'GET',
+                protocol,
+                body,
+                rawPathSegments,
+                decodedPathSegments,
+                url,
+                dataDir: this.options.dataDir,
+                headers: req.headers,
+            }
+
+            return reqCtx;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /** Reads the full request body as UTF-8. */
+    private readBody(req: IncomingMessage): Promise<string> {
+        return new Promise((resolve, reject) => {
+            const chunks: Buffer[] = [];
+            req.on('data', (chunk: Buffer) => chunks.push(chunk));
+            req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+            req.on('error', reject);
+        });
+    }
+
+    /** Sends the response result to the client. */
+    private sendResponse(res: ServerResponse, result: ResponseResult): void {
+        const lc = `${this.lc}[${this.sendResponse.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 37369cf120c14780e8652bf27ada1726)`); }
+
+            const { status, headers = {}, body, isJson = false } = result;
+
+            let payload: any = body;
+            if (isJson) {
+                headers['Content-Type'] = 'application/json; charset=utf-8';
+                payload = JSON.stringify(body);
+            }
+
+            res.writeHead(status, headers);
+            res.end(payload);
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

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

@@ -0,0 +1,90 @@
+import { respecfully, iReckon, ifWe } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+import { ServeGib_V1 } from './serve-gib-v1.mjs';
+import { HealthHandler } from './handlers/api/health.handler.mjs';
+import { ErrorHandler } from './handlers/error-handler.mjs';
+
+const sir = `[${import.meta.url}]`;
+
+await respecfully(sir, 'ServeGib ServeGib_V1', async () => {
+
+    await ifWe(sir, 'construct a RouteInfo object', async () => {
+        const serveGib = new ServeGib_V1({
+            port: 3000,
+            dataDir: './test-data',
+            handlers: [],
+            errorHandler: new ErrorHandler()
+        });
+
+        // Mock request
+        const req: any = {
+            url: '/api/health?foo=bar',
+            method: 'GET',
+            headers: { 'x-forwarded-proto': 'https' },
+            on: (event: string, cb: any) => {
+                if (event === 'end') { cb(); }
+            } // immediate end for readBody
+        };
+
+        const info = await (serveGib as any).buildRouteInfo(req);
+
+        iReckon(sir, info.pathname).isGonnaBe('/api/health');
+        iReckon(sir, info.method).isGonnaBe('GET');
+        iReckon(sir, info.protocol).isGonnaBe('https');
+        iReckon(sir, info.pathSegments).includes('api');
+        iReckon(sir, info.pathSegments).includes('health');
+    });
+
+    await ifWe(sir, 'execute a handler in the pipeline', async () => {
+        const health = new HealthHandler();
+        const serveGib = new ServeGib_V1({
+            port: 3000,
+            dataDir: './test-data',
+            handlers: [health],
+            errorHandler: new ErrorHandler()
+        });
+
+        // Mock objects
+        const req: any = {
+            url: '/api/health',
+            method: 'GET',
+            headers: {},
+            on: (event: string, cb: any) => {
+                if (event === 'end') { cb(); }
+            }
+        };
+        const res: any = {
+            writeHead: () => { },
+            end: () => { },
+            statusCode: 200
+        };
+
+        await serveGib.handleRequest(req, res);
+        iReckon(sir, res.statusCode).isGonnaBe(200);
+    });
+
+    await ifWe(sir, 'fall back to error handler when no handler matches', async () => {
+        const serveGib = new ServeGib_V1({
+            port: 3000,
+            dataDir: './test-data',
+            handlers: [],
+            errorHandler: new ErrorHandler()
+        });
+
+        const req: any = {
+            url: '/not/found',
+            method: 'GET',
+            headers: {},
+            on: (event: string, cb: any) => {
+                if (event === 'end') { cb(); }
+            }
+        };
+        const res: any = {
+            writeHead: () => { },
+            end: () => { },
+            statusCode: 404
+        };
+
+        await serveGib.handleRequest(req, res);
+        iReckon(sir, res.statusCode).isGonnaBe(404);
+    });
+});

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

@@ -0,0 +1,102 @@
+/**
+ * @module serve-gib/types
+ *
+ * Foundational types for the serve-gib microframework.
+ */
+
+import { Gib, Ib, IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { GibInfo } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { MetaspaceService } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs';
+
+/**
+ * Standard HTTP methods supported by the serve-gib framework, plus 'ALL' for catch-all handlers.
+ */
+export type ServeGibHttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'OPTIONS' | 'ALL';
+
+/**
+ * @see {@link RequestContext.domainInfo}
+ */
+export interface DomainInfo {
+    ib: Ib;
+    gib: Gib;
+    addr: IbGibAddr;
+    gibInfo: GibInfo;
+    /** The physical root directory for the current domain. */
+    // rootPath?: string;
+}
+
+export interface ParamsWithDomain {
+    domainInfo: DomainInfo;
+}
+
+/**
+ * Encapsulates the context of an incoming HTTP request.
+ */
+export interface RequestContext<TParams = any, TQueryParams = any> {
+    /** The native Node.js/Web URL object. */
+    url: URL;
+    /** The root data directory for spaces. */
+    dataDir: string;
+    /** The original request URL string. */
+    rawUrl: string;
+    /** The pathname part of the URL (e.g. /api/health). */
+    pathname: string;
+    /** HTTP method (GET, POST, etc.). */
+    method: ServeGibHttpMethod;
+    /** Request protocol (http or https). */
+    protocol: string;
+    /** The raw request body as a string. */
+    body: string;
+    /** Array of raw path segments split by '/'. */
+    rawPathSegments: string[];
+    /**
+     * Same as {@link rawPathSegments}, but with any ibgib addr(s) URL decoded.
+     */
+    decodedPathSegments: string[];
+    params?: TParams;
+    /** Parsed query parameters. */
+    queryParams?: TQueryParams;
+    /** Request headers. */
+    headers: Record<string, string | string[] | undefined>;
+    /**
+     * The bootstrapped MetaspaceService for the current domain.
+     *
+     * Note that not all routes require this, hence it's optional.
+     */
+    metaspace?: MetaspaceService;
+    /**
+     * keystones define "domains" to enable multitenancy. This is info about the
+     * keystone domain.
+     *
+     * ## notes
+     *
+     * I would call this "KeystoneInfo", and right now, this is only one keystone's
+     * info. but ultimately I _think_ that we will have nested domains.
+     */
+    domainInfo?: DomainInfo;
+}
+
+/**
+ * Standardized response shape returned by handlers.
+ */
+export interface ResponseResult {
+    /** HTTP status code (200, 404, etc.). */
+    status: number;
+    /** Optional response headers. */
+    headers?: Record<string, string>;
+    /** Response body content. */
+    body: any;
+    /** If true, body will be stringified as JSON and Content-Type set accordingly. */
+    isJson?: boolean;
+}
+
+/**
+ * Interface for a serve-gib route handler.
+ */
+export interface ServeGibHandler<TParams, TQueryParams> {
+    /**
+     * Attempts to handle the request.
+     * @returns A ResponseResult if handled, or undefined to pass to the next handler.
+     */
+    handleRoute(reqCtx: RequestContext<TParams, TQueryParams>): Promise<ResponseResult | undefined>;
+}

package/src/server/server-constants.mts

@@ -0,0 +1,2 @@
+export const GLOBAL_LOG_A_LOT = false;
+export const GLOBAL_TIMER_NAME = '[space^gib server timer]';

package/src/server/server.mts

@@ -0,0 +1,96 @@
+/**
+ * @module server
+ *
+ * Native Node.js HTTP server for space-gib — using the serve-gib microframework.
+ */
+
+import { createServer } from 'node:http';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import { ServeGib_V1 } from './serve-gib/serve-gib-v1.mjs';
+import { HealthHandler } from './serve-gib/handlers/api/health.handler.mjs';
+import { IbGibHandler } from './serve-gib/handlers/api/ibgib/ibgib.handler.mjs';
+import { KeystonePostHandler } from './serve-gib/handlers/api/keystone/keystone-post.handler.mjs';
+import { KeystoneGetHandler } from './serve-gib/handlers/api/keystone/keystone-get.handler.mjs';
+import { KeystoneGenesisHandler } from './serve-gib/handlers/api/keystone/keystone-genesis.handler.mjs';
+import { KeystoneEvolveHandler } from './serve-gib/handlers/api/keystone/keystone-evolve.handler.mjs';
+import { StaticFileHandler } from './serve-gib/handlers/static-handler.mjs';
+import { ErrorHandler } from './serve-gib/handlers/error-handler.mjs';
+import { canHandleWsUpgrade, handleWsEchoUpgrade } from './serve-gib/handlers/api/debug/ws-echo.handler.mjs';
+import { SyncUpgradeHandler } from './serve-gib/handlers/ws/sync-upgrade.handler.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Config
+// ---------------------------------------------------------------------------
+
+const PORT = parseInt(process.env.PORT ?? '3000', 10);
+const DATA_DIR = process.env.DATA_DIR ?? join(__dirname, '../../.data/ibgib-space');
+const CLIENT_DIR = join(__dirname, '../client');
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main(): Promise<void> {
+    const lc = '[space-gib server]';
+    try {
+        console.log(`${lc} starting...`);
+
+        console.log(`${lc} dataDir: ${DATA_DIR}`);
+
+        const syncUpgradeHandler = new SyncUpgradeHandler();
+
+        // Initialize serve-gib
+        const serveGib = new ServeGib_V1({
+            port: PORT,
+            dataDir: DATA_DIR,
+            handlers: [
+                new HealthHandler(),
+                new IbGibHandler(),
+                new KeystoneGenesisHandler(),
+                new KeystoneEvolveHandler(),
+                new KeystonePostHandler(),
+                new KeystoneGetHandler(),
+                new StaticFileHandler(CLIENT_DIR),
+            ],
+            errorHandler: new ErrorHandler()
+        });
+
+        const server = createServer(async (req, res) => {
+            await serveGib.handleRequest(req, res);
+        });
+
+        // WebSocket upgrade handling — separate from the HTTP request pipeline
+        // since Node.js fires `upgrade` events independently of `request` events.
+        server.on('upgrade', async (req, socket, head) => {
+            const reqCtx = await serveGib.prepareContext(req);
+            
+            // Check sync upgrade handler first
+            const isSync = await syncUpgradeHandler.handleUpgrade(reqCtx, socket as any, head);
+            
+            // Fallback to debug echo if not handled by sync
+            if (!isSync && canHandleWsUpgrade(req)) {
+                handleWsEchoUpgrade(req, socket as any, head);
+            } else if (!isSync) {
+                // Reject unrecognized upgrade requests
+                socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
+                socket.destroy();
+            }
+        });
+
+        server.listen(PORT, '0.0.0.0', () => {
+            console.log(`${lc} listening on http://0.0.0.0:${PORT}`);
+        });
+
+    } catch (error) {
+        console.error(`${lc} fatal: ${extractErrorMsg(error)}`);
+        process.exit(1);
+    }
+}
+
+main();

package/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": false,
+    "rootDir": "./src",
+    "composite": false,
+    "outDir": "./dist/client",
+    "module": "ESNext",
+    "lib": [
+      "DOM",
+      "ES2022",
+      "ES2023"
+    ]
+  },
+  "include": [
+    "src/client/**/*.ts",
+    "src/client/**/*.mts",
+    "src/client/**/*.d.ts",
+    "src/common/**/*.ts",
+    "src/common/**/*.mts"
+  ],
+  "exclude": [
+    "node_modules",
+    "**/*.respec.mts",
+    "./dist/**/*"
+  ]
+}

package/tsconfig.server.json

@@ -0,0 +1,29 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": false,
+    "rootDir": "./src",
+    "composite": false,
+    "outDir": "./dist/server",
+    "module": "ESNext",
+    "lib": [
+      "ES2022",
+      "ES2023"
+    ],
+    "types": ["node"]
+  },
+  "include": [
+    "src/server/**/*.ts",
+    "src/server/**/*.mts",
+    "src/server/**/*.d.ts",
+    "src/common/**/*.ts",
+    "src/common/**/*.mts"
+  ],
+  "exclude": [
+    "node_modules",
+    "**/*.respec.mts",
+    "./dist/**/*"
+  ]
+}

package/tsconfig.test.json

@@ -0,0 +1,27 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": false,
+    "rootDir": "./src",
+    "composite": false,
+    "outDir": "./dist",
+    "module": "ESNext",
+    "lib": [
+      "ES2022",
+      "ES2023"
+    ],
+    "types": ["node"]
+  },
+  "include": [
+    "src/server/**/*.ts",
+    "src/server/**/*.mts",
+    "src/server/**/*.d.ts",
+    "src/respec-gib.node.mts"
+  ],
+  "exclude": [
+    "node_modules",
+    "./dist/**/*"
+  ]
+}