@ibgib/space-gib 0.0.9 → 0.0.13

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

@@ -1,172 +0,0 @@
-/**
- * @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

@@ -1,90 +0,0 @@
-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

@@ -1,102 +0,0 @@
-/**
- * @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

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