@shipfox/api-server 7.0.1 → 7.1.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@shipfox/api-server",
   "license": "MIT",
   "private": false,
-  "version": "7.0.1",
+  "version": "7.1.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ShipfoxHQ/shipfox.git",
@@ -25,46 +25,37 @@
     }
   },
   "dependencies": {
-    "@shipfox/annotations": "6.0.0",
+    "@shipfox/annotations": "7.1.0",
+    "@shipfox/api-agent": "7.1.0",
     "@shipfox/annotations-dto": "6.0.0",
-    "@shipfox/api-agent": "6.0.0",
     "@shipfox/api-agent-dto": "6.0.0",
-    "@shipfox/api-auth": "7.0.1",
-    "@shipfox/api-auth-dto": "6.0.0",
-    "@shipfox/api-definitions": "6.0.0",
+    "@shipfox/api-auth": "7.1.0",
+    "@shipfox/api-auth-dto": "7.1.0",
     "@shipfox/api-definitions-dto": "6.0.0",
-    "@shipfox/api-dispatcher": "6.0.0",
-    "@shipfox/api-email-challenges": "0.2.2",
-    "@shipfox/api-integration-core": "7.0.1",
-    "@shipfox/api-integration-core-dto": "6.0.0",
-    "@shipfox/api-logs": "6.0.0",
-    "@shipfox/api-projects": "6.0.0",
+    "@shipfox/api-dispatcher": "7.1.0",
+    "@shipfox/api-email-challenges": "0.3.0",
+    "@shipfox/api-definitions": "7.1.0",
+    "@shipfox/api-integration-core": "7.1.0",
+    "@shipfox/api-projects": "7.1.0",
+    "@shipfox/api-logs": "7.1.0",
     "@shipfox/api-projects-dto": "6.0.0",
-    "@shipfox/api-runners": "7.0.1",
+    "@shipfox/api-runners": "7.1.0",
     "@shipfox/api-runners-dto": "7.0.1",
-    "@shipfox/api-secrets": "6.0.0",
+    "@shipfox/api-secrets": "7.1.0",
+    "@shipfox/api-integration-core-dto": "6.0.0",
+    "@shipfox/api-workflows": "7.1.0",
     "@shipfox/api-secrets-dto": "6.0.0",
-    "@shipfox/api-triggers": "7.0.1",
-    "@shipfox/api-workflows": "7.0.1",
-    "@shipfox/api-workflows-dto": "6.0.0",
+    "@shipfox/api-triggers": "7.1.0",
     "@shipfox/api-workspaces-dto": "6.0.0",
-    "@shipfox/api-workspaces": "7.0.1",
+    "@shipfox/api-workflows-dto": "6.0.0",
+    "@shipfox/api-workspaces": "7.1.0",
     "@shipfox/config": "1.2.2",
-    "@shipfox/node-error-monitoring": "0.1.3",
-    "@shipfox/node-fastify": "0.2.4",
+    "@shipfox/node-fastify": "0.3.0",
+    "@shipfox/node-error-monitoring": "0.2.0",
     "@shipfox/node-jwt": "0.3.0",
-    "@shipfox/node-module": "0.4.0",
-    "@shipfox/node-opentelemetry": "0.5.2",
-    "@shipfox/node-postgres": "0.4.2"
-  },
-  "devDependencies": {
-    "@shipfox/biome": "1.8.2",
-    "@shipfox/depcruise": "1.0.2",
-    "@shipfox/inter-module": "0.2.0",
-    "@shipfox/swc": "1.2.6",
-    "@shipfox/ts-config": "1.3.8",
-    "@shipfox/typescript": "1.1.7",
-    "@shipfox/vitest": "1.2.3"
+    "@shipfox/node-postgres": "0.4.2",
+    "@shipfox/node-module": "0.5.0",
+    "@shipfox/node-opentelemetry": "0.6.0"
   },
   "scripts": {
     "build": "shipfox-swc",

package/src/index.ts

@@ -1,3 +1,8 @@
-export {type DefaultModulesOptions, defaultModules} from './modules.js';
+export {
+  type DefaultModulesOptions,
+  type DefaultRunnersModuleFactory,
+  defaultModules,
+} from './modules.js';
+export {createLoginMethodsRoute} from './routes/login-methods.js';
 export type {CreateServerOptions, RunServerOptions, ServerHandle} from './server.js';
 export {createServer, runServer} from './server.js';

package/src/instrumentation.ts

@@ -1,8 +1,12 @@
+import {createRequire} from 'node:module';
 import {startInstanceInstrumentation} from '@shipfox/node-opentelemetry';
 
+const {version} = createRequire(import.meta.url)('../package.json') as {version: string};
+
 // The metrics API has no proxy meter: instruments created before this preload
 // completes bind to a no-op provider for the process lifetime.
 await startInstanceInstrumentation({
   serviceName: 'api',
-  instrumentations: {fastify: true, http: true, pg: true},
+  serviceVersion: version,
+  instrumentations: {fastify: true, http: true, pg: true, awsSdk: true},
 });

package/src/modules.test.ts

@@ -254,6 +254,40 @@ describe('defaultModules', () => {
     expect(mocks.createRunnersModule).toHaveBeenCalledWith({auth: expect.any(Object)});
   });
 
+  it('lets a host replace only the Runners module with the composed Auth client', async () => {
+    const policy = {filterEligibleWorkspaceIds: vi.fn().mockResolvedValue(new Set<string>())};
+    const runnersModule = mocks.createRunnersModule({});
+    const createHostRunnersModule = vi.fn(({auth}) =>
+      mocks.createRunnersModule({auth, installationProvisioning: {policy}}),
+    );
+    mocks.createRunnersModule.mockClear();
+
+    const modules = await defaultModules({runnersModule: createHostRunnersModule});
+
+    expect(createHostRunnersModule).toHaveBeenCalledWith({auth: expect.any(Object)});
+    expect(mocks.createRunnersModule).toHaveBeenCalledWith({
+      auth: createHostRunnersModule.mock.calls[0]?.[0].auth,
+      installationProvisioning: {policy},
+    });
+    expect(modules.filter((module) => module.name === 'runners')).toEqual([runnersModule]);
+    expect(modules.map((module) => module.name)).toEqual([
+      'email-challenges',
+      'auth',
+      'workspaces',
+      'secrets',
+      'agent',
+      'integrations',
+      'projects',
+      'definitions',
+      'workflows',
+      'annotations',
+      'runners',
+      'logs',
+      'triggers',
+      'dispatcher',
+    ]);
+  });
+
   it('injects Workflows into integrations and logs and namespaces provider secrets', async () => {
     await defaultModules();
 

package/src/modules.ts

@@ -4,7 +4,10 @@ import {createAgentModule} from '@shipfox/api-agent';
 import {agentInterModuleContract} from '@shipfox/api-agent-dto/inter-module';
 import {createAuthModule} from '@shipfox/api-auth';
 import {config as authConfig} from '@shipfox/api-auth/config';
-import {authInterModuleContract} from '@shipfox/api-auth-dto/inter-module';
+import {
+  type AuthInterModuleClient,
+  authInterModuleContract,
+} from '@shipfox/api-auth-dto/inter-module';
 import {createDefinitionsModule} from '@shipfox/api-definitions';
 import {definitionsInterModuleContract} from '@shipfox/api-definitions-dto/inter-module';
 import {dispatcherModule} from '@shipfox/api-dispatcher';
@@ -23,21 +26,38 @@ import {createWorkflowsModule} from '@shipfox/api-workflows';
 import {workflowsInterModuleContract} from '@shipfox/api-workflows-dto/inter-module';
 import {workspacesModule} from '@shipfox/api-workspaces';
 import {workspacesInterModuleContract} from '@shipfox/api-workspaces-dto/inter-module';
+import {reportError} from '@shipfox/node-error-monitoring';
 import {durationToSeconds} from '@shipfox/node-jwt';
 import type {ShipfoxModule} from '@shipfox/node-module';
 import {
   createInMemoryInterModuleTransport,
   registerInterModulePresentations,
 } from '@shipfox/node-module/inter-module';
+import {logger} from '@shipfox/node-opentelemetry';
 
 export interface DefaultModulesOptions {
   webhookDeliverySource?: WebhookDeliverySource | undefined;
+  runnersModule?: DefaultRunnersModuleFactory | undefined;
 }
 
+export type DefaultRunnersModuleFactory = (options: {auth: AuthInterModuleClient}) => ShipfoxModule;
+
 export async function defaultModules(
   options: DefaultModulesOptions = {},
 ): Promise<ShipfoxModule[]> {
-  const interModuleTransport = createInMemoryInterModuleTransport();
+  const interModuleTransport = createInMemoryInterModuleTransport({
+    reportInternalError: (error, context) => {
+      logger().error(
+        {err: error, module: context.module, method: context.method, phase: context.phase},
+        'Inter-module call failed unexpectedly',
+      );
+      reportError(error, {
+        boundary: 'inter-module',
+        operation: `${context.module}.${context.method}`,
+        tags: {module: context.module, method: context.method, phase: context.phase},
+      });
+    },
+  });
   const workflowsClient = interModuleTransport.createClient(workflowsInterModuleContract);
   const authClient = interModuleTransport.createClient(authInterModuleContract);
   const agentClient = interModuleTransport.createClient(agentInterModuleContract);
@@ -154,7 +174,7 @@ export async function defaultModules(
       integrations: integrationsClient,
     }),
     annotationsModule,
-    createRunnersModule({auth: authClient}),
+    (options.runnersModule ?? createRunnersModule)({auth: authClient}),
     createLogsModule({
       workflows: workflowsClient,
       jobLeaseTokenTtlSeconds: durationToSeconds(authConfig.AUTH_JOB_LEASE_TOKEN_EXPIRES_IN),

package/src/routes/login-methods.test.ts

@@ -0,0 +1,56 @@
+import {createApp} from '@shipfox/node-fastify';
+import type {LoginMethod} from '@shipfox/node-module';
+import {createLoginMethodsRoute} from './login-methods.js';
+
+describe('createLoginMethodsRoute', () => {
+  it('lists registered methods exactly once, including unknown future IDs', async () => {
+    const app = await createApp({
+      auth: [],
+      routes: [
+        createLoginMethodsRoute({
+          loginMethods: [{id: 'password'}, {id: 'oauth-google'}, {id: 'future-provider'}],
+        }),
+      ],
+      swagger: false,
+    });
+
+    try {
+      const response = await app.inject({method: 'GET', url: '/auth/login-methods'});
+
+      expect(response.statusCode).toBe(200);
+      expect(response.json()).toEqual({
+        login_methods: [{id: 'password'}, {id: 'oauth-google'}, {id: 'future-provider'}],
+      });
+    } finally {
+      await app.close();
+    }
+  });
+
+  it('does not serialize module implementation details', async () => {
+    const loginMethod = {
+      id: 'oauth-google',
+      clientSecret: 'not-for-clients',
+      callbackUrl: 'https://api.example.test/auth/callback',
+    } as LoginMethod;
+    const app = await createApp({
+      auth: [],
+      routes: [createLoginMethodsRoute({loginMethods: [loginMethod]})],
+      swagger: false,
+    });
+
+    try {
+      const response = await app.inject({method: 'GET', url: '/auth/login-methods'});
+
+      expect(response.statusCode).toBe(200);
+      expect(response.json()).toEqual({login_methods: [{id: 'oauth-google'}]});
+      expect(response.body).not.toContain('not-for-clients');
+      expect(response.body).not.toContain('api.example.test');
+    } finally {
+      await app.close();
+    }
+  });
+
+  it('rejects an out-of-contract login method ID before the server can start', () => {
+    expect(() => createLoginMethodsRoute({loginMethods: [{id: ''}]})).toThrow();
+  });
+});

package/src/routes/login-methods.ts

@@ -0,0 +1,21 @@
+import {loginMethodsResponseSchema} from '@shipfox/api-auth-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import type {LoginMethod} from '@shipfox/node-module';
+
+export function createLoginMethodsRoute({loginMethods}: {loginMethods: readonly LoginMethod[]}) {
+  const response = loginMethodsResponseSchema.parse({
+    login_methods: loginMethods.map(({id}) => ({id})),
+  });
+
+  return defineRoute({
+    method: 'GET',
+    path: '/auth/login-methods',
+    description: 'List the login methods available in this server composition.',
+    schema: {
+      response: {
+        200: loginMethodsResponseSchema,
+      },
+    },
+    handler: () => response,
+  });
+}

package/src/server.test.ts

@@ -12,11 +12,13 @@ const mocks = vi.hoisted(() => {
   const workersHandle = {stop: vi.fn()};
   const servicesHandle = {stop: vi.fn()};
   return {
-    captureException: vi.fn(),
+    markErrorReported: vi.fn(),
+    reportError: vi.fn(),
     closeApp: vi.fn(),
     closeErrorMonitoring: vi.fn(),
     closePostgresClient: vi.fn(),
     createApp: vi.fn(),
+    defineRoute: vi.fn((route) => route),
     createE2eAdminAuthMethod: vi.fn(),
     createE2eRouteGroup: vi.fn(),
     createPostgresClient: vi.fn(),
@@ -42,12 +44,14 @@ const mocks = vi.hoisted(() => {
 });
 
 vi.mock('@shipfox/node-error-monitoring', () => ({
-  captureException: mocks.captureException,
   closeErrorMonitoring: mocks.closeErrorMonitoring,
+  markErrorReported: mocks.markErrorReported,
+  reportError: mocks.reportError,
 }));
 vi.mock('@shipfox/node-fastify', () => ({
   closeApp: mocks.closeApp,
   createApp: mocks.createApp,
+  defineRoute: mocks.defineRoute,
   listen: mocks.listen,
 }));
 vi.mock('@shipfox/node-module', () => ({
@@ -113,11 +117,13 @@ function lastStartModuleServicesOptions(): {
 
 function resetMocks(): void {
   vi.useRealTimers();
-  mocks.captureException.mockReset();
+  mocks.markErrorReported.mockReset();
+  mocks.reportError.mockReset();
   mocks.closeApp.mockReset();
   mocks.closeErrorMonitoring.mockReset();
   mocks.closePostgresClient.mockReset();
   mocks.createApp.mockReset();
+  mocks.defineRoute.mockReset();
   mocks.createE2eAdminAuthMethod.mockReset();
   mocks.createE2eRouteGroup.mockReset();
   mocks.createPostgresClient.mockReset();
@@ -143,6 +149,7 @@ function resetMocks(): void {
   mocks.closeErrorMonitoring.mockResolvedValue(true);
   mocks.closePostgresClient.mockResolvedValue(undefined);
   mocks.createApp.mockResolvedValue({});
+  mocks.defineRoute.mockImplementation((route) => route);
   mocks.aggregateLoginMethods.mockReturnValue([{id: 'test-login'}]);
   mocks.createE2eRouteGroup.mockReturnValue([]);
   mocks.initializeModules.mockResolvedValue({
@@ -204,9 +211,16 @@ describe('createServer', () => {
     });
     expect(mocks.createApp).toHaveBeenCalledWith({
       auth: [],
-      routes: [],
+      routes: [
+        expect.objectContaining({
+          method: 'GET',
+          path: '/auth/login-methods',
+        }),
+      ],
       fastifyOptions: {trustProxy: false},
     });
+    const appConfig = mocks.createApp.mock.calls.at(0)?.[0];
+    expect(appConfig?.routes[0].handler()).toEqual({login_methods: [{id: 'test-login'}]});
   });
 
   it('fails before startup side effects when no login method is configured', async () => {
@@ -492,7 +506,10 @@ describe('createServer', () => {
       {err: failure, taskQueue: 'runtime-queue'},
       'Module worker stopped unexpectedly',
     );
-    expect(mocks.captureException).toHaveBeenCalledWith(failure);
+    expect(mocks.reportError).toHaveBeenCalledWith(failure, {
+      boundary: 'api.runtime',
+      tags: {taskQueue: 'runtime-queue'},
+    });
     expect(mocks.closeApp).toHaveBeenCalledOnce();
     expect(mocks.closeErrorMonitoring).toHaveBeenCalledWith(2_000);
     expect(mocks.closeErrorMonitoring.mock.invocationCallOrder[0]).toBeLessThan(
@@ -513,7 +530,10 @@ describe('createServer', () => {
       {err: failure, service: 'runtime-service'},
       'Module service stopped unexpectedly',
     );
-    expect(mocks.captureException).toHaveBeenCalledWith(failure);
+    expect(mocks.reportError).toHaveBeenCalledWith(failure, {
+      boundary: 'api.runtime',
+      tags: {service: 'runtime-service'},
+    });
     expect(mocks.closeApp).toHaveBeenCalledOnce();
     expect(mocks.closeErrorMonitoring).toHaveBeenCalledWith(2_000);
     expect(mocks.closeErrorMonitoring.mock.invocationCallOrder[0]).toBeLessThan(

package/src/server.ts

@@ -1,4 +1,4 @@
-import {captureException, closeErrorMonitoring} from '@shipfox/node-error-monitoring';
+import {closeErrorMonitoring, markErrorReported, reportError} from '@shipfox/node-error-monitoring';
 import {closeApp, createApp, listen} from '@shipfox/node-fastify';
 import {
   aggregateLoginMethods,
@@ -17,6 +17,7 @@ import {logger, shutdownServiceMetrics, startServiceMetrics} from '@shipfox/node
 import {closePostgresClient, createPostgresClient} from '@shipfox/node-postgres';
 import {config, parseApiTrustProxy} from './config.js';
 import {createE2eAdminAuthMethod, createE2eRouteGroup} from './e2e.js';
+import {createLoginMethodsRoute} from './routes/login-methods.js';
 
 const RUNTIME_FAILURE_HTTP_SHUTDOWN_TIMEOUT_MS = 10_000;
 const ERROR_MONITORING_SHUTDOWN_TIMEOUT_MS = 2_000;
@@ -46,7 +47,7 @@ export async function createServer(options: CreateServerOptions): Promise<Server
   hasActiveServer = true;
 
   try {
-    aggregateLoginMethods({modules: options.modules});
+    const loginMethods = aggregateLoginMethods({modules: options.modules});
     startServiceMetrics({serviceName: 'api'});
     createPostgresClient();
 
@@ -62,7 +63,7 @@ export async function createServer(options: CreateServerOptions): Promise<Server
     logger().info('Creating HTTP server');
     await createApp({
       auth: [...auth, ...e2eAuth],
-      routes: [...routes, ...mountedE2eRoutes],
+      routes: [createLoginMethodsRoute({loginMethods}), ...routes, ...mountedE2eRoutes],
       fastifyOptions: {trustProxy: parseApiTrustProxy(config.API_TRUST_PROXY)},
     });
 
@@ -116,10 +117,24 @@ export async function createServer(options: CreateServerOptions): Promise<Server
             () => workersHandle?.stop(),
             () => shutdownServiceMetrics(),
             () => closePostgresClient(),
-            async () => {
-              await closeErrorMonitoring(ERROR_MONITORING_SHUTDOWN_TIMEOUT_MS);
-            },
           ]);
+          for (const cleanupError of cleanupErrors) {
+            logger().error({err: cleanupError}, 'Failed to clean up API server during shutdown');
+            reportError(cleanupError, {boundary: 'api.shutdown', operation: 'cleanup'});
+          }
+          try {
+            const errorMonitoringClosed = await closeErrorMonitoring(
+              ERROR_MONITORING_SHUTDOWN_TIMEOUT_MS,
+            );
+            if (!errorMonitoringClosed) {
+              logger().error('Timed out closing error monitoring during API shutdown');
+              cleanupErrors.push(
+                new Error('Timed out closing error monitoring during API shutdown'),
+              );
+            }
+          } catch (error) {
+            cleanupErrors.push(error);
+          }
           throwCleanupErrors(cleanupErrors, 'Failed to stop API server');
           stopped = true;
           hasActiveServer = false;
@@ -138,6 +153,7 @@ export async function createServer(options: CreateServerOptions): Promise<Server
     ]);
     for (const cleanupError of cleanupErrors) {
       logger().error({err: cleanupError, bootError: error}, 'Failed to clean up API server boot');
+      reportError(cleanupError, {boundary: 'api.startup', operation: 'cleanup'});
     }
     hasActiveServer = false;
     throw error;
@@ -168,11 +184,23 @@ export async function runServer(options: RunServerOptions): Promise<ServerHandle
         {err: cleanupError, startError: error},
         'Failed to clean up API server startup',
       );
+      reportError(cleanupError, {
+        boundary: 'api.startup',
+        operation: 'cleanup-after-failed-start',
+      });
     }
     throw error;
   }
 
-  const stopAndExit = () => void handle.stop().finally(() => process.exit(0));
+  const stopAndExit = () =>
+    void handle.stop().then(
+      () => process.exit(0),
+      (error) => {
+        logger().error({err: error}, 'Failed to stop API server after shutdown signal');
+        reportError(error, {boundary: 'api.shutdown', operation: 'signal-stop'});
+        process.exit(1);
+      },
+    );
   process.once('SIGTERM', stopAndExit);
   process.once('SIGINT', stopAndExit);
 
@@ -210,7 +238,9 @@ async function runCleanupSteps(steps: CleanupStep[]): Promise<unknown[]> {
 function throwCleanupErrors(cleanupErrors: unknown[], message: string): void {
   if (cleanupErrors.length === 0) return;
   if (cleanupErrors.length === 1) throw cleanupErrors[0];
-  throw new AggregateError(cleanupErrors, message);
+  const aggregate = new AggregateError(cleanupErrors, message);
+  markErrorReported(aggregate);
+  throw aggregate;
 }
 
 async function handleModuleWorkerFailure(
@@ -246,11 +276,19 @@ async function handleModuleRuntimeFailure(options: {
   onFailure(): void | Promise<void>;
 }): Promise<void> {
   logger().error({err: options.error, ...options.fields}, options.message);
-  captureException(options.error);
+  reportError(options.error, {
+    boundary: 'api.runtime',
+    tags: options.fields,
+  });
 
   try {
     await closeHttpServerAfterRuntimeFailure();
-    await closeErrorMonitoring(ERROR_MONITORING_SHUTDOWN_TIMEOUT_MS);
+    const errorMonitoringClosed = await closeErrorMonitoring(ERROR_MONITORING_SHUTDOWN_TIMEOUT_MS);
+    if (!errorMonitoringClosed) {
+      logger().error('Timed out closing error monitoring after module runtime failure');
+    }
+  } catch (error) {
+    logger().error({err: error}, 'Failed to close error monitoring after module runtime failure');
   } finally {
     await options.onFailure();
   }
@@ -270,13 +308,13 @@ async function closeHttpServerAfterRuntimeFailure(): Promise<void> {
       },
     );
     if (result === 'timeout') {
-      logger().error(
-        {timeoutMs: RUNTIME_FAILURE_HTTP_SHUTDOWN_TIMEOUT_MS},
-        'Timed out closing HTTP server after module runtime failure',
-      );
+      const error = new Error('Timed out closing HTTP server after module runtime failure');
+      logger().error({timeoutMs: RUNTIME_FAILURE_HTTP_SHUTDOWN_TIMEOUT_MS}, error.message);
+      reportError(error, {boundary: 'api.runtime', operation: 'close-http-timeout'});
     }
   } catch (error) {
     logger().error({err: error}, 'Failed to close HTTP server after module runtime failure');
+    reportError(error, {boundary: 'api.runtime', operation: 'close-http'});
   } finally {
     if (timeoutId) {
       clearTimeout(timeoutId);