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
Add catalog controls, persistence backup, and declarative config
Tashfeenf4cd7b4b96b9
diff --git a/.env.example b/.env.exampleindex be3dcfc0..d240ad31 100644--- a/.env.example+++ b/.env.example@@ -20,6 +20,24 @@ PORT=3001REQUEST_ANALYTICS_RETENTION_DAYS=90REQUEST_ANALYTICS_MAX_ROWS=100000+# Optional SQLite location. Useful on hosts where only one directory is mounted+# persistently, or when you want to keep the DB outside server/data.+# FREEAPI_DB_PATH=/app/server/data/freellmapi.db++# Optional encrypted SQLite backup. On startup, FreeLLMAPI restores this backup+# if the configured DB file is missing; while running, it uploads a fresh backup+# periodically. File paths and HTTP(S) URLs are supported.+# FREEAPI_DB_BACKUP_PATH=/app/server/data/freellmapi.db.backup+# FREEAPI_DB_BACKUP_URL=https://example.com/freellmapi.db.backup+# FREEAPI_DB_BACKUP_TOKEN=+# FREEAPI_DB_BACKUP_KEY=use-a-separate-64-char-hex-key-or-omit-to-use-ENCRYPTION_KEY+# FREEAPI_DB_BACKUP_INTERVAL_MS=300000++# Optional declarative startup config. Use either inline JSON or a path to a JSON+# file. It is applied idempotently after migrations on every boot.+# FREEAPI_CONFIG_PATH=/app/server/data/freellmapi.config.json+# FREEAPI_CONFIG_JSON={"keys":[{"platform":"groq","key":"gsk_...","label":"main"}],"routing":{"strategy":"balanced"}}+# Context handoff on model switch. When enabled, FreeLLMAPI injects a compact# system message into the outbound request whenever a session switches from one# model to another (e.g. after a fallback). Off by default.diff --git a/README.md b/README.mdindex d5239bc6..c1c1131d 100644--- a/README.md+++ b/README.md@@ -175,6 +175,42 @@ whichever limit prunes first. Set `REQUEST_ANALYTICS_RETENTION_DAYS=0` orOpen http://localhost:5173 (the Vite dev UI), add your provider keys on the **Keys** page, reorder the **Fallback Chain** to taste, and grab your unified API key from the **Keys** page header. That unified key is what you point your OpenAI SDK at.+### Declarative startup config++For repeatable Docker/server installs, FreeLLMAPI can apply a JSON config on+every boot. Set `FREEAPI_CONFIG_PATH=/path/to/freellmapi.config.json` or put the+same JSON in `FREEAPI_CONFIG_JSON`. The config is idempotent: existing keys,+custom providers, model edits, fallback rows, and routing settings are updated+instead of duplicated.++```json+{+ "keys": [+ { "platform": "groq", "key": "gsk_...", "label": "main" },+ { "platform": "google", "key": "AIza...", "enabled": true }+ ],+ "customProviders": [+ {+ "baseUrl": "http://host.docker.internal:11434/v1",+ "label": "Ollama",+ "models": [+ { "model": "llama3.1:8b", "displayName": "Local Llama", "supportsTools": true }+ ]+ }+ ],+ "models": [+ {+ "platform": "groq",+ "modelId": "llama-3.3-70b-versatile",+ "displayName": "Llama 3.3 70B",+ "supportsTools": true,+ "fallbackEnabled": true+ }+ ],+ "routing": { "strategy": "balanced" }+}+```+> **Reaching the dev UI from another device on your LAN?** Use `npm run dev:lan` — it passes `--host` through to Vite, which then prints a `Network: http://<your-ip>:5173` URL you can open from a phone or another machine. (Plain `npm run dev -- --host` does *not* work here: the root `dev` script is a `concurrently` wrapper, so the flag never reaches Vite.) API calls go through Vite's dev proxy, so no extra server config is needed.For a production build without Docker:@@ -203,7 +239,26 @@ docker compose logs -f freellmapiBy default the container's port is bound to `127.0.0.1` (localhost only). To reach the dashboard/API from another machine on your network, publish it on all interfaces with `HOST_BIND=0.0.0.0 docker compose up -d` — only on a trusted LAN, since the proxy is single-user.-SQLite data is stored in the `freellmapi-data` volume at `/app/server/data`. Keep the same `.env` `ENCRYPTION_KEY` and volume when upgrading, because provider keys are encrypted at rest.+SQLite data is stored in the `freellmapi-data` volume at `/app/server/data`.+Keep the same `.env` `ENCRYPTION_KEY` and volume when upgrading, because+provider keys are encrypted at rest. If your host only persists a specific+directory, set `FREEAPI_DB_PATH=/that/path/freellmapi.db`.++On hosts with ephemeral disks, configure an encrypted backup target:++```env+FREEAPI_DB_BACKUP_PATH=/app/server/data/freellmapi.db.backup+# or:+FREEAPI_DB_BACKUP_URL=https://example.com/freellmapi.db.backup+FREEAPI_DB_BACKUP_TOKEN=optional-bearer-token+FREEAPI_DB_BACKUP_KEY=64-char-hex-backup-key+FREEAPI_DB_BACKUP_INTERVAL_MS=300000+```++When the database file is missing at startup, FreeLLMAPI restores the backup+before migrations run. While the server is running it uploads a fresh encrypted+backup periodically. If `FREEAPI_DB_BACKUP_KEY` is omitted, the app uses+`ENCRYPTION_KEY` for the backup envelope too.More Docker operations and examples live in [docker/README.md](./docker/README.md).diff --git a/client/src/i18n/locales/en.json b/client/src/i18n/locales/en.jsonindex dafb52a5..4d8960c9 100644--- a/client/src/i18n/locales/en.json+++ b/client/src/i18n/locales/en.json@@ -104,6 +104,15 @@"providerIdsHeading": "Provider model ids","providerIdsHint": "Send the unified model id to fail over across every provider, or a provider-specific id to pin one provider.","copyModelName": "Copy model name",+ "settingsHeading": "Provider settings",+ "settingsHint": "Local edits to catalog models are kept across catalog syncs. Deleted catalog models stay deleted until you add them again through config.",+ "catalogModel": "catalog",+ "customModel": "custom",+ "localOverride": "local override",+ "displayName": "Display name",+ "contextWindow": "Context",+ "inFallback": "In chain",+ "saveModelSettings": "Save model settings","aggregateBudget": "{count}/mo","aggregateBudgetTitle": "Total free tokens per month across this model's providers","rateRpm": "{count} RPM",diff --git a/client/src/pages/FallbackPage.tsx b/client/src/pages/FallbackPage.tsxindex 804f178a..16875532 100644--- a/client/src/pages/FallbackPage.tsx+++ b/client/src/pages/FallbackPage.tsx@@ -54,6 +54,10 @@ export interface FallbackEntry {contextWindow?: number | nullsupportsVision: booleansupportsTools: boolean+ source?: 'catalog' | 'custom'+ keyId?: number | null+ keyLabel?: string | null+ hasOverrides?: booleankeyCount: number// Logical-model grouping (sent by the server when unify is relevant). Absent// for ungrouped rows; the UI falls back to a per-row "solo" group then.diff --git a/client/src/pages/ModelDetailPage.tsx b/client/src/pages/ModelDetailPage.tsxindex 578b9708..1285e270 100644--- a/client/src/pages/ModelDetailPage.tsx+++ b/client/src/pages/ModelDetailPage.tsx@@ -1,8 +1,12 @@+import { useEffect, useState } from 'react'import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'import { Link, useParams } from 'react-router-dom'-import { ChevronLeft } from 'lucide-react'+import { ChevronLeft, Save, Trash2 } from 'lucide-react'import { useI18n } from '@/i18n'import { apiFetch } from '@/lib/api'+import { Button } from '@/components/ui/button'+import { Input } from '@/components/ui/input'+import { Switch } from '@/components/ui/switch'import { CopyButton } from '@/components/copy-button'import { Tooltip } from '@/components/tooltip'import { PageHeader } from '@/components/page-header'@@ -16,6 +20,14 @@ import {type Row,} from './FallbackPage'+type ModelSettingsPatch = {+ displayName: string+ contextWindow: number | null+ supportsVision: boolean+ supportsTools: boolean+ fallbackEnabled: boolean+}+// One model's own page: lists every provider that serves it (this model now// fails over across these providers). Reached from the Models list; replaces the// old inline group expansion.@@ -45,6 +57,26 @@ export default function ModelDetailPage() {apiFetch('/api/fallback', { method: 'PUT', body: JSON.stringify(data) }),onSuccess: () => queryClient.invalidateQueries({ queryKey: ['fallback'] }),})+ const modelPatchMutation = useMutation({+ mutationFn: ({ modelDbId, patch }: { modelDbId: number; patch: ModelSettingsPatch }) =>+ apiFetch(`/api/models/${modelDbId}`, {+ method: 'PATCH',+ body: JSON.stringify(patch),+ }),+ onSuccess: () => {+ queryClient.invalidateQueries({ queryKey: ['fallback'] })+ queryClient.invalidateQueries({ queryKey: ['fallback', 'routing'] })+ queryClient.invalidateQueries({ queryKey: ['models'] })+ },+ })+ const modelDeleteMutation = useMutation({+ mutationFn: (modelDbId: number) => apiFetch(`/api/models/${modelDbId}`, { method: 'DELETE' }),+ onSuccess: () => {+ queryClient.invalidateQueries({ queryKey: ['fallback'] })+ queryClient.invalidateQueries({ queryKey: ['fallback', 'routing'] })+ queryClient.invalidateQueries({ queryKey: ['models'] })+ },+ })const isManual = (routing?.strategy ?? 'balanced') === 'priority'const scoreById = new Map((routing?.scores ?? []).map(s => [s.modelDbId, s]))@@ -123,6 +155,25 @@ export default function ModelDetailPage() {</table></div>+ <div className="rounded-2xl border bg-card p-4">+ <div className="mb-3">+ <h2 className="text-sm font-medium">{t('models.settingsHeading')}</h2>+ <p className="mt-0.5 text-xs text-muted-foreground">{t('models.settingsHint')}</p>+ </div>+ <div className="space-y-3">+ {members.map(m => (+ <ProviderSettingsRow+ key={m.modelDbId}+ model={m}+ saving={modelPatchMutation.isPending && modelPatchMutation.variables?.modelDbId === m.modelDbId}+ deleting={modelDeleteMutation.isPending && modelDeleteMutation.variables === m.modelDbId}+ onSave={(patch) => modelPatchMutation.mutate({ modelDbId: m.modelDbId, patch })}+ onDelete={() => modelDeleteMutation.mutate(m.modelDbId)}+ />+ ))}+ </div>+ </div>+{/* The provider-specific model id to send if you want to pin one provider. */}<div className="rounded-2xl border bg-card p-4"><h2 className="text-sm font-medium">{t('models.providerIdsHeading')}</h2>@@ -154,3 +205,137 @@ export default function ModelDetailPage() {</div>)}++function ProviderSettingsRow({+ model,+ saving,+ deleting,+ onSave,+ onDelete,+}: {+ model: Row+ saving: boolean+ deleting: boolean+ onSave: (patch: ModelSettingsPatch) => void+ onDelete: () => void+}) {+ const { t } = useI18n()+ const [displayName, setDisplayName] = useState(model.displayName)+ const [contextWindow, setContextWindow] = useState(model.contextWindow ? String(model.contextWindow) : '')+ const [supportsVision, setSupportsVision] = useState(model.supportsVision)+ const [supportsTools, setSupportsTools] = useState(model.supportsTools)+ const [fallbackEnabled, setFallbackEnabled] = useState(model.enabled)+ const [confirmDelete, setConfirmDelete] = useState(false)++ useEffect(() => {+ setDisplayName(model.displayName)+ setContextWindow(model.contextWindow ? String(model.contextWindow) : '')+ setSupportsVision(model.supportsVision)+ setSupportsTools(model.supportsTools)+ setFallbackEnabled(model.enabled)+ setConfirmDelete(false)+ }, [model.modelDbId, model.displayName, model.contextWindow, model.supportsVision, model.supportsTools, model.enabled])++ useEffect(() => {+ if (!confirmDelete) return+ const timer = window.setTimeout(() => setConfirmDelete(false), 3000)+ return () => window.clearTimeout(timer)+ }, [confirmDelete])++ const parsedContext = contextWindow.trim() === '' ? null : Number(contextWindow)+ const contextInvalid = parsedContext !== null && (!Number.isInteger(parsedContext) || parsedContext <= 0)+ const nameInvalid = displayName.trim().length === 0+ const dirty =+ displayName.trim() !== model.displayName ||+ parsedContext !== (model.contextWindow ?? null) ||+ supportsVision !== model.supportsVision ||+ supportsTools !== model.supportsTools ||+ fallbackEnabled !== model.enabled+ const canSave = dirty && !nameInvalid && !contextInvalid && !saving && !deleting+ const sourceLabel = model.source === 'custom' ? t('models.customModel') : t('models.catalogModel')++ function save() {+ if (!canSave) return+ onSave({+ displayName: displayName.trim(),+ contextWindow: parsedContext,+ supportsVision,+ supportsTools,+ fallbackEnabled,+ })+ }++ function remove() {+ if (!confirmDelete) {+ setConfirmDelete(true)+ return+ }+ onDelete()+ }++ return (+ <div className="rounded-xl border bg-background/60 p-3">+ <div className="mb-3 flex flex-wrap items-center gap-2">+ <span className="text-xs font-medium">{model.platform}</span>+ <code className="min-w-0 truncate font-mono text-[11px] text-muted-foreground">{model.modelId}</code>+ <span className="rounded-full bg-muted px-1.5 py-0.5 text-[10px] text-muted-foreground">{sourceLabel}</span>+ {model.hasOverrides && (+ <span className="rounded-full bg-emerald-600/15 px-1.5 py-0.5 text-[10px] text-emerald-700 dark:text-emerald-400">+ {t('models.localOverride')}+ </span>+ )}+ </div>+ <div className="grid gap-3 md:grid-cols-[minmax(12rem,1fr)_8rem_auto_auto_auto_auto] md:items-end">+ <label className="space-y-1 text-xs text-muted-foreground">+ <span>{t('models.displayName')}</span>+ <Input+ value={displayName}+ onChange={e => setDisplayName(e.target.value)}+ aria-invalid={nameInvalid}+ className="text-sm"+ />+ </label>+ <label className="space-y-1 text-xs text-muted-foreground">+ <span>{t('models.contextWindow')}</span>+ <Input+ type="number"+ min={1}+ step={1}+ value={contextWindow}+ onChange={e => setContextWindow(e.target.value)}+ aria-invalid={contextInvalid}+ className="text-sm tabular-nums"+ />+ </label>+ <label className="flex h-8 items-center gap-2 text-xs">+ <Switch size="sm" checked={supportsTools} onCheckedChange={setSupportsTools} />+ <span>{t('models.tools')}</span>+ </label>+ <label className="flex h-8 items-center gap-2 text-xs">+ <Switch size="sm" checked={supportsVision} onCheckedChange={setSupportsVision} />+ <span>{t('models.vision')}</span>+ </label>+ <label className="flex h-8 items-center gap-2 text-xs">+ <Switch size="sm" checked={fallbackEnabled} onCheckedChange={setFallbackEnabled} />+ <span>{t('models.inFallback')}</span>+ </label>+ <div className="flex items-center justify-end gap-1">+ <Tooltip text={t('models.saveModelSettings')}>+ <Button type="button" size="icon-sm" variant="ghost" disabled={!canSave} onClick={save}>+ <Save className="size-3.5" />+ </Button>+ </Tooltip>+ <Button+ type="button"+ size={confirmDelete ? 'xs' : 'icon-sm'}+ variant="destructive"+ disabled={saving || deleting}+ onClick={remove}+ >+ {confirmDelete ? t('common.confirm') : <Trash2 className="size-3.5" />}+ </Button>+ </div>+ </div>+ </div>+ )+}diff --git a/docker/README.md b/docker/README.mdindex 5be329e4..b7411666 100644--- a/docker/README.md+++ b/docker/README.md@@ -76,9 +76,36 @@ docker compose up -d --build| --- | --- | --- | --- || `ENCRYPTION_KEY` | Yes | None | 64-character hex key used to encrypt provider API keys at rest. Generate it once and keep it stable. || `PORT` | No | `3001` | Host port exposed by Docker Compose. The container listens on port 3001. |+| `FREEAPI_DB_PATH` | No | `/app/server/data/freellmapi.db` | SQLite file path. Set this when your host only persists one mounted directory. |+| `FREEAPI_DB_BACKUP_PATH` | No | None | Local encrypted backup file. Restored on startup if the DB file is missing, then refreshed while the app runs. |+| `FREEAPI_DB_BACKUP_URL` | No | None | HTTP(S) encrypted backup target. Startup uses `GET`; periodic backups use `PUT`. |+| `FREEAPI_DB_BACKUP_TOKEN` | No | None | Optional bearer token for `FREEAPI_DB_BACKUP_URL`. |+| `FREEAPI_DB_BACKUP_KEY` | No | `ENCRYPTION_KEY` | 64-character hex key for backup encryption. Use a separate stable key if possible. |+| `FREEAPI_CONFIG_PATH` | No | None | JSON config file applied idempotently after migrations on every boot. |+| `FREEAPI_CONFIG_JSON` | No | None | Inline JSON config. Takes precedence over `FREEAPI_CONFIG_PATH`. |The `freellmapi-data` volume stores SQLite data at `/app/server/data`. Keep the same volume and `ENCRYPTION_KEY` when upgrading, otherwise existing encrypted provider keys cannot be decrypted.+Example `freellmapi.config.json`:++```json+{+ "keys": [+ { "platform": "groq", "key": "gsk_...", "label": "main" }+ ],+ "customProviders": [+ {+ "baseUrl": "http://host.docker.internal:11434/v1",+ "label": "Ollama",+ "models": [+ { "model": "llama3.1:8b", "displayName": "Local Llama", "supportsTools": true }+ ]+ }+ ],+ "routing": { "strategy": "balanced" }+}+```+## Published ImageImages are published to GitHub Container Registry:diff --git a/server/src/__tests__/db/migrate/roundtrip.test.ts b/server/src/__tests__/db/migrate/roundtrip.test.tsindex e2bd473a..481342d8 100644--- a/server/src/__tests__/db/migrate/roundtrip.test.ts+++ b/server/src/__tests__/db/migrate/roundtrip.test.ts@@ -6,6 +6,7 @@ import { up as runLegacyBaseline } from '../../../db/migrations/20260101_000000_const LEGACY_BASELINE_FILENAME = '20260101_000000_legacy_baseline.ts';const CUSTOM_PROVIDER_MODALITIES_FILENAME = '20260627_000001_custom_provider_modalities.ts';+const CATALOG_MODEL_STATE_FILENAME = '20260627_000002_catalog_model_state.ts';interface SchemaRow {type: string;@@ -58,6 +59,7 @@ describe('migration round trip', () => {expect(getAppliedMigrationNames(db)).toEqual([LEGACY_BASELINE_FILENAME,CUSTOM_PROVIDER_MODALITIES_FILENAME,+ CATALOG_MODEL_STATE_FILENAME,]);} finally {db.close();diff --git a/server/src/__tests__/lib/config.test.ts b/server/src/__tests__/lib/config.test.tsindex 5bf43189..b434dc3c 100644--- a/server/src/__tests__/lib/config.test.ts+++ b/server/src/__tests__/lib/config.test.ts@@ -1,7 +1,7 @@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'];+const ENV_KEYS = ['PORT', 'HOST', 'FREEAPI_DB_PATH', 'DASHBOARD_ORIGINS', 'CLIENT_DIST', 'PROXY_RATE_LIMIT_RPM', 'NODE_ENV'];afterEach(() => {ENV_KEYS.forEach(k => delete process.env[k]);@@ -12,6 +12,7 @@ describe('loadConfig', () => {const cfg = loadConfig();expect(cfg.port).toBe(3001);expect(cfg.host).toBe('::');+ expect(cfg.dbPath).toBeNull();expect(cfg.dashboardOrigins).toEqual([]);expect(cfg.clientDist).toBeNull();expect(cfg.proxyRateLimitRpm).toBe(120);@@ -38,6 +39,11 @@ describe('loadConfig', () => {expect(cfg.clientDist).toBe('/opt/client/dist');});+ it('reads FREEAPI_DB_PATH from env', () => {+ process.env.FREEAPI_DB_PATH = '/data/freeapi.db';+ expect(loadConfig().dbPath).toBe('/data/freeapi.db');+ });+it('parses PROXY_RATE_LIMIT_RPM as a number', () => {process.env.PROXY_RATE_LIMIT_RPM = '60';expect(loadConfig().proxyRateLimitRpm).toBe(60);diff --git a/server/src/__tests__/lib/db-backup.test.ts b/server/src/__tests__/lib/db-backup.test.tsnew file mode 100644index 00000000..2c840772--- /dev/null+++ b/server/src/__tests__/lib/db-backup.test.ts@@ -0,0 +1,54 @@+import fs from 'fs';+import os from 'os';+import path from 'path';+import Database from 'better-sqlite3';+import { afterEach, describe, expect, it } from 'vitest';+import { backupDbNow, restoreDbBackupIfNeeded } from '../../lib/db-backup.js';++const ORIGINAL_BACKUP_PATH = process.env.FREEAPI_DB_BACKUP_PATH;+const ORIGINAL_BACKUP_TARGET = process.env.FREEAPI_DB_BACKUP_TARGET;+const ORIGINAL_BACKUP_URL = process.env.FREEAPI_DB_BACKUP_URL;+const ORIGINAL_BACKUP_KEY = process.env.FREEAPI_DB_BACKUP_KEY;+const ORIGINAL_ENCRYPTION_KEY = process.env.ENCRYPTION_KEY;++function restoreEnv() {+ if (ORIGINAL_BACKUP_PATH === undefined) delete process.env.FREEAPI_DB_BACKUP_PATH;+ else process.env.FREEAPI_DB_BACKUP_PATH = ORIGINAL_BACKUP_PATH;+ if (ORIGINAL_BACKUP_TARGET === undefined) delete process.env.FREEAPI_DB_BACKUP_TARGET;+ else process.env.FREEAPI_DB_BACKUP_TARGET = ORIGINAL_BACKUP_TARGET;+ if (ORIGINAL_BACKUP_URL === undefined) delete process.env.FREEAPI_DB_BACKUP_URL;+ else process.env.FREEAPI_DB_BACKUP_URL = ORIGINAL_BACKUP_URL;+ if (ORIGINAL_BACKUP_KEY === undefined) delete process.env.FREEAPI_DB_BACKUP_KEY;+ else process.env.FREEAPI_DB_BACKUP_KEY = ORIGINAL_BACKUP_KEY;+ if (ORIGINAL_ENCRYPTION_KEY === undefined) delete process.env.ENCRYPTION_KEY;+ else process.env.ENCRYPTION_KEY = ORIGINAL_ENCRYPTION_KEY;+}++describe('encrypted SQLite backup', () => {+ afterEach(() => restoreEnv());++ it('backs up and restores a SQLite file from a configured path', async () => {+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-db-backup-'));+ const dbPath = path.join(dir, 'freeapi.db');+ const backupPath = path.join(dir, 'backup.bin');+ process.env.ENCRYPTION_KEY = 'a'.repeat(64);+ process.env.FREEAPI_DB_BACKUP_PATH = backupPath;++ const db = new Database(dbPath);+ db.exec('CREATE TABLE items (name TEXT NOT NULL); INSERT INTO items (name) VALUES (\'survived\')');+ const backup = await backupDbNow(db, dbPath);+ db.close();++ expect(backup.ok).toBe(true);+ expect(fs.existsSync(backupPath)).toBe(true);+ expect(fs.readFileSync(backupPath).includes(Buffer.from('survived'))).toBe(false);++ fs.rmSync(dbPath);+ const restore = await restoreDbBackupIfNeeded(dbPath);+ expect(restore.restored).toBe(true);++ const restored = new Database(dbPath);+ expect((restored.prepare('SELECT name FROM items').get() as { name: string }).name).toBe('survived');+ restored.close();+ });+});diff --git a/server/src/__tests__/routes/models-management.test.ts b/server/src/__tests__/routes/models-management.test.tsnew file mode 100644index 00000000..4eff86a6--- /dev/null+++ b/server/src/__tests__/routes/models-management.test.ts@@ -0,0 +1,98 @@+import { describe, it, expect, beforeAll } from 'vitest';+import type { Express } from 'express';+import { createApp } from '../../app.js';+import { initDb, getDb } from '../../db/index.js';+import { mintDashboardToken, isGatedApiPath } from '../helpers/auth.js';++let dashToken = '';++async function request(app: Express, method: string, path: string, body?: any) {+ const server = app.listen(0);+ const addr = server.address() as any;+ const url = `http://127.0.0.1:${addr.port}${path}`;++ const res = await fetch(url, {+ method,+ headers: {+ ...(body ? { 'Content-Type': 'application/json' } : {}),+ ...(isGatedApiPath(path) ? { Authorization: `Bearer ${dashToken}` } : {}),+ },+ body: body ? JSON.stringify(body) : undefined,+ });++ const data = await res.json().catch(() => null);+ server.close();+ return { status: res.status, body: data };+}++describe('Model management API', () => {+ let app: Express;++ beforeAll(() => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ initDb(':memory:');+ app = createApp();+ dashToken = mintDashboardToken();+ });++ it('updates catalog model metadata and records durable overrides', async () => {+ const target = getDb().prepare(`+ SELECT id FROM models+ WHERE platform = 'groq' AND key_id IS NULL+ ORDER BY id LIMIT 1+ `).get() as { id: number };++ const { status, body } = await request(app, 'PATCH', `/api/models/${target.id}`, {+ displayName: 'Locally tuned model',+ supportsTools: true,+ contextWindow: 123456,+ fallbackEnabled: false,+ });+ expect(status).toBe(200);+ expect(body.success).toBe(true);++ const row = getDb().prepare(`+ SELECT m.display_name, m.supports_tools, m.context_window, fc.enabled AS fallback_enabled+ FROM models m+ JOIN fallback_config fc ON fc.model_db_id = m.id+ WHERE m.id = ?+ `).get(target.id) as { display_name: string; supports_tools: number; context_window: number; fallback_enabled: number };+ expect(row).toEqual({+ display_name: 'Locally tuned model',+ supports_tools: 1,+ context_window: 123456,+ fallback_enabled: 0,+ });++ const override = getDb().prepare('SELECT overrides_json FROM model_overrides WHERE model_id = (SELECT model_id FROM models WHERE id = ?)')+ .get(target.id) as { overrides_json: string };+ expect(JSON.parse(override.overrides_json)).toMatchObject({+ displayName: 'Locally tuned model',+ supportsTools: true,+ contextWindow: 123456,+ });++ const listed = await request(app, 'GET', '/api/models');+ const item = listed.body.find((m: any) => m.id === target.id);+ expect(item.hasOverrides).toBe(true);+ expect(item.fallbackEnabled).toBe(false);+ });++ it('deletes a catalog model with a tombstone', async () => {+ const target = getDb().prepare(`+ SELECT id, platform, model_id FROM models+ WHERE platform = 'openrouter' AND key_id IS NULL+ ORDER BY id LIMIT 1+ `).get() as { id: number; platform: string; model_id: string };++ const { status, body } = await request(app, 'DELETE', `/api/models/${target.id}`);+ expect(status).toBe(200);+ expect(body).toEqual({ success: true, tombstoned: true });++ expect(getDb().prepare('SELECT id FROM models WHERE id = ?').get(target.id)).toBeUndefined();+ expect(getDb().prepare(`+ SELECT 1 FROM catalog_model_tombstones+ WHERE kind = 'chat' AND platform = ? AND model_id = ?+ `).get(target.platform, target.model_id)).toBeDefined();+ });+});diff --git a/server/src/__tests__/services/catalog-sync.test.ts b/server/src/__tests__/services/catalog-sync.test.tsindex e57c7312..a9b3f3c6 100644--- a/server/src/__tests__/services/catalog-sync.test.ts+++ b/server/src/__tests__/services/catalog-sync.test.ts@@ -2,6 +2,7 @@ import { describe, it, expect, beforeAll } from 'vitest';import { initDb, getDb, setSetting, getSetting } from '../../db/index.js';import { applyCatalog, reapplyCachedCatalog, MIN_CATALOG_VERSION } from '../../services/catalog-sync.js';import { runMigrationsSync } from '../../db/migrate/runner.js';+import { recordCatalogModelTombstone, upsertModelOverrides } from '../../services/model-state.js';// applyCatalog is the write path between the published catalog and the live// router DB. These tests lock its contract: catalog metadata always wins, the@@ -149,6 +150,53 @@ describe('applyCatalog', () => {expect(row.enabled).toBe(1);});+ it('re-applies local model overrides after catalog metadata refreshes', () => {+ const models = existingAsCatalogModels().filter((m) => m.modelId !== 'override-model');+ models.push(baseModel({+ modelId: 'override-model',+ displayName: 'Catalog Name',+ contextWindow: 1000,+ supportsTools: false,+ }));+ applyCatalog(getDb(), catalogOf(models));++ upsertModelOverrides(getDb(), 'groq', 'override-model', {+ displayName: 'Local Name',+ contextWindow: 12345,+ supportsTools: true,+ });++ const refreshed = existingAsCatalogModels().filter((m) => m.modelId !== 'override-model');+ refreshed.push(baseModel({+ modelId: 'override-model',+ displayName: 'Catalog Name v2',+ contextWindow: 2000,+ supportsTools: false,+ }));+ applyCatalog(getDb(), catalogOf(refreshed));++ const row = getDb().prepare(`+ SELECT display_name, context_window, supports_tools+ FROM models+ WHERE platform = 'groq' AND model_id = 'override-model'+ `).get() as { display_name: string; context_window: number; supports_tools: number };+ expect(row).toEqual({ display_name: 'Local Name', context_window: 12345, supports_tools: 1 });+ });++ it('keeps user-deleted catalog models deleted across catalog refreshes', () => {+ const models = existingAsCatalogModels().filter((m) => m.modelId !== 'tombstone-model');+ models.push(baseModel({ modelId: 'tombstone-model', displayName: 'Tombstone Me' }));+ applyCatalog(getDb(), catalogOf(models));+ expect(getDb().prepare("SELECT id FROM models WHERE platform = 'groq' AND model_id = 'tombstone-model'").get()).toBeDefined();++ recordCatalogModelTombstone(getDb(), 'chat', 'groq', 'tombstone-model');+ applyCatalog(getDb(), catalogOf(models));+ expect(getDb().prepare("SELECT id FROM models WHERE platform = 'groq' AND model_id = 'tombstone-model'").get()).toBeUndefined();++ applyCatalog(getDb(), catalogOf(models));+ expect(getDb().prepare("SELECT id FROM models WHERE platform = 'groq' AND model_id = 'tombstone-model'").get()).toBeUndefined();+ });+it('skips models for platforms this binary has no provider for', () => {const models = existingAsCatalogModels();models.push(baseModel({ platform: 'some-future-provider', modelId: 'future-model' }));diff --git a/server/src/__tests__/services/declarative-config.test.ts b/server/src/__tests__/services/declarative-config.test.tsnew file mode 100644index 00000000..d806c43a--- /dev/null+++ b/server/src/__tests__/services/declarative-config.test.ts@@ -0,0 +1,107 @@+import { describe, it, expect, beforeAll, beforeEach, afterEach } from 'vitest';+import { initDb, getDb } from '../../db/index.js';+import { applyDeclarativeConfig, applyDeclarativeConfigFromEnv } from '../../services/declarative-config.js';+import { getRoutingStrategy } from '../../services/router.js';++const ORIGINAL_CONFIG_JSON = process.env.FREEAPI_CONFIG_JSON;+const ORIGINAL_CONFIG_PATH = process.env.FREEAPI_CONFIG_PATH;++function restoreEnv() {+ if (ORIGINAL_CONFIG_JSON === undefined) delete process.env.FREEAPI_CONFIG_JSON;+ else process.env.FREEAPI_CONFIG_JSON = ORIGINAL_CONFIG_JSON;+ if (ORIGINAL_CONFIG_PATH === undefined) delete process.env.FREEAPI_CONFIG_PATH;+ else process.env.FREEAPI_CONFIG_PATH = ORIGINAL_CONFIG_PATH;+}++describe('declarative config import', () => {+ beforeAll(() => {+ process.env.ENCRYPTION_KEY = '0'.repeat(64);+ initDb(':memory:');+ });++ beforeEach(() => {+ delete process.env.FREEAPI_CONFIG_JSON;+ delete process.env.FREEAPI_CONFIG_PATH;+ getDb().prepare('DELETE FROM api_keys').run();+ });++ afterEach(() => restoreEnv());++ it('applies keys, custom providers, model overrides, fallback order and routing', () => {+ const target = getDb().prepare(`+ SELECT platform, model_id FROM models+ WHERE platform = 'groq' AND key_id IS NULL+ ORDER BY id LIMIT 1+ `).get() as { platform: string; model_id: string };++ const result = applyDeclarativeConfig({+ keys: [{ platform: 'groq', key: 'gsk_config_key', label: 'config' }],+ customProviders: [{+ baseUrl: 'http://127.0.0.1:9123/v1',+ apiKey: 'local-key',+ label: 'Local config',+ models: [{ model: 'local-chat', displayName: 'Local Chat', supportsTools: true, contextWindow: 32000 }],+ }],+ models: [{+ platform: target.platform,+ modelId: target.model_id,+ displayName: 'Config Display',+ supportsTools: true,+ contextWindow: 654321,+ }],+ fallback: [{ platform: target.platform, modelId: target.model_id, priority: 1, enabled: false }],+ routing: { strategy: 'custom', weights: { reliability: 3, speed: 1, intelligence: 2 } },+ });++ expect(result).toMatchObject({ applied: true, keys: 1, customModels: 1, models: 1, fallback: 1, routing: true });+ expect((getDb().prepare("SELECT COUNT(*) AS n FROM api_keys WHERE platform = 'groq'").get() as { n: number }).n).toBe(1);+ expect((getDb().prepare("SELECT COUNT(*) AS n FROM api_keys WHERE platform = 'custom'").get() as { n: number }).n).toBe(1);+ expect(getDb().prepare(`+ SELECT display_name, supports_tools, context_window FROM models+ WHERE platform = 'custom' AND model_id = 'local-chat'+ `).get()).toEqual({ display_name: 'Local Chat', supports_tools: 1, context_window: 32000 });++ const model = getDb().prepare(`+ SELECT m.display_name, m.supports_tools, m.context_window, fc.priority, fc.enabled AS fallback_enabled+ FROM models m+ JOIN fallback_config fc ON fc.model_db_id = m.id+ WHERE m.platform = ? AND m.model_id = ?+ `).get(target.platform, target.model_id) as {+ display_name: string;+ supports_tools: number;+ context_window: number;+ priority: number;+ fallback_enabled: number;+ };+ expect(model).toEqual({+ display_name: 'Config Display',+ supports_tools: 1,+ context_window: 654321,+ priority: 1,+ fallback_enabled: 0,+ });+ expect(getDb().prepare('SELECT overrides_json FROM model_overrides WHERE platform = ? AND model_id = ?')+ .get(target.platform, target.model_id)).toBeDefined();+ expect(getRoutingStrategy()).toBe('custom');++ applyDeclarativeConfig({+ models: [{ platform: target.platform, modelId: target.model_id, displayName: 'Edited Again' }],+ });+ expect((getDb().prepare(`+ SELECT fc.enabled AS fallback_enabled+ FROM models m+ JOIN fallback_config fc ON fc.model_db_id = m.id+ WHERE m.platform = ? AND m.model_id = ?+ `).get(target.platform, target.model_id) as { fallback_enabled: number }).fallback_enabled).toBe(0);+ });++ it('applies inline JSON from FREEAPI_CONFIG_JSON idempotently', () => {+ process.env.FREEAPI_CONFIG_JSON = JSON.stringify({+ keys: [{ platform: 'groq', key: 'gsk_config_key', label: 'config' }],+ });++ expect(applyDeclarativeConfigFromEnv().applied).toBe(true);+ expect(applyDeclarativeConfigFromEnv().applied).toBe(true);+ expect((getDb().prepare("SELECT COUNT(*) AS n FROM api_keys WHERE platform = 'groq' AND label = 'config'").get() as { n: number }).n).toBe(1);+ });+});diff --git a/server/src/db/index.ts b/server/src/db/index.tsindex 1bdb6117..bfa7dae9 100644--- a/server/src/db/index.ts+++ b/server/src/db/index.ts@@ -18,6 +18,10 @@ export function getDb(): Database.Database {return db;}+export function getDefaultDbPath(): string {+ return process.env.FREEAPI_DB_PATH?.trim() || DB_PATH;+}+export function connectDb(dbPath?: string,opts?: {@@ -26,7 +30,7 @@ export function connectDb(ensureDir?: boolean;},): Database.Database {- const resolvedPath = dbPath ?? DB_PATH;+ const resolvedPath = dbPath ?? getDefaultDbPath();const isMemory = resolvedPath === ':memory:';const ensureDir = opts?.ensureDir ?? true;diff --git a/server/src/db/migrate/defaults.ts b/server/src/db/migrate/defaults.tsindex 52f7909b..41bdbc15 100644--- a/server/src/db/migrate/defaults.ts+++ b/server/src/db/migrate/defaults.ts@@ -1,6 +1,7 @@import type Database from 'better-sqlite3';import * as legacyBaseline from '../migrations/20260101_000000_legacy_baseline.js';import * as customProviderModalities from '../migrations/20260627_000001_custom_provider_modalities.js';+import * as catalogModelState from '../migrations/20260627_000002_catalog_model_state.js';export interface MigrationModule {up(db: Database.Database): void;@@ -14,8 +15,10 @@ export interface DefaultMigration {export const LEGACY_BASELINE_FILENAME = '20260101_000000_legacy_baseline.ts';export const CUSTOM_PROVIDER_MODALITIES_FILENAME = '20260627_000001_custom_provider_modalities.ts';+export const CATALOG_MODEL_STATE_FILENAME = '20260627_000002_catalog_model_state.ts';export const DEFAULT_MIGRATIONS: readonly DefaultMigration[] = [{ filename: LEGACY_BASELINE_FILENAME, module: legacyBaseline },{ filename: CUSTOM_PROVIDER_MODALITIES_FILENAME, module: customProviderModalities },+ { filename: CATALOG_MODEL_STATE_FILENAME, module: catalogModelState },];diff --git a/server/src/db/migrations/20260627_000002_catalog_model_state.ts b/server/src/db/migrations/20260627_000002_catalog_model_state.tsnew file mode 100644index 00000000..936bd4ad--- /dev/null+++ b/server/src/db/migrations/20260627_000002_catalog_model_state.ts@@ -0,0 +1,32 @@+import type Database from 'better-sqlite3';++export function up(db: Database.Database): void {+ db.exec(`+ CREATE TABLE IF NOT EXISTS catalog_model_tombstones (+ kind TEXT NOT NULL DEFAULT 'chat',+ platform TEXT NOT NULL,+ model_id TEXT NOT NULL,+ created_at TEXT NOT NULL DEFAULT (datetime('now')),+ PRIMARY KEY (kind, platform, model_id)+ );++ CREATE TABLE IF NOT EXISTS model_overrides (+ platform TEXT NOT NULL,+ model_id TEXT NOT NULL,+ overrides_json TEXT NOT NULL DEFAULT '{}',+ updated_at TEXT NOT NULL DEFAULT (datetime('now')),+ PRIMARY KEY (platform, model_id)+ );++ CREATE INDEX IF NOT EXISTS idx_catalog_model_tombstones_platform_model+ ON catalog_model_tombstones(platform, model_id);+ `);+}++export function down(db: Database.Database): void {+ db.exec(`+ DROP INDEX IF EXISTS idx_catalog_model_tombstones_platform_model;+ DROP TABLE IF EXISTS model_overrides;+ DROP TABLE IF EXISTS catalog_model_tombstones;+ `);+}diff --git a/server/src/index.ts b/server/src/index.tsindex 832512a0..6983535a 100644--- a/server/src/index.ts+++ b/server/src/index.ts@@ -1,12 +1,14 @@import './env.js';import { createApp } from './app.js';-import { initDb, getSetting } from './db/index.js';+import { initDb, getDb, getSetting } from './db/index.js';import { startHealthChecker } from './services/health.js';import { applyProxyUrl, applyProxyEnabled, applyProxyBypass } from './lib/proxy.js';import { startCatalogSync } from './services/catalog-sync.js';import { installProcessSafetyNet } from './lib/process-safety-net.js';import { NodeScheduler } from './lib/scheduler.js';import { loadConfig } from './lib/config.js';+import { applyDeclarativeConfigFromEnv } from './services/declarative-config.js';+import { restoreDbBackupIfNeeded, startDbBackupPump } from './lib/db-backup.js';async function main() {const config = loadConfig();@@ -18,7 +20,13 @@ async function main() {const scheduler = new NodeScheduler();- initDb();+ if (config.dbPath) {+ await restoreDbBackupIfNeeded(config.dbPath);+ } else {+ await restoreDbBackupIfNeeded();+ }+ initDb(config.dbPath ?? undefined);+ applyDeclarativeConfigFromEnv();// Load the persisted proxy settings from the DB (env var wins if set).// Must happen after initDb so the settings table is ready.@@ -34,6 +42,7 @@ async function main() {console.log(`Proxy endpoint: http://${display}:${PORT}/v1/chat/completions`);startHealthChecker(scheduler);startCatalogSync(scheduler);+ startDbBackupPump(getDb(), scheduler, config.dbPath ?? undefined);};const server = app.listen(Number(PORT), HOST, onReady(HOST));diff --git a/server/src/lib/config.ts b/server/src/lib/config.tsindex efb0828c..63a6ce40 100644--- a/server/src/lib/config.ts+++ b/server/src/lib/config.ts@@ -11,6 +11,7 @@ function parseRateLimitRpm(): number {export interface Config {port: number | string;host: string;+ dbPath: string | null;dashboardOrigins: string[];clientDist: string | null;proxyRateLimitRpm: number;@@ -25,6 +26,7 @@ export function loadConfig(): Config {// 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 ?? '::',+ dbPath: process.env.FREEAPI_DB_PATH?.trim() || null,dashboardOrigins: (process.env.DASHBOARD_ORIGINS ?? '').split(',').map(s => s.trim())diff --git a/server/src/lib/db-backup.ts b/server/src/lib/db-backup.tsnew file mode 100644index 00000000..f64603d1--- /dev/null+++ b/server/src/lib/db-backup.ts@@ -0,0 +1,164 @@+import crypto from 'crypto';+import fs from 'fs';+import path from 'path';+import { gzipSync, gunzipSync } from 'zlib';+import type Database from 'better-sqlite3';+import type { Scheduler } from './scheduler.js';+import { getDefaultDbPath } from '../db/index.js';++const MAGIC = Buffer.from('FAPIBK1\0');+const DEFAULT_INTERVAL_MS = 5 * 60 * 1000;+const FETCH_TIMEOUT_MS = 30 * 1000;+const PLACEHOLDER_KEY = 'replace-with-64-char-hex';++export interface DbBackupResult {+ ok: boolean;+ target?: string;+ bytes?: number;+ restored?: boolean;+ skipped?: string;+}++function backupTarget(): string | null {+ const raw = process.env.FREEAPI_DB_BACKUP_TARGET+ ?? process.env.FREEAPI_DB_BACKUP_URL+ ?? process.env.FREEAPI_DB_BACKUP_PATH+ ?? '';+ const trimmed = raw.trim();+ return trimmed.length > 0 ? trimmed : null;+}++export function isDbBackupConfigured(): boolean {+ return backupTarget() !== null;+}++function backupIntervalMs(): number {+ const raw = process.env.FREEAPI_DB_BACKUP_INTERVAL_MS;+ if (!raw) return DEFAULT_INTERVAL_MS;+ const n = Number(raw);+ return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_INTERVAL_MS;+}++function isHttpTarget(target: string): boolean {+ return target.startsWith('https://') || target.startsWith('http://');+}++function parseBackupKey(): Buffer {+ const raw = (process.env.FREEAPI_DB_BACKUP_KEY || process.env.ENCRYPTION_KEY || '').trim();+ if (!raw || raw === PLACEHOLDER_KEY || !/^[0-9a-fA-F]{64}$/.test(raw)) {+ throw new Error('FREEAPI_DB_BACKUP_KEY or ENCRYPTION_KEY must be a 64-character hex key when DB backup is enabled');+ }+ return Buffer.from(raw, 'hex');+}++function encryptBackup(plain: Buffer): Buffer {+ const key = parseBackupKey();+ const iv = crypto.randomBytes(12);+ const cipher = crypto.createCipheriv('aes-256-gcm', key, iv);+ const ciphertext = Buffer.concat([cipher.update(plain), cipher.final()]);+ const tag = cipher.getAuthTag();+ return Buffer.concat([MAGIC, iv, tag, ciphertext]);+}++function decryptBackup(payload: Buffer): Buffer {+ if (payload.length < MAGIC.length + 12 + 16 || !payload.subarray(0, MAGIC.length).equals(MAGIC)) {+ throw new Error('backup payload has an unsupported format');+ }+ const key = parseBackupKey();+ const ivStart = MAGIC.length;+ const tagStart = ivStart + 12;+ const bodyStart = tagStart + 16;+ const iv = payload.subarray(ivStart, tagStart);+ const tag = payload.subarray(tagStart, bodyStart);+ const ciphertext = payload.subarray(bodyStart);+ const decipher = crypto.createDecipheriv('aes-256-gcm', key, iv);+ decipher.setAuthTag(tag);+ return Buffer.concat([decipher.update(ciphertext), decipher.final()]);+}++async function readTarget(target: string): Promise<Buffer | null> {+ if (isHttpTarget(target)) {+ const headers: Record<string, string> = {};+ const token = process.env.FREEAPI_DB_BACKUP_TOKEN?.trim();+ if (token) headers.Authorization = `Bearer ${token}`;+ const res = await fetch(target, { method: 'GET', headers, signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });+ if (res.status === 404 || res.status === 204) return null;+ if (!res.ok) throw new Error(`backup restore failed: HTTP ${res.status}`);+ return Buffer.from(await res.arrayBuffer());+ }++ if (!fs.existsSync(target)) return null;+ return fs.readFileSync(target);+}++async function writeTarget(target: string, payload: Buffer): Promise<void> {+ if (isHttpTarget(target)) {+ const headers: Record<string, string> = { 'Content-Type': 'application/octet-stream' };+ const token = process.env.FREEAPI_DB_BACKUP_TOKEN?.trim();+ if (token) headers.Authorization = `Bearer ${token}`;+ const res = await fetch(target, {+ method: 'PUT',+ headers,+ body: payload,+ signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),+ });+ if (!res.ok) throw new Error(`backup upload failed: HTTP ${res.status}`);+ return;+ }++ fs.mkdirSync(path.dirname(path.resolve(target)), { recursive: true });+ fs.writeFileSync(target, payload);+}++export async function restoreDbBackupIfNeeded(dbPath = getDefaultDbPath()): Promise<DbBackupResult> {+ const target = backupTarget();+ if (!target) return { ok: true, skipped: 'not configured' };+ if (dbPath === ':memory:') return { ok: true, target, skipped: 'memory database' };+ if (fs.existsSync(dbPath) && fs.statSync(dbPath).size > 0) return { ok: true, target, skipped: 'database already exists' };++ const payload = await readTarget(target);+ if (!payload || payload.length === 0) return { ok: true, target, skipped: 'no backup found' };++ let restored: Buffer;+ try {+ restored = gunzipSync(decryptBackup(payload));+ } catch (err) {+ const detail = err instanceof Error ? err.message : String(err);+ throw new Error(`could not restore SQLite backup from ${target}: ${detail}`);+ }++ fs.mkdirSync(path.dirname(path.resolve(dbPath)), { recursive: true });+ fs.writeFileSync(dbPath, restored);+ console.log(`[db-backup] restored ${restored.length} bytes from ${target}`);+ return { ok: true, target, bytes: restored.length, restored: true };+}++export async function backupDbNow(db: Database.Database, dbPath = getDefaultDbPath()): Promise<DbBackupResult> {+ const target = backupTarget();+ if (!target) return { ok: true, skipped: 'not configured' };+ if (dbPath === ':memory:') return { ok: true, target, skipped: 'memory database' };+ if (!fs.existsSync(dbPath)) return { ok: false, target, skipped: 'database file missing' };++ try {+ db.pragma('wal_checkpoint(TRUNCATE)');+ } catch {+ // Best effort: reading the main DB still works for rollback-journal or quiet WAL DBs.+ }++ const plain = fs.readFileSync(dbPath);+ const payload = encryptBackup(gzipSync(plain));+ await writeTarget(target, payload);+ console.log(`[db-backup] uploaded ${plain.length} bytes to ${target}`);+ return { ok: true, target, bytes: plain.length };+}++export function startDbBackupPump(db: Database.Database, scheduler: Scheduler, dbPath = getDefaultDbPath()): (() => void) | null {+ if (!backupTarget()) return null;+ const run = () => {+ void backupDbNow(db, dbPath).catch(err => {+ console.warn(`[db-backup] ${err instanceof Error ? err.message : err}`);+ });+ };+ run();+ return scheduler.every(backupIntervalMs(), run);+}diff --git a/server/src/routes/fallback.ts b/server/src/routes/fallback.tsindex 3bc4643f..c6065894 100644--- a/server/src/routes/fallback.ts+++ b/server/src/routes/fallback.ts@@ -63,9 +63,13 @@ fallbackRouter.get('/', (_req: Request, res: Response) => {m.platform, m.model_id, m.display_name, m.intelligence_rank,m.speed_rank, m.size_label, m.rpm_limit, m.rpd_limit,m.tpm_limit, m.tpd_limit, m.context_window,- m.monthly_token_budget, m.supports_vision, m.supports_tools+ m.monthly_token_budget, m.supports_vision, m.supports_tools,+ m.key_id, ak.label AS key_label,+ mo.overrides_json IS NOT NULL AS has_overridesFROM fallback_config fcJOIN models m ON m.id = fc.model_db_id+ LEFT JOIN api_keys ak ON ak.id = m.key_id+ LEFT JOIN model_overrides mo ON mo.platform = m.platform AND mo.model_id = m.model_idWHERE m.enabled = 1ORDER BY fc.priority ASC`).all() as any[];@@ -124,6 +128,10 @@ fallbackRouter.get('/', (_req: Request, res: Response) => {monthlyTokenBudgetTokens: parseBudget(r.monthly_token_budget),supportsVision: r.supports_vision === 1,supportsTools: r.supports_tools === 1,+ source: r.platform === 'custom' || r.key_id != null ? 'custom' : 'catalog',+ keyId: r.key_id ?? null,+ keyLabel: r.key_label ?? null,+ hasOverrides: Boolean(r.has_overrides),keyCount: keyCountMap.get(r.platform) ?? 0,};}));diff --git a/server/src/routes/models.ts b/server/src/routes/models.tsindex e92f7045..9dc79d3e 100644--- a/server/src/routes/models.ts+++ b/server/src/routes/models.ts@@ -1,11 +1,69 @@import { Router } from 'express';import type { Request, Response } from 'express';+import { z } from 'zod';import { getDb } from '../db/index.js';import { hasProvider } from '../providers/index.js';import { deleteUnusedCustomEndpointKey } from '../lib/custom-provider-cleanup.js';+import {+ isCatalogManagedModel,+ recordCatalogModelTombstone,+ upsertModelOverrides,+ type ModelOverridePatch,+} from '../services/model-state.js';export const modelsRouter = Router();+const modelUpdateSchema = z.object({+ displayName: z.string().min(1).max(200).optional(),+ intelligenceRank: z.number().int().min(1).max(1000).optional(),+ speedRank: z.number().int().min(1).max(1000).optional(),+ sizeLabel: z.string().min(1).max(40).optional(),+ rpmLimit: z.number().int().positive().nullable().optional(),+ rpdLimit: z.number().int().positive().nullable().optional(),+ tpmLimit: z.number().int().positive().nullable().optional(),+ tpdLimit: z.number().int().positive().nullable().optional(),+ monthlyTokenBudget: z.string().max(80).optional(),+ contextWindow: z.number().int().positive().nullable().optional(),+ enabled: z.boolean().optional(),+ supportsVision: z.boolean().optional(),+ supportsTools: z.boolean().optional(),+ fallbackEnabled: z.boolean().optional(),+}).strict();++const MODEL_FIELD_COLUMNS: Record<keyof ModelOverridePatch | 'enabled', string> = {+ displayName: 'display_name',+ intelligenceRank: 'intelligence_rank',+ speedRank: 'speed_rank',+ sizeLabel: 'size_label',+ rpmLimit: 'rpm_limit',+ rpdLimit: 'rpd_limit',+ tpmLimit: 'tpm_limit',+ tpdLimit: 'tpd_limit',+ monthlyTokenBudget: 'monthly_token_budget',+ contextWindow: 'context_window',+ supportsVision: 'supports_vision',+ supportsTools: 'supports_tools',+ enabled: 'enabled',+};++type ModelRow = {+ id: number;+ platform: string;+ model_id: string;+ key_id: number | null;+};++function dbValue(key: keyof typeof MODEL_FIELD_COLUMNS, value: unknown): unknown {+ if (key === 'enabled' || key === 'supportsVision' || key === 'supportsTools') return value ? 1 : 0;+ return value;+}++function fetchModelRow(id: number): ModelRow | undefined {+ return getDb()+ .prepare('SELECT id, platform, model_id, key_id FROM models WHERE id = ?')+ .get(id) as ModelRow | undefined;+}+modelsRouter.delete('/custom/:id', (req: Request, res: Response) => {const id = Number(req.params.id);if (!Number.isInteger(id)) {@@ -29,13 +87,108 @@ modelsRouter.delete('/custom/:id', (req: Request, res: Response) => {res.json({ success: true });});+modelsRouter.patch('/:id', (req: Request, res: Response) => {+ const id = Number(req.params.id);+ if (!Number.isInteger(id)) {+ res.status(400).json({ error: { message: 'Invalid id' } });+ return;+ }++ const parsed = modelUpdateSchema.safeParse(req.body);+ if (!parsed.success) {+ res.status(400).json({ error: { message: parsed.error.errors.map(e => e.message).join(', ') } });+ return;+ }++ const db = getDb();+ const row = fetchModelRow(id);+ if (!row) {+ res.status(404).json({ error: { message: `Unknown model ${id}` } });+ return;+ }++ const modelPatch: Partial<typeof parsed.data> = { ...parsed.data };+ delete modelPatch.fallbackEnabled;+ const modelKeys = Object.keys(modelPatch) as Array<keyof typeof modelPatch>;+ if (modelKeys.length === 0 && parsed.data.fallbackEnabled === undefined) {+ res.status(400).json({ error: { message: 'No model fields provided' } });+ return;+ }++ const applyUpdate = db.transaction(() => {+ if (modelKeys.length > 0) {+ const assignments: string[] = [];+ const values: unknown[] = [];+ for (const key of modelKeys) {+ assignments.push(`${MODEL_FIELD_COLUMNS[key as keyof typeof MODEL_FIELD_COLUMNS]} = ?`);+ values.push(dbValue(key as keyof typeof MODEL_FIELD_COLUMNS, modelPatch[key]));+ }+ values.push(id);+ db.prepare(`UPDATE models SET ${assignments.join(', ')} WHERE id = ?`).run(...values);++ if (isCatalogManagedModel(row)) {+ const overridePatch: ModelOverridePatch = {};+ for (const key of [+ 'displayName', 'intelligenceRank', 'speedRank', 'sizeLabel',+ 'rpmLimit', 'rpdLimit', 'tpmLimit', 'tpdLimit',+ 'monthlyTokenBudget', 'contextWindow', 'supportsVision', 'supportsTools',+ ] as const) {+ if (Object.prototype.hasOwnProperty.call(modelPatch, key)) {+ overridePatch[key] = modelPatch[key] as never;+ }+ }+ upsertModelOverrides(db, row.platform, row.model_id, overridePatch);+ }+ }++ if (parsed.data.fallbackEnabled !== undefined) {+ db.prepare('UPDATE fallback_config SET enabled = ? WHERE model_db_id = ?')+ .run(parsed.data.fallbackEnabled ? 1 : 0, id);+ }+ });+ applyUpdate();++ res.json({ success: true, id });+});++modelsRouter.delete('/:id', (req: Request, res: Response) => {+ const id = Number(req.params.id);+ if (!Number.isInteger(id)) {+ res.status(400).json({ error: { message: 'Invalid id' } });+ return;+ }++ const db = getDb();+ const row = fetchModelRow(id);+ if (!row) {+ res.status(404).json({ error: { message: `Unknown model ${id}` } });+ return;+ }++ const remove = db.transaction(() => {+ if (isCatalogManagedModel(row)) {+ recordCatalogModelTombstone(db, 'chat', row.platform, row.model_id);+ }+ db.prepare('DELETE FROM fallback_config WHERE model_db_id = ?').run(id);+ db.prepare('DELETE FROM models WHERE id = ?').run(id);+ if (row.platform === 'custom') deleteUnusedCustomEndpointKey(db, row.key_id);+ });+ remove();++ res.json({ success: true, tombstoned: isCatalogManagedModel(row) });+});+// List all models with availability infomodelsRouter.get('/', (_req: Request, res: Response) => {const db = getDb();const models = db.prepare(`- SELECT m.*, fc.priority, fc.enabled as fallback_enabled+ SELECT m.*, fc.priority, fc.enabled as fallback_enabled,+ mo.overrides_json IS NOT NULL AS has_overrides,+ ak.label AS key_labelFROM models mLEFT JOIN fallback_config fc ON fc.model_db_id = m.id+ LEFT JOIN model_overrides mo ON mo.platform = m.platform AND mo.model_id = m.model_id+ LEFT JOIN api_keys ak ON ak.id = m.key_idORDER BY COALESCE(fc.priority, m.intelligence_rank) ASC`).all() as any[];@@ -68,6 +221,10 @@ modelsRouter.get('/', (_req: Request, res: Response) => {supportsTools: m.supports_tools === 1,priority: m.priority,fallbackEnabled: m.fallback_enabled === 1,+ source: m.platform === 'custom' || m.key_id != null ? 'custom' : 'catalog',+ keyId: m.key_id ?? null,+ keyLabel: m.key_label ?? null,+ hasOverrides: Boolean(m.has_overrides),hasProvider: hasProvider(m.platform),keyCount: keyCountMap.get(m.platform) ?? 0,}));diff --git a/server/src/services/catalog-sync.ts b/server/src/services/catalog-sync.tsindex 4f3eab97..1fa3f8f3 100644--- a/server/src/services/catalog-sync.ts+++ b/server/src/services/catalog-sync.ts@@ -5,6 +5,12 @@ import { hasProvider } from '../providers/index.js';import { MEDIA_PLATFORMS } from './media.js';import type { Platform } from '@freellmapi/shared/types.js';import type { Scheduler } from '../lib/scheduler.js';+import {+ applyAllModelOverrides,+ applyModelOverrides,+ deleteTombstonedCatalogModels,+ isCatalogModelTombstoned,+} from './model-state.js';// Generative-media modalities are routed into the separate media_models table// (see services/media.ts), never into the chat `models` table.@@ -144,12 +150,13 @@ function isCatalog(value: unknown): value is Catalog {* Apply a verified catalog to the local DB inside one transaction.** Rules of engagement with user data:- * - metadata (name, ranks, limits, context, capabilities) always tracks the- * catalog — that is the whole point of the product;+ * - metadata (name, ranks, limits, context, capabilities) tracks the catalog+ * unless the user has an explicit local override;* - catalog enabled=false force-disables (the model is dead upstream), but* enabled=true never re-enables a model the user turned off themselves;* - models the user added via custom providers (platform='custom' or bound to* a key) are never touched;+ * - catalog models the user deleted stay deleted via tombstones;* - models that vanished from the catalog are deleted, exactly like the* dead-model migrations do (fallback_config row first, FK order).*/@@ -201,6 +208,7 @@ export function applyCatalog(db: DatabaseType.Database, catalog: Catalog): NonNucounts.skippedUnknownPlatform++;continue;}+ if (isCatalogModelTombstoned(db, 'media', m.platform, m.modelId)) continue;inMediaCatalog.add(`${m.platform}:${m.modelId}`);const mrow = selectMedia.get(m.platform, m.modelId) as { id: number; enabled: number } | undefined;const mfields = {@@ -226,6 +234,7 @@ export function applyCatalog(db: DatabaseType.Database, catalog: Catalog): NonNucounts.skippedUnknownPlatform++;continue;}+ if (isCatalogModelTombstoned(db, 'chat', m.platform, m.modelId)) continue;inCatalog.add(`${m.platform}:${m.modelId}`);const row = selectModel.get(m.platform, m.modelId) as { id: number; enabled: number } | undefined;@@ -247,13 +256,18 @@ export function applyCatalog(db: DatabaseType.Database, catalog: Catalog): NonNu// Catalog disable wins (dead upstream); local disable also wins.const enabled = m.enabled ? row.enabled : 0;updateModel.run({ ...fields, id: row.id, enabled });+ applyModelOverrides(db, m.platform, m.modelId);counts.updated++;} else {insertModel.run({ ...fields, platform: m.platform, modelId: m.modelId, enabled: m.enabled ? 1 : 0 });+ applyModelOverrides(db, m.platform, m.modelId);counts.inserted++;}}+ counts.removed += deleteTombstonedCatalogModels(db);+ applyAllModelOverrides(db);+// Ensure every model has a fallback_config row (same invariant migrations keep).const missingFb = db.prepare(@@ -268,7 +282,13 @@ export function applyCatalog(db: DatabaseType.Database, catalog: Catalog): NonNu// Remove catalog-managed models that the catalog no longer lists.const candidates = db- .prepare(`SELECT id, platform, model_id FROM models WHERE platform != 'custom' AND key_id IS NULL`)+ .prepare(`+ SELECT id, platform, model_id+ FROM models+ WHERE platform != 'custom'+ AND key_id IS NULL+ AND size_label NOT IN ('User', 'Custom')+ `).all() as { id: number; platform: string; model_id: string }[];const deleteFb = db.prepare('DELETE FROM fallback_config WHERE model_db_id = ?');const deleteModel = db.prepare('DELETE FROM models WHERE id = ?');diff --git a/server/src/services/declarative-config.ts b/server/src/services/declarative-config.tsnew file mode 100644index 00000000..d943c177--- /dev/null+++ b/server/src/services/declarative-config.ts@@ -0,0 +1,391 @@+import fs from 'fs';+import { z } from 'zod';+import type Database from 'better-sqlite3';+import { getDb } from '../db/index.js';+import { encrypt } from '../lib/crypto.js';+import { resolveProvider } from '../providers/index.js';+import { setCustomWeights, setRoutingStrategy } from './router.js';+import {+ clearCatalogModelTombstone,+ isCatalogManagedModel,+ upsertModelOverrides,+ type ModelOverridePatch,+} from './model-state.js';++const modelEntrySchema = z.union([+ z.string().min(1),+ z.object({+ model: z.string().min(1),+ displayName: z.string().optional(),+ intelligenceRank: z.number().int().min(1).max(1000).optional(),+ speedRank: z.number().int().min(1).max(1000).optional(),+ sizeLabel: z.string().min(1).max(40).optional(),+ monthlyTokenBudget: z.string().max(80).optional(),+ contextWindow: z.number().int().positive().nullable().optional(),+ supportsVision: z.boolean().optional(),+ supportsTools: z.boolean().optional(),+ fallbackEnabled: z.boolean().optional(),+ }),+]);++const keySchema = z.object({+ platform: z.string().min(1),+ key: z.string().optional(),+ label: z.string().optional(),+ baseUrl: z.string().url().optional(),+ enabled: z.boolean().optional(),+});++const customProviderSchema = z.object({+ baseUrl: z.string().url(),+ apiKey: z.string().optional(),+ label: z.string().optional(),+ models: z.array(modelEntrySchema).default([]),+});++const modelSchema = z.object({+ platform: z.string().min(1),+ modelId: z.string().min(1),+ displayName: z.string().min(1).optional(),+ intelligenceRank: z.number().int().min(1).max(1000).optional(),+ speedRank: z.number().int().min(1).max(1000).optional(),+ sizeLabel: z.string().min(1).max(40).optional(),+ rpmLimit: z.number().int().positive().nullable().optional(),+ rpdLimit: z.number().int().positive().nullable().optional(),+ tpmLimit: z.number().int().positive().nullable().optional(),+ tpdLimit: z.number().int().positive().nullable().optional(),+ monthlyTokenBudget: z.string().max(80).optional(),+ contextWindow: z.number().int().positive().nullable().optional(),+ enabled: z.boolean().optional(),+ supportsVision: z.boolean().optional(),+ supportsTools: z.boolean().optional(),+ fallbackEnabled: z.boolean().optional(),+});++const fallbackEntrySchema = z.object({+ platform: z.string().min(1),+ modelId: z.string().min(1),+ priority: z.number().int().positive().optional(),+ enabled: z.boolean().optional(),+});++const declarativeConfigSchema = z.object({+ keys: z.array(keySchema).optional(),+ customProviders: z.array(customProviderSchema).optional(),+ models: z.array(modelSchema).optional(),+ fallback: z.array(fallbackEntrySchema).optional(),+ routing: z.object({+ strategy: z.enum(['priority', 'balanced', 'smartest', 'fastest', 'reliable', 'custom']),+ weights: z.object({+ reliability: z.number().nonnegative(),+ speed: z.number().nonnegative(),+ intelligence: z.number().nonnegative(),+ }).optional(),+ }).optional(),+}).strict();++export type DeclarativeConfig = z.infer<typeof declarativeConfigSchema>;++export interface DeclarativeConfigResult {+ applied: boolean;+ source?: string;+ keys: number;+ customModels: number;+ models: number;+ fallback: number;+ routing: boolean;+}++interface NormalizedCustomModel {+ modelId: string;+ displayName: string;+ intelligenceRank?: number;+ speedRank?: number;+ sizeLabel?: string;+ monthlyTokenBudget?: string;+ contextWindow?: number | null;+ supportsVision?: boolean;+ supportsTools?: boolean;+ fallbackEnabled?: boolean;+}++function readConfigFromEnv(): { source: string; value: unknown } | null {+ const inline = process.env.FREEAPI_CONFIG_JSON?.trim();+ if (inline) return { source: 'FREEAPI_CONFIG_JSON', value: JSON.parse(inline) };++ const configPath = process.env.FREEAPI_CONFIG_PATH?.trim();+ if (configPath) return { source: configPath, value: JSON.parse(fs.readFileSync(configPath, 'utf8')) };++ return null;+}++function encryptedKey(raw: string) {+ const { encrypted, iv, authTag } = encrypt(raw);+ return { encrypted, iv, authTag };+}++function upsertApiKey(db: Database.Database, input: z.infer<typeof keySchema>): number {+ const platform = input.platform.trim();+ const enabled = input.enabled === false ? 0 : 1;+ const isCustom = platform === 'custom';+ const baseUrl = input.baseUrl?.trim().replace(/\/+$/, '') ?? null;+ const provider = !isCustom ? resolveProvider(platform as never) : null;+ if (!isCustom && !provider) throw new Error(`unknown provider platform: ${platform}`);+ const keyToStore = input.key?.trim() || (provider?.keyless ? 'no-key' : '');+ if (!keyToStore) throw new Error(`key is required for ${platform}`);+ const label = input.label?.trim() || (isCustom ? 'Custom' : 'env');+ const key = encryptedKey(keyToStore);++ if (isCustom) {+ if (!baseUrl) throw new Error('baseUrl is required for custom keys');+ const existing = db.prepare("SELECT id FROM api_keys WHERE platform = 'custom' AND base_url = ?").get(baseUrl) as { id: number } | undefined;+ if (existing) {+ db.prepare(`+ UPDATE api_keys+ SET label = ?, encrypted_key = ?, iv = ?, auth_tag = ?, enabled = ?, status = 'unknown'+ WHERE id = ?+ `).run(label, key.encrypted, key.iv, key.authTag, enabled, existing.id);+ return existing.id;+ }+ const inserted = db.prepare(`+ INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled, base_url)+ VALUES ('custom', ?, ?, ?, ?, 'unknown', ?, ?)+ `).run(label, key.encrypted, key.iv, key.authTag, enabled, baseUrl);+ return Number(inserted.lastInsertRowid);+ }++ const existing = db.prepare('SELECT id FROM api_keys WHERE platform = ? AND label = ? AND base_url IS NULL LIMIT 1')+ .get(platform, label) as { id: number } | undefined;+ if (existing) {+ db.prepare(`+ UPDATE api_keys+ SET encrypted_key = ?, iv = ?, auth_tag = ?, enabled = ?, status = 'unknown'+ WHERE id = ?+ `).run(key.encrypted, key.iv, key.authTag, enabled, existing.id);+ return existing.id;+ }+ const inserted = db.prepare(`+ INSERT INTO api_keys (platform, label, encrypted_key, iv, auth_tag, status, enabled)+ VALUES (?, ?, ?, ?, ?, 'unknown', ?)+ `).run(platform, label, key.encrypted, key.iv, key.authTag, enabled);+ return Number(inserted.lastInsertRowid);+}++function normalizeModelEntry(entry: z.infer<typeof modelEntrySchema>): NormalizedCustomModel {+ if (typeof entry === 'string') return { modelId: entry.trim(), displayName: entry.trim() };+ const modelId = entry.model.trim();+ return { ...entry, modelId, displayName: entry.displayName?.trim() || modelId };+}++function ensureFallbackRow(db: Database.Database, modelDbId: number, enabled = true, updateExisting = true): void {+ const existing = db.prepare('SELECT 1 FROM fallback_config WHERE model_db_id = ?').get(modelDbId);+ if (existing) {+ if (updateExisting) {+ db.prepare('UPDATE fallback_config SET enabled = ? WHERE model_db_id = ?').run(enabled ? 1 : 0, modelDbId);+ }+ return;+ }+ const max = db.prepare('SELECT COALESCE(MAX(priority), 0) AS m FROM fallback_config').get() as { m: number };+ db.prepare('INSERT INTO fallback_config (model_db_id, priority, enabled) VALUES (?, ?, ?)')+ .run(modelDbId, max.m + 1, enabled ? 1 : 0);+}++function registerCustomProvider(db: Database.Database, input: z.infer<typeof customProviderSchema>): number {+ const keyId = upsertApiKey(db, {+ platform: 'custom',+ key: input.apiKey,+ label: input.label,+ baseUrl: input.baseUrl,+ enabled: true,+ });+ let registered = 0;+ for (const entry of input.models) {+ const model = normalizeModelEntry(entry);+ db.prepare(`+ INSERT INTO models+ (platform, model_id, display_name, intelligence_rank, speed_rank, size_label,+ rpm_limit, rpd_limit, tpm_limit, tpd_limit, monthly_token_budget, context_window,+ enabled, supports_vision, supports_tools, key_id)+ VALUES ('custom', ?, ?, ?, ?, ?, NULL, NULL, NULL, NULL, ?, ?, 1, ?, ?, ?)+ ON CONFLICT(platform, model_id)+ DO UPDATE SET+ display_name = excluded.display_name,+ intelligence_rank = excluded.intelligence_rank,+ speed_rank = excluded.speed_rank,+ size_label = excluded.size_label,+ monthly_token_budget = excluded.monthly_token_budget,+ context_window = excluded.context_window,+ supports_vision = excluded.supports_vision,+ supports_tools = excluded.supports_tools,+ key_id = excluded.key_id,+ enabled = 1+ `).run(+ model.modelId,+ model.displayName,+ model.intelligenceRank ?? 50,+ model.speedRank ?? 50,+ model.sizeLabel ?? 'Custom',+ model.monthlyTokenBudget ?? '',+ model.contextWindow ?? null,+ model.supportsVision ? 1 : 0,+ model.supportsTools ? 1 : 0,+ keyId,+ );+ const row = db.prepare("SELECT id FROM models WHERE platform = 'custom' AND model_id = ?").get(model.modelId) as { id: number };+ ensureFallbackRow(db, row.id, model.fallbackEnabled !== false);+ registered++;+ }+ return registered;+}++function modelPatchFromInput(input: z.infer<typeof modelSchema>): ModelOverridePatch {+ const patch: ModelOverridePatch = {};+ for (const key of [+ 'displayName', 'intelligenceRank', 'speedRank', 'sizeLabel',+ 'rpmLimit', 'rpdLimit', 'tpmLimit', 'tpdLimit',+ 'monthlyTokenBudget', 'contextWindow', 'supportsVision', 'supportsTools',+ ] as const) {+ if (Object.prototype.hasOwnProperty.call(input, key)) patch[key] = input[key] as never;+ }+ return patch;+}++function upsertModel(db: Database.Database, input: z.infer<typeof modelSchema>): void {+ const platform = input.platform.trim();+ const modelId = input.modelId.trim();+ clearCatalogModelTombstone(db, 'chat', platform, modelId);+ const existing = db.prepare('SELECT id, platform, model_id, key_id FROM models WHERE platform = ? AND model_id = ?')+ .get(platform, modelId) as { id: number; platform: string; model_id: string; key_id: number | null } | undefined;++ if (!existing) {+ db.prepare(`+ INSERT INTO models+ (platform, model_id, display_name, intelligence_rank, speed_rank, size_label,+ rpm_limit, rpd_limit, tpm_limit, tpd_limit, monthly_token_budget, context_window,+ enabled, supports_vision, supports_tools)+ VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)+ `).run(+ platform,+ modelId,+ input.displayName ?? modelId,+ input.intelligenceRank ?? 50,+ input.speedRank ?? 50,+ input.sizeLabel ?? 'User',+ input.rpmLimit ?? null,+ input.rpdLimit ?? null,+ input.tpmLimit ?? null,+ input.tpdLimit ?? null,+ input.monthlyTokenBudget ?? '',+ input.contextWindow ?? null,+ input.enabled === false ? 0 : 1,+ input.supportsVision ? 1 : 0,+ input.supportsTools ? 1 : 0,+ );+ const created = db.prepare('SELECT id FROM models WHERE platform = ? AND model_id = ?').get(platform, modelId) as { id: number };+ ensureFallbackRow(db, created.id, input.fallbackEnabled ?? input.enabled !== false);+ return;+ }++ const patch = modelPatchFromInput(input);+ const assignments: string[] = [];+ const values: unknown[] = [];+ const columnMap: Record<keyof ModelOverridePatch, string> = {+ displayName: 'display_name',+ intelligenceRank: 'intelligence_rank',+ speedRank: 'speed_rank',+ sizeLabel: 'size_label',+ rpmLimit: 'rpm_limit',+ rpdLimit: 'rpd_limit',+ tpmLimit: 'tpm_limit',+ tpdLimit: 'tpd_limit',+ monthlyTokenBudget: 'monthly_token_budget',+ contextWindow: 'context_window',+ supportsVision: 'supports_vision',+ supportsTools: 'supports_tools',+ };+ for (const key of Object.keys(patch) as Array<keyof ModelOverridePatch>) {+ assignments.push(`${columnMap[key]} = ?`);+ values.push(key === 'supportsVision' || key === 'supportsTools' ? (patch[key] ? 1 : 0) : patch[key]);+ }+ if (input.enabled !== undefined) {+ assignments.push('enabled = ?');+ values.push(input.enabled ? 1 : 0);+ }+ if (assignments.length > 0) {+ values.push(existing.id);+ db.prepare(`UPDATE models SET ${assignments.join(', ')} WHERE id = ?`).run(...values);+ }+ if (isCatalogManagedModel(existing) && Object.keys(patch).length > 0) {+ upsertModelOverrides(db, platform, modelId, patch);+ }+ ensureFallbackRow(db, existing.id, input.fallbackEnabled ?? input.enabled !== false, input.fallbackEnabled !== undefined);+}++function applyFallback(db: Database.Database, entries: z.infer<typeof fallbackEntrySchema>[]): number {+ const update = db.prepare('UPDATE fallback_config SET priority = ?, enabled = ? WHERE model_db_id = ?');+ let changed = 0;+ entries.forEach((entry, i) => {+ const row = db.prepare('SELECT id FROM models WHERE platform = ? AND model_id = ?')+ .get(entry.platform, entry.modelId) as { id: number } | undefined;+ if (!row) return;+ ensureFallbackRow(db, row.id, entry.enabled !== false);+ update.run(entry.priority ?? i + 1, entry.enabled === false ? 0 : 1, row.id);+ changed++;+ });+ return changed;+}++export function applyDeclarativeConfig(input: unknown, source = 'inline'): DeclarativeConfigResult {+ const parsed = declarativeConfigSchema.safeParse(input);+ if (!parsed.success) {+ throw new Error(`invalid declarative config: ${parsed.error.errors.map(e => `${e.path.join('.')}: ${e.message}`).join(', ')}`);+ }++ const db = getDb();+ const result: DeclarativeConfigResult = {+ applied: true,+ source,+ keys: 0,+ customModels: 0,+ models: 0,+ fallback: 0,+ routing: false,+ };++ const apply = db.transaction(() => {+ for (const key of parsed.data.keys ?? []) {+ upsertApiKey(db, key);+ result.keys++;+ }+ for (const customProvider of parsed.data.customProviders ?? []) {+ result.customModels += registerCustomProvider(db, customProvider);+ }+ for (const model of parsed.data.models ?? []) {+ upsertModel(db, model);+ result.models++;+ }+ if (parsed.data.fallback) {+ result.fallback = applyFallback(db, parsed.data.fallback);+ }+ if (parsed.data.routing) {+ if (parsed.data.routing.weights) setCustomWeights(parsed.data.routing.weights);+ setRoutingStrategy(parsed.data.routing.strategy);+ result.routing = true;+ }+ });+ apply();+ return result;+}++export function applyDeclarativeConfigFromEnv(): DeclarativeConfigResult {+ const loaded = readConfigFromEnv();+ if (!loaded) {+ return { applied: false, keys: 0, customModels: 0, models: 0, fallback: 0, routing: false };+ }+ const result = applyDeclarativeConfig(loaded.value, loaded.source);+ console.log(+ `[config] applied ${loaded.source}: ${result.keys} keys, ${result.customModels} custom models, ` ++ `${result.models} model edits, ${result.fallback} fallback rows${result.routing ? ', routing' : ''}`,+ );+ return result;+}diff --git a/server/src/services/model-state.ts b/server/src/services/model-state.tsnew file mode 100644index 00000000..9e42e519--- /dev/null+++ b/server/src/services/model-state.ts@@ -0,0 +1,192 @@+import type Database from 'better-sqlite3';++export type CatalogModelKind = 'chat' | 'media';++export interface ModelOverridePatch {+ displayName?: string;+ intelligenceRank?: number;+ speedRank?: number;+ sizeLabel?: string;+ rpmLimit?: number | null;+ rpdLimit?: number | null;+ tpmLimit?: number | null;+ tpdLimit?: number | null;+ monthlyTokenBudget?: string;+ contextWindow?: number | null;+ supportsVision?: boolean;+ supportsTools?: boolean;+}++type StoredOverrides = Partial<ModelOverridePatch>;++const OVERRIDE_COLUMNS: Record<keyof ModelOverridePatch, string> = {+ displayName: 'display_name',+ intelligenceRank: 'intelligence_rank',+ speedRank: 'speed_rank',+ sizeLabel: 'size_label',+ rpmLimit: 'rpm_limit',+ rpdLimit: 'rpd_limit',+ tpmLimit: 'tpm_limit',+ tpdLimit: 'tpd_limit',+ monthlyTokenBudget: 'monthly_token_budget',+ contextWindow: 'context_window',+ supportsVision: 'supports_vision',+ supportsTools: 'supports_tools',+};++function parseOverrides(raw: string | undefined): StoredOverrides {+ if (!raw) return {};+ try {+ const parsed = JSON.parse(raw) as unknown;+ return parsed && typeof parsed === 'object' ? parsed as StoredOverrides : {};+ } catch {+ return {};+ }+}++function toDbValue(key: keyof ModelOverridePatch, value: unknown): unknown {+ if (key === 'supportsVision' || key === 'supportsTools') return value ? 1 : 0;+ return value;+}++function cleanPatch(patch: ModelOverridePatch): StoredOverrides {+ const cleaned: StoredOverrides = {};+ for (const key of Object.keys(OVERRIDE_COLUMNS) as Array<keyof ModelOverridePatch>) {+ if (Object.prototype.hasOwnProperty.call(patch, key)) {+ cleaned[key] = patch[key] as never;+ }+ }+ return cleaned;+}++export function isCatalogManagedModel(row: { platform: string; key_id?: number | null }): boolean {+ return row.platform !== 'custom' && row.key_id == null;+}++export function isCatalogModelTombstoned(+ db: Database.Database,+ kind: CatalogModelKind,+ platform: string,+ modelId: string,+): boolean {+ return !!db+ .prepare('SELECT 1 FROM catalog_model_tombstones WHERE kind = ? AND platform = ? AND model_id = ?')+ .get(kind, platform, modelId);+}++export function recordCatalogModelTombstone(+ db: Database.Database,+ kind: CatalogModelKind,+ platform: string,+ modelId: string,+): void {+ db.prepare(`+ INSERT INTO catalog_model_tombstones (kind, platform, model_id)+ VALUES (?, ?, ?)+ ON CONFLICT(kind, platform, model_id) DO UPDATE SET created_at = datetime('now')+ `).run(kind, platform, modelId);+ if (kind === 'chat') {+ db.prepare('DELETE FROM model_overrides WHERE platform = ? AND model_id = ?').run(platform, modelId);+ }+}++export function clearCatalogModelTombstone(+ db: Database.Database,+ kind: CatalogModelKind,+ platform: string,+ modelId: string,+): void {+ db.prepare('DELETE FROM catalog_model_tombstones WHERE kind = ? AND platform = ? AND model_id = ?')+ .run(kind, platform, modelId);+}++export function upsertModelOverrides(+ db: Database.Database,+ platform: string,+ modelId: string,+ patch: ModelOverridePatch,+): StoredOverrides {+ const cleaned = cleanPatch(patch);+ if (Object.keys(cleaned).length === 0) return {};+ const existing = db+ .prepare('SELECT overrides_json FROM model_overrides WHERE platform = ? AND model_id = ?')+ .get(platform, modelId) as { overrides_json: string } | undefined;+ const merged: StoredOverrides = { ...parseOverrides(existing?.overrides_json), ...cleaned };+ db.prepare(`+ INSERT INTO model_overrides (platform, model_id, overrides_json, updated_at)+ VALUES (?, ?, ?, datetime('now'))+ ON CONFLICT(platform, model_id)+ DO UPDATE SET overrides_json = excluded.overrides_json, updated_at = excluded.updated_at+ `).run(platform, modelId, JSON.stringify(merged));+ return merged;+}++export function getModelOverrides(+ db: Database.Database,+ platform: string,+ modelId: string,+): StoredOverrides {+ const row = db+ .prepare('SELECT overrides_json FROM model_overrides WHERE platform = ? AND model_id = ?')+ .get(platform, modelId) as { overrides_json: string } | undefined;+ return parseOverrides(row?.overrides_json);+}++export function applyModelOverrides(+ db: Database.Database,+ platform: string,+ modelId: string,+): boolean {+ const overrides = getModelOverrides(db, platform, modelId);+ const keys = Object.keys(overrides) as Array<keyof ModelOverridePatch>;+ if (keys.length === 0) return false;++ const assignments: string[] = [];+ const values: unknown[] = [];+ for (const key of keys) {+ assignments.push(`${OVERRIDE_COLUMNS[key]} = ?`);+ values.push(toDbValue(key, overrides[key]));+ }+ values.push(platform, modelId);+ db.prepare(`UPDATE models SET ${assignments.join(', ')} WHERE platform = ? AND model_id = ?`).run(...values);+ return true;+}++export function applyAllModelOverrides(db: Database.Database): number {+ const rows = db.prepare('SELECT platform, model_id FROM model_overrides').all() as { platform: string; model_id: string }[];+ let applied = 0;+ for (const row of rows) {+ if (applyModelOverrides(db, row.platform, row.model_id)) applied++;+ }+ return applied;+}++export function deleteTombstonedCatalogModels(db: Database.Database): number {+ const chatRows = db.prepare(`+ SELECT m.id, m.platform, m.model_id+ FROM models m+ JOIN catalog_model_tombstones t+ ON t.kind = 'chat' AND t.platform = m.platform AND t.model_id = m.model_id+ WHERE m.platform != 'custom' AND m.key_id IS NULL+ `).all() as { id: number; platform: string; model_id: string }[];+ const mediaRows = db.prepare(`+ SELECT mm.id+ FROM media_models mm+ JOIN catalog_model_tombstones t+ ON t.kind = 'media' AND t.platform = mm.platform AND t.model_id = mm.model_id+ `).all() as { id: number }[];++ const deleteChatFallback = db.prepare('DELETE FROM fallback_config WHERE model_db_id = ?');+ const deleteChat = db.prepare('DELETE FROM models WHERE id = ?');+ const deleteMedia = db.prepare('DELETE FROM media_models WHERE id = ?');++ for (const row of chatRows) {+ deleteChatFallback.run(row.id);+ deleteChat.run(row.id);+ }+ for (const row of mediaRows) {+ deleteMedia.run(row.id);+ }++ return chatRows.length + mediaRows.length;+}