graphile-plugin-utils 1.12.1 → 1.13.0

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.1",
+  "version": "1.13.0",
   "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",
@@ -51,5 +51,5 @@
     "pg-sql2": "^5.0.1",
     "postgraphile": "^5.1.3"
   },
-  "gitHead": "5e0bfead2856d1a062b495d343a43e543343f9b8"
+  "gitHead": "75b888926505b473eeef7a76fea1554e5a1cf4cc"
 }

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);
+    }));
+}

package/__tests__/pg-resources.test.d.ts

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

package/__tests__/pg-resources.test.js

@@ -1,30 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-const pg_resources_1 = require("../pg-resources");
-const tableCodec = { attributes: { id: {} } };
-const scalarCodec = {};
-function resource(overrides) {
-    return {
-        isUnique: true,
-        codec: scalarCodec,
-        parameters: [{ codec: tableCodec }],
-        ...overrides
-    };
-}
-describe('isComputedScalarAttributeResource', () => {
-    it('accepts a unique scalar function taking a table row', () => {
-        expect((0, pg_resources_1.isComputedScalarAttributeResource)(resource({}))).toBe(true);
-    });
-    it('rejects a resource without parameters', () => {
-        expect((0, pg_resources_1.isComputedScalarAttributeResource)(resource({ parameters: [] }))).toBe(false);
-    });
-    it('rejects a table-returning resource (codec has attributes)', () => {
-        expect((0, pg_resources_1.isComputedScalarAttributeResource)(resource({ codec: tableCodec }))).toBe(false);
-    });
-    it('rejects a non-unique resource', () => {
-        expect((0, pg_resources_1.isComputedScalarAttributeResource)(resource({ isUnique: false }))).toBe(false);
-    });
-    it('rejects when the first parameter is not a table row', () => {
-        expect((0, pg_resources_1.isComputedScalarAttributeResource)(resource({ parameters: [{ codec: scalarCodec }] }))).toBe(false);
-    });
-});

package/esm/__tests__/pg-resources.test.js

@@ -1,28 +0,0 @@
-import { isComputedScalarAttributeResource } from '../pg-resources';
-const tableCodec = { attributes: { id: {} } };
-const scalarCodec = {};
-function resource(overrides) {
-    return {
-        isUnique: true,
-        codec: scalarCodec,
-        parameters: [{ codec: tableCodec }],
-        ...overrides
-    };
-}
-describe('isComputedScalarAttributeResource', () => {
-    it('accepts a unique scalar function taking a table row', () => {
-        expect(isComputedScalarAttributeResource(resource({}))).toBe(true);
-    });
-    it('rejects a resource without parameters', () => {
-        expect(isComputedScalarAttributeResource(resource({ parameters: [] }))).toBe(false);
-    });
-    it('rejects a table-returning resource (codec has attributes)', () => {
-        expect(isComputedScalarAttributeResource(resource({ codec: tableCodec }))).toBe(false);
-    });
-    it('rejects a non-unique resource', () => {
-        expect(isComputedScalarAttributeResource(resource({ isUnique: false }))).toBe(false);
-    });
-    it('rejects when the first parameter is not a table row', () => {
-        expect(isComputedScalarAttributeResource(resource({ parameters: [{ codec: scalarCodec }] }))).toBe(false);
-    });
-});