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
+2
View File
@@ -203,6 +203,8 @@ function createDevContext(id: string, grants: Set<string>, fx: Fixtures, db: Plu
query: (sql: string, ...a: unknown[]) => { need('db:own', 'db.query'); return db.query(sql, ...a); },
exec: (sql: string, ...a: unknown[]) => { need('db:own', 'db.exec'); return db.exec(sql, ...a); },
migrate: (mid: string, sql: string) => { need('db:own', 'db.migrate'); return db.migrate(mid, sql); },
// `dev` always runs your plugin on SQLite; test the Postgres dialect against a TREK on Postgres.
engine: async () => { need('db:own', 'db.engine'); return 'sqlite' as const; },
// A functional (not strictly atomic) tx over the real dev db so read-modify-write
// batches work in dev; production runs it in one better-sqlite3 transaction.
tx: async (ops: Array<{ sql: string; args?: unknown[] }>) => {
+3
View File
@@ -100,6 +100,7 @@ export const METHOD_PERMISSION: Readonly<Record<string, string>> = {
'db.query': 'db:own',
'db.migrate': 'db:own',
'db.tx': 'db:own',
'db.engine': 'db:own',
'trips.getById': 'db:read:trips',
'trips.getPlaces': 'db:read:trips',
'trips.getReservations': 'db:read:trips',
@@ -214,6 +215,7 @@ export const KNOWN_METHODS: string[] = [
'db.query',
'db.migrate',
'db.tx',
'db.engine',
'trips.getById',
'trips.getPlaces',
'trips.getReservations',
@@ -927,6 +929,7 @@ export const PLUGIN_METHOD_RESULT: Readonly<Record<string, string>> = {
'db.query': 'host',
'db.migrate': 'host',
'db.tx': 'host',
'db.engine': 'host',
'trips.getById': 'trip',
'trips.getPlaces': 'place[]',
'trips.getReservations': 'reservation[]',
+7 -2
View File
@@ -74,8 +74,10 @@ export interface PluginContext {
settings: {
get(key: string): Promise<unknown>;
};
/** Your OWN sqlite database (`db:own`): a separate file the plugin never gets a
* path or connection to directly. Quota: 256 MB per plugin (writes past it fail);
/** Your OWN database (`db:own`): a SQLite file of its own, or, when TREK runs on
* Postgres, a schema of its own in TREK's database, which your SQL is confined to
* (`engine()` says which, and README § Your own database on Postgres has the rules).
* The plugin never gets a path or connection to it directly. Quota: 256 MB per plugin (writes past it fail);
* result sets are capped at 100,000 rows, and a `query`, a `tx` or an `exec` script
* without args gets 2 s of wall-clock time, checked between the rows it reads and
* the statements it runs (past it, it throws, a `tx` rolls back and a script stops
@@ -87,6 +89,9 @@ export interface PluginContext {
query<T = unknown>(sql: string, ...args: unknown[]): Promise<T[]>;
exec(sql: string, ...args: unknown[]): Promise<{ changes: number }>;
migrate(id: string, sql: string): Promise<{ applied: boolean }>;
/** The engine your SQL runs on: 'sqlite' (the default), or 'postgres' when TREK runs on
* Postgres. Your SQL is passed through as written, so write it in that engine's dialect. */
engine(): Promise<'sqlite' | 'postgres'>;
/** Run several statements atomically on your OWN db — all commit or all roll
* back. Each op is one statement; reads see the batch's own earlier writes.
* A read returns `{ rows }`, a write `{ changes }`. Max 100 statements. */
+6
View File
@@ -48,6 +48,8 @@ export interface MockHostOptions {
users?: Record<number, unknown>;
/** Optional canned db.query results, keyed by the exact sql string. */
queryResults?: Record<string, unknown[]>;
/** What `db.engine()` answers; 'sqlite' when unset. Set 'postgres' to test a plugin's Postgres SQL path. */
dbEngine?: 'sqlite' | 'postgres';
/** The host-bound acting user for costs.* (a job/onLoad has none → refused). */
actingUserId?: number;
/** Trip bound to the mock plugin UI's `session` helper. Required for scope: 'trip'. */
@@ -451,6 +453,10 @@ export function createMockHost(opts: MockHostOptions = {}): MockHost {
guardSql(sql);
return { applied: true };
},
async engine() {
need('db:own', 'db.engine');
return opts.dbEngine ?? 'sqlite';
},
async tx(ops) {
need('db:own', 'db.tx');
// Same batch guards as the host's PluginDataDb: an op cap, the forbidden