@ibgib/space-gib 0.0.1

package/src/server/serve-gib/handlers/api/keystone/keystone-get.respec.mts

@@ -0,0 +1,107 @@
+import { join } from 'node:path';
+import { existsSync, rmSync, mkdirSync } from 'node:fs';
+
+import {
+    respecfully, iReckon, ifWe, ifWeMight
+} 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 '../../../constants.mjs';
+import { ServeGib_V1 } from '../../../serve-gib-v1.mjs';
+import { KeystonePostHandler } from './keystone-post.handler.mjs';
+import { KeystoneGetHandler } from './keystone-get.handler.mjs';
+import { ErrorHandler } from '../../error-handler.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+class MockMetaspace {
+    async getLocalUserSpace() { return new MockSpace(); }
+    async put() { }
+    async registerNewIbGib() { }
+}
+class MockSpace {
+    async witness() { return { data: { success: true } }; }
+}
+
+await respecfully(sir, 'Keystone GET Integration', async () => {
+    const testDataDir = './test-data-get';
+    const port = 3003;
+
+    // Clean test data
+    if (existsSync(testDataDir)) {
+        rmSync(testDataDir, { recursive: true, force: true });
+    }
+    mkdirSync(testDataDir, { recursive: true });
+
+    await ifWeMight(sir, 'retrieve a keystone chain via GET /api/keystone/:addr', async () => {
+        const keystoneService = new KeystoneService_V1();
+        const config = createStandardPoolConfig({ id: POOL_ID_DEFAULT, salt: POOL_ID_DEFAULT });
+
+        // 1. Setup ServeGib_V1 with both POST and GET handlers
+        const serveGib = new ServeGib_V1({
+            port,
+            dataDir: testDataDir,
+            handlers: [
+                new KeystonePostHandler(),
+                new KeystoneGetHandler(),
+            ],
+            errorHandler: new ErrorHandler()
+        });
+
+        // 2. Generate and POST genesis
+        const genesis = await keystoneService.genesis({
+            masterSecret: 'AliceSecret',
+            configs: [config],
+            metaspace: new MockMetaspace() as any,
+            space: new MockSpace() as any,
+        });
+        const addr = getIbGibAddr({ ibGib: genesis });
+
+        const postReq: any = {
+            url: '/api/keystone',
+            method: 'POST',
+            headers: { 'ibgib-domain': addr, 'content-type': 'application/json' },
+            on: (event: string, cb: any) => {
+                if (event === 'data') cb(Buffer.from(JSON.stringify({ ibGibs: [genesis] })));
+                if (event === 'end') cb();
+            }
+        };
+        const postRes: any = {
+            writeHead: () => { },
+            end: () => { },
+        };
+        await serveGib.handleRequest(postReq, postRes);
+
+        // 3. Mock GET Request
+        const getReq: any = {
+            url: `/api/keystone/${encodeURIComponent(addr)}`,
+            method: 'GET',
+            headers: { 'ibgib-domain': addr },
+            on: (event: string, cb: any) => {
+                if (event === 'end') cb();
+            }
+        };
+
+        let capturedStatus: number = 0;
+        let capturedBody: any = null;
+        const getRes: any = {
+            writeHead: (status: number) => { capturedStatus = status; },
+            end: (body: string) => { capturedBody = JSON.parse(body); },
+        };
+
+        // 4. Handle GET
+        await serveGib.handleRequest(getReq, getRes);
+
+        // 5. Verify
+        iReckon(sir, capturedStatus).asTo('captured status code').isGonnaBe(200);
+        iReckon(sir, capturedBody.chain).asTo('captured body chain').isGonnaBeTruthy();
+        iReckon(sir, Array.isArray(capturedBody.chain)).asTo('chain is array').isGonnaBe(true);
+        iReckon(sir, capturedBody.chain.length).asTo('chain length').isGonnaBe(1);
+        iReckon(sir, capturedBody.chain[0].gib).asTo('genesis gib matches').isGonnaBe(genesis.gib);
+    });
+});

package/src/server/serve-gib/handlers/api/keystone/keystone-handler-types.mts

@@ -0,0 +1,29 @@
+import { DomainInfo } from "../../../types.mjs";
+
+export interface KeystoneParams {
+    domainInfo: DomainInfo;
+}
+
+// #region KeystoneGetQueryParams
+export const DEFAULT_QUERY_PARAMS_GET_KEYSTONE = {
+    /**
+     * If true, will get the latest keystone frame.
+     */
+    getLatest: true,
+    /**
+     * If true, will get the keystone's entire dependency graph
+     */
+    getGraph: true,
+};
+/**
+ * @see {@link DEFAULT_QUERY_PARAMS_GET_KEYSTONE} key/values for jsdocs
+ */
+export type KeystoneGetQueryParams = Partial<typeof DEFAULT_QUERY_PARAMS_GET_KEYSTONE>;
+export type KNOWN_QUERY_PARAMS_KEYSTONE_GET = keyof KeystoneGetQueryParams;
+export const KNOWN_QUERY_PARAMS_KEYSTONE_GET = Object.keys(DEFAULT_QUERY_PARAMS_GET_KEYSTONE) as KNOWN_QUERY_PARAMS_KEYSTONE_GET[];
+export function isKnownQueryParamsKey_KeystoneGet(key: any): key is KNOWN_QUERY_PARAMS_KEYSTONE_GET {
+    return !!key && typeof key === 'string' ?
+        KNOWN_QUERY_PARAMS_KEYSTONE_GET.includes(key as any) :
+        false;
+}
+// #endregion KeystoneGetQueryParams

package/src/server/serve-gib/handlers/api/keystone/keystone-post.handler.mts

@@ -0,0 +1,70 @@
+/**
+ * @module serve-gib/handlers/api/keystone
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { validateIbGibIntrinsically } from '@ibgib/ts-gib/dist/V1/validate-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../../../constants.mjs';
+import { ServeGibHandlerBase } from '../../handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../../../types.mjs';
+import { API_PATH_REGEXES } from '../../../../path-constants.mjs';
+import { KeystoneParams } from './keystone-handler-types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * POST /api/keystone
+ */
+export class KeystonePostHandler extends ServeGibHandlerBase<KeystoneParams, any> { // todo: keystone post query params if needed?
+    protected override lc: string = `[${KeystonePostHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'POST';
+    protected override regex = API_PATH_REGEXES.KEYSTONE;
+
+    protected async handleRouteImpl(reqCtx: RequestContext<KeystoneParams, any>): Promise<ResponseResult | undefined> {
+        const lc = `[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting... (I: 63bab8214834cb6e383e0fc364ee8826)`); }
+
+            const { metaspace } = reqCtx;
+            if (!metaspace) { throw new Error(`(UNEXPECTED) reqCtx.metaspace falsy? (E: 3d03027ea7f6f237980e511801255826)`); }
+
+            const { ibGibs } = JSON.parse(reqCtx.body) as { ibGibs: any[] };
+            if (!Array.isArray(ibGibs)) return this.error(400, 'ibGibs array required');
+
+            // 1. Intrinsic Validation
+            for (const ibGib of ibGibs) {
+                const errors = await validateIbGibIntrinsically({ ibGib });
+                if (errors) {
+                    return this.error(422, 'Intrinsic validation failed', { failedAddr: getIbGibAddr({ ibGib }), errors });
+                }
+            }
+
+            // 2. Keystone-specific checks
+            for (const ibGib of ibGibs) {
+                if (ibGib.ib?.startsWith('keystone')) {
+                    if (!reqCtx.metaspace) { return this.error(500, 'Metaspace not initialized'); }
+                    // Registration handles genesis vs evolution internally via metastones
+                    await reqCtx.metaspace.registerNewIbGib({
+                        ibGib,
+                    });
+                }
+            }
+
+            // 3. Persistence
+            console.log(`[KeystoneHandler] Persisting ${ibGibs.length} ibGibs...`);
+            await metaspace.put({ ibGibs })
+            // await spaceSvc.putIbGibGraph(ibGibs);
+            console.log(`[KeystoneHandler] Persistence successful.`);
+            return { status: 201, body: { success: true }, isJson: true };
+
+        } catch (error) {
+            const emsg = `${lc} ${extractErrorMsg(error)}`;
+            console.error(emsg);
+            return this.error(500, emsg);
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}

package/src/server/serve-gib/handlers/api/keystone/keystone-post.respec.mts

@@ -0,0 +1,130 @@
+import { join } from 'node:path';
+import { existsSync, rmSync, mkdirSync, readdirSync } from 'node:fs';
+
+import {
+    respecfully, iReckon, ifWe, ifWeMight
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+const sir = `[${import.meta.url}]`;
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+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 '../../../constants.mjs';
+import { ServeGib_V1 } from '../../../serve-gib-v1.mjs';
+import { KeystonePostHandler } from './keystone-post.handler.mjs';
+import { ErrorHandler } from '../../error-handler.mjs';
+import { getDomainRootPath } from '../../../../bootstrap-helper.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+if (logalot) { console.log(`[test] keystone-post.respec.mts top-level entry`); }
+
+class MockMetaspace {
+    async getLocalUserSpace() { return new MockSpace(); }
+    async put() { }
+    async registerNewIbGib() { }
+}
+class MockSpace {
+    async witness() { return { data: { success: true } }; }
+}
+
+await respecfully(sir, 'Keystone POST Integration', async () => {
+    const testDataDir = './test-data-post';
+    const port = 3001;
+
+    // Clean test data
+    if (existsSync(testDataDir)) {
+        rmSync(testDataDir, { recursive: true, force: true });
+    }
+    mkdirSync(testDataDir, { recursive: true });
+
+    await ifWe(sir, 'bootstrap a new domain via POST /api/keystone', async () => {
+        const keystoneService = new KeystoneService_V1();
+        const config = createStandardPoolConfig({ id: POOL_ID_DEFAULT, salt: POOL_ID_DEFAULT });
+
+        // 1. Generate real genesis
+        const genesis = await keystoneService.genesis({
+            masterSecret: 'AliceSecret',
+            configs: [config],
+            metaspace: new MockMetaspace() as any,
+            space: new MockSpace() as any,
+        });
+        const addr = getIbGibAddr({ ibGib: genesis });
+
+        if (logalot) { console.log(`[test] Generated genesis: ${addr}`); }
+
+        // 2. Setup ServeGib_V1
+        const serveGib = new ServeGib_V1({
+            port,
+            dataDir: testDataDir,
+            handlers: [new KeystonePostHandler()],
+            errorHandler: new ErrorHandler()
+        });
+
+        if (logalot) { console.log(`[test] ServeGib_V1 setup. Posting to /api/keystone...`); }
+
+        // 3. Mock POST Request
+        const req: any = {
+            url: '/api/keystone',
+            method: 'POST',
+            headers: {
+                'ibgib-domain': addr,
+                'content-type': 'application/json'
+            },
+            on: (event: string, cb: any) => {
+                if (event === 'data') {
+                    if (logalot) { console.log(`[test] sending data chunk...`); }
+                    cb(Buffer.from(JSON.stringify({ ibGibs: [genesis] })));
+                }
+                if (event === 'end') {
+                    if (logalot) { console.log(`[test] end of request.`); }
+                    cb();
+                }
+            }
+        };
+
+        let capturedStatus: number = 0;
+        let capturedBody: any = null;
+        const res: any = {
+            writeHead: (status: number) => {
+                if (logalot) { console.log(`[test] writeHead: ${status}`); }
+                capturedStatus = status;
+            },
+            end: (body: string) => {
+                if (logalot) { console.log(`[test] res.end called with body length: ${body?.length}`); }
+                capturedBody = JSON.parse(body);
+            },
+            statusCode: 0
+        };
+
+        // 4. Handle
+        if (logalot) { console.log(`[test] Calling handleRequest...`); }
+        await serveGib.handleRequest(req, res);
+        if (logalot) { console.log(`[test] handleRequest completed.`); }
+
+        // 5. Verify
+        iReckon(sir, capturedStatus).asTo('captured status code').isGonnaBe(201);
+        iReckon(sir, capturedBody.success).asTo(`Handler failed: ${capturedBody.message || 'no message'}`).isGonnaBe(true);
+
+        const domainPath = getDomainRootPath(genesis.gib!, testDataDir);
+        iReckon(sir, existsSync(domainPath)).asTo('domain path exists').isGonnaBe(true);
+
+        // Verify the ibgib actually exists in the new domain's storage
+        // With indexed storage, it's in a bucketed subpath: ibgib/default/ibgibs/B1/B2/
+        const bucket1 = genesis.gib!.substring(0, 3).toUpperCase();
+        const bucket2 = genesis.gib!.substring(3, 6).toUpperCase();
+        const bucketPath = join(domainPath, 'ibgib', 'default', 'ibgibs', bucket1, bucket2);
+
+        iReckon(sir, existsSync(bucketPath)).asTo(`Bucket path does not exist: ${bucketPath}`).isGonnaBe(true);
+
+        // We don't know the random filename, but we know it's a .json file in that bucket
+        try {
+            const files = readdirSync(bucketPath).filter(f => f.endsWith('.json'));
+            iReckon(sir, files.length > 0).asTo(`No .json files found in bucket: ${bucketPath}`).isGonnaBe(true);
+        } catch (error) {
+            iReckon(sir, true).asTo(`error trying to readdir ${bucketPath}: ${extractErrorMsg(error)}`).isGonnaBe(true);
+        }
+    });
+});

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

@@ -0,0 +1,36 @@
+/**
+ * @module serve-gib/handlers/error-handler
+ *
+ * Default error handler for serve-gib.
+ */
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT } from '../constants.mjs';
+import { ServeGibHandlerBase } from './handler-base.mjs';
+import { RequestContext, ResponseResult, ServeGibHttpMethod } from '../types.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+export class ErrorHandler extends ServeGibHandlerBase {
+    protected override lc: string = `[${ErrorHandler.name}]`;
+    protected override method: ServeGibHttpMethod = 'ALL';
+    protected override regex = /.*/;
+
+    async handleRouteImpl(reqCtx: RequestContext): Promise<ResponseResult | undefined> {
+        const lc = `${this.lc}[${this.handleRouteImpl.name}]`;
+        try {
+            if (logalot) { console.log(`${lc} starting...`); }
+
+            const { rawUrl, pathname, method, } = reqCtx;
+
+            // This is the fallback handler
+            return this.error(404, 'Not Found', { method, rawUrl, pathname });
+        } catch (error: any) {
+            console.log(`${lc} ${extractErrorMsg(error)}`);
+            throw error;
+        } finally {
+            if (logalot) { console.log(`${lc} complete.`); }
+        }
+    }
+}