feat(plugins): store plugin data on the engine TREK runs on

PLUGIN_DATA binds the plugin data backend to the engine (the same
{ sqlite, postgres }[engine.id] binding the backup port uses): the SQLite
file per plugin, unchanged, or the Postgres schema per plugin. The host
opens a plugin's store through it and an uninstall that deletes data erases
through it, which drops the schema on Postgres. Nothing outside db/engine
asks which engine runs.

A plugin's SQL is passed through as written, so a plugin needs to know the
dialect: db.engine (db:own) answers 'sqlite' or 'postgres', and the SDK
exposes it as ctx.db.engine(), in the mock host (dbEngine option) and in
dev. The plugin facts are regenerated and the SDK goes to 1.10.0.

The Postgres lane's PGPLUG suite installs, uses and erases plugin data on
Postgres and shows that a plugin reaches neither TREK's users table nor
another plugin's schema.
This commit is contained in:
Maurice
2026-11-17 13:00:47 +01:00
parent b144781e9f
commit 910c98b971
26 changed files with 574 additions and 44 deletions
+16 -8
View File
@@ -28,6 +28,7 @@ import type { LlmConfigResolver } from '../../../src/nest/llm-parse/llm-config.r
import type { NotificationsService } from '../../../src/nest/notifications/notifications.service';
import type { PermissionsService } from '../../../src/nest/permissions/permissions.service';
import { verifyChain } from '../../../src/nest/plugins/host/plugin-audit';
import { SqlitePluginDataBackend } from '../../../src/nest/plugins/host/plugin-data.backend';
import { getPluginDataDb, closePluginDataDb } from '../../../src/nest/plugins/host/plugin-host-state';
import { PluginRpcHostFactory, type PluginCallRouter } from '../../../src/nest/plugins/host/plugin-rpc-host.factory';
import { DbRpc } from '../../../src/nest/plugins/host/rpc/db.rpc';
@@ -416,7 +417,8 @@ const registry = createTestPluginRegistry([
uow,
),
]);
const factory = new PluginRpcHostFactory(pluginAuditRepo, registry as unknown as PluginRpcRegistryService);
const sqliteData = new SqlitePluginDataBackend();
const factory = new PluginRpcHostFactory(pluginAuditRepo, registry as unknown as PluginRpcRegistryService, sqliteData);
const stubRouter: PluginCallRouter = { callPlugin: async () => undefined, emitPluginEvent: async () => {} };
const makeHost = (id: string, ...perms: string[]) => factory.create(id, new Set(perms), stubRouter);
/**
@@ -457,7 +459,7 @@ afterAll(() => {
describe("DbRpc — the plugin's own sqlite", () => {
it('HOSTRPC-001 caches one data db per plugin id', () => {
expect(getPluginDataDb('wired')).toBe(getPluginDataDb('wired'));
expect(getPluginDataDb('wired', sqliteData)).toBe(getPluginDataDb('wired', sqliteData));
});
it('HOSTRPC-002 a granted db:own call runs against the plugin db', async () => {
@@ -482,13 +484,19 @@ describe("DbRpc — the plugin's own sqlite", () => {
closePluginDataDb('wtx');
});
it('HOSTRPC-004 without db:own not one of the four is reachable', async () => {
it('HOSTRPC-004 without db:own not one of the five is reachable', async () => {
const host = makeHost('wnogrant');
for (const method of ['db.query', 'db.exec', 'db.migrate', 'db.tx']) {
for (const method of ['db.query', 'db.exec', 'db.migrate', 'db.tx', 'db.engine']) {
expect((await call(host, method, { sql: 'SELECT 1', id: '1', ops: [] })).error?.code).toBe('PERMISSION_DENIED');
}
});
it('HOSTRPC-004b db.engine names the engine the plugin SQL runs on', async () => {
const host = makeHost('wengine', 'db:own');
expect((await call(host, 'db.engine', {})).result).toEqual({ engine: 'sqlite' });
closePluginDataDb('wengine');
});
it("HOSTRPC-005 two plugins never see each other's tables", async () => {
// The regression this guards: DbRpc is a SINGLETON that serves every plugin, so a
// handle captured in a field or a closure would hand plugin B the rows of whichever
@@ -508,20 +516,20 @@ describe("DbRpc — the plugin's own sqlite", () => {
});
it('HOSTRPC-006 a handle closed WITHOUT eviction is recreated, not reused dead', () => {
const a = getPluginDataDb('closedcache');
const a = getPluginDataDb('closedcache', sqliteData);
expect(a.isOpen()).toBe(true);
// The supervisor's dispose() path: close the handle but leave it cached.
a.close();
const b = getPluginDataDb('closedcache');
const b = getPluginDataDb('closedcache', sqliteData);
expect(b).not.toBe(a);
expect(b.isOpen()).toBe(true);
closePluginDataDb('closedcache');
});
it('HOSTRPC-007 closePluginDataDb drops the cached handle', () => {
const a = getPluginDataDb('transient');
const a = getPluginDataDb('transient', sqliteData);
closePluginDataDb('transient');
const b = getPluginDataDb('transient');
const b = getPluginDataDb('transient', sqliteData);
expect(a).not.toBe(b);
closePluginDataDb('transient');
});
@@ -0,0 +1,104 @@
/**
* The plugin data port (src/nest/plugins/host/plugin-data.backend.ts): the
* backend `PLUGIN_DATA` binds is the engine's, the SQLite one keeps a file per
* plugin, and the Postgres one opens a schema store and writes no SQLite file.
* The Postgres store against a real database is the Postgres lane's
* tests/postgres/plugin-data.test.ts.
*/
import type { DbSettings } from '../../../src/app-config';
import type { DatabaseEngine } from '../../../src/db/engine';
import { PostgresPluginDataStore } from '../../../src/db/engine/postgres/plugin-data-store';
import {
PLUGIN_DATA,
PLUGIN_DATA_PROVIDERS,
PostgresPluginDataBackend,
SqlitePluginDataBackend,
} from '../../../src/nest/plugins/host/plugin-data.backend';
import { PluginDataDb } from '../../../src/nest/plugins/host/plugin-data.service';
import type { MikroORM } from '@mikro-orm/core';
import type { FactoryProvider } from '@nestjs/common';
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { afterAll, beforeAll, describe, expect, it } from 'vitest';
let tmp: string;
beforeAll(() => {
tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'trek-plugin-data-port-'));
process.env.TREK_PLUGINS_DATA_DIR = tmp;
});
afterAll(() => {
delete process.env.TREK_PLUGINS_DATA_DIR;
fs.rmSync(tmp, { recursive: true, force: true });
});
/** An ORM whose Kysely client records the SQL it is handed. */
function fakeOrm(executed: string[]): MikroORM {
const client = {
executeQuery: async (query: { sql: string }) => {
executed.push(query.sql);
return { rows: [] };
},
};
return { em: { getConnection: () => ({ getClient: () => client }) } } as unknown as MikroORM;
}
const POSTGRES = { engine: 'postgres', url: 'postgres://trek@db/trek', poolMax: 4 } as unknown as DbSettings;
const SQLITE = { engine: 'sqlite' } as unknown as DbSettings;
describe('plugin data port', () => {
it('PLUGDATA-001: PLUGIN_DATA is the backend of the engine TREK runs on', () => {
const binding = PLUGIN_DATA_PROVIDERS.find(
(p): p is FactoryProvider => typeof p === 'object' && 'provide' in p && p.provide === PLUGIN_DATA,
);
expect(binding).toBeDefined();
const sqlite = new SqlitePluginDataBackend();
const postgres = new PostgresPluginDataBackend(fakeOrm([]), POSTGRES);
const pick = (id: 'sqlite' | 'postgres') => binding?.useFactory({ id } as DatabaseEngine, sqlite, postgres);
expect(pick('sqlite')).toBe(sqlite);
expect(pick('postgres')).toBe(postgres);
expect(sqlite.engine).toBe('sqlite');
expect(postgres.engine).toBe('postgres');
});
it("PLUGDATA-002: on SQLite a plugin's data is a file of its own, and erasing removes its directory", async () => {
const backend = new SqlitePluginDataBackend();
const store = backend.open('sqlite-one');
expect(store).toBeInstanceOf(PluginDataDb);
expect(store.engine).toBe('sqlite');
store.close();
expect(fs.existsSync(path.join(tmp, 'sqlite-one', 'plugin.db'))).toBe(true);
await backend.erase('sqlite-one');
expect(fs.existsSync(path.join(tmp, 'sqlite-one'))).toBe(false);
});
it('PLUGDATA-003: on Postgres a plugin gets a schema store and its data directory, but no SQLite file', async () => {
const executed: string[] = [];
const backend = new PostgresPluginDataBackend(fakeOrm(executed), POSTGRES);
const store = backend.open('pg-one');
expect(store).toBeInstanceOf(PostgresPluginDataStore);
expect(store.engine).toBe('postgres');
expect(fs.readdirSync(path.join(tmp, 'pg-one'))).toEqual([]);
expect(executed).toEqual([]);
await backend.erase('pg-one');
expect(executed).toEqual(['drop schema if exists "trek_plugin_pg_one" cascade']);
expect(fs.existsSync(path.join(tmp, 'pg-one'))).toBe(false);
});
it('PLUGDATA-004: the Postgres backend refuses to open a store without a Postgres database', () => {
const backend = new PostgresPluginDataBackend(fakeOrm([]), SQLITE);
expect(() => backend.open('pg-two')).toThrow(/without TREK_DB_URL/);
});
it('PLUGDATA-005: a closed Postgres store refuses new calls, so the host opens a fresh one', async () => {
const backend = new PostgresPluginDataBackend(fakeOrm([]), POSTGRES);
const store = backend.open('pg-three');
expect(store.isOpen()).toBe(true);
store.close();
expect(store.isOpen()).toBe(false);
await expect(store.query('SELECT 1')).rejects.toThrow('The database connection is not open');
await expect(store.query('SELECT * FROM public.users')).rejects.toThrow('The database connection is not open');
});
});
@@ -46,13 +46,13 @@ describe('plugin RPC coverage ledger', () => {
expect(fromRegistry.size).toBe(KNOWN_METHODS.length + UNCONDITIONAL_METHODS.length);
});
it('RPCLEDGER-005 the surface is the 114 methods the protocol declares', () => {
it('RPCLEDGER-005 the surface is the 115 methods the protocol declares', () => {
// Pinned rather than derived: a method DELETED from KNOWN_METHODS together with
// its handler would keep every test above green, and this is the line that makes
// that show up in the diff.
expect(KNOWN_METHODS.length).toBe(111);
expect(KNOWN_METHODS.length).toBe(112);
expect(UNCONDITIONAL_METHODS.length).toBe(3);
expect(fromRegistry.size).toBe(114);
expect(fromRegistry.size).toBe(115);
});
it('RPCLEDGER-006 boot-time total coverage is armed in production', () => {