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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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: enabledapplyProxyBypass(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.tsnew file mode 100644index 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.tsindex 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.tsindex 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 {