fix: Vercel 404 on /api/v1/meta and /api/v1/packages — path normalisation, kernel boot resilience, broker-optional metadata

CHANGELOG.md

@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+- **Vercel serverless 404 fix** — `api/[...path].ts` now normalises request paths and includes
+ robust error handling, preventing silent 404s when the Vercel runtime strips or alters the
+ `/api/` prefix. Cold-start errors are now caught and returned as structured 500 responses
+ instead of being swallowed.
+- **Kernel cold-start race condition** — `api/_kernel.ts` uses a shared boot promise so that
+ concurrent cold-start requests wait for the same initialisation rather than launching
+ duplicate boot sequences. Seed-data failures are treated as non-fatal, and the broker shim
+ is validated after bootstrap with automatic reattachment if lost.
+- **Broker-resilient metadata handler** — `HttpDispatcher.handleMetadata()` no longer requires
+ a broker upfront. It tries the protocol service and ObjectQL registry first, falling back to
+ the broker only when available. Serverless/lightweight setups without a full message broker
+ now return proper metadata responses instead of throwing 500 errors.
+
 ### Added
 - **Studio system objects visibility** — Studio now auto-registers all system objects (sys_user,
  sys_role, sys_audit_log, etc.) from plugin-auth, plugin-security, and plugin-audit at kernel

apps/studio/api/[...path].ts

@@ -23,8 +23,27 @@ import { getApp } from './_kernel';
 const app = new Hono();
 
 app.all('/*', async (c) => {
- const inner = await getApp();
- return inner.fetch(c.req.raw);
+ try {
+ const inner = await getApp();
+
+ // Normalise the request URL so the inner Hono app always sees the
+ // full /api/… prefix. Vercel's Node.js runtime preserves it, but
+ // some runtimes or proxies may strip the function directory prefix.
+ const url = new URL(c.req.url);
+ if (!url.pathname.startsWith('/api')) {
+ url.pathname = '/api' + url.pathname;
+ const request = new Request(url.toString(), c.req.raw);
+ return await inner.fetch(request);
+ }
+
+ return await inner.fetch(c.req.raw);
+ } catch (err: any) {
+ console.error('[Vercel] Handler error:', err?.message || err);
+ return c.json(
+ { success: false, error: { message: err?.message || 'Internal Server Error', code: 500 } },
+ 500,
+ );
+ }
 });
 
 export default handle(app);

apps/studio/api/_kernel.ts

@@ -24,31 +24,61 @@ import studioConfig from '../objectstack.config';
 let _kernel: ObjectKernel | null = null;
 let _app: Hono | null = null;
 
+// Initialisation lock — prevents concurrent cold-start boots from racing.
+let _bootPromise: Promise<ObjectKernel> | null = null;
+
 /**
  * Boot the ObjectStack kernel (one-time cold-start cost).
+ *
+ * Uses a shared promise so that concurrent requests during a cold start
+ * wait for the same boot sequence rather than starting duplicates.
  */
 async function bootKernel(): Promise<ObjectKernel> {
  if (_kernel) return _kernel;
 
- console.log('[Vercel] Booting ObjectStack Kernel (server mode)...');
+ // Return the in-flight boot if one is already running
+ if (_bootPromise) return _bootPromise;
+
+ _bootPromise = (async () => {
+ console.log('[Vercel] Booting ObjectStack Kernel (server mode)...');
+
+ try {
+ const kernel = new ObjectKernel();
 
- const kernel = new ObjectKernel();
+ await kernel.use(new ObjectQLPlugin());
+ await kernel.use(new DriverPlugin(new InMemoryDriver(), 'memory'));
+ await kernel.use(new AppPlugin(studioConfig));
 
- await kernel.use(new ObjectQLPlugin());
- await kernel.use(new DriverPlugin(new InMemoryDriver(), 'memory'));
- await kernel.use(new AppPlugin(studioConfig));
+ // Broker shim — bridges HttpDispatcher → ObjectQL engine
+ (kernel as any).broker = createBrokerShim(kernel);
 
- // Broker shim — bridges HttpDispatcher → ObjectQL engine
- (kernel as any).broker = createBrokerShim(kernel);
+ await kernel.bootstrap();
 
- await kernel.bootstrap();
+ // Validate broker attachment
+ if (!(kernel as any).broker) {
+ console.warn('[Vercel] Broker shim lost during bootstrap — reattaching.');
+ (kernel as any).broker = createBrokerShim(kernel);
+ }
+
+ // Seed data from config (non-fatal — the kernel is usable without seed data)
+ try {
+ await seedData(kernel, [studioConfig]);
+ } catch (seedErr: any) {
+ console.warn('[Vercel] Seed data failed (non-fatal):', seedErr?.message || seedErr);
+ }
 
- // Seed data from config
- await seedData(kernel, [studioConfig]);
+ _kernel = kernel;
+ console.log('[Vercel] Kernel ready.');
+ return kernel;
+ } catch (err) {
+ // Clear the lock so the next request can retry
+ _bootPromise = null;
+ console.error('[Vercel] Kernel boot failed:', (err as any)?.message || err);
+ throw err;
+ }
+ })();
 
- _kernel = kernel;
- console.log('[Vercel] Kernel ready.');
- return kernel;
+ return _bootPromise;
 }
 
 /**

packages/adapters/hono/src/hono.test.ts

@@ -544,4 +544,110 @@ describe('createHonoApp', () => {
  expect(json.id).toBe(1);
  });
  });
+
+ describe('Vercel Delegation Pattern (inner.fetch)', () => {
+ it('works when an outer Hono app delegates via inner.fetch(c.req.raw)', async () => {
+ const innerApp = createHonoApp({ kernel: mockKernel, prefix: '/api/v1' });
+
+ // Simulate the Vercel catch-all pattern: outer app wraps inner app
+ const outerApp = new Hono();
+ outerApp.all('/*', async (c) => {
+ return innerApp.fetch(c.req.raw);
+ });
+
+ // Request with the full /api/v1 prefix — should route correctly
+ const res = await outerApp.request('/api/v1/meta');
+ expect(res.status).toBe(200);
+ expect(mockDispatcher.dispatch).toHaveBeenCalledWith(
+ 'GET',
+ '/meta',
+ undefined,
+ expect.any(Object),
+ expect.objectContaining({ request: expect.anything() }),
+ );
+ });
+
+ it('routes /api/v1/packages through outer→inner delegation', async () => {
+ const innerApp = createHonoApp({ kernel: mockKernel, prefix: '/api/v1' });
+
+ const outerApp = new Hono();
+ outerApp.all('/*', async (c) => {
+ return innerApp.fetch(c.req.raw);
+ });
+
+ const res = await outerApp.request('/api/v1/packages');
+ expect(res.status).toBe(200);
+ expect(mockDispatcher.dispatch).toHaveBeenCalledWith(
+ 'GET',
+ '/packages',
+ undefined,
+ expect.any(Object),
+ expect.objectContaining({ request: expect.anything() }),
+ );
+ });
+
+ it('routes /api/v1 discovery through outer→inner delegation', async () => {
+ const innerApp = createHonoApp({ kernel: mockKernel, prefix: '/api/v1' });
+
+ const outerApp = new Hono();
+ outerApp.all('/*', async (c) => {
+ return innerApp.fetch(c.req.raw);
+ });
+
+ const res = await outerApp.request('/api/v1');
+ expect(res.status).toBe(200);
+ const json = await res.json();
+ expect(json.data).toBeDefined();
+ expect(mockDispatcher.getDiscoveryInfo).toHaveBeenCalledWith('/api/v1');
+ });
+
+ it('handles path normalisation (strips prefix correctly) through delegation', async () => {
+ const innerApp = createHonoApp({ kernel: mockKernel, prefix: '/api/v1' });
+
+ const outerApp = new Hono();
+ outerApp.all('/*', async (c) => {
+ // Simulate the normalisation logic from [...path].ts
+ const url = new URL(c.req.url);
+ if (!url.pathname.startsWith('/api')) {
+ url.pathname = '/api' + url.pathname;
+ const request = new Request(url.toString(), c.req.raw);
+ return innerApp.fetch(request);
+ }
+ return innerApp.fetch(c.req.raw);
+ });
+
+ // Request with the full path — should work directly
+ const res1 = await outerApp.request('/api/v1/data/account');
+ expect(res1.status).toBe(200);
+ expect(mockDispatcher.dispatch).toHaveBeenCalledWith(
+ 'GET',
+ '/data/account',
+ undefined,
+ expect.any(Object),
+ expect.objectContaining({ request: expect.anything() }),
+ );
+ });
+
+ it('returns 500 with error details when inner app throws', async () => {
+ const outerApp = new Hono();
+
+ outerApp.all('/*', async (c) => {
+ try {
+ // Simulate a kernel boot failure
+ throw new Error('Kernel boot failed');
+ } catch (err: any) {
+ return c.json(
+ { success: false, error: { message: err.message, code: 500 } },
+ 500,
+ );
+ }
+ });
+
+ const res = await outerApp.request('/api/v1/meta');
+ expect(res.status).toBe(500);
+ const json = await res.json();
+ expect(json.success).toBe(false);
+ expect(json.error.message).toBe('Kernel boot failed');
+ });
+ });
 });

packages/runtime/src/http-dispatcher.test.ts

@@ -1208,4 +1208,104 @@ describe('HttpDispatcher', () => {
  expect(result.response?.status).toBe(200);
  });
  });
+
+ describe('handleMetadata without broker (serverless degradation)', () => {
+ let brokerlessKernel: any;
+ let brokerlessDispatcher: HttpDispatcher;
+
+ beforeEach(() => {
+ // Kernel with NO broker — simulates a lightweight/serverless setup
+ // where only the protocol service and/or ObjectQL registry are available.
+ brokerlessKernel = {
+ broker: null,
+ context: {
+ getService: vi.fn().mockReturnValue(null),
+ },
+ };
+ brokerlessDispatcher = new HttpDispatcher(brokerlessKernel);
+ });
+
+ it('GET /meta should return default types when broker is missing', async () => {
+ const context = { request: {} };
+ const result = await brokerlessDispatcher.handleMetadata('', context, 'GET');
+ expect(result.handled).toBe(true);
+ expect(result.response?.status).toBe(200);
+ expect(result.response?.body?.data?.types).toContain('object');
+ });
+
+ it('GET /meta/types should return default types when broker is missing', async () => {
+ const context = { request: {} };
+ const result = await brokerlessDispatcher.handleMetadata('/types', context, 'GET');
+ expect(result.handled).toBe(true);
+ expect(result.response?.status).toBe(200);
+ expect(result.response?.body?.data?.types).toContain('object');
+ });
+
+ it('GET /meta/objects should use ObjectQL registry when broker is missing', async () => {
+ const mockRegistry = {
+ getAllObjects: vi.fn().mockReturnValue([{ name: 'account' }]),
+ getObject: vi.fn(),
+ };
+ brokerlessKernel.context.getService = vi.fn().mockImplementation((name: string) => {
+ if (name === 'objectql') return { registry: mockRegistry };
+ return null;
+ });
+
+ const context = { request: {} };
+ const result = await brokerlessDispatcher.handleMetadata('/objects', context, 'GET');
+ expect(result.handled).toBe(true);
+ expect(result.response?.status).toBe(200);
+ expect(mockRegistry.getAllObjects).toHaveBeenCalled();
+ });
+
+ it('GET /meta/objects/:name should use ObjectQL registry when broker is missing', async () => {
+ const mockRegistry = {
+ registry: {
+ getObject: vi.fn().mockReturnValue({ name: 'account', fields: {} }),
+ },
+ };
+ brokerlessKernel.context.getService = vi.fn().mockImplementation((name: string) => {
+ if (name === 'objectql') return mockRegistry;
+ return null;
+ });
+
+ const context = { request: {} };
+ const result = await brokerlessDispatcher.handleMetadata('/objects/account', context, 'GET');
+ expect(result.handled).toBe(true);
+ expect(result.response?.status).toBe(200);
+ expect(mockRegistry.registry.getObject).toHaveBeenCalledWith('account');
+ });
+
+ it('GET /meta/:type/:name/published should return 404 when broker is missing and metadata service is unavailable', async () => {
+ const context = { request: {} };
+ const result = await brokerlessDispatcher.handleMetadata('/object/my_obj/published', context, 'GET');
+ expect(result.handled).toBe(true);
+ expect(result.response?.status).toBe(404);
+ });
+
+ it('PUT /meta/:type/:name should return 501 when broker is missing and protocol is unavailable', async () => {
+ const context = { request: {} };
+ const body = { label: 'Test' };
+ const result = await brokerlessDispatcher.handleMetadata('/objects/my_obj', context, 'PUT', body);
+ expect(result.handled).toBe(true);
+ expect(result.response?.status).toBe(501);
+ });
+
+ it('should use protocol service even when broker is missing', async () => {
+ const mockProtocolLocal = {
+ getMetaTypes: vi.fn().mockResolvedValue({ types: ['custom_type'] }),
+ };
+ brokerlessKernel.context.getService = vi.fn().mockImplementation((name: string) => {
+ if (name === 'protocol') return mockProtocolLocal;
+ return null;
+ });
+
+ const context = { request: {} };
+ const result = await brokerlessDispatcher.handleMetadata('/types', context, 'GET');
+ expect(result.handled).toBe(true);
+ expect(result.response?.status).toBe(200);
+ expect(mockProtocolLocal.getMetaTypes).toHaveBeenCalled();
+ expect(result.response?.body?.data?.types).toContain('custom_type');
+ });
+ });
 });