@saasicat/adapter-prisma 1.0.0-rc.23 → 1.0.0-rc.25

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:
@@ -70,37 +83,44 @@ PromoCodesModule.forRoot({
 
 ## Shipped adapters
 
-| Class                                    | Implements port                    | Tables                                                              |
-| ---------------------------------------- | ---------------------------------- | ------------------------------------------------------------------- |
-| `PrismaTransactionRunner`                | `TransactionRunner`                | — (`$transaction`)                                                  |
-| `PrismaMfaAdapter`                       | `MfaPort`                          | `super_admin_mfa`                                                   |
-| `PrismaAuditAdapter`                     | `AuditPort`                        | `audit_logs`                                                        |
-| `PrismaAuditQueryAdapter`                | `AuditQueryPort`                   | `audit_logs`                                                        |
-| `PrismaAuditStatsAdapter`                | `AuditStatsPort`                   | `audit_logs`                                                        |
-| `AsyncLocalRlsBypassAdapter`             | `RlsBypassPort`                    | (no DB access)                                                      |
-| `PrismaSubscriptionRepository`           | `SubscriptionRepository`           | `subscriptions`, `plan_versions`, optionally `subscription_bundles` |
-| `PrismaSubscriptionBundleRepository`     | `SubscriptionBundleRepository`     | `subscription_bundles`                                              |
-| `PrismaTenantSubscriptionWriteAdapter`   | `TenantSubscriptionWritePort`      | `subscriptions`, `plans`, `plan_versions`                           |
-| `PrismaPlanVersionRepository`            | `PlanVersionRepository`            | `plan_versions`                                                     |
-| `PrismaPromoCodeRepository`              | `PromoCodeRepository`              | `promo_codes`                                                       |
-| `PrismaPromoCodeRedemptionRepository`    | `PromoCodeRedemptionRepository`    | `promo_code_redemptions`                                            |
-| `PrismaPromoCodeHoldRepository`          | `PromoCodeHoldRepository`          | `promo_code_holds`, `promo_codes`                                   |
-| `PrismaPromoCodeValidationLogRepository` | `PromoCodeValidationLogRepository` | `promo_code_validation_logs`                                        |
-| `PrismaPromoSubscriptionLookup`          | `PromoSubscriptionLookup`          | `subscriptions`                                                     |
-| `ZeroPromoRevenueDeductionAggregator`    | `PromoRevenueDeductionAggregator`  | — (constant `'0.00'`)                                               |
-| `PrismaSuperAdminBootstrapAdapter`       | `SuperAdminProvisioningPort`       | `super_admin_users`                                                 |
-| `PrismaPlanCatalogReadSink`              | `PlanCatalogReadSink`              | `plans`, `plan_versions`, `feature_catalog_entries`                 |
-| `PrismaPlanCatalogImportSink`            | `PlanCatalogImportSink`            | same                                                                |
-| `PrismaPlanRepository`                   | `PlanRepository`                   | `plans`, `plan_versions`                                            |
-| `PrismaBundleRepository`                 | `BundleRepository`                 | `bundles`, `bundle_versions`                                        |
-| `PrismaCatalogEntryRepository`           | `CatalogEntryRepository`           | capability, feature and quota catalog tables                        |
-| `PrismaMarketingProjectionRepository`    | `MarketingProjectionRepository`    | `marketing_projections`                                             |
-| `PrismaMarketingSettingsRepository`      | `MarketingSettingsRepository`      | `marketing_settings`                                                |
-| `PrismaPromotionRepository`              | `PromotionRepository`              | `promotions`                                                        |
-| `PrismaSubscriptionContractRepository`   | `SubscriptionContractRepository`   | `subscription_contracts`, `contract_line_items`                     |
-| `PrismaSubscriberLedgerRepository`       | `SubscriberLedgerRepository`       | `subscriber_ledger_entries`                                         |
-| `PrismaAppliedSettingsRepository`        | `AppliedSettingsPort`              | `applied_settings`, `settings_changes`                              |
-| `PrismaMaintenanceWindowRepository`      | `MaintenanceWindowPort`            | `maintenance_windows`                                               |
+| Class                                     | Implements port                     | Tables                                                              |
+| ----------------------------------------- | ----------------------------------- | ------------------------------------------------------------------- |
+| `PrismaTransactionRunner`                 | `TransactionRunner`                 | — (`$transaction`)                                                  |
+| `PrismaMfaAdapter`                        | `MfaPort`                           | `super_admin_mfa`                                                   |
+| `PrismaAuditAdapter`                      | `AuditPort`                         | `audit_logs`                                                        |
+| `PrismaAuditQueryAdapter`                 | `AuditQueryPort`                    | `audit_logs`                                                        |
+| `PrismaAuditStatsAdapter`                 | `AuditStatsPort`                    | `audit_logs`                                                        |
+| `AsyncLocalRlsBypassAdapter`              | `RlsBypassPort`                     | (no DB access)                                                      |
+| `PrismaSubscriptionRepository`            | `SubscriptionRepository`            | `subscriptions`, `plan_versions`, optionally `subscription_bundles` |
+| `PrismaSubscriptionBundleRepository`      | `SubscriptionBundleRepository`      | `subscription_bundles`                                              |
+| `PrismaTenantSubscriptionWriteAdapter`    | `TenantSubscriptionWritePort`       | `subscriptions`, `plans`, `plan_versions`                           |
+| `PrismaPlanVersionRepository`             | `PlanVersionRepository`             | `plan_versions`                                                     |
+| `PrismaPromoCodeRepository`               | `PromoCodeRepository`               | `promo_codes`                                                       |
+| `PrismaPromoCodeRedemptionRepository`     | `PromoCodeRedemptionRepository`     | `promo_code_redemptions`                                            |
+| `PrismaPromoCodeHoldRepository`           | `PromoCodeHoldRepository`           | `promo_code_holds`, `promo_codes`                                   |
+| `PrismaPromoCodeValidationLogRepository`  | `PromoCodeValidationLogRepository`  | `promo_code_validation_logs`                                        |
+| `PrismaPromoSubscriptionLookup`           | `PromoSubscriptionLookup`           | `subscriptions`                                                     |
+| `ZeroPromoRevenueDeductionAggregator`     | `PromoRevenueDeductionAggregator`   | — (constant `'0.00'`)                                               |
+| `PrismaSuperAdminBootstrapAdapter`        | `SuperAdminProvisioningPort`        | `super_admin_users`                                                 |
+| `PrismaPlanCatalogReadSink`               | `PlanCatalogReadSink`               | `plans`, `plan_versions`, `feature_catalog_entries`                 |
+| `PrismaPlanCatalogImportSink`             | `PlanCatalogImportSink`             | same                                                                |
+| `PrismaPlanRepository`                    | `PlanRepository`                    | `plans`, `plan_versions`                                            |
+| `PrismaBundleRepository`                  | `BundleRepository`                  | `bundles`, `bundle_versions`                                        |
+| `PrismaCatalogEntryRepository`            | `CatalogEntryRepository`            | capability, feature and quota catalog tables                        |
+| `PrismaMarketingProjectionRepository`     | `MarketingProjectionRepository`     | `marketing_projections`                                             |
+| `PrismaMarketingSettingsRepository`       | `MarketingSettingsRepository`       | `marketing_settings`                                                |
+| `PrismaPromotionRepository`               | `PromotionRepository`               | `promotions`                                                        |
+| `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`                                              |
+| `PrismaVersionRetirementRepository`       | `VersionRetirementRepository`       | `version_retirements`                                               |
+| `PrismaBundleVersionRetirementRepository` | `BundleVersionRetirementRepository` | `bundle_version_retirements`                                        |
+
+`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`.
@@ -124,6 +144,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
@@ -138,8 +200,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
@@ -148,16 +212,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;
 
@@ -179,8 +237,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 = {
@@ -188,10 +246,6 @@ const schema = {
         catalogPlanVersion: 'catalogPlanVersion',
         entitlementPlanVersion: 'planVersion',
     },
-    planVersionFields: {
-        catalog: { validityWindows: true },
-        entitlement: { validityWindows: false },
-    },
 } satisfies PrismaSchemaOptions;
 ```
 
@@ -209,7 +263,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`,
@@ -240,40 +294,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
 
@@ -287,7 +376,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 @@
-821ef71efe4cd8c4e8e2ceadb8e1585dcfe868a6c2f2f8eaab6dad3bd6e04431
+14b4708a748d842d0a925ffcb3e181b338b3cdd02caf4163f69ac455485a4758