@shipfox/api-server 2.0.0

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+$ shipfox-swc
+Successfully compiled: 6 files with swc (77.53ms)

package/.turbo/turbo-type$colon$emit.log

@@ -0,0 +1 @@
+$ shipfox-tsc-emit

package/.turbo/turbo-type.log

@@ -0,0 +1 @@
+$ shipfox-tsc-check

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# @shipfox/api-server
+
+## 2.0.0
+
+### Minor Changes
+
+- 7fc3ab5: Adds a startup-failure hook so applications can report errors before server cleanup closes monitoring.
+- 521e006: Adds the @shipfox/api-server package with server lifecycle, default module composition, and an
+  instrumentation preload entry, and exposes shutdownServiceMetrics from @shipfox/node-opentelemetry.
+
+### Patch Changes
+
+- Updated dependencies [0cd6dd4]
+- Updated dependencies [c31a7e0]
+- Updated dependencies [1b0d344]
+- Updated dependencies [521e006]
+  - @shipfox/node-module@0.2.0
+  - @shipfox/api-integration-core@2.0.0
+  - @shipfox/api-auth@2.0.0
+  - @shipfox/api-workspaces@2.0.0
+  - @shipfox/annotations@2.0.0
+  - @shipfox/api-agent@2.0.0
+  - @shipfox/api-definitions@2.0.0
+  - @shipfox/api-dispatcher@2.0.0
+  - @shipfox/api-logs@2.0.0
+  - @shipfox/api-projects@2.0.0
+  - @shipfox/api-runners@2.0.0
+  - @shipfox/api-secrets@2.0.0
+  - @shipfox/api-triggers@2.0.0
+  - @shipfox/api-workflows@2.0.0
+  - @shipfox/config@1.2.1
+  - @shipfox/node-error-monitoring@0.1.2
+  - @shipfox/node-fastify@0.2.1
+  - @shipfox/node-opentelemetry@0.5.0
+  - @shipfox/node-postgres@0.4.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shipfox
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# Shipfox API Server
+
+Runs a Shipfox API server.
+
+## What it does
+
+- **`defaultModules()`**: Returns the standard module list.
+- **`createServer()`**: Builds an API server. The caller owns process signals.
+- **`runServer()`**: Starts the server. It listens for SIGTERM and SIGINT.
+- **Instrumentation preload**: Starts metrics early. Load it before feature modules.
+
+## Installation
+
+```sh
+pnpm add @shipfox/api-server
+```
+
+## Usage
+
+```ts
+import {defaultModules, runServer} from '@shipfox/api-server';
+
+await runServer({modules: await defaultModules()});
+```
+
+Load the instrumentation entry before feature modules:
+
+```sh
+node --import @shipfox/api-server/instrumentation ./dist/index.js
+```
+
+## Environment
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `E2E_ENABLED` | `false` | Enables routes under `/__e2e` when `E2E_ADMIN_API_KEY` is set. |
+| `E2E_ADMIN_API_KEY` | none | Required to enable and protect E2E routes. |
+| `API_PORT` | shared `PORT` | Sets the listener port. |
+| `API_TRUST_PROXY` | `false` | Sets proxy IP checks. |
+
+## Behavior Notes
+
+- **Custom composition**: Pass a module list to make a custom server.
+- **Signal handling**: `createServer` does not install signal handlers.
+- **Lifecycle**: `start` starts workers before the HTTP listener. `stop` is safe to call again.
+- **Process scope**: Run one server at a time.
+
+## Development
+
+```sh
+turbo build --filter=@shipfox/api-server
+turbo check --filter=@shipfox/api-server
+turbo type --filter=@shipfox/api-server
+turbo test --filter=@shipfox/api-server
+```
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export type ApiTrustProxy = false | true | number | string;
+export declare const config: Readonly<{
+    E2E_ENABLED: boolean;
+    E2E_ADMIN_API_KEY: string | undefined;
+    API_PORT: number | undefined;
+    API_TRUST_PROXY: string;
+} & import("@shipfox/config").CleanedEnvAccessors>;
+export declare function parseApiTrustProxy(value: string): ApiTrustProxy;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC;AAI3D,eAAO,MAAM,MAAM;;;;;kDAiBjB,CAAC;AAaH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,CAgB/D"}

package/dist/config.js

@@ -0,0 +1,43 @@
+import { isIP } from 'node:net';
+import { bool, createConfig, port, str } from '@shipfox/config';
+const INTEGER_PATTERN = /^\d+$/;
+export const config = createConfig({
+    E2E_ENABLED: bool({
+        desc: 'Enables the end-to-end test routes under /__e2e. Keep it false in production.',
+        default: false
+    }),
+    E2E_ADMIN_API_KEY: str({
+        desc: 'Bearer token that protects the E2E admin routes. Set it when E2E_ENABLED is true.',
+        default: undefined
+    }),
+    API_PORT: port({
+        desc: 'Port the API HTTP server listens on. When unset, the shared PORT setting controls the server port.',
+        default: undefined
+    }),
+    API_TRUST_PROXY: str({
+        desc: 'Controls how the API trusts proxy headers for client IP detection. Use false when clients connect directly, true only when every caller is a trusted proxy, a positive hop count such as 1, or a trusted proxy IP/CIDR such as 10.0.0.0/8.',
+        default: 'false'
+    })
+});
+function parseCidr(value) {
+    const [address, prefix, extra] = value.split('/');
+    if (!address || !prefix || extra !== undefined || isIP(address) === 0) return false;
+    const maxPrefix = isIP(address) === 4 ? 32 : 128;
+    if (!INTEGER_PATTERN.test(prefix)) return false;
+    const prefixNumber = Number(prefix);
+    return prefixNumber >= 0 && prefixNumber <= maxPrefix;
+}
+export function parseApiTrustProxy(value) {
+    const trimmed = value.trim();
+    if (trimmed === 'false') return false;
+    if (trimmed === 'true') return true;
+    if (INTEGER_PATTERN.test(trimmed)) {
+        const hops = Number(trimmed);
+        if (Number.isSafeInteger(hops) && hops > 0) return hops;
+        throw new Error('API_TRUST_PROXY hop count must be a positive safe integer');
+    }
+    if (isIP(trimmed) !== 0 || parseCidr(trimmed)) return trimmed;
+    throw new Error('API_TRUST_PROXY must be false, true, a positive hop count, or a trusted proxy IP/CIDR');
+}
+
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts"],"sourcesContent":["import {isIP} from 'node:net';\nimport {bool, createConfig, port, str} from '@shipfox/config';\n\nexport type ApiTrustProxy = false | true | number | string;\n\nconst INTEGER_PATTERN = /^\\d+$/;\n\nexport const config = createConfig({\n  E2E_ENABLED: bool({\n    desc: 'Enables the end-to-end test routes under /__e2e. Keep it false in production.',\n    default: false,\n  }),\n  E2E_ADMIN_API_KEY: str({\n    desc: 'Bearer token that protects the E2E admin routes. Set it when E2E_ENABLED is true.',\n    default: undefined,\n  }),\n  API_PORT: port({\n    desc: 'Port the API HTTP server listens on. When unset, the shared PORT setting controls the server port.',\n    default: undefined,\n  }),\n  API_TRUST_PROXY: str({\n    desc: 'Controls how the API trusts proxy headers for client IP detection. Use false when clients connect directly, true only when every caller is a trusted proxy, a positive hop count such as 1, or a trusted proxy IP/CIDR such as 10.0.0.0/8.',\n    default: 'false',\n  }),\n});\n\nfunction parseCidr(value: string): boolean {\n  const [address, prefix, extra] = value.split('/');\n  if (!address || !prefix || extra !== undefined || isIP(address) === 0) return false;\n\n  const maxPrefix = isIP(address) === 4 ? 32 : 128;\n  if (!INTEGER_PATTERN.test(prefix)) return false;\n\n  const prefixNumber = Number(prefix);\n  return prefixNumber >= 0 && prefixNumber <= maxPrefix;\n}\n\nexport function parseApiTrustProxy(value: string): ApiTrustProxy {\n  const trimmed = value.trim();\n  if (trimmed === 'false') return false;\n  if (trimmed === 'true') return true;\n\n  if (INTEGER_PATTERN.test(trimmed)) {\n    const hops = Number(trimmed);\n    if (Number.isSafeInteger(hops) && hops > 0) return hops;\n    throw new Error('API_TRUST_PROXY hop count must be a positive safe integer');\n  }\n\n  if (isIP(trimmed) !== 0 || parseCidr(trimmed)) return trimmed;\n\n  throw new Error(\n    'API_TRUST_PROXY must be false, true, a positive hop count, or a trusted proxy IP/CIDR',\n  );\n}\n"],"names":["isIP","bool","createConfig","port","str","INTEGER_PATTERN","config","E2E_ENABLED","desc","default","E2E_ADMIN_API_KEY","undefined","API_PORT","API_TRUST_PROXY","parseCidr","value","address","prefix","extra","split","maxPrefix","test","prefixNumber","Number","parseApiTrustProxy","trimmed","trim","hops","isSafeInteger","Error"],"mappings":"AAAA,SAAQA,IAAI,QAAO,WAAW;AAC9B,SAAQC,IAAI,EAAEC,YAAY,EAAEC,IAAI,EAAEC,GAAG,QAAO,kBAAkB;AAI9D,MAAMC,kBAAkB;AAExB,OAAO,MAAMC,SAASJ,aAAa;IACjCK,aAAaN,KAAK;QAChBO,MAAM;QACNC,SAAS;IACX;IACAC,mBAAmBN,IAAI;QACrBI,MAAM;QACNC,SAASE;IACX;IACAC,UAAUT,KAAK;QACbK,MAAM;QACNC,SAASE;IACX;IACAE,iBAAiBT,IAAI;QACnBI,MAAM;QACNC,SAAS;IACX;AACF,GAAG;AAEH,SAASK,UAAUC,KAAa;IAC9B,MAAM,CAACC,SAASC,QAAQC,MAAM,GAAGH,MAAMI,KAAK,CAAC;IAC7C,IAAI,CAACH,WAAW,CAACC,UAAUC,UAAUP,aAAaX,KAAKgB,aAAa,GAAG,OAAO;IAE9E,MAAMI,YAAYpB,KAAKgB,aAAa,IAAI,KAAK;IAC7C,IAAI,CAACX,gBAAgBgB,IAAI,CAACJ,SAAS,OAAO;IAE1C,MAAMK,eAAeC,OAAON;IAC5B,OAAOK,gBAAgB,KAAKA,gBAAgBF;AAC9C;AAEA,OAAO,SAASI,mBAAmBT,KAAa;IAC9C,MAAMU,UAAUV,MAAMW,IAAI;IAC1B,IAAID,YAAY,SAAS,OAAO;IAChC,IAAIA,YAAY,QAAQ,OAAO;IAE/B,IAAIpB,gBAAgBgB,IAAI,CAACI,UAAU;QACjC,MAAME,OAAOJ,OAAOE;QACpB,IAAIF,OAAOK,aAAa,CAACD,SAASA,OAAO,GAAG,OAAOA;QACnD,MAAM,IAAIE,MAAM;IAClB;IAEA,IAAI7B,KAAKyB,aAAa,KAAKX,UAAUW,UAAU,OAAOA;IAEtD,MAAM,IAAII,MACR;AAEJ"}

package/dist/e2e.d.ts

@@ -0,0 +1,10 @@
+import { type AuthMethod, type RouteExport, type RouteGroup } from '@shipfox/node-fastify';
+export declare const AUTH_E2E_ADMIN = "e2e-admin";
+export interface E2eConfig {
+    E2E_ENABLED: boolean;
+    E2E_ADMIN_API_KEY?: string | undefined;
+}
+export declare function shouldMountE2eRoutes(config: E2eConfig): boolean;
+export declare function createE2eAdminAuthMethod(config: E2eConfig): AuthMethod;
+export declare function createE2eRouteGroup(routes: RouteExport[], config: E2eConfig): RouteGroup[];
+//# sourceMappingURL=e2e.d.ts.map

package/dist/e2e.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"e2e.d.ts","sourceRoot":"","sources":["../src/e2e.ts"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,UAAU,EAEf,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,uBAAuB,CAAC;AAE/B,eAAO,MAAM,cAAc,cAAc,CAAC;AAE1C,MAAM,WAAW,SAAS;IACxB,WAAW,EAAE,OAAO,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAID,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAE/D;AAcD,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,SAAS,GAAG,UAAU,CAetE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,MAAM,EAAE,SAAS,GAAG,UAAU,EAAE,CAU1F"}

package/dist/e2e.js

@@ -0,0 +1,42 @@
+import { timingSafeEqual } from 'node:crypto';
+import { ClientError } from '@shipfox/node-fastify';
+export const AUTH_E2E_ADMIN = 'e2e-admin';
+const BEARER_RE = /^Bearer /iu;
+export function shouldMountE2eRoutes(config) {
+    return config.E2E_ENABLED && Boolean(config.E2E_ADMIN_API_KEY);
+}
+function extractBearerToken(header) {
+    return header?.replace(BEARER_RE, '');
+}
+function tokensMatch(actual, expected) {
+    const actualBuffer = Buffer.from(actual);
+    const expectedBuffer = Buffer.from(expected);
+    return actualBuffer.length === expectedBuffer.length && timingSafeEqual(actualBuffer, expectedBuffer);
+}
+export function createE2eAdminAuthMethod(config) {
+    return {
+        name: AUTH_E2E_ADMIN,
+        authenticate: async (request)=>{
+            await Promise.resolve();
+            const expected = config.E2E_ADMIN_API_KEY;
+            const actual = extractBearerToken(request.headers.authorization);
+            if (!expected || !actual || !tokensMatch(actual, expected)) {
+                throw new ClientError('Missing or invalid E2E admin API key', 'unauthorized', {
+                    status: 401
+                });
+            }
+        }
+    };
+}
+export function createE2eRouteGroup(routes, config) {
+    if (!shouldMountE2eRoutes(config) || routes.length === 0) return [];
+    return [
+        {
+            prefix: '/__e2e',
+            auth: AUTH_E2E_ADMIN,
+            routes
+        }
+    ];
+}
+
+//# sourceMappingURL=e2e.js.map

package/dist/e2e.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/e2e.ts"],"sourcesContent":["import {timingSafeEqual} from 'node:crypto';\nimport {\n  type AuthMethod,\n  ClientError,\n  type RouteExport,\n  type RouteGroup,\n} from '@shipfox/node-fastify';\n\nexport const AUTH_E2E_ADMIN = 'e2e-admin';\n\nexport interface E2eConfig {\n  E2E_ENABLED: boolean;\n  E2E_ADMIN_API_KEY?: string | undefined;\n}\n\nconst BEARER_RE = /^Bearer /iu;\n\nexport function shouldMountE2eRoutes(config: E2eConfig): boolean {\n  return config.E2E_ENABLED && Boolean(config.E2E_ADMIN_API_KEY);\n}\n\nfunction extractBearerToken(header: string | undefined): string | undefined {\n  return header?.replace(BEARER_RE, '');\n}\n\nfunction tokensMatch(actual: string, expected: string): boolean {\n  const actualBuffer = Buffer.from(actual);\n  const expectedBuffer = Buffer.from(expected);\n  return (\n    actualBuffer.length === expectedBuffer.length && timingSafeEqual(actualBuffer, expectedBuffer)\n  );\n}\n\nexport function createE2eAdminAuthMethod(config: E2eConfig): AuthMethod {\n  return {\n    name: AUTH_E2E_ADMIN,\n    authenticate: async (request) => {\n      await Promise.resolve();\n      const expected = config.E2E_ADMIN_API_KEY;\n      const actual = extractBearerToken(request.headers.authorization);\n\n      if (!expected || !actual || !tokensMatch(actual, expected)) {\n        throw new ClientError('Missing or invalid E2E admin API key', 'unauthorized', {\n          status: 401,\n        });\n      }\n    },\n  };\n}\n\nexport function createE2eRouteGroup(routes: RouteExport[], config: E2eConfig): RouteGroup[] {\n  if (!shouldMountE2eRoutes(config) || routes.length === 0) return [];\n\n  return [\n    {\n      prefix: '/__e2e',\n      auth: AUTH_E2E_ADMIN,\n      routes,\n    },\n  ];\n}\n"],"names":["timingSafeEqual","ClientError","AUTH_E2E_ADMIN","BEARER_RE","shouldMountE2eRoutes","config","E2E_ENABLED","Boolean","E2E_ADMIN_API_KEY","extractBearerToken","header","replace","tokensMatch","actual","expected","actualBuffer","Buffer","from","expectedBuffer","length","createE2eAdminAuthMethod","name","authenticate","request","Promise","resolve","headers","authorization","status","createE2eRouteGroup","routes","prefix","auth"],"mappings":"AAAA,SAAQA,eAAe,QAAO,cAAc;AAC5C,SAEEC,WAAW,QAGN,wBAAwB;AAE/B,OAAO,MAAMC,iBAAiB,YAAY;AAO1C,MAAMC,YAAY;AAElB,OAAO,SAASC,qBAAqBC,MAAiB;IACpD,OAAOA,OAAOC,WAAW,IAAIC,QAAQF,OAAOG,iBAAiB;AAC/D;AAEA,SAASC,mBAAmBC,MAA0B;IACpD,OAAOA,QAAQC,QAAQR,WAAW;AACpC;AAEA,SAASS,YAAYC,MAAc,EAAEC,QAAgB;IACnD,MAAMC,eAAeC,OAAOC,IAAI,CAACJ;IACjC,MAAMK,iBAAiBF,OAAOC,IAAI,CAACH;IACnC,OACEC,aAAaI,MAAM,KAAKD,eAAeC,MAAM,IAAInB,gBAAgBe,cAAcG;AAEnF;AAEA,OAAO,SAASE,yBAAyBf,MAAiB;IACxD,OAAO;QACLgB,MAAMnB;QACNoB,cAAc,OAAOC;YACnB,MAAMC,QAAQC,OAAO;YACrB,MAAMX,WAAWT,OAAOG,iBAAiB;YACzC,MAAMK,SAASJ,mBAAmBc,QAAQG,OAAO,CAACC,aAAa;YAE/D,IAAI,CAACb,YAAY,CAACD,UAAU,CAACD,YAAYC,QAAQC,WAAW;gBAC1D,MAAM,IAAIb,YAAY,wCAAwC,gBAAgB;oBAC5E2B,QAAQ;gBACV;YACF;QACF;IACF;AACF;AAEA,OAAO,SAASC,oBAAoBC,MAAqB,EAAEzB,MAAiB;IAC1E,IAAI,CAACD,qBAAqBC,WAAWyB,OAAOX,MAAM,KAAK,GAAG,OAAO,EAAE;IAEnE,OAAO;QACL;YACEY,QAAQ;YACRC,MAAM9B;YACN4B;QACF;KACD;AACH"}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { defaultModules } from './modules.js';
+export type { CreateServerOptions, RunServerOptions, ServerHandle } from './server.js';
+export { createServer, runServer } from './server.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAC,cAAc,EAAC,MAAM,cAAc,CAAC;AAC5C,YAAY,EAAC,mBAAmB,EAAE,gBAAgB,EAAE,YAAY,EAAC,MAAM,aAAa,CAAC;AACrF,OAAO,EAAC,YAAY,EAAE,SAAS,EAAC,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { defaultModules } from './modules.js';
+export { createServer, runServer } from './server.js';
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["export {defaultModules} from './modules.js';\nexport type {CreateServerOptions, RunServerOptions, ServerHandle} from './server.js';\nexport {createServer, runServer} from './server.js';\n"],"names":["defaultModules","createServer","runServer"],"mappings":"AAAA,SAAQA,cAAc,QAAO,eAAe;AAE5C,SAAQC,YAAY,EAAEC,SAAS,QAAO,cAAc"}

package/dist/instrumentation.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=instrumentation.d.ts.map

package/dist/instrumentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instrumentation.d.ts","sourceRoot":"","sources":["../src/instrumentation.ts"],"names":[],"mappings":""}

package/dist/instrumentation.js

@@ -0,0 +1,13 @@
+import { startInstanceInstrumentation } from '@shipfox/node-opentelemetry';
+// 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
+    }
+});
+
+//# sourceMappingURL=instrumentation.js.map

package/dist/instrumentation.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/instrumentation.ts"],"sourcesContent":["import {startInstanceInstrumentation} from '@shipfox/node-opentelemetry';\n\n// The metrics API has no proxy meter: instruments created before this preload\n// completes bind to a no-op provider for the process lifetime.\nawait startInstanceInstrumentation({\n  serviceName: 'api',\n  instrumentations: {fastify: true, http: true, pg: true},\n});\n"],"names":["startInstanceInstrumentation","serviceName","instrumentations","fastify","http","pg"],"mappings":"AAAA,SAAQA,4BAA4B,QAAO,8BAA8B;AAEzE,8EAA8E;AAC9E,+DAA+D;AAC/D,MAAMA,6BAA6B;IACjCC,aAAa;IACbC,kBAAkB;QAACC,SAAS;QAAMC,MAAM;QAAMC,IAAI;IAAI;AACxD"}

package/dist/modules.d.ts

@@ -0,0 +1,3 @@
+import type { ShipfoxModule } from '@shipfox/node-module';
+export declare function defaultModules(): Promise<ShipfoxModule[]>;
+//# sourceMappingURL=modules.d.ts.map

package/dist/modules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modules.d.ts","sourceRoot":"","sources":["../src/modules.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,sBAAsB,CAAC;AAExD,wBAAsB,cAAc,IAAI,OAAO,CAAC,aAAa,EAAE,CAAC,CA+D/D"}

package/dist/modules.js

@@ -0,0 +1,76 @@
+import { annotationsModule } from '@shipfox/annotations';
+import { agentModule } from '@shipfox/api-agent';
+import { authModule } from '@shipfox/api-auth';
+import { createDefinitionsModule } from '@shipfox/api-definitions';
+import { dispatcherModule } from '@shipfox/api-dispatcher';
+import { buildAgentToolCatalogs, buildAgentToolSelectionCatalogs, createIntegrationsContext, createWorkspaceConnectionSnapshotLoader, getIntegrationConnectionById } from '@shipfox/api-integration-core';
+import { logsModule } from '@shipfox/api-logs';
+import { createProjectsModule } from '@shipfox/api-projects';
+import { runnersModule } from '@shipfox/api-runners';
+import { deleteSecrets, getSecret, secretsModule, setSecrets } from '@shipfox/api-secrets';
+import { triggersModule } from '@shipfox/api-triggers';
+import { loadRunningLeasedStep, setAgentToolMaterializationServices, setSourceControl, workflowsModule } from '@shipfox/api-workflows';
+import { workspacesModule } from '@shipfox/api-workspaces';
+export async function defaultModules() {
+    const integrations = await createIntegrationsContext({
+        secrets: {
+            deleteSecrets,
+            linear: {
+                getSecret: (params)=>getSecret({
+                        ...params,
+                        namespace: `system/integrations/linear/${params.namespace}`
+                    }),
+                setSecrets: (params)=>setSecrets({
+                        ...params,
+                        namespace: `system/integrations/linear/${params.namespace}`
+                    }),
+                deleteSecrets: (params)=>deleteSecrets({
+                        ...params,
+                        namespace: `system/integrations/linear/${params.namespace}`
+                    })
+            }
+        },
+        agentTools: {
+            loadLeasedAgentStep: loadRunningLeasedStep
+        }
+    });
+    const [agentToolSelectionCatalogs, agentToolCatalogs] = await Promise.all([
+        buildAgentToolSelectionCatalogs(integrations.registry),
+        buildAgentToolCatalogs(integrations.registry)
+    ]);
+    const loadWorkspaceConnectionSnapshot = createWorkspaceConnectionSnapshotLoader(integrations.registry);
+    // The checkout-token route resolves intents and mints credentials through the
+    // source-control service; wire it into the workflows module before serving.
+    setSourceControl(integrations.sourceControl);
+    setAgentToolMaterializationServices({
+        catalogs: agentToolCatalogs,
+        loadWorkspaceConnectionSnapshot,
+        getIntegrationConnectionById
+    });
+    const projectsModule = createProjectsModule({
+        sourceControl: integrations.sourceControl
+    });
+    const definitionsModule = createDefinitionsModule({
+        sourceControl: integrations.sourceControl,
+        agentToolSelectionCatalogs,
+        loadWorkspaceConnectionSnapshot,
+        getIntegrationConnectionById
+    });
+    return [
+        authModule,
+        workspacesModule,
+        secretsModule,
+        agentModule,
+        integrations.module,
+        projectsModule,
+        definitionsModule,
+        workflowsModule,
+        annotationsModule,
+        runnersModule,
+        logsModule,
+        triggersModule,
+        dispatcherModule
+    ];
+}
+
+//# sourceMappingURL=modules.js.map

package/dist/modules.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/modules.ts"],"sourcesContent":["import {annotationsModule} from '@shipfox/annotations';\nimport {agentModule} from '@shipfox/api-agent';\nimport {authModule} from '@shipfox/api-auth';\nimport {createDefinitionsModule} from '@shipfox/api-definitions';\nimport {dispatcherModule} from '@shipfox/api-dispatcher';\nimport {\n  buildAgentToolCatalogs,\n  buildAgentToolSelectionCatalogs,\n  createIntegrationsContext,\n  createWorkspaceConnectionSnapshotLoader,\n  getIntegrationConnectionById,\n} from '@shipfox/api-integration-core';\nimport {logsModule} from '@shipfox/api-logs';\nimport {createProjectsModule} from '@shipfox/api-projects';\nimport {runnersModule} from '@shipfox/api-runners';\nimport {deleteSecrets, getSecret, secretsModule, setSecrets} from '@shipfox/api-secrets';\nimport {triggersModule} from '@shipfox/api-triggers';\nimport {\n  loadRunningLeasedStep,\n  setAgentToolMaterializationServices,\n  setSourceControl,\n  workflowsModule,\n} from '@shipfox/api-workflows';\nimport {workspacesModule} from '@shipfox/api-workspaces';\nimport type {ShipfoxModule} from '@shipfox/node-module';\n\nexport async function defaultModules(): Promise<ShipfoxModule[]> {\n  const integrations = await createIntegrationsContext({\n    secrets: {\n      deleteSecrets,\n      linear: {\n        getSecret: (params) =>\n          getSecret({\n            ...params,\n            namespace: `system/integrations/linear/${params.namespace}`,\n          }),\n        setSecrets: (params) =>\n          setSecrets({\n            ...params,\n            namespace: `system/integrations/linear/${params.namespace}`,\n          }),\n        deleteSecrets: (params) =>\n          deleteSecrets({\n            ...params,\n            namespace: `system/integrations/linear/${params.namespace}`,\n          }),\n      },\n    },\n    agentTools: {loadLeasedAgentStep: loadRunningLeasedStep},\n  });\n  const [agentToolSelectionCatalogs, agentToolCatalogs] = await Promise.all([\n    buildAgentToolSelectionCatalogs(integrations.registry),\n    buildAgentToolCatalogs(integrations.registry),\n  ]);\n  const loadWorkspaceConnectionSnapshot = createWorkspaceConnectionSnapshotLoader(\n    integrations.registry,\n  );\n\n  // The checkout-token route resolves intents and mints credentials through the\n  // source-control service; wire it into the workflows module before serving.\n  setSourceControl(integrations.sourceControl);\n  setAgentToolMaterializationServices({\n    catalogs: agentToolCatalogs,\n    loadWorkspaceConnectionSnapshot,\n    getIntegrationConnectionById,\n  });\n  const projectsModule = createProjectsModule({sourceControl: integrations.sourceControl});\n  const definitionsModule = createDefinitionsModule({\n    sourceControl: integrations.sourceControl,\n    agentToolSelectionCatalogs,\n    loadWorkspaceConnectionSnapshot,\n    getIntegrationConnectionById,\n  });\n\n  return [\n    authModule,\n    workspacesModule,\n    secretsModule,\n    agentModule,\n    integrations.module,\n    projectsModule,\n    definitionsModule,\n    workflowsModule,\n    annotationsModule,\n    runnersModule,\n    logsModule,\n    triggersModule,\n    dispatcherModule,\n  ];\n}\n"],"names":["annotationsModule","agentModule","authModule","createDefinitionsModule","dispatcherModule","buildAgentToolCatalogs","buildAgentToolSelectionCatalogs","createIntegrationsContext","createWorkspaceConnectionSnapshotLoader","getIntegrationConnectionById","logsModule","createProjectsModule","runnersModule","deleteSecrets","getSecret","secretsModule","setSecrets","triggersModule","loadRunningLeasedStep","setAgentToolMaterializationServices","setSourceControl","workflowsModule","workspacesModule","defaultModules","integrations","secrets","linear","params","namespace","agentTools","loadLeasedAgentStep","agentToolSelectionCatalogs","agentToolCatalogs","Promise","all","registry","loadWorkspaceConnectionSnapshot","sourceControl","catalogs","projectsModule","definitionsModule","module"],"mappings":"AAAA,SAAQA,iBAAiB,QAAO,uBAAuB;AACvD,SAAQC,WAAW,QAAO,qBAAqB;AAC/C,SAAQC,UAAU,QAAO,oBAAoB;AAC7C,SAAQC,uBAAuB,QAAO,2BAA2B;AACjE,SAAQC,gBAAgB,QAAO,0BAA0B;AACzD,SACEC,sBAAsB,EACtBC,+BAA+B,EAC/BC,yBAAyB,EACzBC,uCAAuC,EACvCC,4BAA4B,QACvB,gCAAgC;AACvC,SAAQC,UAAU,QAAO,oBAAoB;AAC7C,SAAQC,oBAAoB,QAAO,wBAAwB;AAC3D,SAAQC,aAAa,QAAO,uBAAuB;AACnD,SAAQC,aAAa,EAAEC,SAAS,EAAEC,aAAa,EAAEC,UAAU,QAAO,uBAAuB;AACzF,SAAQC,cAAc,QAAO,wBAAwB;AACrD,SACEC,qBAAqB,EACrBC,mCAAmC,EACnCC,gBAAgB,EAChBC,eAAe,QACV,yBAAyB;AAChC,SAAQC,gBAAgB,QAAO,0BAA0B;AAGzD,OAAO,eAAeC;IACpB,MAAMC,eAAe,MAAMjB,0BAA0B;QACnDkB,SAAS;YACPZ;YACAa,QAAQ;gBACNZ,WAAW,CAACa,SACVb,UAAU;wBACR,GAAGa,MAAM;wBACTC,WAAW,CAAC,2BAA2B,EAAED,OAAOC,SAAS,EAAE;oBAC7D;gBACFZ,YAAY,CAACW,SACXX,WAAW;wBACT,GAAGW,MAAM;wBACTC,WAAW,CAAC,2BAA2B,EAAED,OAAOC,SAAS,EAAE;oBAC7D;gBACFf,eAAe,CAACc,SACdd,cAAc;wBACZ,GAAGc,MAAM;wBACTC,WAAW,CAAC,2BAA2B,EAAED,OAAOC,SAAS,EAAE;oBAC7D;YACJ;QACF;QACAC,YAAY;YAACC,qBAAqBZ;QAAqB;IACzD;IACA,MAAM,CAACa,4BAA4BC,kBAAkB,GAAG,MAAMC,QAAQC,GAAG,CAAC;QACxE5B,gCAAgCkB,aAAaW,QAAQ;QACrD9B,uBAAuBmB,aAAaW,QAAQ;KAC7C;IACD,MAAMC,kCAAkC5B,wCACtCgB,aAAaW,QAAQ;IAGvB,8EAA8E;IAC9E,4EAA4E;IAC5Ef,iBAAiBI,aAAaa,aAAa;IAC3ClB,oCAAoC;QAClCmB,UAAUN;QACVI;QACA3B;IACF;IACA,MAAM8B,iBAAiB5B,qBAAqB;QAAC0B,eAAeb,aAAaa,aAAa;IAAA;IACtF,MAAMG,oBAAoBrC,wBAAwB;QAChDkC,eAAeb,aAAaa,aAAa;QACzCN;QACAK;QACA3B;IACF;IAEA,OAAO;QACLP;QACAoB;QACAP;QACAd;QACAuB,aAAaiB,MAAM;QACnBF;QACAC;QACAnB;QACArB;QACAY;QACAF;QACAO;QACAb;KACD;AACH"}

package/dist/server.d.ts

@@ -0,0 +1,16 @@
+import { type ModuleWorker, type ShipfoxModule } from '@shipfox/node-module';
+export interface CreateServerOptions {
+    modules: ShipfoxModule[];
+    onWorkerFailure?: (error: unknown, worker: ModuleWorker) => void | Promise<void>;
+}
+export interface ServerHandle {
+    start(): Promise<string>;
+    stop(): Promise<void>;
+}
+export interface RunServerOptions {
+    modules: ShipfoxModule[];
+    onStartupFailure?: (error: unknown) => void | Promise<void>;
+}
+export declare function createServer(options: CreateServerOptions): Promise<ServerHandle>;
+export declare function runServer(options: RunServerOptions): Promise<ServerHandle>;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,YAAY,EAMjB,KAAK,aAAa,EAEnB,MAAM,sBAAsB,CAAC;AAW9B,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClF;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACzB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D;AAED,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,YAAY,CAAC,CA2FtF;AAED,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,YAAY,CAAC,CAgChF"}

package/dist/server.js

@@ -0,0 +1,215 @@
+import { captureException, closeErrorMonitoring } from '@shipfox/node-error-monitoring';
+import { closeApp, createApp, listen } from '@shipfox/node-fastify';
+import { initializeModules, registerModuleMetrics, resetPublishers, resetSubscribers, runModuleStartupTasks, startModuleWorkers } from '@shipfox/node-module';
+import { logger, shutdownServiceMetrics, startServiceMetrics } from '@shipfox/node-opentelemetry';
+import { closePostgresClient, createPostgresClient } from '@shipfox/node-postgres';
+import { config, parseApiTrustProxy } from './config.js';
+import { createE2eAdminAuthMethod, createE2eRouteGroup } from './e2e.js';
+const WORKER_FAILURE_HTTP_SHUTDOWN_TIMEOUT_MS = 10_000;
+const ERROR_MONITORING_SHUTDOWN_TIMEOUT_MS = 2_000;
+let hasActiveServer = false;
+export async function createServer(options) {
+    if (hasActiveServer) {
+        throw new Error('Cannot create a second API server before the existing server stops');
+    }
+    hasActiveServer = true;
+    try {
+        startServiceMetrics({
+            serviceName: 'api'
+        });
+        createPostgresClient();
+        const { auth, routes, e2eRoutes, workers } = await initializeModules({
+            modules: options.modules
+        });
+        registerModuleMetrics({
+            modules: options.modules
+        });
+        await runModuleStartupTasks({
+            modules: options.modules
+        });
+        const e2eAuth = config.E2E_ENABLED ? [
+            createE2eAdminAuthMethod(config)
+        ] : [];
+        const mountedE2eRoutes = createE2eRouteGroup(e2eRoutes, config);
+        logger().info('Creating HTTP server');
+        await createApp({
+            auth: [
+                ...auth,
+                ...e2eAuth
+            ],
+            routes: [
+                ...routes,
+                ...mountedE2eRoutes
+            ],
+            fastifyOptions: {
+                trustProxy: parseApiTrustProxy(config.API_TRUST_PROXY)
+            }
+        });
+        let workersHandle;
+        let startPromise;
+        let stopPromise;
+        let stopped = false;
+        const start = ()=>{
+            if (stopPromise || stopped) return Promise.reject(new Error('Cannot start a stopped API server'));
+            startPromise ??= (async ()=>{
+                logger().info('Starting module workers');
+                workersHandle = await startModuleWorkers({
+                    workers,
+                    onWorkerFailure: (error, worker)=>handleModuleWorkerFailure(error, worker, options.onWorkerFailure)
+                });
+                if (stopPromise) throw new Error('API server stopped during startup');
+                logger().info('Starting HTTP server');
+                const address = config.API_PORT === undefined ? await listen() : await listen({
+                    port: config.API_PORT
+                });
+                logger().info({
+                    address
+                }, 'HTTP server listening');
+                return address;
+            })();
+            return startPromise;
+        };
+        const stop = ()=>{
+            if (stopped) return Promise.resolve();
+            stopPromise ??= (async ()=>{
+                try {
+                    await startPromise?.catch(()=>undefined);
+                    const cleanupErrors = await runCleanupSteps([
+                        ()=>closeApp(),
+                        ()=>workersHandle?.stop(),
+                        ()=>shutdownServiceMetrics(),
+                        ()=>closePostgresClient(),
+                        ()=>resetPublishers(),
+                        ()=>resetSubscribers(),
+                        ()=>closeErrorMonitoring(ERROR_MONITORING_SHUTDOWN_TIMEOUT_MS)
+                    ]);
+                    throwCleanupErrors(cleanupErrors, 'Failed to stop API server');
+                    stopped = true;
+                    hasActiveServer = false;
+                } finally{
+                    stopPromise = undefined;
+                }
+            })();
+            return stopPromise;
+        };
+        return {
+            start,
+            stop
+        };
+    } catch (error) {
+        const cleanupErrors = await runCleanupSteps([
+            ()=>shutdownServiceMetrics(),
+            ()=>closePostgresClient(),
+            ()=>resetPublishers(),
+            ()=>resetSubscribers()
+        ]);
+        for (const cleanupError of cleanupErrors){
+            logger().error({
+                err: cleanupError,
+                bootError: error
+            }, 'Failed to clean up API server boot');
+        }
+        hasActiveServer = false;
+        throw error;
+    }
+}
+export async function runServer(options) {
+    let handle;
+    try {
+        handle = await createServer({
+            modules: options.modules,
+            onWorkerFailure: ()=>process.exit(1)
+        });
+    } catch (error) {
+        await reportStartupFailure(error, options.onStartupFailure);
+        throw error;
+    }
+    try {
+        await handle.start();
+    } catch (error) {
+        await reportStartupFailure(error, options.onStartupFailure);
+        try {
+            await handle.stop();
+        } catch (cleanupError) {
+            logger().error({
+                err: cleanupError,
+                startError: error
+            }, 'Failed to clean up API server startup');
+        }
+        throw error;
+    }
+    const stopAndExit = ()=>void handle.stop().finally(()=>process.exit(0));
+    process.once('SIGTERM', stopAndExit);
+    process.once('SIGINT', stopAndExit);
+    return handle;
+}
+async function reportStartupFailure(error, onStartupFailure) {
+    try {
+        await onStartupFailure?.(error);
+    } catch (reportingError) {
+        logger().error({
+            err: reportingError,
+            startError: error
+        }, 'Failed to report API server startup error');
+    }
+}
+async function runCleanupSteps(steps) {
+    const cleanupErrors = [];
+    for (const step of steps){
+        try {
+            await step();
+        } catch (error) {
+            cleanupErrors.push(error);
+        }
+    }
+    return cleanupErrors;
+}
+function throwCleanupErrors(cleanupErrors, message) {
+    if (cleanupErrors.length === 0) return;
+    if (cleanupErrors.length === 1) throw cleanupErrors[0];
+    throw new AggregateError(cleanupErrors, message);
+}
+async function handleModuleWorkerFailure(error, worker, onWorkerFailure) {
+    logger().error({
+        err: error,
+        taskQueue: worker.taskQueue
+    }, 'Module worker stopped unexpectedly');
+    captureException(error);
+    try {
+        await closeHttpServerAfterWorkerFailure();
+        await closeErrorMonitoring(ERROR_MONITORING_SHUTDOWN_TIMEOUT_MS);
+    } finally{
+        await onWorkerFailure?.(error, worker);
+    }
+}
+async function closeHttpServerAfterWorkerFailure() {
+    let timeoutId;
+    const timeout = new Promise((resolve)=>{
+        timeoutId = setTimeout(()=>resolve('timeout'), WORKER_FAILURE_HTTP_SHUTDOWN_TIMEOUT_MS);
+    });
+    try {
+        const result = await Promise.race([
+            closeApp().then(()=>'closed'),
+            timeout
+        ]).finally(()=>{
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+        });
+        if (result === 'timeout') {
+            logger().error({
+                timeoutMs: WORKER_FAILURE_HTTP_SHUTDOWN_TIMEOUT_MS
+            }, 'Timed out closing HTTP server after worker failure');
+        }
+    } catch (error) {
+        logger().error({
+            err: error
+        }, 'Failed to close HTTP server after worker failure');
+    } finally{
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+    }
+}
+
+//# sourceMappingURL=server.js.map