Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

refactor: add runtime-capability guards and centralize Config (#375)

LoneRifled1943a8ca3f1
diff --git a/server/src/__tests__/db/init-db-options.test.ts b/server/src/__tests__/db/init-db-options.test.ts
new file mode 100644
index 00000000..3fd36e96
--- /dev/null
+++ b/server/src/__tests__/db/init-db-options.test.ts
@@ -0,0 +1,42 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import fs from 'fs';
+import path from 'path';
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+describe('initDb ensureDir option', () => {
+ it('skips mkdirSync when ensureDir is false', async () => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+
+ const mkdirSpy = vi.spyOn(fs, 'mkdirSync');
+
+ vi.resetModules();
+ const { initDb } = await import('../../db/index.js');
+
+ // A non-memory path in a directory that (mocked) doesn't exist; ensureDir:
+ // false means initDb must not check or create the parent directory.
+ const dbPath = path.join('/tmp', `freeapi-missing-${Date.now()}-${Math.random()}`, 'freeapi.db');
+ try { initDb(dbPath, { ensureDir: false }); } catch { /* DB open will fail */ }
+
+ expect(mkdirSpy).not.toHaveBeenCalled();
+ });
+
+ it('calls mkdirSync when ensureDir is true (the default) and dir is absent', async () => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+
+ const mkdirSpy = vi.spyOn(fs, 'mkdirSync').mockImplementation(() => undefined as any);
+ vi.spyOn(fs, 'existsSync').mockReturnValue(false);
+
+ vi.resetModules();
+ const { initDb } = await import('../../db/index.js');
+
+ // A fake on-disk path — existsSync returns false so mkdirSync should be called.
+ const dir = path.join('/tmp', `freeapi-missing-${Date.now()}-${Math.random()}`);
+ const dbPath = path.join(dir, 'freeapi.db');
+ try { initDb(dbPath, { ensureDir: true }); } catch { /* DB open will fail */ }
+
+ expect(mkdirSpy).toHaveBeenCalledWith(dir, { recursive: true });
+ });
+});
diff --git a/server/src/__tests__/lib/config.test.ts b/server/src/__tests__/lib/config.test.ts
new file mode 100644
index 00000000..5bf43189
--- /dev/null
+++ b/server/src/__tests__/lib/config.test.ts
@@ -0,0 +1,62 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { loadConfig } from '../../lib/config.js';
+
+const ENV_KEYS = ['PORT', 'HOST', 'DASHBOARD_ORIGINS', 'CLIENT_DIST', 'PROXY_RATE_LIMIT_RPM', 'NODE_ENV'];
+
+afterEach(() => {
+ ENV_KEYS.forEach(k => delete process.env[k]);
+});
+
+describe('loadConfig', () => {
+ it('returns sensible defaults when no env vars are set', () => {
+ const cfg = loadConfig();
+ expect(cfg.port).toBe(3001);
+ expect(cfg.host).toBe('::');
+ expect(cfg.dashboardOrigins).toEqual([]);
+ expect(cfg.clientDist).toBeNull();
+ expect(cfg.proxyRateLimitRpm).toBe(120);
+ expect(cfg.serveStaticAssets).toBe(true);
+ });
+
+ it('reads PORT and HOST from env', () => {
+ process.env.PORT = '8080';
+ process.env.HOST = '0.0.0.0';
+ const cfg = loadConfig();
+ expect(cfg.port).toBe('8080');
+ expect(cfg.host).toBe('0.0.0.0');
+ });
+
+ it('parses DASHBOARD_ORIGINS as a comma-separated list', () => {
+ process.env.DASHBOARD_ORIGINS = 'http://localhost:3000, http://example.com , ';
+ const cfg = loadConfig();
+ expect(cfg.dashboardOrigins).toEqual(['http://localhost:3000', 'http://example.com']);
+ });
+
+ it('reads CLIENT_DIST from env', () => {
+ process.env.CLIENT_DIST = '/opt/client/dist';
+ const cfg = loadConfig();
+ expect(cfg.clientDist).toBe('/opt/client/dist');
+ });
+
+ it('parses PROXY_RATE_LIMIT_RPM as a number', () => {
+ process.env.PROXY_RATE_LIMIT_RPM = '60';
+ expect(loadConfig().proxyRateLimitRpm).toBe(60);
+ });
+
+ it('falls back to default RPM for invalid PROXY_RATE_LIMIT_RPM', () => {
+ process.env.PROXY_RATE_LIMIT_RPM = 'not-a-number';
+ expect(loadConfig().proxyRateLimitRpm).toBe(120);
+ process.env.PROXY_RATE_LIMIT_RPM = '-5';
+ expect(loadConfig().proxyRateLimitRpm).toBe(120);
+ });
+
+ it('accepts 0 to disable rate limiting', () => {
+ process.env.PROXY_RATE_LIMIT_RPM = '0';
+ expect(loadConfig().proxyRateLimitRpm).toBe(0);
+ });
+
+ it('reads NODE_ENV from env', () => {
+ process.env.NODE_ENV = 'production';
+ expect(loadConfig().nodeEnv).toBe('production');
+ });
+});
diff --git a/server/src/__tests__/lib/process-safety-net.test.ts b/server/src/__tests__/lib/process-safety-net.test.ts
index 2d5b2092..f35d2b34 100644
--- a/server/src/__tests__/lib/process-safety-net.test.ts
+++ b/server/src/__tests__/lib/process-safety-net.test.ts
@@ -4,6 +4,7 @@ import {
classifyProcessError,
handleProcessError,
} from '../../lib/process-safety-net.js';
+import type { SafetyNetHooks } from '../../lib/process-safety-net.js';
describe('isTransportError', () => {
it('matches Node socket error codes', () => {
@@ -47,6 +48,19 @@ describe('classifyProcessError', () => {
});
});
+describe('installProcessSafetyNet', () => {
+ it('skips process.on registration when hasProcessHooks is false', async () => {
+ vi.resetModules();
+ const spy = vi.spyOn(process, 'on');
+ const { installProcessSafetyNet } = await import('../../lib/process-safety-net.js');
+ installProcessSafetyNet({ hasProcessHooks: false } satisfies SafetyNetHooks);
+ expect(spy).not.toHaveBeenCalledWith('uncaughtException', expect.any(Function));
+ expect(spy).not.toHaveBeenCalledWith('unhandledRejection', expect.any(Function));
+ spy.mockRestore();
+ vi.resetModules();
+ });
+});
+
describe('handleProcessError', () => {
it('swallows a transport error without exiting', () => {
const exit = vi.fn();
diff --git a/server/src/app.ts b/server/src/app.ts
index 241b6c47..371eaefb 100644
--- a/server/src/app.ts
+++ b/server/src/app.ts
@@ -20,6 +20,8 @@ import { authRouter } from './routes/auth.js';
import { requireAuth } from './middleware/requireAuth.js';
import { createProxyRateLimiter } from './middleware/rateLimit.js';
import { errorHandler } from './middleware/errorHandler.js';
+import type { Config } from './lib/config.js';
+import { loadConfig } from './lib/config.js';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -29,18 +31,13 @@ const DEFAULT_DASHBOARD_ORIGINS = [
'http://[::1]:5173',
];
-function getAllowedCorsOrigins() {
- const configuredOrigins = (process.env.DASHBOARD_ORIGINS ?? '')
- .split(',')
- .map(origin => origin.trim())
- .filter(Boolean);
-
- return new Set([...DEFAULT_DASHBOARD_ORIGINS, ...configuredOrigins]);
-}
-
-export function createApp() {
+export function createApp(config?: Config) {
+ const cfg = config ?? loadConfig();
const app = express();
- const allowedCorsOrigins = getAllowedCorsOrigins();
+ const allowedCorsOrigins = new Set([
+ ...DEFAULT_DASHBOARD_ORIGINS,
+ ...cfg.dashboardOrigins,
+ ]);
// CSP intentionally disabled — the SPA bundles inline styles and the OG
// image is loaded from the same origin; enabling helmet's default CSP
@@ -79,7 +76,7 @@ export function createApp() {
// OpenAI-compatible proxy. Per-IP rate limiting (#35 item #6) runs first so
// it throttles unauthenticated brute-force / flood attempts before any
// routing work. Tune via PROXY_RATE_LIMIT_RPM; 0 disables it.
- app.use('/v1', createProxyRateLimiter());
+ app.use('/v1', createProxyRateLimiter(cfg.proxyRateLimitRpm));
// Anthropic-compatible Messages API (`POST /v1/messages`, `/count_tokens`) for
// Claude Code and anything else speaking the Anthropic SDK. Mounted BEFORE the
// OpenAI router so it can content-negotiate `GET /v1/models` (Anthropic shape
@@ -101,18 +98,22 @@ export function createApp() {
// Serve client static files (after API error handler). CLIENT_DIST lets
// embedders relocate the built dashboard (e.g. the desktop app ships it in
// extraResources, where the __dirname-relative path can't reach).
- const clientDist = process.env.CLIENT_DIST
- ? path.resolve(process.env.CLIENT_DIST)
- : path.resolve(__dirname, '../../client/dist');
- app.use(express.static(clientDist));
- // SPA fallback — serve index.html for non-API routes
- app.use((req, res, next) => {
- if (req.path.startsWith('/api/') || req.path.startsWith('/v1/')) {
- next();
- return;
- }
- res.sendFile(path.join(clientDist, 'index.html'));
- });
+ // Set serveStaticAssets: false in Config to skip static serving entirely
+ // (e.g. in runtimes that serve assets through a different mechanism).
+ if (cfg.serveStaticAssets) {
+ const clientDist = cfg.clientDist
+ ? path.resolve(cfg.clientDist)
+ : path.resolve(__dirname, '../../client/dist');
+ app.use(express.static(clientDist));
+ // SPA fallback — serve index.html for non-API routes
+ app.use((req, res, next) => {
+ if (req.path.startsWith('/api/') || req.path.startsWith('/v1/')) {
+ next();
+ return;
+ }
+ res.sendFile(path.join(clientDist, 'index.html'));
+ });
+ }
return app;
}
diff --git a/server/src/db/index.ts b/server/src/db/index.ts
index d800c2c4..98f584e2 100644
--- a/server/src/db/index.ts
+++ b/server/src/db/index.ts
@@ -17,11 +17,19 @@ export function getDb(): Database.Database {
return db;
}
-export function connectDb(dbPath?: string): Database.Database {
+export function connectDb(
+ dbPath?: string,
+ opts?: {
+ /** Create the parent directory if absent. Default: true. Set false in
+ * environments that do not have a writable local filesystem. */
+ ensureDir?: boolean;
+ },
+): Database.Database {
const resolvedPath = dbPath ?? DB_PATH;
const isMemory = resolvedPath === ':memory:';
+ const ensureDir = opts?.ensureDir ?? true;
- if (!isMemory) {
+ if (!isMemory && ensureDir) {
const dataDir = path.dirname(resolvedPath);
if (!fs.existsSync(dataDir)) {
fs.mkdirSync(dataDir, { recursive: true });
@@ -36,8 +44,11 @@ export function connectDb(dbPath?: string): Database.Database {
return db;
}
-export function initDb(dbPath?: string): Database.Database {
- const db = connectDb(dbPath);
+export function initDb(
+ dbPath?: string,
+ opts?: { ensureDir?: boolean },
+): Database.Database {
+ const db = connectDb(dbPath, opts);
if (process.env.NODE_ENV !== 'development') {
runMigrationsSync(db, 'up');
diff --git a/server/src/index.ts b/server/src/index.ts
index 436764fc..832512a0 100644
--- a/server/src/index.ts
+++ b/server/src/index.ts
@@ -6,14 +6,12 @@ import { applyProxyUrl, applyProxyEnabled, applyProxyBypass } from './lib/proxy.
import { startCatalogSync } from './services/catalog-sync.js';
import { installProcessSafetyNet } from './lib/process-safety-net.js';
import { NodeScheduler } from './lib/scheduler.js';
-
-const PORT = process.env.PORT ?? 3001;
-// Dual-stack ('::') by default so the dashboard is reachable over both IPv4
-// and IPv6 (e.g. IPv6-enabled Docker networks — #180). Hosts with IPv6
-// disabled fall back to IPv4-only below; HOST overrides the default outright.
-const HOST = process.env.HOST ?? '::';
+import { loadConfig } from './lib/config.js';
async function main() {
+ const config = loadConfig();
+ const { port: PORT, host: HOST } = config;
+
// Install first so a late provider socket reset (undici HTTP/2 error with no
// listener) can't take the proxy down. Genuine bugs still exit 1.
installProcessSafetyNet();
@@ -28,7 +26,7 @@ async function main() {
applyProxyEnabled(getSetting('proxy_enabled') !== '0'); // default: enabled
applyProxyBypass(getSetting('proxy_bypass') ?? '');
- const app = createApp();
+ const app = createApp(config);
const onReady = (host: string) => () => {
const display = host.includes(':') ? `[${host}]` : host;
diff --git a/server/src/lib/config.ts b/server/src/lib/config.ts
new file mode 100644
index 00000000..efb0828c
--- /dev/null
+++ b/server/src/lib/config.ts
@@ -0,0 +1,37 @@
+const DEFAULT_RPM = 120;
+
+function parseRateLimitRpm(): number {
+ const raw = process.env.PROXY_RATE_LIMIT_RPM;
+ if (raw === undefined || raw.trim() === '') return DEFAULT_RPM;
+ const n = Number(raw);
+ if (!Number.isFinite(n) || n < 0) return DEFAULT_RPM;
+ return Math.floor(n);
+}
+
+export interface Config {
+ port: number | string;
+ host: string;
+ dashboardOrigins: string[];
+ clientDist: string | null;
+ proxyRateLimitRpm: number;
+ nodeEnv: string;
+ serveStaticAssets: boolean;
+}
+
+export function loadConfig(): Config {
+ return {
+ port: process.env.PORT ?? 3001,
+ // Dual-stack ('::') by default so the dashboard is reachable over both IPv4
+ // and IPv6 (e.g. IPv6-enabled Docker networks — #180). Hosts with IPv6
+ // disabled fall back to IPv4-only below; HOST overrides the default outright.
+ host: process.env.HOST ?? '::',
+ dashboardOrigins: (process.env.DASHBOARD_ORIGINS ?? '')
+ .split(',')
+ .map(s => s.trim())
+ .filter(Boolean),
+ clientDist: process.env.CLIENT_DIST ?? null,
+ proxyRateLimitRpm: parseRateLimitRpm(),
+ nodeEnv: process.env.NODE_ENV ?? 'development',
+ serveStaticAssets: true,
+ };
+}
diff --git a/server/src/lib/process-safety-net.ts b/server/src/lib/process-safety-net.ts
index b8a54029..cd3d682d 100644
--- a/server/src/lib/process-safety-net.ts
+++ b/server/src/lib/process-safety-net.ts
@@ -72,6 +72,9 @@ function describeError(err: unknown): string {
export interface SafetyNetHooks {
log?: (...args: unknown[]) => void;
exit?: (code: number) => void;
+ /** Set false to skip registering process.on() handlers (e.g. in test environments
+ * or runtimes that do not expose a Node process). Default: true. */
+ hasProcessHooks?: boolean;
}
/** Decide and act on a process-level error. Returns the decision so callers and
@@ -96,10 +99,12 @@ export function handleProcessError(
let installed = false;
/** Install the global handlers once. Idempotent. Call as early as possible at
- * boot (before the server starts taking traffic). */
+ * boot (before the server starts taking traffic). Pass `hasProcessHooks: false`
+ * to skip handler registration without changing other hook behaviour. */
export function installProcessSafetyNet(hooks: SafetyNetHooks = {}): void {
if (installed) return;
installed = true;
+ if (hooks.hasProcessHooks === false) return;
process.on('uncaughtException', (err) => handleProcessError('uncaughtException', err, hooks));
process.on('unhandledRejection', (reason) => handleProcessError('unhandledRejection', reason, hooks));
}
diff --git a/server/src/middleware/rateLimit.ts b/server/src/middleware/rateLimit.ts
index 7090bf3a..e2ba2ea7 100644
--- a/server/src/middleware/rateLimit.ts
+++ b/server/src/middleware/rateLimit.ts
@@ -31,8 +31,8 @@ function parseLimit(): number {
return Math.floor(n);
}
-export function createProxyRateLimiter() {
- const limit = parseLimit();
+export function createProxyRateLimiter(rpmLimit?: number) {
+ const limit = rpmLimit !== undefined ? Math.floor(Math.max(0, rpmLimit)) : parseLimit();
const windows = new Map<string, WindowState>();
return function proxyRateLimit(req: Request, res: Response, next: NextFunction): void {