slotlock 0.2.0 → 0.5.0

package/ddl.d.ts

@@ -1,5 +1,18 @@
 /** The start of the message with which the deployment DDL refuses a `slotlock` schema. */
 export declare const SLOTLOCK_SCHEMA_CONTROL_REFUSAL = "Slotlock will not deploy into schema slotlock";
+/**
+ * The version of the schema this release creates, recorded in `slotlock.schema_version` by every
+ * migration. Releases up to 0.2 recorded nothing; 0.1 was version 1 and 0.2 version 2.
+ */
+export declare const SLOTLOCK_SCHEMA_VERSION = 3;
+/** The start of the message with which the deployment DDL refuses a schema a newer release migrated. */
+export declare const SLOTLOCK_SCHEMA_NEWER_REFUSAL = "Slotlock will not migrate a schema a newer release migrated";
+/**
+ * What every migration checks before it changes anything, applySchema and applyTenantRls included
+ * when they find nothing to change: that no other role controls the schema, then the server version
+ * and the schema version. Run with search_path pinned, as the DDL pins it.
+ */
+export declare const SLOTLOCK_DEPLOYMENT_CHECKS = "DO $slotlock_schema_control$\nDECLARE\n  refusals text[];\nBEGIN\n  SELECT pg_catalog.array_agg(refusal.reason ORDER BY refusal.reason)\n    INTO refusals\n    FROM (\n      SELECT 'schema slotlock is owned by ' || owned_by.rolname AS reason\n        FROM pg_catalog.pg_namespace ns\n        JOIN pg_catalog.pg_roles owned_by ON owned_by.oid = ns.nspowner\n       WHERE ns.nspname = 'slotlock'\n         AND owned_by.rolname <> CURRENT_USER AND NOT owned_by.rolsuper\n      UNION\n      SELECT COALESCE(grantee_role.rolname, 'PUBLIC') || ' can create objects in schema slotlock'\n        FROM pg_catalog.pg_namespace ns\n       CROSS JOIN LATERAL pg_catalog.aclexplode(ns.nspacl) acl\n        LEFT JOIN pg_catalog.pg_roles grantee_role ON grantee_role.oid = acl.grantee\n       WHERE ns.nspname = 'slotlock'\n         AND acl.privilege_type = 'CREATE'\n         AND acl.grantee <> ns.nspowner\n         AND (acl.grantee = 0\n              OR (grantee_role.rolname <> CURRENT_USER AND NOT grantee_role.rolsuper))\n      UNION\n      SELECT ident.type || ' ' || ident.identity || ' is owned by ' || owned_by.rolname\n        FROM pg_catalog.pg_shdepend owned\n        JOIN pg_catalog.pg_roles owned_by ON owned_by.oid = owned.refobjid\n       CROSS JOIN LATERAL pg_catalog.pg_identify_object(owned.classid, owned.objid, owned.objsubid) ident\n       WHERE owned.dbid = (SELECT db.oid FROM pg_catalog.pg_database db\n                            WHERE db.datname = pg_catalog.current_database())\n         AND owned.deptype = 'o'\n         AND owned.refclassid = 'pg_catalog.pg_authid'::pg_catalog.regclass\n         AND owned_by.rolname <> CURRENT_USER AND NOT owned_by.rolsuper\n         AND ident.schema = 'slotlock'\n      UNION\n      SELECT 'trigger ' || trg.tgname || ' on slotlock.' || rel.relname || ' runs '\n             || trg.tgfoid::pg_catalog.regprocedure::pg_catalog.text\n             || ', owned by ' || owned_by.rolname\n        FROM pg_catalog.pg_trigger trg\n        JOIN pg_catalog.pg_class rel ON rel.oid = trg.tgrelid\n        JOIN pg_catalog.pg_namespace ns ON ns.oid = rel.relnamespace\n        JOIN pg_catalog.pg_proc fn ON fn.oid = trg.tgfoid\n        JOIN pg_catalog.pg_roles owned_by ON owned_by.oid = fn.proowner\n       WHERE ns.nspname = 'slotlock'\n         AND NOT trg.tgisinternal\n         AND owned_by.rolname <> CURRENT_USER AND NOT owned_by.rolsuper\n      UNION\n      SELECT COALESCE(grantee_role.rolname, 'PUBLIC') || ' can create triggers on slotlock.'\n             || rel.relname\n        FROM pg_catalog.pg_class rel\n        JOIN pg_catalog.pg_namespace ns ON ns.oid = rel.relnamespace\n       CROSS JOIN LATERAL pg_catalog.aclexplode(rel.relacl) acl\n        LEFT JOIN pg_catalog.pg_roles grantee_role ON grantee_role.oid = acl.grantee\n       WHERE ns.nspname = 'slotlock'\n         AND acl.privilege_type = 'TRIGGER'\n         AND acl.grantee <> rel.relowner\n         AND (acl.grantee = 0\n              OR (grantee_role.rolname <> CURRENT_USER AND NOT grantee_role.rolsuper))\n      UNION\n      SELECT 'extension ' || ext.extname || ' in schema slotlock is owned by ' || owned_by.rolname\n        FROM pg_catalog.pg_extension ext\n        JOIN pg_catalog.pg_namespace ns ON ns.oid = ext.extnamespace\n        JOIN pg_catalog.pg_roles owned_by ON owned_by.oid = ext.extowner\n       WHERE ns.nspname = 'slotlock'\n         AND owned_by.rolname <> CURRENT_USER AND NOT owned_by.rolsuper\n    ) refusal;\n  IF refusals IS NOT NULL THEN\n    RAISE EXCEPTION 'Slotlock will not deploy into schema slotlock: another role controls it'\n      USING ERRCODE = 'insufficient_privilege',\n            DETAIL = pg_catalog.to_jsonb(refusals)::pg_catalog.text,\n            HINT = 'The deployment role must own schema slotlock and every object in it, and no other role may create objects in it.';\n  END IF;\nEND\n$slotlock_schema_control$;\nDO $slotlock_schema_preconditions$\nDECLARE\n  installed integer;\nBEGIN\n  IF pg_catalog.current_setting('server_version_num')::integer < 160000 THEN\n    RAISE EXCEPTION 'Slotlock needs PostgreSQL 16 or later; this server is %',\n      pg_catalog.current_setting('server_version')\n      USING ERRCODE = 'feature_not_supported';\n  END IF;\n  IF pg_catalog.to_regclass('slotlock.schema_version') IS NOT NULL THEN\n    EXECUTE 'SELECT version FROM slotlock.schema_version WHERE singleton' INTO installed;\n    IF installed > 3 THEN\n      RAISE EXCEPTION 'Slotlock will not migrate a schema a newer release migrated (version %; this release is version 3)', installed\n        USING ERRCODE = 'object_not_in_prerequisite_state',\n              HINT = 'Migrate and serve it with the release that migrated it, or a later one.';\n    END IF;\n  END IF;\nEND\n$slotlock_schema_preconditions$;\n";
 /** Active (unrevoked, unexpired) API keys one tenant may hold. */
 export declare const SLOTLOCK_API_KEY_ACTIVE_LIMIT = 100;
 /** API keys one tenant may hold in all, revoked and expired ones included, so lists stay bounded. */
@@ -23,18 +36,47 @@ export declare const SLOTLOCK_DASHBOARD_TABLES: readonly ["dashboard_tokens"];
 export declare const SLOTLOCK_DASHBOARD_FUNCTIONS: readonly ["slotlock.use_dashboard_token(text, bytea, timestamptz, bytea)", "slotlock.dashboard_session_ended(bytea, timestamptz)"];
 /** Live form records one person may leave in the dashboard's records (12 hours of forms). */
 export declare const SLOTLOCK_DASHBOARD_FORM_LIMIT = 1000;
+/** The table that records which release migrated the schema (SLOTLOCK_SCHEMA_VERSION). */
+export declare const SLOTLOCK_SCHEMA_TABLES: readonly ["schema_version"];
+/** The SECURITY DEFINER function through which a server reads the version it is serving. */
+export declare const SLOTLOCK_SCHEMA_FUNCTIONS: readonly ["slotlock.installed_schema_version()"];
+/** The table of suspended tenants: they may read, and write nothing (store.ts withTenant). */
+export declare const SLOTLOCK_TENANT_ADMIN_TABLES: readonly ["tenant_suspensions", "webhook_tenants", "rate_buckets"];
+/**
+ * The SECURITY DEFINER functions through which a server checks a tenant's suspension and erases a
+ * tenant, by signature.
+ */
+export declare const SLOTLOCK_TENANT_ADMIN_FUNCTIONS: readonly ["slotlock.tenant_suspended(text)", "slotlock.erase_tenant(text)", "slotlock.register_webhook_tenant(text)", "slotlock.webhook_tenants(text)", "slotlock.unregister_webhook_tenant(text)", "slotlock.take_rate_token(text, double precision, double precision)"];
+/**
+ * Functions only the deployment role runs: suspending and lifting a suspension. No other role is
+ * granted them, so a serving role cannot lift a suspension.
+ */
+export declare const SLOTLOCK_OPERATOR_FUNCTIONS: readonly ["slotlock.suspend_tenant(text, text)", "slotlock.unsuspend_tenant(text)"];
 /** Every SECURITY DEFINER function the serving role may execute, by signature. */
-export declare const SLOTLOCK_DEFINER_FUNCTIONS: readonly ("slotlock.authenticate_api_key(bytea)" | "slotlock.create_api_key(text, text, text, bytea, text[], timestamptz, text)" | "slotlock.dashboard_session_ended(bytea, timestamptz)" | "slotlock.erase_api_keys(text)" | "slotlock.list_api_keys(text)" | "slotlock.revoke_api_key(text, uuid)" | "slotlock.rotate_api_key(text, uuid, text, bytea)" | "slotlock.use_dashboard_token(text, bytea, timestamptz, bytea)")[];
+export declare const SLOTLOCK_DEFINER_FUNCTIONS: readonly ("slotlock.authenticate_api_key(bytea)" | "slotlock.create_api_key(text, text, text, bytea, text[], timestamptz, text)" | "slotlock.dashboard_session_ended(bytea, timestamptz)" | "slotlock.erase_api_keys(text)" | "slotlock.erase_tenant(text)" | "slotlock.installed_schema_version()" | "slotlock.list_api_keys(text)" | "slotlock.register_webhook_tenant(text)" | "slotlock.revoke_api_key(text, uuid)" | "slotlock.rotate_api_key(text, uuid, text, bytea)" | "slotlock.take_rate_token(text, double precision, double precision)" | "slotlock.tenant_suspended(text)" | "slotlock.unregister_webhook_tenant(text)" | "slotlock.use_dashboard_token(text, bytea, timestamptz, bytea)" | "slotlock.webhook_tenants(text)")[];
 /** Tables no role but their owner reads or writes, reached only through SLOTLOCK_DEFINER_FUNCTIONS. */
-export declare const SLOTLOCK_DEFINER_TABLES: readonly ("api_key_retired_digests" | "api_keys" | "dashboard_tokens")[];
+export declare const SLOTLOCK_DEFINER_TABLES: readonly ("api_key_retired_digests" | "api_keys" | "dashboard_tokens" | "rate_buckets" | "schema_version" | "tenant_suspensions" | "webhook_tenants")[];
+/**
+ * The advisory lock every server transaction for a tenant holds shared (store.ts withTenant), and
+ * suspension and erasure take exclusively, keyed by this text's hashtextextended(…, 0).
+ */
+export declare function slotlockTenantLockKey(tenantRef: string): string;
+/** The constraint validation applySchema runs after the rest of SLOTLOCK_CORE_DDL has committed. */
+export declare const SLOTLOCK_VALIDATION_DDL: string;
+/** The whole deployment DDL, run in one transaction: the schema, then its constraints validated. */
 export declare const SLOTLOCK_CORE_DDL: string;
+/**
+ * SLOTLOCK_CORE_DDL without the validation, which applySchema runs as a step of its own after this
+ * commits (SLOTLOCK_VALIDATION_DDL).
+ */
+export declare const SLOTLOCK_STRUCTURE_DDL: string;
 export declare const SLOTLOCK_TENANT_CONTEXT_SETTING = "slotlock.tenant_ref";
 /**
  * Every table the store reads or writes at runtime, each under forced tenant RLS.
  * `slotlock.rls_policy_contracts` and `slotlock.deployment_lifted_row_security` are
  * deployment-only and deliberately absent.
  */
-export declare const SLOTLOCK_TENANT_TABLES: readonly ["resources", "reservations", "reservation_tombstones", "reservation_conflict_archive", "calendar_events", "calendar_event_attendees", "calendar_event_reminders", "calendar_event_exceptions", "calendar_event_occurrences", "calendar_event_tombstones", "calendar_event_commands", "calendar_coverage"];
+export declare const SLOTLOCK_TENANT_TABLES: readonly ["resources", "reservations", "reservation_tombstones", "reservation_conflict_archive", "calendar_events", "calendar_event_attendees", "calendar_event_reminders", "calendar_event_exceptions", "calendar_event_occurrences", "calendar_event_tombstones", "calendar_event_commands", "calendar_coverage", "hold_commands", "outbox", "outbox_pruned", "webhook_endpoints", "waitlist_entries"];
 /**
  * Build the grants for the application role: USAGE on the `slotlock` schema, DML on the store's
  * tables and EXECUTE on the API key and dashboard functions. Nothing else: no ownership, DDL,