graphile-plugin-utils 1.12.0 → 1.12.2

package/__tests__/system-lane.test.d.ts

@@ -0,0 +1 @@
+export {};

package/__tests__/system-lane.test.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const system_lane_1 = require("../system-lane");
+/**
+ * A client whose `withTransaction` behaves like grafast's: it brackets the
+ * callback with BEGIN and COMMIT, and rolls back when the callback throws.
+ */
+const makeClient = () => {
+    const calls = [];
+    const client = {
+        query: async (opts) => {
+            calls.push(opts);
+            return { rows: [] };
+        },
+        withTransaction: async (cb) => {
+            calls.push({ text: 'BEGIN' });
+            try {
+                const result = await cb(client);
+                calls.push({ text: 'COMMIT' });
+                return result;
+            }
+            catch (err) {
+                calls.push({ text: 'ROLLBACK' });
+                throw err;
+            }
+        }
+    };
+    return { client, calls };
+};
+const makeWithPgClient = (client, settings) => ((pgSettings, cb) => {
+    settings.push(pgSettings);
+    return cb(client);
+});
+describe('withSystemLaneClient', () => {
+    it('runs the callback in one transaction under a transaction-local role', async () => {
+        const { client, calls } = makeClient();
+        const settings = [];
+        const result = await (0, system_lane_1.withSystemLaneClient)(makeWithPgClient(client, settings), async (tx) => {
+            await tx.query({ text: 'SELECT 1' });
+            return 'ok';
+        });
+        expect(result).toBe('ok');
+        expect(settings).toEqual([null]);
+        expect(calls.map((c) => c.text)).toEqual([
+            'BEGIN',
+            'SELECT set_config($1, $2, true)',
+            'SELECT 1',
+            'COMMIT'
+        ]);
+        expect(calls[1].values).toEqual(['role', system_lane_1.SYSTEM_LANE_ROLE]);
+    });
+    it('honours an explicit role', async () => {
+        const { client, calls } = makeClient();
+        await (0, system_lane_1.withSystemLaneClient)(makeWithPgClient(client, []), async () => null, {
+            role: 'anonymous'
+        });
+        expect(calls[1].values).toEqual(['role', 'anonymous']);
+    });
+    it('leaves the rollback to the client and rethrows the callback failure', async () => {
+        const { client, calls } = makeClient();
+        await expect((0, system_lane_1.withSystemLaneClient)(makeWithPgClient(client, []), async () => {
+            throw new Error('boom');
+        })).rejects.toThrow('boom');
+        expect(calls.map((c) => c.text)).toEqual([
+            'BEGIN',
+            'SELECT set_config($1, $2, true)',
+            'ROLLBACK'
+        ]);
+    });
+});

package/esm/__tests__/system-lane.test.js

@@ -0,0 +1,68 @@
+import { SYSTEM_LANE_ROLE, withSystemLaneClient } from '../system-lane';
+/**
+ * A client whose `withTransaction` behaves like grafast's: it brackets the
+ * callback with BEGIN and COMMIT, and rolls back when the callback throws.
+ */
+const makeClient = () => {
+    const calls = [];
+    const client = {
+        query: async (opts) => {
+            calls.push(opts);
+            return { rows: [] };
+        },
+        withTransaction: async (cb) => {
+            calls.push({ text: 'BEGIN' });
+            try {
+                const result = await cb(client);
+                calls.push({ text: 'COMMIT' });
+                return result;
+            }
+            catch (err) {
+                calls.push({ text: 'ROLLBACK' });
+                throw err;
+            }
+        }
+    };
+    return { client, calls };
+};
+const makeWithPgClient = (client, settings) => ((pgSettings, cb) => {
+    settings.push(pgSettings);
+    return cb(client);
+});
+describe('withSystemLaneClient', () => {
+    it('runs the callback in one transaction under a transaction-local role', async () => {
+        const { client, calls } = makeClient();
+        const settings = [];
+        const result = await withSystemLaneClient(makeWithPgClient(client, settings), async (tx) => {
+            await tx.query({ text: 'SELECT 1' });
+            return 'ok';
+        });
+        expect(result).toBe('ok');
+        expect(settings).toEqual([null]);
+        expect(calls.map((c) => c.text)).toEqual([
+            'BEGIN',
+            'SELECT set_config($1, $2, true)',
+            'SELECT 1',
+            'COMMIT'
+        ]);
+        expect(calls[1].values).toEqual(['role', SYSTEM_LANE_ROLE]);
+    });
+    it('honours an explicit role', async () => {
+        const { client, calls } = makeClient();
+        await withSystemLaneClient(makeWithPgClient(client, []), async () => null, {
+            role: 'anonymous'
+        });
+        expect(calls[1].values).toEqual(['role', 'anonymous']);
+    });
+    it('leaves the rollback to the client and rethrows the callback failure', async () => {
+        const { client, calls } = makeClient();
+        await expect(withSystemLaneClient(makeWithPgClient(client, []), async () => {
+            throw new Error('boom');
+        })).rejects.toThrow('boom');
+        expect(calls.map((c) => c.text)).toEqual([
+            'BEGIN',
+            'SELECT set_config($1, $2, true)',
+            'ROLLBACK'
+        ]);
+    });
+});

package/esm/index.js

@@ -3,4 +3,5 @@
 export { getQueryBuilder } from './query-builder';
 // pg-resource introspection helpers (connection-filter / pg-aggregates)
 export { isComputedScalarAttributeResource } from './pg-resources';
+export { SYSTEM_LANE_ROLE, withSystemLaneClient } from './system-lane';
 export { JSON_SCHEMA_SCALARS, PG_TYPE_SCALARS } from './scalar-maps';

package/esm/system-lane.js

@@ -0,0 +1,40 @@
+/**
+ * The system lane: server-owned reads and writes that are not a tenant
+ * session — schema metadata, module registration, storage config.
+ *
+ * Grafast's `withPgClient(null, cb)` acquires a client with NO settings, so
+ * `cb` runs with whatever role the pool connected as (in practice `postgres`,
+ * a superuser that bypasses RLS) and each statement lands in its own implicit
+ * transaction. This helper names the role instead: one transaction with a
+ * transaction-local `role`, so the lane's reach is the grants of a named role
+ * rather than the connection's. It is the server-owned counterpart to the
+ * request lane's `withRequestPgClient`.
+ */
+/**
+ * Role the system lane runs as: a named role instead of whatever the pool
+ * connected as.
+ *
+ * This is NOT an RLS-subject role. `ROLES.md` documents `administrator` as the
+ * BYPASSRLS role, so the lane still bypasses RLS — what changes is that it no
+ * longer inherits the connection's superuser and its work is one transaction.
+ * Narrowing it further needs grants that do not exist yet.
+ */
+export const SYSTEM_LANE_ROLE = 'administrator';
+/**
+ * Run `cb` in one transaction under the system lane's role.
+ *
+ * The role is set with a transaction-local `set_config`, so it is discarded
+ * with the transaction and cannot leak to the next borrower of the pooled
+ * connection the way a session-level `SET ROLE` would. The client's own
+ * `withTransaction` owns commit and rollback.
+ */
+export function withSystemLaneClient(withPgClient, cb, opts = {}) {
+    const role = opts.role ?? SYSTEM_LANE_ROLE;
+    return withPgClient(null, (client) => client.withTransaction(async (tx) => {
+        await tx.query({
+            text: 'SELECT set_config($1, $2, true)',
+            values: ['role', role],
+        });
+        return cb(tx);
+    }));
+}

package/index.d.ts

@@ -1,4 +1,6 @@
 export { getQueryBuilder } from './query-builder';
 export { isComputedScalarAttributeResource } from './pg-resources';
+export type { SystemLaneOptions, SystemLanePgClient, SystemLaneWithPgClient } from './system-lane';
+export { SYSTEM_LANE_ROLE, withSystemLaneClient } from './system-lane';
 export type { GraphQLScalarName } from './scalar-maps';
 export { JSON_SCHEMA_SCALARS, PG_TYPE_SCALARS } from './scalar-maps';

package/index.js

@@ -1,13 +1,16 @@
 "use strict";
 // Shared internals for Constructive PostGraphile v5 plugins.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.PG_TYPE_SCALARS = exports.JSON_SCHEMA_SCALARS = exports.isComputedScalarAttributeResource = exports.getQueryBuilder = void 0;
+exports.PG_TYPE_SCALARS = exports.JSON_SCHEMA_SCALARS = exports.withSystemLaneClient = exports.SYSTEM_LANE_ROLE = exports.isComputedScalarAttributeResource = exports.getQueryBuilder = void 0;
 // PgCondition → PgSelectQueryBuilder walker (search / BM25 / pgvector)
 var query_builder_1 = require("./query-builder");
 Object.defineProperty(exports, "getQueryBuilder", { enumerable: true, get: function () { return query_builder_1.getQueryBuilder; } });
 // pg-resource introspection helpers (connection-filter / pg-aggregates)
 var pg_resources_1 = require("./pg-resources");
 Object.defineProperty(exports, "isComputedScalarAttributeResource", { enumerable: true, get: function () { return pg_resources_1.isComputedScalarAttributeResource; } });
+var system_lane_1 = require("./system-lane");
+Object.defineProperty(exports, "SYSTEM_LANE_ROLE", { enumerable: true, get: function () { return system_lane_1.SYSTEM_LANE_ROLE; } });
+Object.defineProperty(exports, "withSystemLaneClient", { enumerable: true, get: function () { return system_lane_1.withSystemLaneClient; } });
 var scalar_maps_1 = require("./scalar-maps");
 Object.defineProperty(exports, "JSON_SCHEMA_SCALARS", { enumerable: true, get: function () { return scalar_maps_1.JSON_SCHEMA_SCALARS; } });
 Object.defineProperty(exports, "PG_TYPE_SCALARS", { enumerable: true, get: function () { return scalar_maps_1.PG_TYPE_SCALARS; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-plugin-utils",
-  "version": "1.12.0",
+  "version": "1.12.2",
   "description": "Shared internals for Constructive PostGraphile v5 plugins - PgCondition query-builder walker and pg-resource introspection helpers",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -40,7 +40,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.19.11",
-    "makage": "^0.3.0"
+    "makage": "^0.8.0"
   },
   "peerDependencies": {
     "@dataplan/pg": "^1.1.1",
@@ -51,5 +51,5 @@
     "pg-sql2": "^5.0.1",
     "postgraphile": "^5.1.3"
   },
-  "gitHead": "b5b6b9f05276b7e9cbd3d1f4acd31dd315c353ea"
+  "gitHead": "01e073830677c0587bab564b7d575a06b5156f0c"
 }

package/system-lane.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The system lane: server-owned reads and writes that are not a tenant
+ * session — schema metadata, module registration, storage config.
+ *
+ * Grafast's `withPgClient(null, cb)` acquires a client with NO settings, so
+ * `cb` runs with whatever role the pool connected as (in practice `postgres`,
+ * a superuser that bypasses RLS) and each statement lands in its own implicit
+ * transaction. This helper names the role instead: one transaction with a
+ * transaction-local `role`, so the lane's reach is the grants of a named role
+ * rather than the connection's. It is the server-owned counterpart to the
+ * request lane's `withRequestPgClient`.
+ */
+/** The subset of grafast's PgClient the system lane needs. */
+export interface SystemLanePgClient {
+    query(opts: {
+        text: string;
+        values?: unknown[];
+    }): Promise<{
+        rows: Array<Record<string, unknown>>;
+    }>;
+    withTransaction<T>(cb: (tx: SystemLanePgClient) => Promise<T>): Promise<T>;
+}
+export type SystemLaneWithPgClient = <T>(pgSettings: Record<string, string> | null, cb: (client: SystemLanePgClient) => Promise<T>) => Promise<T>;
+/**
+ * Role the system lane runs as: a named role instead of whatever the pool
+ * connected as.
+ *
+ * This is NOT an RLS-subject role. `ROLES.md` documents `administrator` as the
+ * BYPASSRLS role, so the lane still bypasses RLS — what changes is that it no
+ * longer inherits the connection's superuser and its work is one transaction.
+ * Narrowing it further needs grants that do not exist yet.
+ */
+export declare const SYSTEM_LANE_ROLE = "administrator";
+export interface SystemLaneOptions {
+    /** Role to run as. Defaults to {@link SYSTEM_LANE_ROLE}. */
+    role?: string;
+}
+/**
+ * Run `cb` in one transaction under the system lane's role.
+ *
+ * The role is set with a transaction-local `set_config`, so it is discarded
+ * with the transaction and cannot leak to the next borrower of the pooled
+ * connection the way a session-level `SET ROLE` would. The client's own
+ * `withTransaction` owns commit and rollback.
+ */
+export declare function withSystemLaneClient<T>(withPgClient: SystemLaneWithPgClient, cb: (client: SystemLanePgClient) => Promise<T>, opts?: SystemLaneOptions): Promise<T>;

package/system-lane.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * The system lane: server-owned reads and writes that are not a tenant
+ * session — schema metadata, module registration, storage config.
+ *
+ * Grafast's `withPgClient(null, cb)` acquires a client with NO settings, so
+ * `cb` runs with whatever role the pool connected as (in practice `postgres`,
+ * a superuser that bypasses RLS) and each statement lands in its own implicit
+ * transaction. This helper names the role instead: one transaction with a
+ * transaction-local `role`, so the lane's reach is the grants of a named role
+ * rather than the connection's. It is the server-owned counterpart to the
+ * request lane's `withRequestPgClient`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SYSTEM_LANE_ROLE = void 0;
+exports.withSystemLaneClient = withSystemLaneClient;
+/**
+ * Role the system lane runs as: a named role instead of whatever the pool
+ * connected as.
+ *
+ * This is NOT an RLS-subject role. `ROLES.md` documents `administrator` as the
+ * BYPASSRLS role, so the lane still bypasses RLS — what changes is that it no
+ * longer inherits the connection's superuser and its work is one transaction.
+ * Narrowing it further needs grants that do not exist yet.
+ */
+exports.SYSTEM_LANE_ROLE = 'administrator';
+/**
+ * Run `cb` in one transaction under the system lane's role.
+ *
+ * The role is set with a transaction-local `set_config`, so it is discarded
+ * with the transaction and cannot leak to the next borrower of the pooled
+ * connection the way a session-level `SET ROLE` would. The client's own
+ * `withTransaction` owns commit and rollback.
+ */
+function withSystemLaneClient(withPgClient, cb, opts = {}) {
+    const role = opts.role ?? exports.SYSTEM_LANE_ROLE;
+    return withPgClient(null, (client) => client.withTransaction(async (tx) => {
+        await tx.query({
+            text: 'SELECT set_config($1, $2, true)',
+            values: ['role', role],
+        });
+        return cb(tx);
+    }));
+}