@ibgib/space-gib 0.0.9 → 0.0.13

package/src/server/bootstrap-helper.respec.mts

@@ -1,100 +0,0 @@
-import { join } from 'node:path';
-import { existsSync, mkdirSync, rmSync } from 'node:fs';
-
-import { respecfully, iReckon, ifWe } from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
-const sir = `[${import.meta.url}]`;
-import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
-import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
-import { createStandardPoolConfig } from '@ibgib/core-gib/dist/keystone/keystone-config-builder.mjs';
-import { POOL_ID_DEFAULT } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
-
-import { GLOBAL_LOG_A_LOT } from './server-constants.mjs';
-import { getDomainRootPath, bootstrapDomainMetaspace } from './bootstrap-helper.mjs';
-
-const logalot = GLOBAL_LOG_A_LOT;
-
-
-/**
- * Minimal mock to satisfy KeystoneService requirements during genesis.
- */
-class MockMetaspace {
-    async getLocalUserSpace() { return new MockSpace(); }
-    async put() { }
-    async registerNewIbGib() { }
-}
-class MockSpace {
-    async witness() { return { data: { success: true } }; }
-}
-
-await respecfully(sir, 'bootstrap-helper', async () => {
-    const lc = `[bootstrap-helper.respec.mts][bootstrap-helper]`;
-    const testDataDir = './test-data';
-    console.log(`${lc} testDataDir: ${testDataDir} (I: c9f39853a57a5af97ab8ff7882c49826)`);
-
-    // Clean and recreate test-data directory
-    if (existsSync(testDataDir)) {
-        rmSync(testDataDir, { recursive: true, force: true });
-    }
-    mkdirSync(testDataDir, { recursive: true });
-
-    await ifWe(sir, 'calculate balanced domain root paths', async () => {
-        const tjpGib = 'abcde1234567890';
-        const root = getDomainRootPath(tjpGib, testDataDir);
-
-        // Should be: testDataDir/domains/ab/cd/abcde1234567890
-        iReckon(sir, root).includes(join('domains', 'ab', 'cd', tjpGib));
-    });
-
-    await ifWe(sir, 'bootstrap a domain metaspace and create the directory', async () => {
-        const keystoneAddr = 'keystone_alice^abcde1234567890';
-        const metaspace = await bootstrapDomainMetaspace(keystoneAddr, testDataDir);
-
-        iReckon(sir, metaspace).isGonnaBe(metaspace);
-        iReckon(sir, metaspace.initialized).isGonnaBe(true);
-
-        const expectedPath = getDomainRootPath('abcde1234567890', testDataDir);
-        iReckon(sir, existsSync(expectedPath)).isGonnaBe(true);
-
-        // The ibgib framework uses a specific subdirectory structure for the bootstrap
-        const bootstrapFile = join(expectedPath, 'ibgib', '000_zerospace', 'gib', 'bootstrap.json');
-        iReckon(sir, existsSync(bootstrapFile)).isGonnaBe(true);
-
-        // Also check that the default space was created
-        const defaultSpaceDir = join(expectedPath, 'ibgib', 'default');
-        iReckon(sir, existsSync(defaultSpaceDir)).isGonnaBe(true);
-    });
-
-    await ifWe(sir, 'integrate with KeystoneService and bootstrap 5 unique domains', async () => {
-        const keystoneService = new KeystoneService_V1();
-        const mockMetaspace = new MockMetaspace() as any;
-        const mockSpace = new MockSpace() as any;
-        const config = createStandardPoolConfig({ id: POOL_ID_DEFAULT, salt: POOL_ID_DEFAULT });
-
-        const identities = ['Alice', 'Bob', 'Charlie', 'Dave', 'Eve'];
-
-        for (const name of identities) {
-            // 1. Generate an actual genesis keystone for this identity
-            const keystone = await keystoneService.genesis({
-                masterSecret: `SecretFor_${name}`,
-                configs: [config],
-                metaspace: mockMetaspace,
-                space: mockSpace,
-            });
-            const addr = getIbGibAddr({ ibGib: keystone });
-            const tjpGib = keystone.gib!;
-
-            if (logalot) { console.log(`[test] Bootstrapping domain for ${name}: ${addr} (I: 7ba45828f2719ca578a1f078ff16e126)`); }
-
-            // 2. Drive the bootstrap logic
-            const metaspace = await bootstrapDomainMetaspace(addr, testDataDir);
-            iReckon(sir, metaspace.initialized).isGonnaBe(true);
-
-            // 3. Verify the unique path
-            const expectedPath = getDomainRootPath(tjpGib, testDataDir);
-            iReckon(sir, existsSync(expectedPath)).isGonnaBe(true);
-
-            const bootstrapFile = join(expectedPath, 'ibgib', '000_zerospace', 'gib', 'bootstrap.json');
-            iReckon(sir, existsSync(bootstrapFile)).isGonnaBe(true);
-        }
-    });
-});

package/src/server/metaspace-nodeindexedspace/metaspace-nodeindexedspace.mts

@@ -1,85 +0,0 @@
-/**
- * @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 { 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 { GLOBAL_LOG_A_LOT, GLOBAL_TIMER_NAME } from '../server-constants.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.`); }
-    }
-  }
-
-  // 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/server/path-constants.mts

@@ -1,101 +0,0 @@
-/** 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/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\/?$/,
-};
-
-export const VALID_STATIC_PATH_REGEX = /^\/[a-zA-Z0-9\-_\.\/]*$/;

package/src/server/path-helper.mts

@@ -1,101 +0,0 @@
-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/server/path-helper.respec.mts

@@ -1,99 +0,0 @@
-// 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/server/serve-gib/CHANGELOG.md

@@ -1,29 +0,0 @@
-# serve-gib changelog
-
-_note: as you implement features/fixes/etc., please document them here under the "Working Version" section._
-
-## Working Version
-
-* impl: initial core infrastructure
-  * defined `RouteInfo`, `ResponseResult`, and `ServeGibHandler` foundational types.
-  * implemented `ServeGib_V1` with pipeline-based request processing.
-  * added robust `try..catch..finally` pattern with built-in access logging and timing.
-* impl: handler "pit of success" plumbing
-  * implemented `ServeGibHandlerBase` abstract class to reduce boilerplate.
-  * automated route matching via `canHandleRoute` and `regex` properties.
-  * implemented `handleRouteImpl` pattern to separate plumbing from business logic.
-  * added generic `TQueryParams` support with automated parsing via `parseQueryParams`.
-* feat: hierarchical handler organization
-  * established folder-based grouping mirroring URL paths (e.g., `handlers/api/ibgib/`).
-  * enforced "one handler per hard route" and "one handler per file" architectural guidelines.
-* feat: concrete core handlers
-  * `HealthHandler`: Simple liveness probe.
-  * `IbGibHandler`: Single ibGib address resolution.
-  * `IbGibGraphHandler`: Complex graph/BFS retrieval.
-  * `KeystoneHandler`: Genesis and evolution turn persistence.
-  * `StaticFileHandler`: High-performance asset serving with SPA history fallback.
-  * `ErrorHandler`: Standardized 404 and fatal error reporting.
-* docs: architectural guidance
-  * created `README.md` with detailed guidance on handler philosophy and plumbing usage.
-* test: validation suite
-  * implemented `serve-gib.respec.mts` verifying orchestrator pipeline and `RouteInfo` construction.

package/src/server/serve-gib/README.md

@@ -1,43 +0,0 @@
-# serve-gib Microframework
-
-A minimalist, high-observability HTTP microframework for ibgib servers.
-
-## Architecture & Guidance
-
-### 1. Handler Philosophy
-*   **One handler per "hard" route**: A handler should correspond to a unique URL path pattern, disregarding query parameters.
-*   **One regex per handler**: Concrete handlers should ideally define a single `regex` property for routing.
-*   **One handler per file**: Each route handler should live in its own file within the `handlers/` directory (e.g., `handlers/api/health.handler.mts`).
-  * The subfolders should match the hard route of the handler, e.g., `api/ibgib` route should be in the `handlers/api/ibgib` subfolder.
-
-### 2. The "Pit of Success" Plumbing
-The `ServeGibHandlerBase` class provides built-in plumbing to reduce boilerplate:
-*   **`handleRoute` (Plumbing)**: Automatically checks `canHandleRoute`, parses query parameters, and provides a top-level `try..catch` block for logging and error reporting.
-*   **`handleRouteImpl` (Implementation)**: This is where the core logic of the handler resides.
-*   **`canHandleRoute`**: Defaults to a regex match on `info.pathname`. Override this for more complex routing logic.
-
-### 3. Query Parameters
-Query parameters are handled via the `parseQueryParams` method in the base class.
-*   By default, it parses URL search params into a key-value object.
-*   Handlers can override this method to perform custom parsing or validation (e.g., parsing JSON strings from query params).
-*   The base class is generic: `ServeGibHandlerBase<TQueryParams = any>`.
-
-### 4. RouteInfo
-The `RouteInfo` object provides an enriched view of the incoming request:
-*   `decodedPathSegments`: Pre-split and decoded path parts.
-*   `protocol`, `method`, `body`: Basic HTTP info.
-*   `queryParams`: The result of the handler's `parseQueryParams` call.
-
-## Pipeline Order
-The `ServeGib_V1` executes handlers in the order they are provided in the `handlers` array. The first handler to return a non-undefined `ResponseResult` wins.
-*   **Tip**: Order specific routes (like `/api/ibgib/graph`) before more general ones (like `/api/ibgib`).
-*   **Fallback**: The `ErrorHandler` is used as a final catch-all for 404s and fatal errors.
-
-## Docker / Server Resilience Note
-When deploying or running this service (or any downstream applications) within a Docker Compose environment, ensure that the `docker-compose.yml` configuration specifies a restart policy such as:
-```yaml
-services:
-  space-gib:
-    restart: unless-stopped
-```
-This ensures that the container auto-recovers and restarts if the node process crashes due to unhandled events (such as raw TCP socket `ECONNRESET` exceptions from client refreshes).

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

@@ -1 +0,0 @@
-export const GLOBAL_LOG_A_LOT = false;

package/src/server/serve-gib/handlers/api/debug/ws-echo.handler.mts

@@ -1,105 +0,0 @@
-/**
- * @module handlers/api/debug/ws-echo.handler
- *
- * Minimal WebSocket echo handler for validating end-to-end WebSocket
- * plumbing: Traefik passthrough → Node.js upgrade event → browser client.
- *
- * ## intent
- *
- * This is a diagnostic-only endpoint. The goal is to confirm that:
- *   1. Traefik correctly forwards WS upgrade requests to the container
- *   2. The Node.js `upgrade` event fires and we can accept the connect handshake
- *   3. The browser client can open a wss:// connection and exchange frames
- *
- * Once WS sync is confirmed end-to-end, this handler can be removed or
- * gated behind an env flag.
- *
- * ## endpoint
- *
- * `GET /api/debug/ws-echo` (with Upgrade: websocket header)
- *
- * On connect: server sends `{"status":"connected","msg":"ws-echo ready"}`
- * On message: server echoes `{"echo":<original message>}`
- * On close: server logs and cleans up
- */
-
-import { IncomingMessage } from 'node:http';
-import { Socket } from 'node:net';
-
-import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
-
-import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
-import {
-    encodeTextFrame, decodeTextFrame, encodeCloseFrame, performConnect,
-    WebSocketFrameDecoder
-} from '../../ws/ws-helper.mjs';
-import { API_PATH_REGEXES } from '../../../../path-constants.mjs';
-
-const logalot = GLOBAL_LOG_A_LOT;
-
-const lc = `[WsEchoHandler]`;
-
-
-// ---------------------------------------------------------------------------
-// Public handler
-// ---------------------------------------------------------------------------
-
-/**
- * Returns true if this request is a WebSocket upgrade to the debug echo path.
- * Call this from the server's `upgrade` event listener.
- */
-export function canHandleWsUpgrade(req: IncomingMessage): boolean {
-    const pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
-    return API_PATH_REGEXES.DEBUG_WS_ECHO.test(pathname);
-}
-
-/**
- * Accepts the WebSocket upgrade and sets up the echo loop.
- *
- * Client will receive a JSON `{status:"connected"}` on open, and
- * `{echo:<msg>}` for every message it sends.
- */
-export function handleWsEchoUpgrade(req: IncomingMessage, socket: Socket, head: Buffer): void {
-    const lc_fn = `${lc}[handleWsEchoUpgrade]`;
-    try {
-        if (logalot) { console.log(`${lc_fn} starting...`); }
-
-        const ok = performConnect(req, socket);
-        if (!ok) { return; }
-
-        // Send the "connected" greeting
-        socket.write(encodeTextFrame(JSON.stringify({ status: 'connected', msg: 'ws-echo ready' })));
-
-        // Echo loop
-        const decoder = new WebSocketFrameDecoder();
-        socket.on('data', (data: Buffer) => {
-            try {
-                decoder.addChunk(data);
-                let frameText = decoder.nextFrame();
-                while (frameText !== null) {
-                    if (logalot) { console.log(`${lc_fn} echo: ${frameText}`); }
-                    socket.write(encodeTextFrame(JSON.stringify({ echo: frameText })));
-                    frameText = decoder.nextFrame();
-                }
-            } catch (error) {
-                console.error(`${lc_fn} error in data handler: ${extractErrorMsg(error)}`);
-                socket.write(encodeCloseFrame(1000));
-                socket.end();
-            }
-        });
-
-        socket.on('error', (error) => {
-            console.error(`${lc_fn} socket error: ${extractErrorMsg(error)}`);
-        });
-
-        socket.on('close', () => {
-            if (logalot) { console.log(`${lc_fn} socket closed.`); }
-        });
-
-    } catch (error) {
-        console.error(`${lc_fn} ${extractErrorMsg(error)}`);
-        socket.destroy();
-    } finally {
-        if (logalot) { console.log(`${lc_fn} complete.`); }
-    }
-}