@ibgib/node-gib 0.0.10 → 0.0.14

package/src/serve-gib/metaspace-nodeindexedspace/metaspace-nodeindexedspace.mts

@@ -0,0 +1,109 @@
+/**
+ * @module node-metaspace driven by a node+fs storage substrate
+ *
+ * a metaspace is a space of spaces. it adds/removes spaces and does
+ * inter-spatial composition related things. it's similar to what people think
+ * of in terms of a node in a p2p network.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { IbGibSpaceAny } from '@ibgib/core-gib/dist/witness/space/space-base-v1.mjs';
+import { IbGibCacheService } from '@ibgib/core-gib/dist/common/cache/cache-types.mjs';
+import { MetaspaceBase } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-base.mjs';
+import { MetaspaceFactory } from '@ibgib/core-gib/dist/witness/space/metaspace/metaspace-types.mjs';
+import { SpaceId } from '@ibgib/core-gib/dist/witness/space/space-types.mjs';
+
+import { GLOBAL_LOG_A_LOT, GLOBAL_TIMER_NAME } from '../server-constants.mjs';
+import { NodeFilesystemSpaceData_V1 } from '../../witness/space/node-filesystem-space/node-filesystem-space-types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ *
+ */
+export class Metaspace_Nodeindexedspace extends MetaspaceBase {
+
+  // we won't get an object back, only a DTO ibGib essentially
+  protected lc: string = `[${Metaspace_Nodeindexedspace.name}]`;
+
+  get zeroSpace(): IbGibSpaceAny {
+    const lc = `[${this.lc}][get zeroSpace]`;
+    if (this.metaspaceFactory.fnZeroSpaceFactory) {
+      return this.metaspaceFactory.fnZeroSpaceFactory();
+    } else {
+      throw new Error(`${lc} (UNEXPECTED) this.metaspaceFactory.fnZeroSpaceFactory falsy. not initialized? (E: 9e6c6954dacd868b18c9f34a71e63523)`);
+    }
+  }
+
+  constructor(
+    // public modalController: ModalController,
+    // public alertController: AlertController,
+    protected cacheSvc: IbGibCacheService | undefined,
+    // private latestCacheSvc: IonicStorageLatestIbgibCacheService,
+  ) {
+    super(cacheSvc);
+    const lc = `${this.lc}[ctor]`;
+    if (logalot) {
+      console.log(`${lc}${GLOBAL_TIMER_NAME}`);
+      console.timeLog(GLOBAL_TIMER_NAME);
+      console.log(`${lc} created. (I: 5690dc2ebf774df3a442bd463dee7455)`);
+    }
+
+  }
+
+  protected async initializeMetaspaceFactory({ metaspaceFactory }: {
+    metaspaceFactory: MetaspaceFactory,
+  }): Promise<void> {
+    const lc = `[${this.initializeMetaspaceFactory.name}]`;
+    try {
+      if (logalot) { console.log(`${lc} starting... (I: 5a29670439ac47634dcdfe25225c8223)`); }
+      if (!metaspaceFactory) { throw new Error(`(UNEXPECTED) metaspaceFactory falsy? space-gib server initialization should have guaranteed this to be truthy (E: f305356c2978cf0ee8062fd818940826)`); }
+      if (!metaspaceFactory.fnDefaultLocalSpaceFactory) { throw new Error(`(UNEXPECTED) !metaspaceFactory.fnDefaultLocalSpaceFactory? space-gib server initialization should have guaranteed this to be truthy (E: 884281e5251bd65528eb7b3f48737826)`); }
+      if (!metaspaceFactory.fnDtoToSpace) { throw new Error(`(UNEXPECTED) !metaspaceFactory.fnDtoToSpace? space-gib server initialization should have guaranteed this to be truthy (E: 885b7828606f36f9183bb9e687e25826)`); }
+      if (!metaspaceFactory.fnZeroSpaceFactory) { throw new Error(`(UNEXPECTED) !metaspaceFactory.fnZeroSpaceFactory? space-gib server initialization should have guaranteed this to be truthy (E: 336cf6655758bad4aaeea8ce08d8c826)`); }
+
+      await super.initializeMetaspaceFactory({ metaspaceFactory });
+    } catch (error) {
+      console.error(`${lc} ${extractErrorMsg(error)}`);
+      throw error;
+    } finally {
+      if (logalot) { console.log(`${lc} complete.`); }
+    }
+  }
+
+  /**
+   * Space deletion on server-side `Metaspace_Nodeindexedspace` is intentionally disabled.
+   *
+   * ## security rationale
+   * Server metaspaces are exposed to network traffic. Exposing automated space deletion
+   * on the server without extensive security/authorization controls introduces a major
+   * attack vector. Server spaces must not be deleted via metaspace API until explicit
+   * server authorization controls are designed and implemented.
+   */
+  override async deleteLocalUserSpace({
+    spaceId,
+    deletePhysicalStorage = true,
+  }: {
+    spaceId: SpaceId;
+    deletePhysicalStorage?: boolean;
+  }): Promise<void> {
+    const lc = `${this.lc}[${this.deleteLocalUserSpace.name}]`;
+    throw new Error(`${lc} Space deletion on server-side Metaspace_Nodeindexedspace is intentionally disabled to prevent internet-exposed attack vectors. (E: c9410a5170d14b4fb2478d102e3b2e23)`);
+  }
+
+  // async initializeZeroSpace(): Promise<void> {
+  //   const lc = `[${this.initializeZeroSpace.name}]`;
+  //   try {
+  //     if (logalot) { console.log(`${lc} starting... (I: a3364e9601c70c8163e67868e5d67723)`); }
+
+  //   } catch (error) {
+  //     console.error(`${lc} ${extractErrorMsg(error)}`);
+  //     throw error;
+  //   } finally {
+  //     if (logalot) { console.log(`${lc} complete.`); }
+  //   }
+  // }
+
+}

package/src/serve-gib/path-constants.mts

@@ -0,0 +1,119 @@
+/** Maximum allowed path length to prevent DoS. */
+export const MAX_PATH_LENGTH = 2048;
+
+/**
+ * Blacklisted patterns for any incoming path.
+ * We iterate through these for a quick security check.
+ */
+export const FORBIDDEN_PATTERNS = [
+    /\.\./,      // No directory traversal
+    /\/\//,      // No redundant slashes
+    /\0/,        // No null bytes
+    /(^|\/)\./,  // No hidden/dot-files (e.g. .env, .git)
+];
+
+/**
+ * Regex for valid API paths.
+ *
+ * IMPORTANT: See IMPLEMENTATION.md for overall path schema documentation.
+ *
+ * Paths are URL encoded. The `ib` and `gib` portions of addresses are captured explicitly
+ * by splitting on `%5E` or `^`.
+ */
+export const API_PATH_REGEXES = {
+    /**
+     * /api/health
+     */
+    HEALTH: /^\/api\/health\/?$/,
+
+    /**
+     * /api/ibgib/graph/:domainAddr/:ibgibAddr
+     */
+    IBGIB_GRAPH: /^\/api\/ibgib\/graph\/([^\/]+?)(?:%5E|\^)([^\/]+)\/([^\/]+?)(?:%5E|\^)([^\/]+)\/?$/,
+
+    /**
+     * /api/ibgib/:domainAddr/:ibgibAddr
+     */
+    IBGIB_ADDR: /^\/api\/ibgib\/([^\/]+?)(?:%5E|\^)([^\/]+)\/([^\/]+?)(?:%5E|\^)([^\/]+)\/?$/,
+
+    /**
+     * /api/keystone
+     */
+    KEYSTONE: /^\/api\/keystone\/?$/,
+
+    /**
+     * /api/keystone/:domainAddr
+     */
+    KEYSTONE_ADDR: /^\/api\/keystone\/([^\/]+?)(?:%5E|\^)([^\/]+)\/?$/,
+
+    /**
+     * /api/ibgib
+     */
+    IBGIB_BASE: /^\/api\/ibgib\/?$/,
+
+    /**
+     * /api/keystone/evolve/:domainAddr
+     */
+    KEYSTONE_EVOLVE: /^\/api\/keystone\/evolve\/([^\/]+?)(?:%5E|\^)([^\/]+)\/?$/,
+
+    /**
+     * /api/keystone/genesis
+     *
+     * Accepts a single genesis-frame keystone ibgib and creates a new
+     * domain-isolated metaspace for it. No `:domainAddr` in the URL because
+     * the server derives the domain from the incoming keystone ibgib itself.
+     *
+     * Parallel to /api/keystone/evolve.
+     */
+    KEYSTONE_GENESIS: /^\/api\/keystone\/genesis\/?$/,
+
+    /**
+     * /api/keystone/lookup
+     */
+    KEYSTONE_LOOKUP: /^\/api\/keystone\/lookup\/?$/,
+
+    /**
+     * /api/keystone/check-email
+     */
+    KEYSTONE_CHECK_EMAIL: /^\/api\/keystone\/check-email\/?$/,
+
+    /**
+     * /api/debug/ws-echo
+     *
+     * Minimal WebSocket echo endpoint for validating WS plumbing (Traefik
+     * passthrough, server upgrade handling, client connectivity) before
+     * integrating real sync logic.
+     *
+     * ## intent
+     *
+     * NOT for production use. Remove or gate behind a flag once WS sync is
+     * confirmed working end-to-end.
+     */
+    DEBUG_WS_ECHO: /^\/api\/debug\/ws-echo\/?$/,
+    /**
+     * /api/sync/ws/:domainAddr
+     */
+    SYNC_WS: /^\/api\/sync\/ws\/([^\/]+?)(?:%5E|\^)([^\/]+)\/?$/,
+    /**
+     * /api/identity/sso/link
+     */
+    IDENTITY_SSO_LINK: /^\/api\/identity\/sso\/link\/?$/,
+    /**
+     * /api/identity/sso/login
+     */
+    IDENTITY_SSO_LOGIN: /^\/api\/identity\/sso\/login\/?$/,
+    /**
+     * /api/identity/sso/config
+     */
+    IDENTITY_SSO_CONFIG: /^\/api\/identity\/sso\/config\/?$/,
+    /**
+     * /api/email/inbound
+     */
+    EMAIL_INBOUND: /^\/api\/email\/inbound\/?$/,
+    /**
+     * /api/email/send
+     */
+    EMAIL_SEND: /^\/api\/email\/send\/?$/,
+};
+
+export const VALID_STATIC_PATH_REGEX = /^\/[a-zA-Z0-9\-_\.\/]*$/;

package/src/serve-gib/path-helper.mts

@@ -0,0 +1,101 @@
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { validateIbGibAddr } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from './server-constants.mjs';
+import { FORBIDDEN_PATTERNS, MAX_PATH_LENGTH, VALID_STATIC_PATH_REGEX } from './path-constants.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * little helper function just to DRY out code.
+ */
+export function runtimeErrorValidationStrings(lc: string, error: any): string[] {
+    const emsg = `${lc} ${extractErrorMsg(error)}`;
+    console.error(emsg);
+    return [`runtime error: ${emsg}`];
+}
+
+/**
+ * Validates that a path is safe from common attacks and under max length.
+ */
+export function validateRawPath(rawPath: string): string[] {
+    const lc = `[${validateRawPath.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 80bd6f63e6c83b8e943b90383e044826)`); }
+
+        const errors: string[] = [];
+
+        if (!rawPath || rawPath.length > MAX_PATH_LENGTH) {
+            errors.push(`path too long. MAX_PATH_LENGTH: ${MAX_PATH_LENGTH}, incoming path length: ${rawPath.length}`);
+        }
+
+        for (const pattern of FORBIDDEN_PATTERNS) {
+            if (pattern.test(rawPath)) {
+                errors.push(`invalid path. contains forbidden pattern.source: ${pattern.source} (E: 56a228fb9473a086b83d0088b5af1826)`);
+            }
+        }
+
+        return errors;
+    } catch (error) {
+        return runtimeErrorValidationStrings(lc, error);
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * simple boolean wrapper for {@link validateRawPath}
+ */
+export function isSafePath(path: string): boolean {
+    const errors = validateRawPath(path);
+    return errors.length === 0;
+}
+
+export function validateStaticPath(path: string): string[] {
+    const lc = `[${validateStaticPath.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 4f9cf8ffd528c7dd88324529528eeb26)`); }
+
+        const errors: string[] = [];
+
+        if (!VALID_STATIC_PATH_REGEX.test(path)) {
+            errors.push(`static path fails to match VALID_STATIC_PATH_REGEX of ${VALID_STATIC_PATH_REGEX} (E: dfdf38a0439d4d09186e6fa81ab66826) `);
+        }
+
+        return errors;
+    } catch (error) {
+        return runtimeErrorValidationStrings(lc, error);
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+/**
+ * Validates a static file path.
+ */
+export function isValidStaticPath(path: string): boolean {
+    if (!isSafePath(path)) { return false; }
+    const errors = validateStaticPath(path);
+    return errors.length === 0;
+}
+
+/**
+ * Decodes and validates a single ibGib address segment from a URL path.
+ * Uses the library's internal validateIbGibAddr for deep checking.
+ */
+export function validateAddressSegment(encodedAddr: string): string[] {
+    const lc = `[${validateAddressSegment.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: 1bb9ff7e1aefb77b670b2519658cc126)`); }
+        if (!encodedAddr) {
+            throw new Error(`(UNEXPECTED) falsy encodedAddr? We're expecting to have already guaranteed there are no double-slashes (i.e. no empty segments) (E: 7be7668e7b8c9fbbdf56f0fe19f92e26)`);
+        }
+        const addr = decodeURIComponent(encodedAddr);
+        const errors = validateIbGibAddr({ addr });
+        return errors ?? [];
+    } catch (error) {
+        return runtimeErrorValidationStrings(lc, error);
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}

package/src/serve-gib/path-helper.respec.mts

@@ -0,0 +1,99 @@
+// import { respecfully, iReckon, ifWe } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+// import {
+//     isSafePath, isValidStaticPath,
+//     // API_PATHS, getPathParams, MAX_PATH_LENGTH,
+//     validateAddressSegment
+// } from './path-helper.mjs';
+// import { MAX_PATH_LENGTH } from './path-constants.mts';
+
+// const sir = `[${import.meta.url}]`;
+
+// await respecfully(sir, 'Path Helper Validation', async () => {
+
+//     await respecfully(sir, 'isSafePath', async () => {
+//         await ifWe(sir, 'valid simple paths', async () => {
+//             iReckon(sir, isSafePath('/api/health')).isGonnaBeTrue();
+//             iReckon(sir, isSafePath('/index.html')).isGonnaBeTrue();
+//         });
+
+//         await ifWe(sir, 'too long paths', async () => {
+//             const longPath = '/'.repeat(MAX_PATH_LENGTH + 1);
+//             iReckon(sir, isSafePath(longPath)).isGonnaBeFalse();
+//         });
+
+//         await ifWe(sir, 'directory traversal attempts', async () => {
+//             iReckon(sir, isSafePath('/../etc/passwd')).isGonnaBeFalse();
+//             iReckon(sir, isSafePath('/api/../../etc/passwd')).isGonnaBeFalse();
+//         });
+
+//         await ifWe(sir, 'null bytes', async () => {
+//             iReckon(sir, isSafePath('/api/health\0')).isGonnaBeFalse();
+//         });
+
+//         await ifWe(sir, 'redundant slashes', async () => {
+//             iReckon(sir, isSafePath('/api//health')).isGonnaBeFalse();
+//         });
+
+//         await ifWe(sir, 'dot-file access', async () => {
+//             iReckon(sir, isSafePath('/.env')).isGonnaBeFalse();
+//             iReckon(sir, isSafePath('/scripts/.hidden')).isGonnaBeFalse();
+//             iReckon(sir, isSafePath('/.git/config')).isGonnaBeFalse();
+//         });
+//     });
+
+//     await respecfully(sir, 'validateAddressSegment', async () => {
+//         await ifWe(sir, 'valid encoded addresses', async () => {
+//             const validGib = 'a'.repeat(64);
+//             iReckon(sir, validateAddressSegment(`someib%5E${validGib}`)).isGonnaBeTrue();
+//             // gib with dots (common in sha256.sha256)
+//             const dotGib = `${validGib}.${validGib}`;
+//             iReckon(sir, validateAddressSegment(`someib%5E${dotGib}`)).isGonnaBeTrue();
+//         });
+
+//         await ifWe(sir, 'invalid encoded addresses', async () => {
+//             iReckon(sir, validateAddressSegment('no_delim')).isGonnaBeFalse();
+//             iReckon(sir, validateAddressSegment('%5Estarts_with_delim')).isGonnaBeFalse();
+//             iReckon(sir, validateAddressSegment('too%5Emany%5Edelims')).isGonnaBeFalse();
+//             iReckon(sir, validateAddressSegment('too%5Emany..dots')).isGonnaBeFalse();
+//             iReckon(sir, validateAddressSegment('invalid_chars_!%5Eabc')).isGonnaBeFalse();
+//         });
+//     });
+
+//     await respecfully(sir, 'API_PATHS Regexes', async () => {
+//         await ifWe(sir, 'HEALTH regex', async () => {
+//             iReckon(sir, API_PATHS.HEALTH.test('/api/health')).isGonnaBeTrue();
+//             iReckon(sir, API_PATHS.HEALTH.test('/api/health/')).isGonnaBeTrue();
+//             iReckon(sir, API_PATHS.HEALTH.test('/api/health/more')).isGonnaBeFalse();
+//         });
+
+//         await ifWe(sir, 'IBGIB_ADDR regex', async () => {
+//             // valid encoded addr: someib%5Esomegib
+//             const addr = '/api/ibgib/someib%5Esomegib';
+//             iReckon(sir, API_PATHS.IBGIB_ADDR.test(addr)).isGonnaBeTrue();
+
+//             const params = getPathParams(addr, API_PATHS.IBGIB_ADDR);
+//             iReckon(sir, params?.[0]).isGonnaBe('someib%5Esomegib');
+//         });
+
+//         await ifWe(sir, 'IBGIB_GRAPH regex', async () => {
+//             const path = '/api/ibgib/graph/someib%5Esomegib';
+//             iReckon(sir, API_PATHS.IBGIB_GRAPH.test(path)).isGonnaBeTrue();
+
+//             const params = getPathParams(path, API_PATHS.IBGIB_GRAPH);
+//             iReckon(sir, params?.[0]).isGonnaBe('someib%5Esomegib');
+//         });
+
+//         await ifWe(sir, 'KEYSTONE regex', async () => {
+//             iReckon(sir, API_PATHS.KEYSTONE.test('/api/keystone')).isGonnaBeTrue();
+//             iReckon(sir, API_PATHS.KEYSTONE.test('/api/keystone/')).isGonnaBeTrue();
+//         });
+
+//         await ifWe(sir, 'KEYSTONE_EVOLVE regex', async () => {
+//             const path = '/api/keystone/evolve/someib%5Esomegib';
+//             iReckon(sir, API_PATHS.KEYSTONE_EVOLVE.test(path)).isGonnaBeTrue();
+
+//             const params = getPathParams(path, API_PATHS.KEYSTONE_EVOLVE);
+//             iReckon(sir, params?.[0]).isGonnaBe('someib%5Esomegib');
+//         });
+//     });
+// });

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

@@ -0,0 +1,32 @@
+/**
+ * @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.
+    }
+}

package/src/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.`); }
+        }
+    }
+}