@ibgib/space-gib 0.0.1

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

@@ -0,0 +1,383 @@
+/**
+ * @module serve-gib/handler
+ *
+ * Base class and utilities for serve-gib handlers.
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { IbGibAddr } from '@ibgib/ts-gib/dist/types.mjs';
+import { getIbAndGib } from '@ibgib/ts-gib/dist/helper.mjs';
+import { getGibInfo } from '@ibgib/ts-gib/dist/V1/transforms/transform-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../constants.mjs';
+import { DomainInfo, ParamsWithDomain, RequestContext, ResponseResult, ServeGibHandler } from '../types.mjs';
+import { ServeGibHttpMethod } from '../types.mjs';
+import { bootstrapDomainMetaspace, getDomainRootPath } from '../../bootstrap-helper.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * Abstract base class for serve-gib handlers.
+ * Provides a "pit of success" plumbing for routing, error handling, and parameter parsing.
+ *
+ * @template TParams Type for the parsed query parameters.
+ * @template TQueryParams Type for the parsed query parameters.
+ */
+export abstract class ServeGibHandlerBase<TParams = any, TQueryParams = any>
+    implements ServeGibHandler<TParams, TQueryParams> {
+    protected lc: string = `[${ServeGibHandlerBase.name}]`;
+
+    /** The HTTP method this handler supports, or 'ALL' for catch-all. */
+    protected abstract method: ServeGibHttpMethod;
+
+    /** Regex for quick route matching via the default `canHandleRoute`. */
+    protected abstract regex: RegExp;
+
+    /**
+     * The main entry point processing incoming requests.
+     * Implements standard plumbing for matching, error handling, and param parsing.
+     */
+    async handleRoute(reqCtx: RequestContext<TParams, TQueryParams>): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRoute.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: ad1a523a7bbd222db2e6ffab54f59c26)`); }
+
+            // First check if we can handle it
+            if (!this.canHandleRoute(reqCtx)) {
+                if (logalot) { console.log(`${lc} cannot handle route. returning undefined. (I: 359bd4a9d44acb2408e3ad9570cfa526)`); }
+                return undefined; /* <<<< returns early */
+            }
+
+            // prepare handling params, e.g., keystone/domain addr(s), ibgib
+            // addr(s), not sure what else
+            reqCtx.params = await this.parseParams(reqCtx);
+
+            // prepare queryParams
+            reqCtx.queryParams = await this.parseQueryParams(reqCtx);
+
+            // hook to initialize contextual things like metaspace
+            await this.initConcreteContext(reqCtx);
+
+            // Delegate to implementation
+            return await this.handleRouteImpl(reqCtx);
+
+        } catch (error) {
+            const emsg = `${lc} Error handling route: ${extractErrorMsg(error)}`;
+            console.error(emsg);
+            // Standard fallback error. Individual handlers can override with more specific catches in handleRouteImpl.
+            return this.error(500, 'Internal Server Error', {
+                errorMsg: emsg,
+                method: this.method,
+                regex: this.regex?.source,
+                rawUrl: reqCtx?.rawUrl,
+            });
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+    /**
+     * Concrete implementation of the handler logic.
+     *
+     * This is where the "meat" of the code goes, as there is some
+     * pre-processing in the parent wrapper.
+     */
+    protected abstract handleRouteImpl(reqCtx: RequestContext<TParams, TQueryParams>): Promise<ResponseResult | undefined>;
+
+    /**
+     * Extracts per-handler/route params from a request context.
+     *
+     * @see {@link RequestContext.params}
+     */
+    parseParams(reqCtx: RequestContext<TParams, TQueryParams>): Promise<TParams | undefined> {
+        const lc = `${this.lc}[${this.parseParams.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: c08d98768f449317b8e4b56925d3b826)`); }
+            return this.parseParamsImpl(reqCtx);
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+    /**
+     * Concrete implementation for extracting params from a path.
+     *
+     * @see {@link RequestContext.params}
+     */
+    protected async parseParamsImpl(reqCtx: RequestContext<TParams, TQueryParams>): Promise<TParams | undefined> {
+        const lc = `${this.lc}[${this.parseParamsImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 849e491b436860d6788b76c898b0a826)`); }
+
+            if (logalot) { console.log(`${lc} default implementation in base class is a no-op (I: 88d128a11e1c66030839dc582486e826)`); }
+
+            return undefined;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Hook to initialize concrete context, e.g., initializing a metaspace for the
+     * specific domain. The base implementation is a no-op.
+     */
+    protected async initConcreteContext(reqCtx: RequestContext<TParams, TQueryParams>): Promise<void> {
+        const lc = `${this.lc}[${this.initConcreteContext.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            if (logalot) { console.log(`${lc} default implementation in base class is a no-op`); }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Determines if this handler should attempt to handle the given request.
+     *
+     * Default implementation checks {@link method} and {@link regex} matching
+     * against the pathname. Override for more advanced logic for edge cases.
+     */
+    protected canHandleRoute(reqCtx: RequestContext<TParams, TQueryParams>): boolean {
+        const lc = `${this.lc}[${this.canHandleRoute.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: d790f637074feee63c4bfcb158f47826)`); }
+
+            const isMethodMatch = this.method === 'ALL' || reqCtx.method === this.method;
+            const isRegexMatch = this.regex.test(reqCtx.pathname);
+            return isMethodMatch && isRegexMatch;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Parses query parameters from the URL.
+     * Defaults to a basic key-value mapping of the URL search params.
+     */
+    protected async parseQueryParams(reqCtx: RequestContext<TParams, TQueryParams>): Promise<TQueryParams | undefined> {
+        const lc = `${this.lc}[${this.parseQueryParams.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: b5d985a4a58b8f3edff9f5ab500e5c26)`); }
+
+            const queryParams: any = {};
+            reqCtx.url.searchParams.forEach((value, key) => {
+                queryParams[key] = value;
+            });
+
+            if (Object.keys(queryParams).length > 0) {
+                // query params exist, validate and return if valid, throw if not
+                const validationErrors = await this.validateQueryParams({ queryParams });
+                if (validationErrors.length === 0) {
+                    return queryParams as TQueryParams;
+                } else {
+                    throw new Error(`invalid query params. validationErrors: ${validationErrors.join(', ')} (E: 9355f8a9643803f52f2241f1c7f39826)`);
+                }
+            } else {
+                // no query params given
+                return undefined;
+            }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * base class implementation is a no-op. override this in descendant class
+     * who expect the possibility of query params
+     * @returns array of validation errors, empty if valid
+     */
+    protected async validateQueryParams({ queryParams }: { queryParams: any }): Promise<string[]> {
+        const lc = `${this.lc}[${this.validateQueryParams.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 33b448e223c8682bd8b8b055cab86f26)`); }
+
+            if (logalot) { console.log(`${lc} base class implementation is a no-op. returning empty array (i.e., valid) (I: 393e8db53d5a9e6ca8eb69ae25810826)`); }
+
+            return [];
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Standard JSON success response.
+     */
+    protected ok(body: any, status: number = 200): ResponseResult {
+        return { status, body, isJson: true };
+    }
+
+    /**
+     * Standard JSON error response.
+     */
+    protected error(status: number, message: string, details?: any): ResponseResult {
+        return { status, body: { error: message, details }, isJson: true };
+    }
+
+    /**
+     * 404 Not Found response.
+     */
+    protected notFound(message: string = 'Not found'): ResponseResult {
+        return this.error(404, message);
+    }
+}
+
+/**
+ * Base class for handlers that have to first initialize a metaspace in order to
+ * process the incoming request.
+ *
+ * ## notes
+ *
+ * Some handlers, like those who do error handling or serving static files, do
+ * not need to initialize a metaspace or do any get/put of any ibgibs. So those
+ * don't need to descend from this class.
+ *
+ * But if the handler is one that has to put/get an ibgib, then a metaspace will
+ * need to be init. Those handlers should descend from this class.
+ */
+export abstract class ServeGibHandlerWithMetaspaceBase<TParams extends ParamsWithDomain = ParamsWithDomain, TQueryParams = any>
+    extends ServeGibHandlerBase<TParams, TQueryParams> {
+    protected override lc: string = `[${ServeGibHandlerWithMetaspaceBase.name}]`;
+
+    protected override async initConcreteContext(reqCtx: RequestContext<TParams, TQueryParams>): Promise<void> {
+        const lc = `${this.lc}[${this.initConcreteContext.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            await this.initAndPopulateDomainContext(reqCtx);
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected override parseParamsImpl(reqCtx: RequestContext<TParams, TQueryParams>): Promise<TParams | undefined> {
+        const lc = `${this.lc}[${this.parseParamsImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: f3ae6e662fe8d28db8c230e80a700826)`); }
+
+            throw new Error(`(UNEXPECTED) not implemented. this function must be implemented in handlers that initialize metaspace. in that concrete handler class, you must parse out the raw path and build up the params object. That params object must at least include domain info, because that drives the multitenancy. (E: bd6a584b8f988f9ed81c77eedd36b826)`);
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    protected override validateQueryParams({ queryParams }: { queryParams: any; }): Promise<string[]> {
+        const lc = `${this.lc}[${this.validateQueryParams.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 14bb4659f9587d18786105c8e4966826)`); }
+
+            throw new Error(`(UNEXPECTED) not implemented. this function must be implemented in handlers that initialize metaspace. in that concrete handler class, you must provide a function that validates query params expectations, even if you expect no query params. (E: 804c98a724ddf59998199ec87a9ee126)`);
+
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * helper that should extract the "domain" (driven by the correctly scoped
+     * keystone) and set related props on the context.
+     */
+    protected async initAndPopulateDomainContext(reqCtx: RequestContext<TParams, TQueryParams>): Promise<void> {
+        const lc = `${this.lc}[${this.initAndPopulateDomainContext.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            if (!reqCtx.params) { throw new Error(`invalid RequestContext. params is falsy but we expected params.domainInfo at the minimum. (E: 433c15116e2e821768847d23f7853a26)`); }
+            if (!reqCtx.params.domainInfo) { throw new Error(`invalid RequestContext. reqCtx.params is truthy but params.domainInfo is falsy. at this point, we should have parsed domain info from reqCtx.params (E: ae40882910aa6f45a810e268fd126f26)`); }
+
+            const { domainInfo } = reqCtx.params as TParams
+            const { addr: domainAddr, } = domainInfo;
+            if (!domainAddr) {
+                throw new Error(`(UNEXPECTED) domainAddr falsy? reqCtx.params does not contain domainIb and domainGib for a handler extending ServeGibHandlerWithMetaspaceBase. If extending this metaspace base, we are expected to have a domain addr with ib and gib. (E: 06bae6908ba8f200e8c50b28ed8df626)`);
+            }
+
+            // since we have access to reqCtx.dataDir, not sure if we need rootPath in DomainInfo?
+            reqCtx.metaspace = await bootstrapDomainMetaspace(domainAddr, reqCtx.dataDir);
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+
+    /**
+     * Helper to build the domain info from a {@link domainAddr}.
+     *
+     * ## usage
+     *
+     * Use this helper function once your concrete handler has parsed the
+     * domainAddr from the request url.
+     *
+     * For example, say the incoming path is /api/ibgib/:domainAddr/:ibgibAddr (GET)
+     * Then the concrete handler for this path would pull out domainAddr, call
+     * this function to build the domain info, and then put that domain info on
+     * the `reqCtx`.
+     */
+    protected getDomainInfo({
+        domainAddr,
+        // dataDir,
+    }: {
+        /**
+         * addr extracted from incoming url by concrete handler
+         */
+        domainAddr: IbGibAddr,
+        // /**
+        //  * root dir of multitenancy on server. get from reqCtx.dataDir
+        //  */
+        // dataDir: string,
+    }): DomainInfo {
+        const lc = `${this.lc}[${this.getDomainInfo.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 2d8bc8f40fd8ae3c98b84f6aaf6e0f26)`); }
+
+            if (!domainAddr) { throw new Error(`(UNEXPECTED) domainAddr falsy? (E: 7009f98fead9712cb5d4c8985162c826)`); }
+
+            const domainGibInfo = getGibInfo({ ibGibAddr: domainAddr });
+            const { tjpGib, punctiliarHash } = domainGibInfo;
+            const { ib: domainIb, gib: domainGib } = getIbAndGib({ ibGibAddr: domainAddr });
+            const finalDomainGib = tjpGib || punctiliarHash;
+            if (!finalDomainGib) { throw new Error(`(UNEXPECTED) finalDomainGib falsy? we have a domainAddr (${domainAddr}) so we should have a domain gib. (E: de1e18078678f3b4887ebfae3c893626)`); }
+
+            const domainInfo: DomainInfo = {
+                addr: domainAddr,
+                gib: domainGib,
+                ib: domainIb,
+                gibInfo: domainGibInfo,
+                // rootPath: getDomainRootPath(finalDomainGib, dataDir),
+            }
+
+            return domainInfo;
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

package/src/server/serve-gib/handlers/static-handler.mts

@@ -0,0 +1,82 @@
+/**
+ * @module serve-gib/handlers/static-handler
+ *
+ * Handler for serving static client assets and SPA fallback.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { existsSync, statSync } from 'node:fs';
+import { join, extname } from 'node:path';
+
+import { ServeGibHandlerBase } from './handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../types.mjs';
+import { isValidStaticPath } from '../../path-helper.mjs';
+import { GLOBAL_LOG_A_LOT } from '../constants.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+export class StaticFileHandler extends ServeGibHandlerBase {
+    protected override lc: string = `[${StaticFileHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'GET';
+    protected override regex = /.*/;
+
+    private MIME_TYPES: Record<string, string> = {
+        '.html': 'text/html; charset=utf-8',
+        '.css': 'text/css; charset=utf-8',
+        '.js': 'text/javascript; charset=utf-8',
+        '.mjs': 'text/javascript; charset=utf-8',
+        '.json': 'application/json; charset=utf-8',
+        '.png': 'image/png',
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.svg': 'image/svg+xml',
+        '.ico': 'image/x-icon',
+        '.woff': 'font/woff',
+        '.woff2': 'font/woff2',
+        '.ttf': 'font/ttf',
+        '.webp': 'image/webp',
+    };
+
+    constructor(private clientDir: string) { super(); }
+
+    protected async handleRouteImpl(reqCtx: RequestContext): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            // Hardened path validation
+            const { pathname } = reqCtx;
+            if (!isValidStaticPath(pathname)) { return undefined; }
+
+            let filePath = join(this.clientDir, pathname);
+
+            // Directory → index.html
+            if (existsSync(filePath) && statSync(filePath).isDirectory()) {
+                filePath = join(filePath, 'index.html');
+            }
+
+            // File not found → SPA fallback
+            if (!existsSync(filePath)) {
+                filePath = join(this.clientDir, 'index.html');
+            }
+
+            // Final check just in case the fallback doesn't exist
+            if (!existsSync(filePath)) { return undefined; }
+
+            const content = await readFile(filePath);
+            const ext = extname(filePath).toLowerCase();
+            const contentType = this.MIME_TYPES[ext] ?? 'application/octet-stream';
+
+            return {
+                status: 200,
+                headers: { 'Content-Type': contentType },
+                body: content
+            };
+        } catch (error: any) {
+            console.error(`${lc} ${error.message}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}