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

Bring the desktop boot sequence up to server parity and bump to 0.8.7 (#1017)

Tashfeen4774cf02a4e6
diff --git a/desktop/package-lock.json b/desktop/package-lock.json
index a63e16cb..e3c45de0 100644
--- a/desktop/package-lock.json
+++ b/desktop/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "freellmapi-desktop",
- "version": "0.8.6",
+ "version": "0.8.7",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "freellmapi-desktop",
- "version": "0.8.6",
+ "version": "0.8.7",
"dependencies": {
"better-sqlite3": "^12.10.0"
},
diff --git a/desktop/package.json b/desktop/package.json
index 0876e67a..02d142ac 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -1,6 +1,6 @@
{
"name": "freellmapi-desktop",
- "version": "0.8.6",
+ "version": "0.8.7",
"description": "FreeLLMAPI menu-bar app — local OpenAI-compatible LLM router",
"author": {
"name": "tashfeenahmed",
diff --git a/desktop/src/__tests__/server-host-boot.test.ts b/desktop/src/__tests__/server-host-boot.test.ts
index 7984a7c1..9eb30f75 100644
--- a/desktop/src/__tests__/server-host-boot.test.ts
+++ b/desktop/src/__tests__/server-host-boot.test.ts
@@ -1,3 +1,5 @@
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { EventEmitter } from 'node:events';
@@ -27,6 +29,53 @@ vi.mock('../../../server/src/lib/proxy.js', () => ({
restoreProxySettings: vi.fn(() => {
calls.push('restoreProxySettings');
}),
+ flushProxyCache: vi.fn(),
+}));
+
+vi.mock('../../../server/src/lib/log-redaction.js', () => ({
+ installLogRedaction: vi.fn(() => {
+ calls.push('installLogRedaction');
+ return () => undefined;
+ }),
+}));
+
+vi.mock('../../../server/src/lib/process-safety-net.js', () => ({
+ installProcessSafetyNet: vi.fn(() => {
+ calls.push('installProcessSafetyNet');
+ }),
+}));
+
+vi.mock('../../../server/src/services/ratelimit.js', () => ({
+ cleanupExpiredCooldowns: vi.fn(() => {
+ calls.push('cleanupExpiredCooldowns');
+ return 0;
+ }),
+}));
+
+vi.mock('../../../server/src/services/cooldown-probe.js', () => ({
+ startCooldownProbe: vi.fn(() => {
+ calls.push('startCooldownProbe');
+ }),
+}));
+
+vi.mock('../../../server/src/services/backups.js', () => ({
+ startBackupScheduler: vi.fn(() => {
+ calls.push('startBackupScheduler');
+ return () => undefined;
+ }),
+}));
+
+vi.mock('../../../server/src/services/custom-model-sync.js', () => ({
+ startCustomModelSync: vi.fn(() => {
+ calls.push('startCustomModelSync');
+ return null;
+ }),
+}));
+
+vi.mock('../../../server/src/lib/wake-detect.js', () => ({
+ startWakeDetect: vi.fn(() => {
+ calls.push('startWakeDetect');
+ }),
}));
vi.mock('../../../server/src/app.js', () => ({
@@ -47,6 +96,7 @@ vi.mock('../../../server/src/services/health.js', () => ({
startHealthChecker: vi.fn(() => {
calls.push('startHealthChecker');
}),
+ checkAllKeys: vi.fn(async () => ({})),
}));
vi.mock('../../../server/src/services/catalog-sync.js', () => ({
@@ -100,12 +150,51 @@ describe('desktop server boot sequence (#949)', () => {
it('runs the whole startup in the order server/src/index.ts uses', async () => {
await boot();
expect(calls).toEqual([
+ 'installLogRedaction',
+ 'installProcessSafetyNet',
'initDb',
+ 'cleanupExpiredCooldowns',
'restoreProxySettings',
'createApp',
'listen',
'startHealthChecker',
'startCatalogSync',
+ 'startCooldownProbe',
+ 'startBackupScheduler',
+ 'startCustomModelSync',
+ 'startWakeDetect',
]);
});
+
+ // The literal list above froze an incomplete sequence once already: it was
+ // written for #949 with six steps and then green-lit eight later omissions,
+ // including startBackupScheduler — the Backups page saved a schedule that
+ // never fired. So derive the required steps from the index.ts source instead
+ // of trusting anyone to update both places.
+ it('mirrors every startup step server/src/index.ts performs (minus the documented env-only skips)', async () => {
+ const indexSrc = fs.readFileSync(
+ fileURLToPath(new URL('../../../server/src/index.ts', import.meta.url)),
+ 'utf8',
+ );
+ const withoutComments = indexSrc
+ .replace(/\/\*[\s\S]*?\*\//g, '')
+ .replace(/\/\/[^\n]*/g, '');
+ const steps = new Set(
+ [...withoutComments.matchAll(/\b((?:install|start|cleanup|restore)[A-Z]\w*)\(/g)].map((m) => m[1]),
+ );
+ // Env-gated (FREEAPI_DB_BACKUP_*): a GUI-launched packaged app inherits no
+ // shell environment, so these can never activate on desktop.
+ const SKIPPED = new Set(['restoreDbBackupIfNeeded', 'startDbBackupPump']);
+ // Regex sanity floor — an index.ts restructure must not blank this test.
+ expect(steps.size).toBeGreaterThanOrEqual(10);
+
+ await boot();
+ for (const step of steps) {
+ if (SKIPPED.has(step)) continue;
+ expect(
+ calls,
+ `server/src/index.ts calls ${step}() but the desktop embedder never does — add it to startServer() in server-host.ts`,
+ ).toContain(step);
+ }
+ });
});
diff --git a/desktop/src/i18n.ts b/desktop/src/i18n.ts
index fd21a808..8df5c73a 100644
--- a/desktop/src/i18n.ts
+++ b/desktop/src/i18n.ts
@@ -30,6 +30,7 @@ const STRINGS: Record<NativeLocale, Strings> = {
openDashboard: 'Open Dashboard',
lanAccess: 'Allow LAN access (0.0.0.0)',
openLogs: 'Open Logs Folder',
+ openBackups: 'Open Backups Folder',
quitApp: 'Quit FreeLLMAPI',
running: 'running',
requestsToday: 'Requests today',
@@ -51,6 +52,7 @@ const STRINGS: Record<NativeLocale, Strings> = {
openDashboard: '打开仪表板',
lanAccess: '允许局域网访问 (0.0.0.0)',
openLogs: '打开日志文件夹',
+ openBackups: '打开备份文件夹',
quitApp: '退出 FreeLLMAPI',
running: '运行中',
requestsToday: '今日请求',
@@ -72,6 +74,7 @@ const STRINGS: Record<NativeLocale, Strings> = {
openDashboard: 'Ouvrir le tableau de bord',
lanAccess: 'Autoriser l\'accès LAN (0.0.0.0)',
openLogs: 'Ouvrir le dossier des journaux',
+ openBackups: 'Ouvrir le dossier des sauvegardes',
quitApp: 'Quitter FreeLLMAPI',
running: 'en cours',
requestsToday: "Requêtes aujourd'hui",
@@ -93,6 +96,7 @@ const STRINGS: Record<NativeLocale, Strings> = {
openDashboard: 'Abrir el panel',
lanAccess: 'Permitir acceso LAN (0.0.0.0)',
openLogs: 'Abrir la carpeta de registros',
+ openBackups: 'Abrir la carpeta de copias de seguridad',
quitApp: 'Salir de FreeLLMAPI',
running: 'en ejecución',
requestsToday: 'Solicitudes hoy',
@@ -114,6 +118,7 @@ const STRINGS: Record<NativeLocale, Strings> = {
openDashboard: 'Abrir o painel',
lanAccess: 'Permitir acesso LAN (0.0.0.0)',
openLogs: 'Abrir a pasta de logs',
+ openBackups: 'Abrir a pasta de backups',
quitApp: 'Sair do FreeLLMAPI',
running: 'em execução',
requestsToday: 'Solicitações hoje',
@@ -135,6 +140,7 @@ const STRINGS: Record<NativeLocale, Strings> = {
openDashboard: 'Apri il pannello',
lanAccess: 'Consenti accesso LAN (0.0.0.0)',
openLogs: 'Apri la cartella dei log',
+ openBackups: 'Apri la cartella dei backup',
quitApp: 'Esci da FreeLLMAPI',
running: 'in esecuzione',
requestsToday: 'Richieste oggi',
diff --git a/desktop/src/logger.ts b/desktop/src/logger.ts
index 665fdf53..585b9eb8 100644
--- a/desktop/src/logger.ts
+++ b/desktop/src/logger.ts
@@ -123,3 +123,18 @@ export function openLogsFolder(): void {
console.warn('[desktop] could not open the logs folder:', err);
}
}
+
+// Tray → "Open Backups Folder". The server writes dumps to <db dir>/backups
+// (server/src/services/backups.ts dataDir()) and main.ts puts the DB at
+// <userData>/freeapi.db, so this is where they land — the dashboard's Backups
+// panel only ever shows paths relative to that directory, which a desktop
+// user has no other way to locate.
+export function openBackupsFolder(): void {
+ try {
+ const dir = path.join(app.getPath('userData'), 'backups');
+ fs.mkdirSync(dir, { recursive: true });
+ void shell.openPath(dir);
+ } catch (err) {
+ console.warn('[desktop] could not open the backups folder:', err);
+ }
+}
diff --git a/desktop/src/server-host.ts b/desktop/src/server-host.ts
index 983641ef..00a00109 100644
--- a/desktop/src/server-host.ts
+++ b/desktop/src/server-host.ts
@@ -11,9 +11,16 @@ import crypto from 'node:crypto';
import type { Server } from 'node:http';
import { createApp } from '../../server/src/app.js';
import { initDb, getDb, getUnifiedApiKey } from '../../server/src/db/index.js';
-import { restoreProxySettings } from '../../server/src/lib/proxy.js';
-import { startHealthChecker } from '../../server/src/services/health.js';
+import { restoreProxySettings, flushProxyCache } from '../../server/src/lib/proxy.js';
+import { startHealthChecker, checkAllKeys } from '../../server/src/services/health.js';
import { startCatalogSync } from '../../server/src/services/catalog-sync.js';
+import { startCooldownProbe } from '../../server/src/services/cooldown-probe.js';
+import { startCustomModelSync } from '../../server/src/services/custom-model-sync.js';
+import { startBackupScheduler } from '../../server/src/services/backups.js';
+import { cleanupExpiredCooldowns } from '../../server/src/services/ratelimit.js';
+import { startWakeDetect } from '../../server/src/lib/wake-detect.js';
+import { installProcessSafetyNet } from '../../server/src/lib/process-safety-net.js';
+import { installLogRedaction } from '../../server/src/lib/log-redaction.js';
import { userCount, createUser, createSession } from '../../server/src/services/auth.js';
import { NodeScheduler } from '../../server/src/lib/scheduler.js';
@@ -31,7 +38,44 @@ export interface ServerHandle {
port: number;
}
+// This function mirrors the boot sequence of server/src/index.ts — every
+// startup step index.ts performs has to be repeated here by hand (#949), and
+// __tests__/server-host-boot.test.ts cross-checks this list against the
+// index.ts source so the next step added there fails a desktop test instead
+// of silently never running (that is exactly how startBackupScheduler was
+// missed: the Backups page saved a schedule that never fired).
+//
+// Deliberately NOT mirrored, because they are env-driven and the packaged app
+// inherits no shell environment:
+// restoreDbBackupIfNeeded / startDbBackupPump (FREEAPI_DB_BACKUP_* only)
+// applyDeclarativeConfigFromEnv, warnOnEnvDrift, warnOnRoutingOverrideDrift
+// generateSetupCode (desktop mints its own user)
export async function startServer(opts: StartOptions): Promise<ServerHandle> {
+ // After main.ts's installFileLogger (which already wrapped console.*), so
+ // the redaction wrapper sits outermost and the tray-revealed log file gets
+ // the same credential-stripped lines a terminal would — users paste it into
+ // bug reports. This tap is also the ONLY feed of the dashboard's log viewer
+ // (#993): without it the Logs page renders near-empty on desktop. Must not
+ // run at module scope: main.ts imports this bundle before the file logger
+ // is installed, and wrapping in the other order would tee raw secrets to disk.
+ installLogRedaction();
+ // A late provider socket reset (undici emits with no listener) must down the
+ // request, not the whole menu-bar app.
+ installProcessSafetyNet();
+ // bundle-server.mjs stamps the build identity via esbuild `define`, which
+ // rewrites only the exact `process.env.X` member expressions in this bundle.
+ // routes/update.ts reads the values through a plain env object reference, so
+ // mirror the inlined literals into the real process.env — without this the
+ // packaged app's update check resolves {sha: null, installation: 'unknown'}
+ // and reports 'unsupported'.
+ const buildSha = process.env.FREELLMAPI_COMMIT_SHA;
+ const buildInstall = process.env.FREELLMAPI_INSTALL_METHOD;
+ if (buildSha && buildInstall) {
+ Object.assign(process.env, {
+ FREELLMAPI_COMMIT_SHA: buildSha,
+ FREELLMAPI_INSTALL_METHOD: buildInstall,
+ });
+ }
process.env.CLIENT_DIST = opts.clientDist;
// #786: the desktop build has no user-set password (the machine user's
// password is random and never shown), so password re-verification for
@@ -41,6 +85,12 @@ export async function startServer(opts: StartOptions): Promise<ServerHandle> {
// 0.0.0.0, and a remote viewer must still enter the password.
process.env.FREEAPI_DESKTOP = '1';
initDb(opts.dbPath);
+ // One sweep at boot, while the DB is quiet — expired cooldown rows are only
+ // collected lazily per route and would otherwise accumulate forever.
+ const expiredCooldowns = cleanupExpiredCooldowns();
+ if (expiredCooldowns > 0) {
+ console.log(`[ratelimit] cleared ${expiredCooldowns} expired cooldown${expiredCooldowns === 1 ? '' : 's'}`);
+ }
// #949: the standalone server hydrates its proxy state in index.ts after
// initDb; this embedder builds the app without index.ts, so without this
// the URL saved in the settings table is ignored on every restart and the
@@ -54,6 +104,25 @@ export async function startServer(opts: StartOptions): Promise<ServerHandle> {
const scheduler = new NodeScheduler();
startHealthChecker(scheduler);
startCatalogSync(scheduler);
+ startCooldownProbe(scheduler);
+ startBackupScheduler(scheduler);
+ startCustomModelSync(getDb(), scheduler);
+ // Post-sleep recovery — the menu-bar app on a laptop is the canonical
+ // lid-close case: flush pooled sockets and force-re-probe every key so the
+ // first request after wake doesn't ride a dead connection or a pre-sleep
+ // key status. Same hook as server/src/index.ts.
+ startWakeDetect({
+ async onWake(event) {
+ const idle = Math.round(event.idleMs / 1000);
+ console.log(`[wake] resumed after ~${idle}s (${event.reason}${event.signal ? `:${event.signal}` : ''}) — flushing stale sockets, re-probing keys`);
+ flushProxyCache();
+ try {
+ await checkAllKeys({ force: true });
+ } catch (err: any) {
+ console.error(`[wake] post-wake key re-probe failed: ${err?.message ?? err}`);
+ }
+ },
+ });
return { server, port };
}
diff --git a/desktop/src/tray.ts b/desktop/src/tray.ts
index 3ad742eb..2c39dd8c 100644
--- a/desktop/src/tray.ts
+++ b/desktop/src/tray.ts
@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
import { Tray, Menu, app, nativeImage } from 'electron';
import { togglePopover } from './popover.js';
import { openDashboard } from './window.js';
-import { openLogsFolder } from './logger.js';
+import { openLogsFolder, openBackupsFolder } from './logger.js';
import { dt, type NativeLocale } from './i18n.js';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -42,6 +42,9 @@ export function buildTray(
// #824: the password-reset code is printed to the log and nowhere else,
// so the folder holding it needs to be reachable without a terminal.
{ label: dt(locale, 'openLogs'), click: () => openLogsFolder() },
+ // Scheduled/manual backups land in <userData>/backups; the dashboard
+ // only shows relative paths, so the tray is the discovery point.
+ { label: dt(locale, 'openBackups'), click: () => openBackupsFolder() },
{ type: 'separator' },
{ label: dt(locale, 'quitApp'), click: () => app.quit() },
]));