Skip to content

A full-featured download manager.

9.4 KB
Raw Blame
// Per-plugin per-task metadata store backed by SQLite (better-sqlite3).
// Each value is JSON-serialized; binary is not supported at this layer.
// Access is scoped per (taskId, pluginId) pair — plugins cannot read each
// other's metadata for the same task.
//
// Quota: 64 KB per (plugin_id, task_id) pair (default; overridable in
// constructor). Enforced via a pre-flight SUM(size) check before every write.
// `size` = Buffer.byteLength(json, 'utf8') for the incoming value.
//
// Schema bootstrap: call `ensureMetadataSchema(db)` once at startup.
//   Task 18 factory (createElectronCapabilityHost / createServerCapabilityHost)
//   is responsible for calling this.
//   `deleteAllForTask` is intended to be called when a download task is
//   removed, so metadata is cleaned up across all plugins.
//   Plan C hook context integration will wire taskId from hook invocation.

import type Database from 'better-sqlite3'

// ---------------------------------------------------------------------------
// Schema bootstrap
// ---------------------------------------------------------------------------

export function ensureMetadataSchema(db: Database.Database): void {
  db.exec(`
    CREATE TABLE IF NOT EXISTS plugin_task_metadata (
      task_id    TEXT NOT NULL,
      plugin_id  TEXT NOT NULL,
      key        TEXT NOT NULL,
      value      TEXT NOT NULL,
      size       INTEGER NOT NULL,
      updated_at INTEGER NOT NULL,
      PRIMARY KEY (task_id, plugin_id, key)
    );
    CREATE INDEX IF NOT EXISTS idx_plugin_task_metadata_task
      ON plugin_task_metadata(task_id);
  `)
}

// ---------------------------------------------------------------------------
// Error class
// ---------------------------------------------------------------------------

export class MetadataError extends Error {
  constructor(
    public readonly code: string,
    message: string
  ) {
    super(message)
    this.name = 'MetadataError'
  }
}

// ---------------------------------------------------------------------------
// Internal helpers
// ---------------------------------------------------------------------------

export const DEFAULT_METADATA_QUOTA_BYTES = 64 << 10 // 64 KiB

/**
 * Serialize `value` to JSON.
 * Throws `plugin.metadata.value_not_serializable` when:
 *  - the value is top-level `undefined`
 *  - JSON.stringify returns undefined (e.g. a plain function)
 *  - JSON.stringify throws (e.g. BigInt, class with throwing toJSON)
 */
export function serializeMetadataValue(value: unknown): string {
  if (value === undefined) {
    throw new MetadataError(
      'plugin.metadata.value_not_serializable',
      'plugin.metadata.value_not_serializable: undefined is not JSON-serializable'
    )
  }
  let json: string | undefined
  try {
    json = JSON.stringify(value)
  } catch {
    throw new MetadataError(
      'plugin.metadata.value_not_serializable',
      'plugin.metadata.value_not_serializable: value cannot be serialized to JSON'
    )
  }
  if (json === undefined) {
    throw new MetadataError(
      'plugin.metadata.value_not_serializable',
      'plugin.metadata.value_not_serializable: value cannot be serialized to JSON'
    )
  }
  return json
}

// ---------------------------------------------------------------------------
// MetadataCapabilityHost
// ---------------------------------------------------------------------------

export class MetadataCapabilityHost {
  private readonly db: Database.Database
  private readonly perPluginPerTaskBytes: number

  constructor(opts: {
    db: Database.Database
    perPluginPerTaskBytes?: number
  }) {
    this.db = opts.db
    this.perPluginPerTaskBytes =
      opts.perPluginPerTaskBytes ?? DEFAULT_METADATA_QUOTA_BYTES
  }

  // -------------------------------------------------------------------------
  // Quota pre-flight
  // -------------------------------------------------------------------------

  private assertQuota(
    taskId: string,
    pluginId: string,
    key: string,
    projectedSize: number
  ): void {
    const totRow = this.db
      .prepare<[string, string], { total: number }>(
        `SELECT COALESCE(SUM(size), 0) AS total
         FROM plugin_task_metadata
         WHERE task_id = ? AND plugin_id = ?`
      )
      .get(taskId, pluginId) ?? { total: 0 }

    const curRow = this.db
      .prepare<[string, string, string], { size: number } | undefined>(
        `SELECT size FROM plugin_task_metadata
         WHERE task_id = ? AND plugin_id = ? AND key = ?`
      )
      .get(taskId, pluginId, key)

    const currentSize = curRow?.size ?? 0
    const projected = totRow.total - currentSize + projectedSize

    if (projected > this.perPluginPerTaskBytes) {
      throw new MetadataError(
        'plugin.metadata.quota_exceeded',
        `plugin.metadata.quota_exceeded: projected usage ${projected} exceeds quota ${this.perPluginPerTaskBytes}`
      )
    }
  }

  // -------------------------------------------------------------------------
  // get
  // -------------------------------------------------------------------------

  async get(taskId: string, pluginId: string, key: string): Promise<unknown> {
    const row = this.db
      .prepare<[string, string, string], { value: string } | undefined>(
        `SELECT value FROM plugin_task_metadata
         WHERE task_id = ? AND plugin_id = ? AND key = ?`
      )
      .get(taskId, pluginId, key)

    if (!row) return undefined
    return JSON.parse(row.value) as unknown
  }

  // -------------------------------------------------------------------------
  // has
  // -------------------------------------------------------------------------

  async has(taskId: string, pluginId: string, key: string): Promise<boolean> {
    const row = this.db
      .prepare<[string, string, string], { found: number } | undefined>(
        `SELECT 1 AS found FROM plugin_task_metadata
         WHERE task_id = ? AND plugin_id = ? AND key = ?`
      )
      .get(taskId, pluginId, key)

    return row !== undefined
  }

  // -------------------------------------------------------------------------
  // getAll
  // -------------------------------------------------------------------------

  async getAll(
    taskId: string,
    pluginId: string
  ): Promise<Record<string, unknown>> {
    const rows = this.db
      .prepare<[string, string], { key: string; value: string }>(
        `SELECT key, value FROM plugin_task_metadata
         WHERE task_id = ? AND plugin_id = ?`
      )
      .all(taskId, pluginId)

    return Object.fromEntries(
      rows.map((r) => [r.key, JSON.parse(r.value) as unknown])
    )
  }

  // -------------------------------------------------------------------------
  // keys
  // -------------------------------------------------------------------------

  async keys(taskId: string, pluginId: string): Promise<string[]> {
    const rows = this.db
      .prepare<[string, string], { key: string }>(
        `SELECT key FROM plugin_task_metadata
         WHERE task_id = ? AND plugin_id = ?
         ORDER BY key ASC`
      )
      .all(taskId, pluginId)

    return rows.map((r) => r.key)
  }

  // -------------------------------------------------------------------------
  // set (unconditional upsert)
  // -------------------------------------------------------------------------

  async set(
    taskId: string,
    pluginId: string,
    key: string,
    value: unknown
  ): Promise<void> {
    const json = serializeMetadataValue(value)
    const size = Buffer.byteLength(json, 'utf8')
    this.assertQuota(taskId, pluginId, key, size)

    const now = Date.now()
    this.db
      .prepare<[string, string, string, string, number, number]>(
        `INSERT INTO plugin_task_metadata
           (task_id, plugin_id, key, value, size, updated_at)
         VALUES (?, ?, ?, ?, ?, ?)
         ON CONFLICT (task_id, plugin_id, key) DO UPDATE SET
           value      = excluded.value,
           size       = excluded.size,
           updated_at = excluded.updated_at`
      )
      .run(taskId, pluginId, key, json, size, now)
  }

  // -------------------------------------------------------------------------
  // delete
  // -------------------------------------------------------------------------

  async delete(
    taskId: string,
    pluginId: string,
    key: string
  ): Promise<{ deleted: boolean }> {
    const result = this.db
      .prepare<[string, string, string]>(
        `DELETE FROM plugin_task_metadata
         WHERE task_id = ? AND plugin_id = ? AND key = ?`
      )
      .run(taskId, pluginId, key)

    return { deleted: result.changes > 0 }
  }

  // -------------------------------------------------------------------------
  // deleteAllForTask
  // -------------------------------------------------------------------------

  async deleteAllForTask(taskId: string): Promise<{ deleted: number }> {
    const result = this.db
      .prepare<[string]>(`DELETE FROM plugin_task_metadata WHERE task_id = ?`)
      .run(taskId)

    return { deleted: result.changes }
  }

  // -------------------------------------------------------------------------
  // deleteAllForPlugin (uninstall cascade — I14)
  // -------------------------------------------------------------------------

  // Called by PluginInstaller.uninstall: drops every row written by this
  // plugin across all tasks.
  async deleteAllForPlugin(pluginId: string): Promise<{ deleted: number }> {
    const result = this.db
      .prepare<[string]>(`DELETE FROM plugin_task_metadata WHERE plugin_id = ?`)
      .run(pluginId)
    return { deleted: result.changes }
  }
}