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
13.3 KB
Raw Blame
import fs from 'fs';
import os from 'os';
import path from 'path';
import Database from 'better-sqlite3';
import { afterEach, describe, expect, it, vi } from 'vitest';
import { backupDbNow, parseHuggingFaceTarget, restoreDbBackupIfNeeded } from '../../lib/db-backup.js';
import { aclEntries } from '../helpers/acl.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_BACKUP_TOKEN = process.env.FREEAPI_DB_BACKUP_TOKEN;
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_BACKUP_TOKEN === undefined) delete process.env.FREEAPI_DB_BACKUP_TOKEN;
  else process.env.FREEAPI_DB_BACKUP_TOKEN = ORIGINAL_BACKUP_TOKEN;
  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();
  });
});

describe('backup file permissions', () => {
  // The blob is AES-256-GCM encrypted and the restored file is a plain SQLite
  // database, but both live on a host that also holds the key — usually in a
  // .env in the same tree — so neither may be left world-readable.
  //
  // As elsewhere, each platform asserts what it can actually enforce: Node
  // synthesizes a 0o666 mode on Windows regardless of the ACL, so a POSIX-mode
  // assertion there would pass or fail for reasons unrelated to the guarantee.
  const isWindows = process.platform === 'win32';
  const itPosix = it.skipIf(isWindows);
  const itWindows = it.skipIf(!isWindows);

  afterEach(() => restoreEnv());

  async function backupInto(dir: string): Promise<string> {
    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)');
    await backupDbNow(db, dbPath);
    db.close();
    return backupPath;
  }

  itPosix('writes the backup blob owner-only', async () => {
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-backup-perms-'));
    const backupPath = await backupInto(dir);

    expect(fs.statSync(backupPath).mode & 0o077).toBe(0);
  });

  itPosix('tightens a backup target that already existed', async () => {
    // writeFileSync's mode argument only applies when the file is created, so
    // every backup after the first overwrites a file that keeps whatever mode
    // it already had. Without the explicit restrict call this is the case that
    // stays group-readable forever.
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-backup-perms-'));
    const backupPath = path.join(dir, 'backup.bin');
    fs.writeFileSync(backupPath, 'stale');
    // chmod rather than a creation mode: the mode argument is filtered through
    // the runner's umask, so a strict umask would leave this pre-condition
    // asserting the very thing it means to rule out.
    fs.chmodSync(backupPath, 0o644);
    expect(fs.statSync(backupPath).mode & 0o077).not.toBe(0);

    await backupInto(dir);

    expect(fs.statSync(backupPath).mode & 0o077).toBe(0);
  });

  itPosix('writes the restored database owner-only', async () => {
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-backup-perms-'));
    const dbPath = path.join(dir, 'freeapi.db');
    await backupInto(dir);
    fs.rmSync(dbPath);

    // The restore lands before connectDb runs, and sometimes in a different
    // process entirely; the decrypted database must not be readable in between.
    expect((await restoreDbBackupIfNeeded(dbPath)).restored).toBe(true);
    expect(fs.statSync(dbPath).mode & 0o077).toBe(0);
  });

  itWindows('replaces the inherited ACL on the backup blob', async () => {
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-backup-perms-'));
    const backupPath = await backupInto(dir);

    const entries = aclEntries(backupPath);
    expect(entries.filter(e => e.includes('(I)'))).toEqual([]);
    expect(entries).toHaveLength(3);
  });
});

describe('parseHuggingFaceTarget', () => {
  it('maps a dataset download URL onto the commit API', () => {
    expect(parseHuggingFaceTarget('https://huggingface.co/datasets/acme/state/resolve/main/backups/freeapi.db.enc')).toEqual({
      commitUrl: 'https://huggingface.co/api/datasets/acme/state/commit/main',
      filePath: 'backups/freeapi.db.enc',
    });
  });

  it('treats the prefix-less repo path as a model repo', () => {
    expect(parseHuggingFaceTarget('https://huggingface.co/acme/state/resolve/main/freeapi.db.enc')).toEqual({
      commitUrl: 'https://huggingface.co/api/models/acme/state/commit/main',
      filePath: 'freeapi.db.enc',
    });
  });

  it('maps a space download URL', () => {
    expect(parseHuggingFaceTarget('https://huggingface.co/spaces/acme/app/resolve/main/data/freeapi.db.enc')?.commitUrl)
      .toBe('https://huggingface.co/api/spaces/acme/app/commit/main');
  });

  it('leaves every other target alone', () => {
    expect(parseHuggingFaceTarget('https://example.com/acme/state/resolve/main/freeapi.db.enc')).toBeNull();
    // A HF URL that is not a /resolve/ download has no commit route to derive.
    expect(parseHuggingFaceTarget('https://huggingface.co/acme/state')).toBeNull();
    expect(parseHuggingFaceTarget('/var/backups/freeapi.db.enc')).toBeNull();
  });
});

describe('Hugging Face backup target', () => {
  // The /resolve/ URL a HF repo serves downloads from is read-only: the PUT this
  // used to send was answered 404 and the blob never landed, so an ephemeral
  // host restored nothing on its next cold start. Uploads go through the commit
  // API, and the blob travels as base64 text because repos on Xet storage reject
  // binary pushed through that route.
  const TARGET = 'https://huggingface.co/datasets/acme/state/resolve/main/backups/freeapi.db.enc';

  afterEach(() => {
    vi.unstubAllGlobals();
    restoreEnv();
  });

  function seedDb(dir: string): string {
    const dbPath = path.join(dir, 'freeapi.db');
    const db = new Database(dbPath);
    db.exec('CREATE TABLE items (name TEXT NOT NULL); INSERT INTO items (name) VALUES (\'survived\')');
    db.close();
    return dbPath;
  }

  it('uploads through the commit API as base64 and restores it', async () => {
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-hf-backup-'));
    const dbPath = seedDb(dir);
    process.env.ENCRYPTION_KEY = 'a'.repeat(64);
    process.env.FREEAPI_DB_BACKUP_TARGET = TARGET;
    process.env.FREEAPI_DB_BACKUP_TOKEN = 'hf_token';

    let stored = '';
    const fetchMock = vi.fn(async (url: string, init: RequestInit) => {
      if (init.method === 'POST') {
        stored = String(init.body);
        return new Response('{}', { status: 200 });
      }
      return new Response(stored, { status: 200 });
    });
    vi.stubGlobal('fetch', fetchMock);

    const db = new Database(dbPath);
    expect((await backupDbNow(db, dbPath)).ok).toBe(true);
    db.close();

    const [uploadUrl, uploadInit] = fetchMock.mock.calls[0] as [string, RequestInit];
    expect(uploadUrl).toBe('https://huggingface.co/api/datasets/acme/state/commit/main');
    expect(uploadInit.method).toBe('POST');
    expect((uploadInit.headers as Record<string, string>)['Content-Type']).toBe('application/x-ndjson');
    expect((uploadInit.headers as Record<string, string>).Authorization).toBe('Bearer hf_token');

    const [header, file] = String(uploadInit.body).split('\n').map(line => JSON.parse(line));
    expect(header).toEqual({ key: 'header', value: { summary: 'chore: update backups/freeapi.db.enc' } });
    expect(file.key).toBe('file');
    expect(file.value.path).toBe('backups/freeapi.db.enc');
    // Base64 text, not bytes — 'base64' here would make HF write the binary back.
    expect(file.value.encoding).toBe('utf-8');
    expect(file.value.content).toMatch(/^[A-Za-z0-9+/]+={0,2}$/);
    expect(file.value.content).not.toContain('survived');

    // What HF serves back from /resolve/ is that base64 text; the restore has to
    // decode it before it is a database again.
    stored = file.value.content;
    fs.rmSync(dbPath);
    expect((await restoreDbBackupIfNeeded(dbPath)).restored).toBe(true);

    const restored = new Database(dbPath);
    expect((restored.prepare('SELECT name FROM items').get() as { name: string }).name).toBe('survived');
    restored.close();
  });

  it('still restores a blob that was stored raw', async () => {
    // Anything a previous build managed to land is raw ciphertext. Sniffing the
    // magic header keeps that path recoverable instead of base64-decoding it
    // into garbage.
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-hf-legacy-'));
    const dbPath = seedDb(dir);
    const blobPath = path.join(dir, 'backup.bin');
    process.env.ENCRYPTION_KEY = 'a'.repeat(64);
    process.env.FREEAPI_DB_BACKUP_PATH = blobPath;

    const db = new Database(dbPath);
    await backupDbNow(db, dbPath);
    db.close();
    const raw = fs.readFileSync(blobPath);

    delete process.env.FREEAPI_DB_BACKUP_PATH;
    process.env.FREEAPI_DB_BACKUP_TARGET = TARGET;
    vi.stubGlobal('fetch', vi.fn(async () => new Response(raw, { status: 200 })));

    fs.rmSync(dbPath);
    expect((await restoreDbBackupIfNeeded(dbPath)).restored).toBe(true);
    const restored = new Database(dbPath);
    expect((restored.prepare('SELECT name FROM items').get() as { name: string }).name).toBe('survived');
    restored.close();
  });

  it('refuses to upload without a token rather than 401ing on a schedule', async () => {
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-hf-token-'));
    const dbPath = seedDb(dir);
    process.env.ENCRYPTION_KEY = 'a'.repeat(64);
    process.env.FREEAPI_DB_BACKUP_TARGET = TARGET;
    delete process.env.FREEAPI_DB_BACKUP_TOKEN;

    const fetchMock = vi.fn();
    vi.stubGlobal('fetch', fetchMock);

    const db = new Database(dbPath);
    await expect(backupDbNow(db, dbPath)).rejects.toThrow(/FREEAPI_DB_BACKUP_TOKEN is required/);
    db.close();
    expect(fetchMock).not.toHaveBeenCalled();
  });

  it('surfaces a rejected commit', async () => {
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-hf-error-'));
    const dbPath = seedDb(dir);
    process.env.ENCRYPTION_KEY = 'a'.repeat(64);
    process.env.FREEAPI_DB_BACKUP_TARGET = TARGET;
    process.env.FREEAPI_DB_BACKUP_TOKEN = 'hf_token';
    vi.stubGlobal('fetch', vi.fn(async () => new Response('repo not found', { status: 404 })));

    const db = new Database(dbPath);
    await expect(backupDbNow(db, dbPath)).rejects.toThrow(/HF commit HTTP 404 — repo not found/);
    db.close();
  });

  it('leaves a plain HTTP target on the PUT path', async () => {
    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'freeapi-http-backup-'));
    const dbPath = seedDb(dir);
    process.env.ENCRYPTION_KEY = 'a'.repeat(64);
    process.env.FREEAPI_DB_BACKUP_TARGET = 'https://storage.example.com/freeapi.db.enc';
    process.env.FREEAPI_DB_BACKUP_TOKEN = 'plain_token';

    const fetchMock = vi.fn(async () => new Response('', { status: 200 }));
    vi.stubGlobal('fetch', fetchMock);

    const db = new Database(dbPath);
    expect((await backupDbNow(db, dbPath)).ok).toBe(true);
    db.close();

    const [url, init] = fetchMock.mock.calls[0] as unknown as [string, RequestInit];
    expect(url).toBe('https://storage.example.com/freeapi.db.enc');
    expect(init.method).toBe('PUT');
    expect((init.headers as Record<string, string>)['Content-Type']).toBe('application/octet-stream');
    expect(Buffer.isBuffer(init.body)).toBe(true);
  });
});