Merge pull request #985 from objectstack-ai/copilot/fix-discovery-api-routing-issues

hotlong · web-flow · commit 733f582e3084 · 2026-03-27T11:43:35.000+08:00
diff --git a/.changeset/discovery-route-consistency.md b/.changeset/discovery-route-consistency.md
@@ -0,0 +1,30 @@
+---
+"@objectstack/spec": minor
+"@objectstack/client": minor
+"@objectstack/runtime": patch
+"@objectstack/express": patch
+"@objectstack/fastify": patch
+"@objectstack/hono": patch
+"@objectstack/nestjs": patch
+"@objectstack/nextjs": patch
+"@objectstack/nuxt": patch
+"@objectstack/sveltekit": patch
+---
+
+Fix discovery API endpoint routing and protocol consistency.
+
+**Discovery route standardization:**
+- All adapters (Express, Fastify, Hono, NestJS, Next.js, Nuxt, SvelteKit) now mount the discovery endpoint at `{prefix}/discovery` instead of `{prefix}` root.
+- `.well-known/objectstack` redirects now point to `{prefix}/discovery`.
+- Client `connect()` fallback URL changed from `/api/v1` to `/api/v1/discovery`.
+- Runtime dispatcher handles both `/discovery` (standard) and `/` (legacy) for backward compatibility.
+
+**Schema & route alignment:**
+- Added `storage` (service: `file-storage`) and `feed` (service: `data`) routes to `DEFAULT_DISPATCHER_ROUTES`.
+- Added `feed` and `discovery` fields to `ApiRoutesSchema`.
+- Unified `GetDiscoveryResponseSchema` with `DiscoverySchema` as single source of truth.
+- Client `getRoute('feed')` fallback updated from `/api/v1/data` to `/api/v1/feed`.
+
+**Type safety:**
+- Extracted `ApiRouteType` from `ApiRoutes` keys for type-safe client route resolution.
+- Removed `as any` type casting in client route access.
diff --git a/packages/adapters/express/src/index.ts b/packages/adapters/express/src/index.ts
@@ -78,7 +78,7 @@ export function createExpressRouter(options: ExpressAdapterOptions): Router {
   // ─── Explicit routes (framework-specific handling required) ────────────────
 
   // --- Discovery ---
-  router.get('/', async (_req: Request, res: Response) => {
+  router.get('/discovery', async (_req: Request, res: Response) => {
     res.json({ data: await dispatcher.getDiscoveryInfo(prefix) });
   });
 
diff --git a/packages/adapters/fastify/src/index.ts b/packages/adapters/fastify/src/index.ts
@@ -76,13 +76,13 @@ export async function objectStackPlugin(fastify: FastifyInstance, options: Fasti
   // ─── Explicit routes (framework-specific handling required) ────────────────
 
   // --- Discovery ---
-  fastify.get(`${prefix}`, async (_request: FastifyRequest, reply: FastifyReply) => {
+  fastify.get(`${prefix}/discovery`, async (_request: FastifyRequest, reply: FastifyReply) => {
     return reply.send({ data: await dispatcher.getDiscoveryInfo(prefix) });
   });
 
   // --- .well-known ---
   fastify.get('/.well-known/objectstack', async (_request: FastifyRequest, reply: FastifyReply) => {
-    return reply.redirect(prefix);
+    return reply.redirect(`${prefix}/discovery`);
   });
 
   // --- Auth (needs auth service integration) ---
diff --git a/packages/adapters/hono/src/index.ts b/packages/adapters/hono/src/index.ts
@@ -81,13 +81,13 @@ export function createHonoApp(options: ObjectStackHonoOptions): Hono {
   // ─── Explicit routes (framework-specific handling required) ────────────────
 
   // --- Discovery ---
-  app.get(`${prefix}`, async (c) => {
+  app.get(`${prefix}/discovery`, async (c) => {
     return c.json({ data: await dispatcher.getDiscoveryInfo(prefix) });
   });
 
   // --- .well-known ---
   app.get('/.well-known/objectstack', (c) => {
-    return c.redirect(prefix);
+    return c.redirect(`${prefix}/discovery`);
   });
 
   // --- Auth (needs auth service integration) ---
diff --git a/packages/adapters/nestjs/src/index.ts b/packages/adapters/nestjs/src/index.ts
@@ -94,7 +94,7 @@ export class ObjectStackController {
   }
 
   // --- Discovery Endpoint ---
-  @Get()
+  @Get('discovery')
   async discovery() {
     return { data: await this.service.dispatcher.getDiscoveryInfo('/api') };
   }
@@ -241,7 +241,7 @@ export class ObjectStackController {
 export class DiscoveryController {
   @Get('objectstack')
   discover(@Res() res: any) {
-    return res.redirect('/api');
+    return res.redirect('/api/discovery');
   }
 }
 
diff --git a/packages/adapters/nestjs/src/nestjs.test.ts b/packages/adapters/nestjs/src/nestjs.test.ts
@@ -442,12 +442,12 @@ describe('ObjectStackController', () => {
 });
 
 describe('DiscoveryController', () => {
-  it('redirects to /api', () => {
+  it('redirects to /api/discovery', () => {
     const controller = new DiscoveryController();
     const res = createMockRes();
 
     controller.discover(res);
 
-    expect(res._redirectUrl).toBe('/api');
+    expect(res._redirectUrl).toBe('/api/discovery');
   });
 });
diff --git a/packages/adapters/nextjs/src/index.ts b/packages/adapters/nextjs/src/index.ts
@@ -62,7 +62,7 @@ export function createRouteHandler(options: NextAdapterOptions) {
     const method = req.method;
     
     // --- 0. Discovery Endpoint ---
-    if (segments.length === 0 && method === 'GET') {
+    if (segments.length === 1 && segments[0] === 'discovery' && method === 'GET') {
       return NextResponse.json({ data: await dispatcher.getDiscoveryInfo(options.prefix || '/api') });
     }
 
@@ -152,7 +152,7 @@ export function createDiscoveryHandler(options: NextAdapterOptions) {
   return async function discoveryHandler(req: NextRequest) {
       const apiPath = options.prefix || '/api';
       const url = new URL(req.url);
-      const targetUrl = new URL(apiPath, url.origin);
+      const targetUrl = new URL(`${apiPath}/discovery`, url.origin);
       return NextResponse.redirect(targetUrl);
   }
 }
diff --git a/packages/adapters/nuxt/src/index.ts b/packages/adapters/nuxt/src/index.ts
@@ -89,7 +89,7 @@ export function createH3Router(options: NuxtAdapterOptions): Router {
 
   // --- Discovery ---
   router.get(
-    `${prefix}`,
+    `${prefix}/discovery`,
     defineEventHandler(async () => {
       return { data: await dispatcher.getDiscoveryInfo(prefix) };
     }),
@@ -99,7 +99,7 @@ export function createH3Router(options: NuxtAdapterOptions): Router {
   router.get(
     '/.well-known/objectstack',
     defineEventHandler((event) => {
-      return sendRedirect(event, prefix);
+      return sendRedirect(event, `${prefix}/discovery`);
     }),
   );
 
diff --git a/packages/adapters/sveltekit/src/index.ts b/packages/adapters/sveltekit/src/index.ts
@@ -99,7 +99,7 @@ export function createRequestHandler(options: SvelteKitAdapterOptions) {
     const segments = path.split('/').filter(Boolean);
 
     // --- Discovery ---
-    if (segments.length === 0 && method === 'GET') {
+    if (segments.length === 1 && segments[0] === 'discovery' && method === 'GET') {
       return new Response(JSON.stringify({ data: await dispatcher.getDiscoveryInfo(prefix) }), {
         status: 200,
         headers: { 'Content-Type': 'application/json' },
diff --git a/packages/client/src/index.ts b/packages/client/src/index.ts
@@ -87,9 +87,17 @@ import {
   SubscribeResponse,
   UnsubscribeResponse,
   WellKnownCapabilities,
+  ApiRoutes,
 } from '@objectstack/spec/api';
 import { Logger, createLogger } from '@objectstack/core';
 
+/**
+ * Route types that the client can resolve.
+ * Covers all keys from `ApiRoutes` (the discovery schema) plus
+ * client-specific virtual routes (`views`, `permissions`).
+ */
+export type ApiRouteType = keyof ApiRoutes | 'views' | 'permissions';
+
 export interface ClientConfig {
   baseUrl: string;
   token?: string;
@@ -238,10 +246,10 @@ export class ObjectStackClient {
         this.logger.debug('Standard discovery probe failed', { error: (e as Error).message });
       }
 
-      // 2. Fallback to Legacy/Direct Path /api/v1
+      // 2. Fallback to Protocol-standard Discovery Path /api/v1/discovery
       if (!data) {
-        const fallbackUrl = `${this.baseUrl}/api/v1`;
-        this.logger.debug('Falling back to legacy discovery', { url: fallbackUrl });
+        const fallbackUrl = `${this.baseUrl}/api/v1/discovery`;
+        this.logger.debug('Falling back to standard discovery endpoint', { url: fallbackUrl });
         const res = await this.fetchImpl(fallbackUrl);
         if (!res.ok) {
            throw new Error(`Failed to connect to ${fallbackUrl}: ${res.statusText}`);
@@ -1677,16 +1685,20 @@ export class ObjectStackClient {
    * Get the conventional route path for a given API endpoint type
    * ObjectStack uses standard conventions: /api/v1/data, /api/v1/meta, /api/v1/ui
    */
-  private getRoute(type: 'data' | 'metadata' | 'ui' | 'auth' | 'analytics' | 'storage' | 'automation' | 'packages' | 'permissions' | 'realtime' | 'workflow' | 'views' | 'notifications' | 'ai' | 'i18n' | 'feed'): string {
-    // 1. Use discovered routes if available
-    if (this.discoveryInfo?.routes && (this.discoveryInfo.routes as any)[type]) {
-        return (this.discoveryInfo.routes as any)[type];
+  private getRoute(type: ApiRouteType): string {
+    // 1. Use discovered routes if available (only for ApiRoutes keys, not client-specific keys)
+    const routes = this.discoveryInfo?.routes;
+    if (routes) {
+        const key = type as keyof ApiRoutes;
+        const discovered = routes[key];
+        if (discovered) return discovered;
     }
 
-    // 2. Fallback to conventions
-    const routeMap: Record<string, string> = {
+    // 2. Fallback to conventions (covers all ApiRoutes keys + client-specific virtual routes)
+    const routeMap: Record<ApiRouteType, string> = {
       data: '/api/v1/data',
       metadata: '/api/v1/meta',
+      discovery: '/api/v1/discovery',
       ui: '/api/v1/ui',
       auth: '/api/v1/auth',
       analytics: '/api/v1/analytics',
@@ -1700,7 +1712,8 @@ export class ObjectStackClient {
       notifications: '/api/v1/notifications',
       ai: '/api/v1/ai',
       i18n: '/api/v1/i18n',
-      feed: '/api/v1/data',
+      feed: '/api/v1/feed',
+      graphql: '/graphql',
     };
     
     return routeMap[type] || `/api/v1/${type}`;
diff --git a/packages/plugins/plugin-hono-server/src/hono-plugin.ts b/packages/plugins/plugin-hono-server/src/hono-plugin.ts
@@ -276,8 +276,8 @@ export class HonoServerPlugin implements Plugin {
         };
 
         // Discovery endpoints
-        rawApp.get('/.well-known/objectstack', (c: any) => c.json({ data: discovery }));
-        rawApp.get(prefix, (c: any) => c.json({ data: discovery }));
+        rawApp.get('/.well-known/objectstack', (c: any) => c.redirect(`${prefix}/discovery`));
+        rawApp.get(`${prefix}/discovery`, (c: any) => c.json({ data: discovery }));
 
         ctx.logger.info('Registered discovery endpoints', { prefix });
 
diff --git a/packages/runtime/src/http-dispatcher.root.test.ts b/packages/runtime/src/http-dispatcher.root.test.ts
@@ -46,6 +46,21 @@ describe('HttpDispatcher Root Handling', () => {
         expect(data.routes.metadata).toBe('/meta');
     });
 
+    it('should handle GET /discovery (protocol-standard route)', async () => {
+        const context = { request: {} };
+        const result = await dispatcher.dispatch('GET', '/discovery', undefined, {}, context);
+
+        expect(result.handled).toBe(true);
+        expect(result.response).toBeDefined();
+        expect(result.response?.status).toBe(200);
+        
+        const data = result.response?.body?.data;
+        expect(data).toBeDefined();
+        expect(data.name).toBe('ObjectOS');
+        expect(data.version).toBe('1.0.0');
+        expect(data.routes).toBeDefined();
+    });
+
     it('should NOT handle POST request to root path ("")', async () => {
         const context = { request: {} };
         const method = 'POST';
diff --git a/packages/runtime/src/http-dispatcher.ts b/packages/runtime/src/http-dispatcher.ts
@@ -1154,9 +1154,10 @@ export class HttpDispatcher {
     async dispatch(method: string, path: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult> {
         const cleanPath = path.replace(/\/$/, ''); // Remove trailing slash if present, but strict on clean paths
 
-        // 0. Root Discovery Endpoint (GET /)
-        // Handles request to base URL (e.g. /api/v1) which MSW strips to empty string
-        if (cleanPath === '' && method === 'GET') {
+        // 0. Discovery Endpoint (GET /discovery or GET /)
+        // Standard route: /discovery (protocol-compliant)
+        // Legacy route: / (empty path, for backward compatibility — MSW strips base URL)
+        if ((cleanPath === '/discovery' || cleanPath === '') && method === 'GET') {
              // We use '' as prefix since we are internal dispatcher
              const info = await this.getDiscoveryInfo('');
              return { 
diff --git a/packages/spec/src/api/discovery.test.ts b/packages/spec/src/api/discovery.test.ts
@@ -29,10 +29,14 @@ describe('ApiRoutesSchema', () => {
       actions: '/api/v1/p',
       storage: '/api/v1/storage',
       graphql: '/api/v1/graphql',
+      feed: '/api/v1/feed',
+      discovery: '/api/v1/discovery',
     });
 
     expect(routes.data).toBe('/api/v1/data');
     expect(routes.graphql).toBe('/api/v1/graphql');
+    expect(routes.feed).toBe('/api/v1/feed');
+    expect(routes.discovery).toBe('/api/v1/discovery');
   });
 
   it('should accept custom route paths', () => {
diff --git a/packages/spec/src/api/discovery.zod.ts b/packages/spec/src/api/discovery.zod.ts
@@ -42,6 +42,9 @@ export const ApiRoutesSchema = z.object({
   /** Base URL for Schema Definitions (Metadata Protocol) */
   metadata: z.string().describe('e.g. /api/v1/meta'),
 
+  /** Base URL for API Discovery endpoint */
+  discovery: z.string().optional().describe('e.g. /api/v1/discovery'),
+
   /** Base URL for UI Configurations (Views, Menus) */
   ui: z.string().optional().describe('e.g. /api/v1/ui'),
   
@@ -77,6 +80,9 @@ export const ApiRoutesSchema = z.object({
 
   /** Base URL for Internationalization */
   i18n: z.string().optional().describe('e.g. /api/v1/i18n'),
+
+  /** Base URL for Feed / Chatter API */
+  feed: z.string().optional().describe('e.g. /api/v1/feed'),
 });
 
 /**
diff --git a/packages/spec/src/api/dispatcher.test.ts b/packages/spec/src/api/dispatcher.test.ts
@@ -120,7 +120,7 @@ describe('DispatcherConfigSchema', () => {
 
 describe('DEFAULT_DISPATCHER_ROUTES', () => {
   it('should have routes for all protocol namespaces', () => {
-    expect(DEFAULT_DISPATCHER_ROUTES.length).toBeGreaterThanOrEqual(13);
+    expect(DEFAULT_DISPATCHER_ROUTES.length).toBeGreaterThanOrEqual(15);
   });
 
   it('should include required services', () => {
@@ -130,6 +130,15 @@ describe('DEFAULT_DISPATCHER_ROUTES', () => {
     expect(services).toContain('auth');
   });
 
+  it('should include storage and feed services', () => {
+    const services = DEFAULT_DISPATCHER_ROUTES.map(r => r.service);
+    expect(services).toContain('file-storage');
+    // feed route maps to the data service
+    const feedRoute = DEFAULT_DISPATCHER_ROUTES.find(r => r.prefix.includes('feed'));
+    expect(feedRoute).toBeDefined();
+    expect(feedRoute!.service).toBe('data');
+  });
+
   it('should include optional services', () => {
     const services = DEFAULT_DISPATCHER_ROUTES.map(r => r.service);
     expect(services).toContain('ai');
diff --git a/packages/spec/src/api/dispatcher.zod.ts b/packages/spec/src/api/dispatcher.zod.ts
@@ -153,6 +153,8 @@ export const DEFAULT_DISPATCHER_ROUTES: DispatcherRouteInput[] = [
   { prefix: '/api/v1/workflow',      service: 'workflow' },
   { prefix: '/api/v1/analytics',     service: 'analytics' },
   { prefix: '/api/v1/automation',    service: 'automation' },
+  { prefix: '/api/v1/storage',       service: 'file-storage' },
+  { prefix: '/api/v1/feed',          service: 'data' },
   { prefix: '/api/v1/i18n',          service: 'i18n' },
   { prefix: '/api/v1/notifications', service: 'notification' },
   { prefix: '/api/v1/realtime',      service: 'realtime' },
diff --git a/packages/spec/src/api/protocol.test.ts b/packages/spec/src/api/protocol.test.ts
diff --git a/packages/spec/src/api/protocol.zod.ts b/packages/spec/src/api/protocol.zod.ts

Original file line number	Diff line number	Diff line change
`@@ -94,7 +94,7 @@ export class ObjectStackController {`
`94`	`94`	`}`
`95`	`95`
`96`	`96`	`// --- Discovery Endpoint ---`
`97`		`- @Get()`
	`97`	`+ @Get('discovery')`
`98`	`98`	`async discovery() {`
`99`	`99`	`return { data: await this.service.dispatcher.getDiscoveryInfo('/api') };`
`100`	`100`	`}`
`@@ -241,7 +241,7 @@ export class ObjectStackController {`
`241`	`241`	`export class DiscoveryController {`
`242`	`242`	`@Get('objectstack')`
`243`	`243`	`discover(@Res() res: any) {`
`244`		`- return res.redirect('/api');`
	`244`	`+ return res.redirect('/api/discovery');`
`245`	`245`	`}`
`246`	`246`	`}`
`247`	`247`
Original file line number	Diff line number	Diff line change
`@@ -62,7 +62,7 @@ export function createRouteHandler(options: NextAdapterOptions) {`
`62`	`62`	`const method = req.method;`
`63`	`63`
`64`	`64`	`// --- 0. Discovery Endpoint ---`
`65`		`- if (segments.length === 0 && method === 'GET') {`
	`65`	`+ if (segments.length === 1 && segments[0] === 'discovery' && method === 'GET') {`
`66`	`66`	`return NextResponse.json({ data: await dispatcher.getDiscoveryInfo(options.prefix \|\| '/api') });`
`67`	`67`	`}`
`68`	`68`
`@@ -152,7 +152,7 @@ export function createDiscoveryHandler(options: NextAdapterOptions) {`
`152`	`152`	`return async function discoveryHandler(req: NextRequest) {`
`153`	`153`	`const apiPath = options.prefix \|\| '/api';`
`154`	`154`	`const url = new URL(req.url);`
`155`		`- const targetUrl = new URL(apiPath, url.origin);`
	`155`	+ const targetUrl = new URL(`${apiPath}/discovery`, url.origin);
`156`	`156`	`return NextResponse.redirect(targetUrl);`
`157`	`157`	`}`
`158`	`158`	`}`