@saasicat/adapter-prisma 1.0.0-rc.22 → 1.0.0-rc.24

package/README.md

@@ -25,6 +25,7 @@ rows, which order, which lock — and every decision above that lives in
 
 ```ts
 import { prismaPersistence } from '@saasicat/adapter-prisma';
+import { aesGcmSecretSealer } from '@saasicat/nest/platform';
 import { PrismaService } from './prisma/prisma.service';
 
 SaaSiCatModule.forRoot({
@@ -32,6 +33,8 @@ SaaSiCatModule.forRoot({
     controller: { guards: [JwtAuthGuard] },
     imports: [AuthModule],
     persistence: prismaPersistence({ client: PrismaService }),
+    // Not the bundle's to supply: the key that seals the SuperAdmin's second factor.
+    adapters: { secretSealer: aesGcmSecretSealer(process.env.SECRET_SEALER_KEY) },
     entitlement: {},
 });
 ```
@@ -47,10 +50,20 @@ Options:
 
 - `passwordHasher` — your `PasswordHasher` (token or instance). Enables
   `core.superAdminProvisioning` (setup wizard / `user create-super-admin`).
-- `rlsIntegration: true` — declare the `rowLevelSecurity` capability once
-  your Prisma middleware really applies the bypass (see below).
+- `rlsIntegration: true` — lift your row policies for what the platform does
+  across tenants (see [RLS bypass](#rls-bypass)).
 - `schema` — explicit plan identity, delegate and optional-field capabilities
   for schemas that differ from the 0.6 canonical layout.
+- `notAdopted` — the canonical models your schema leaves out, as
+  `saasicat schema check` prints them (it hands over the list it can use). The
+  bundle leaves out what needs them, and a model it cannot do without is
+  refused with the ones it can. Leaving out `SuperAdminMfa` means passing your
+  own `MfaPort` in `adapters`; a start without one is refused. A ready client
+  passed as `client` needs no delegate of a model named here.
+- `transactions` — `maxConcurrent`, the most platform transactions open at
+  once, and Prisma's `timeout` and `maxWait` for each. Unset, nothing is
+  bounded and Prisma's defaults apply; see
+  [Transactions under load](#transactions-under-load).
 
 The bundle also ships `planCatalogReadSink` for DB hydration. To use it,
 omit `planCatalog` and name the file the settings come from:
@@ -100,6 +113,12 @@ PromoCodesModule.forRoot({
 | `PrismaSubscriptionContractRepository`   | `SubscriptionContractRepository`   | `subscription_contracts`, `contract_line_items`                     |
 | `PrismaSubscriberLedgerRepository`       | `SubscriberLedgerRepository`       | `subscriber_ledger_entries`                                         |
 | `PrismaAppliedSettingsRepository`        | `AppliedSettingsPort`              | `applied_settings`, `settings_changes`                              |
+| `PrismaMaintenanceWindowRepository`      | `MaintenanceWindowPort`            | `maintenance_windows`                                               |
+| `PrismaSubscriptionNoticeRepository`     | `SubscriptionNoticeRepository`     | `subscription_notices`                                              |
+
+`PrismaMfaAdapter` stores the secret it is handed. The platform seals it first with the
+`SecretSealer` bound in `adapters`, which this bundle does not supply: the key belongs to the
+installation, not to the database.
 
 Not shipped (custom adapters stay yours): registration persistence,
 consumer-specific payment/invoice integrations, and `FirstTimeCustomerCheck`.
@@ -123,6 +142,48 @@ providers: [
 builds without `prisma generate`, and any client generated from the
 canonical schema satisfies them.
 
+## Transactions under load
+
+The platform's transactions take row locks and then read further, and each
+holds a pooled connection for its whole life. Opened for every request at
+once, they can end up holding every connection while waiting for a lock or for
+a read that needs one — and the service stalls until Prisma's `timeout` aborts
+them with `P2028`. `maxConcurrent` keeps some connections free: transactions
+beyond it wait in arrival order before they open, and that wait does not count
+against `timeout`.
+
+```ts
+prismaPersistence({
+    client: PrismaService,
+    // A pool of 20 connections (`connection_limit` in the database URL).
+    transactions: { maxConcurrent: 15, timeout: 30_000, maxWait: 10_000 },
+});
+```
+
+Your pool size minus five is a sound start; too low a value queues work that
+could have run side by side. `timeout` bounds what runs inside a transaction,
+including the wait for a row lock, so a burst at a quota limit wants more than
+Prisma's five seconds.
+
+What is counted is what runs through `transactionRunner`. A repository called
+without a transaction opens its own for that one call; it works on its own
+handle only, so it cannot hold a connection while waiting for another, and it
+is not counted. A transaction opened inside another — `run` called again rather
+than `tx` passed on — needs a second place, and with every place taken waits
+for the one its caller holds; pass `tx` on.
+
+The bound belongs to the pool, not to a runner: every runner on one client
+shares it, however many modules Nest builds one for, and a second, different
+bound for the same client is refused. A transaction waits for its place as long
+as it takes — the wait has no deadline, so a sustained overload queues rather
+than fails; leave the bound headroom against your request timeouts. Wired by
+hand, provide the options beside the runner:
+
+```ts
+{ provide: PRISMA_TRANSACTION_OPTIONS_TOKEN, useValue: { maxConcurrent: 15 } },
+PrismaTransactionRunner,
+```
+
 ## Schema assumptions
 
 The canonical schema: copy the models from
@@ -137,8 +198,10 @@ the platform ports stay identical.
 ### Plan identity and split PlanVersion delegates
 
 The default is the SaaSiCat 0.6 layout: `PlanVersion.planId` stores the
-semantic `planKey`, both catalog and entitlement reads use the `planVersion`
-delegate, and optional validity columns are not queried. There is no schema
+semantic `planKey`, and both catalog and entitlement reads use the `planVersion`
+delegate. Every plan-version model carries `validFrom`, `validUntil` and
+`endsAt`, as the canonical schema does: they decide which version is on sale,
+for a catalogue, a price and a booking alike. There is no schema
 auto-detection.
 
 An app with a normalized UUID foreign key opts in explicitly. Port inputs and
@@ -147,16 +210,10 @@ outputs still use the semantic key:
 ```ts
 const schema = {
     planBinding: { mode: 'normalized-plan-id' },
-    planVersionFields: {
-        validityWindows: true,
-        endsAt: true,
-    },
     tenantSubscription: {
         subscriptionBundleDelegate: 'subscriptionBundle',
         synchronizePlanVersion: true,
         atomicOnboardingSelection: true,
-        activeVersionSelection: 'validity-window',
-        withEndsAt: true,
     },
 } satisfies PrismaSchemaOptions;
 
@@ -178,8 +235,8 @@ providers: [
 ```
 
 Split schemas can name catalog and entitlement delegates independently. This
-keeps, for example, `catalogPlanVersion` with validity columns separate from a
-legacy billing `planVersion`:
+keeps, for example, `catalogPlanVersion` separate from a billing `planVersion`;
+both carry the date columns:
 
 ```ts
 const schema = {
@@ -187,10 +244,6 @@ const schema = {
         catalogPlanVersion: 'catalogPlanVersion',
         entitlementPlanVersion: 'planVersion',
     },
-    planVersionFields: {
-        catalog: { validityWindows: true },
-        entitlement: { validityWindows: false },
-    },
 } satisfies PrismaSchemaOptions;
 ```
 
@@ -208,7 +261,7 @@ and optional promo callback share one Prisma transaction.
 
 Immediate changes and onboarding bind the subscription to the version they
 sell: they resolve the target plan's live PlanVersion and update `plan`,
-`planVersionId`, cycle and stale pending-version fields together. That is what
+`planVersionId` and cycle together. That is what
 the entitlements read and what a contract freeze records, and it is the
 default. It needs a schema that carries it — a `planVersionId` column on the
 subscription model, the plan-version model (`schema.delegates.entitlementPlanVersion`,
@@ -239,40 +292,75 @@ is absent and the catalog service remains fail-closed.
 
 ### Bundle validity windows
 
-`PrismaBundleRepository` keeps its 0.6-compatible behavior by default and does
-not require `bundle_versions.validFrom` / `validUntil`. After applying the
-additive columns from the current `@saasicat/spec` bundle fragment, enable them
-explicitly:
-
-```ts
-const bundles = new PrismaBundleRepository(prisma, {
-    validityWindows: true,
-});
-```
-
-The enabled mode persists and returns both dates. Publishing also sets the
-predecessor's `validUntil` to one UTC calendar day before the successor starts,
-and wraps supersede + publish in a transaction when the caller did not already
-provide one. It also exposes the optional
-`BundleRepository.findActiveBundleVersion(bundleId, asOf?)` capability, using
-inclusive UTC-day boundaries and preferring the highest `validFrom`, then
-`version`. In the default legacy mode that optional capability is `undefined`.
+`PrismaBundleRepository` writes and reads `bundle_versions.validFrom` and
+`validUntil`, as the canonical schema carries them: they decide which add-on
+version is on sale, as they do for plans. Publishing sets the predecessor's
+`validUntil` to one UTC calendar day before the successor starts, and wraps
+supersede + publish in a transaction when the caller did not already provide
+one. `BundleRepository.findActiveBundleVersion(bundleId, asOf?)` answers the
+version on sale, using inclusive UTC-day boundaries and preferring the highest
+`validFrom`, then `version`; a version superseded without a last day is not on
+sale.
 
 ## RLS bypass
 
-`AsyncLocalRlsBypassAdapter` only toggles an `AsyncLocalStorage` flag — your
-`PrismaService` must apply it:
+An operator's lists, the nightly sweeps and the platform's boot checks work
+across tenants. Under a row policy that filters on the tenant they see nothing
+of the others — an empty list, a count of 0, an update of no row — unless the
+policy is lifted for them. `rlsIntegration: true` does that for every statement
+the bundle's adapters run inside the platform's `runWithBypass`: a read, a
+write, a raw statement, a batch, and an interactive transaction the platform's
+runner or one of its repositories opens.
 
 ```ts
-this.$use(async (params, next) => {
-    if (rls.isBypassActive()) {
-        await this.$executeRawUnsafe('SET LOCAL row_security = off');
-    }
-    return next(params);
-});
+prismaPersistence({ client: PrismaService, rlsIntegration: true });
+```
+
+PostgreSQL has no per-statement switch for this. `SET row_security = off`
+makes a query the policy would filter fail rather than see more, and a role
+with `BYPASSRLS` skips every policy for every statement it runs. What the
+bundle does instead is set `app.bypass_rls` to `'true'` for one transaction —
+the statement's own, a batch's, or an interactive transaction's opened inside
+the bypass — and your policy accepts that setting beside the tenant:
+
+```sql
+ALTER TABLE subscriptions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE subscriptions FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_rows ON subscriptions
+    USING ("tenantId" = current_setting('app.tenant_id', true)
+           OR current_setting('app.bypass_rls', true) = 'true')
+    WITH CHECK ("tenantId" = current_setting('app.tenant_id', true)
+           OR current_setting('app.bypass_rls', true) = 'true');
 ```
 
-Only then pass `rlsIntegration: true` to `prismaPersistence`.
+- **The application connects as a role the policy applies to**: not a
+  superuser, not a role with `BYPASSRLS`. The table owner is subject to it
+  only with `FORCE ROW LEVEL SECURITY`.
+- **`app.tenant_id` is yours.** Setting it for a tenant's request is your
+  application's tenant scoping; the bundle sets only the bypass.
+- **A transaction opened outside the bypass cannot enter it.** The setting
+  would outlast the bypass for the rest of that transaction, so a statement of
+  it that tries is refused with an error saying so. Open the transaction inside
+  `runWithBypass`; the platform's own code does. A statement on the client
+  itself, sent from inside a transaction's callback, runs on another connection
+  and is lifted on its own either way.
+- **Where a statement runs is Prisma's to say.** It hands every query extension
+  the transaction a statement belongs to, outside its public types; Prisma 6,
+  which the suites here run against, does. A client that does not say is
+  refused inside the bypass rather than guessed at, since a wrong guess breaks
+  either the lifting or the transaction.
+- **Another setting name**: `rlsIntegration: new PrismaRlsBypass('app.other')`.
+- **Statements of your own** inside the platform's bypass — a job of yours
+  that injects `RLS_BYPASS_PORT_TOKEN` — go through the same instance: build
+  one, pass it as `rlsIntegration`, and run them on `bypass.extend(prisma)`.
+  Batch and open transactions for them on that client too: a batch or a
+  transaction opened on another client carries no setting, and a lifted
+  statement in it is refused.
+
+An installation that keeps a bypass of its own, over its own tenant context,
+binds its `RlsBypassPort` in `adapters` and leaves `rlsIntegration` out.
+Without row policies, leave it out too: the bundle's port then runs the work
+as it is.
 
 ## Tests
 
@@ -286,7 +374,9 @@ The integration run builds its schema from the normative reference SQL,
 generates a client from the composed fragments and executes the
 `@saasicat/persistence-testing` contract — CI does the same against a
 postgres service. **The database is disposable: the harness drops and
-recreates its `public` schema.**
+recreates its `public` schema.** The RLS suite beside it creates the database
+`<name>_rls` and the role `saasicat_rls_probe`, puts the policy above on a
+table and runs the bundle as that role.
 
 ## Next
 

package/dist/.build-stamp

@@ -1 +1 @@
-bc8ca8ae3cba91e8cd52395cac265267fcfb1fd7174a169f629b5defba397d15
+ea73c0e7bf28f59cc874609ad77c869e7129802a8297ffd6bd0f9ec21d3cabe9