Crate syrup_rail_postgres

Expand description

PostgreSQL schema contract and transaction orchestration for Syrup Rail.

Production service construction must not expose or invoke a migrator; host applications materialize versioned install artifacts as immutable migrations.

§syrup-rail-postgres

syrup-rail-postgres provides Syrup Rail’s canonical provider-neutral ledger, SQLx operations, and high-level subscription billing service. Version 0.2 supports PostgreSQL 18 only and uses schema v2.

[dependencies]
syrup-rail = "0.2.0"
syrup-rail-postgres = "0.2.0"

New hosts install schema/v2/install.sql through their normal migration system. Hosts upgrading from 0.1 must stop every 0.1 billing writer, run the checked-in v1 preflight and retry-reclassification audit, apply schema/v2/upgrade_from_v1.sql transactionally, and roll forward with 0.2. Schema v1 is immutable. Budget the stopped-writer maintenance window for a full payment-attempt heap scan and transactional partial-index construction; the detailed cutover guide explains the lock and rehearsal requirements.

After the host applies its migration and before it serves billing traffic, verify the runtime catalog:

syrup_rail_postgres::assert_runtime_schema_v2_compatible(pool).await?;

During REINDEX CONCURRENTLY, PostgreSQL exposes the command, phase, and target details only to the maintenance role and statistics-privileged roles. The runtime assertion tolerates _ccnew and _ccold shadows only when those visible progress details and the backend’s relation locks agree, then rechecks the evidence before committing. Run maintenance and startup validation as the same database role when startup must remain available during a reindex; a cross-role observer fails closed. Drop stale invalid shadows left by failed maintenance before serving billing traffic.

SubscriptionBillingService is the primary mutation facade. Hosts supply offer locking, gateway resolution, abuse admission, and a transaction coordinator that locks the authorized billing subject first and appends every typed BillingEvent to the host outbox on the same connection. The packaged host_integration example includes concrete service wiring and a versioned, redacted host-owned event-envelope mapping. It separates first-write metadata from the replay-stable value and demonstrates the complete atomic insert/conflict-read/raw-structural-comparison/typed-reconstruction path on the same transaction. Version 1 owns its nested enum labels instead of delegating them to core display methods. The example keeps subject identifiers and payload values out of Debug output; its card payload uses the core canonical brand vocabulary and never copies an unknown provider string into the host event.

Errors returned by host transaction, event, charge-target, and operator-review callbacks remain opaque through ordinary formatting and the standard Error::source() chain. A host can deliberately recover its original callback error only by classifying the outer service error, destructuring an owned callback-error variant, and consuming that wrapper with into_source() in a protected diagnostic path.

Customer billing portal/history queries, stable due-renewal pagination, and other lower-level transaction-local operations remain available for hosts that need to compose them into a larger application transaction. The protected-write guard described below deliberately owns its top-level transaction instead. Authentication, authorization, migrations, job queues, and event transport remain host-owned.

Protected product writes use two ownership-enforced phases. Start an EntitlementWriteTransaction from the pool and use its connection for any preparatory host writes; that pending value has no commit operation. require_entitlement_for_update returns an AdmittedEntitlementWriteTransaction only when current paid or granted access is admitted and keeps the relevant locks held for the host mutation. Completed denials and SQL failures await rollback, while cancellation queues rollback of the owned transaction, including any earlier host writes. Perform and commit the host-owned protected mutation only through the admitted value, and finish any nested savepoint before consuming that value with commit or rollback.

This package is proprietary software distributed under the terms in the packaged LICENSE file.

Structs§

AdmittedEntitlementWriteTransaction: A top-level transaction that passed entitlement admission.
AdmittedHostCharge
AdmittedSubscriptionEnrollment: One committed final-admission result that authorizes exactly one immediate provider submission by consuming this value.
AdmittedSubscriptionPaymentMethodReplacement: One committed final-admission result authorizing exactly one immediate Customer Vault mutation.
AdmittedSubscriptionRecovery: One committed final-admission result authorizing exactly one immediate subscription-recovery submission.
AdmittedSubscriptionRenewal: One committed final-admission result authorizing exactly one immediate automatic recurring charge.
BillingEventWriteError: Value-redacted failure returned while appending a host outbox event.
BillingTransactionError: Value-redacted failure returned by the host transaction coordinator.
EntitlementWriteTransaction: A top-level PostgreSQL transaction awaiting entitlement admission.
ExternalReversalHostStoreError: Value-redacted failure returned by the host’s reversal target store.
GatewayLifecycleQuarantineAlert
GatewayLifecycleQuarantineResolutionRecord
GatewayLifecycleQuarantineReviewRecord
GatewayLifecycleReconciliationSummary
HostChargeLedgerAdmissionQuery
HostChargeSubmissionAdmission
HostChargeTargetError: Value-redacted failure returned by the host charge-target store.
HostChargeTargetReservation
ManualAttemptFailureHostStoreError: Value-redacted failure returned by the host’s manual-failure store.
ProcessorChargeClassificationSummary
SubscriptionBillingService: High-level provider-neutral billing facade for authorized host commands.
SubscriptionEnrollmentOfferContext: Stable identity and lifecycle context for locking an enrollment offer.

Enums§

BillingTransactionSubjectState: Durable availability of the host recipient locked for a billing event.
CompensatingProcessorChargeOutcome
EntitlementGuardError
EntitlementQueryError
ExactQueryObservation
ExternalReversalAttestationOutcome
ExternalReversalHostTransitionOutcome
GatewayLifecycleApplyOutcome
GatewayLifecycleQuarantineResolutionOutcome
GatewayLifecycleReconciliationError
GatewayMutationCooldownScope: Canonical cooldown level that stopped a gateway mutation before submission.
HostChargeAdmissionOutcome
HostChargeApplicationError
HostChargeLedgerAdmission
HostChargeLedgerAdmissionError
HostChargeLedgerAdmissionMode
HostChargePreflightOutcome
HostChargeProviderResult
HostChargeReservationDecision
HostChargeReservationOutcome
HostChargeStoreError
HostChargeSubmissionDecision
HostChargeSubmissionOutcome
ManualAttemptFailureHostTransitionOutcome
OperatorReviewError
PaymentAttemptStoreError
ProcessorChargeObservationOutcome
ProcessorChargeStoreError
RenewalStoreError
SchemaConformanceError: Why a host database does not satisfy a canonical schema contract.
SubscriptionBillingPortalQueryError: Error returned while loading a customer-facing billing portal projection.
SubscriptionBillingServiceError: Failure returned by the high-level subscription billing facade.
SubscriptionBillingServiceErrorDisposition: A stable, conservative operational category for a SubscriptionBillingServiceError.
SubscriptionCancellationError
SubscriptionDiscountOperationError
SubscriptionEnrollmentAdmissionOutcome
SubscriptionEnrollmentApplicationError
SubscriptionEnrollmentOfferStage: The lifecycle boundary at which enrollment terms are locked.
SubscriptionEnrollmentProviderResult
SubscriptionGrantMutationError
SubscriptionPaymentMethodReplacementAdmissionOutcome
SubscriptionPaymentMethodReplacementProviderResult
SubscriptionRecoveryAdmissionOutcome
SubscriptionRecoveryProviderResult
SubscriptionRenewalAdmissionOutcome
SubscriptionRenewalProviderResult

Constants§

SUPPORTED_POSTGRES_MAJOR_VERSION: The only PostgreSQL major version supported by this crate and schema contract.

Traits§

BillingTransaction: One host-owned transaction and its typed event projection capability.
BillingTransactionCoordinator: Host-prepared transaction whose subject authorization lock is acquired before any shared billing lock.
ExternalReversalHostStore
HostChargeTargetStore: Host-owned target extension composed into shared ledger transactions.
ManualAttemptFailureHostStore
SubscriptionOfferStore

Functions§

activate_gateway_configuration: Activates an exact gateway configuration without touching cooldown state.
admit_host_charge_submission
admit_host_charge_submission_in_transaction
admit_subscription_enrollment_submission: Owns and commits final enrollment admission before exposing a one-shot submission capability. A rolled-back transaction can never yield the capability consumed by submit_admitted_subscription_enrollment.
admit_subscription_enrollment_submission_in_transaction: Revalidates a prepared initial attempt and durably admits its one provider mutation.
admit_subscription_payment_method_replacement: Commits final payment-method replacement admission before exposing its one-shot Customer Vault capability.
admit_subscription_payment_method_replacement_in_transaction: Revalidates the exact subscription baseline and commits one-shot Customer Vault admission. Semantic drift terminalizes the prepared attempt.
admit_subscription_recovery_submission: Commits final recovery admission before exposing its one-shot capability.
admit_subscription_recovery_submission_in_transaction: Revalidates the exact locked snapshot and commits one-shot provider admission. Every semantic rejection terminalizes the prepared attempt.
admit_subscription_renewal_submission: Commits final automatic-renewal admission and captures the exact stored credential.
admit_subscription_renewal_submission_in_transaction: Revalidates one exact renewal snapshot and commits one-shot submission admission.
apply_exact_query_observation: Applies one authoritative negative exact-query observation.
apply_gateway_lifecycle_evidence
apply_host_charge_gateway_outcome
apply_reconciled_host_charge_gateway_outcome
apply_reconciled_subscription_enrollment_gateway_outcome: Applies an already-observed provider outcome to an exact durable enrollment attempt.
apply_reconciled_subscription_payment_method_replacement_gateway_outcome
apply_reconciled_subscription_recovery_gateway_outcome: Re-enters the same recovery application authority from durable evidence and never resolves a live gateway or submits another mutation.
apply_reconciled_subscription_renewal_gateway_outcome
apply_staged_gateway_lifecycle_evidence
apply_subscription_enrollment_gateway_outcome: Applies one initial-enrollment gateway outcome to the durable billing ledger.
apply_subscription_payment_method_replacement_gateway_outcome
apply_subscription_recovery_gateway_outcome: Applies one recovery outcome through the canonical charge ledger and host billing transaction.
apply_subscription_renewal_gateway_outcome
assert_runtime_schema_v2_compatible: Asserts that a host database is compatible with the canonical schema-v2 contract before the host accepts billing work.
attempt_review_page
attest_external_reversal
billing_deletion_blockers: Reports the canonical financial rows that prevent host account deletion.
cancel_subscription_in_transaction: Cancels one exact scope/subscriber/plan subscription inside the caller’s transaction.
claim_exact_reconciliation_attempts: Claims one bounded, account-scoped batch for authoritative exact queries.
claim_gateway_lifecycle_quarantine_alert
claim_subscription_discount
claim_subscription_discount_in_transaction
classify_pending_processor_charges: Classifies one bounded batch of durable pending processor charges.
clear_subscription_discount
clear_subscription_discount_in_transaction
create_subscription_discount_code
create_subscription_discount_code_in_transaction: Creates an active durable code after validating its terms against the locked current offer. The returned value is the administrative record; use validate_subscription_discount_code_in_transaction to obtain a quote.
create_subscription_grant: Creates a grant inside the caller’s transaction.
disable_subscription_discount_code
disable_subscription_discount_code_in_transaction: Disables an administrative record even when its historical terms are no longer quoteable against the host’s current offer.
due_renewals: Returns the first deterministic, provider-neutral renewal dispatch page.
due_renewals_page: Returns one deterministic page of renewal work due in a stable scan.
entitlement: Loads one exact scope/subscriber/plan entitlement from a single database snapshot.
fail_review_required_attempt
fail_stale_unsubmitted_payment_method_replacements: Fails one bounded batch of stale payment-method replacements for an account.
fail_stale_unsubmitted_subscription_enrollments: Expires every stale prepared enrollment for one account.
find_payment_attempt_by_id_in_transaction: Loads an attempt by its exact scope and durable identity without locking it.
gateway_lifecycle_quarantine_review_page
gateway_lifecycle_reconciliation_start
host_charge_ledger_admission
list_subscription_discount_codes
list_subscription_discount_codes_in_transaction: Lists durable administrative records without reinterpreting them against the current offer. Quote eligibility is intentionally owned by validate_subscription_discount_code_in_transaction.
lock_payment_attempt_by_idempotency_in_transaction: Locks the exact owner-scoped idempotency row for replay or mutation.
mark_subscription_discount_claim_applied_in_transaction
observe_processor_charge_in_transaction
preflight_host_charge_in_transaction
preflight_subscription_enrollment_in_transaction: Resolves subscriber-wide enrollment idempotency before host admission.
preflight_subscription_payment_method_replacement_in_transaction: Resolves payment-method replacement idempotency before host admission.
preflight_subscription_recovery_in_transaction: Resolves subscriber-wide recovery idempotency before host admission.
processor_charge_review_page
reconcile_gateway_transaction_reports
reconciliation_gateway_accounts: Returns every registered gateway account in deterministic locator order.
record_gateway_lifecycle_quarantines
register_gateway_account: Registers canonical gateway metadata on the caller’s connection.
renewal_attempt_state: Computes the one shared renewal/recovery period ledger state.
require_entitlement_for_update: Locks and revalidates one exact entitlement inside a top-level transaction.
reserve_host_charge_in_transaction
reserve_subscription_enrollment_in_transaction: Reserves or resumes one exact-plan initial enrollment inside the caller’s transaction.
reserve_subscription_payment_method_replacement_in_transaction: Locks the exact subscription baseline and reserves a token-free replacement attempt before Customer Vault I/O.
reserve_subscription_recovery_in_transaction: Locks the canonical subscription, derives the exact due-period request, and inserts a token-free recovery attempt in one transaction.
reserve_subscription_renewal_in_transaction: Locks one exact due subscription and inserts its automatic-renewal attempt.
resolve_gateway_lifecycle_quarantine
revoke_subscription_grant: Revokes an exact grant inside the caller’s transaction.
save_gateway_lifecycle_reconciliation_cursor
saved_subscription_discount_claim
saved_subscription_discount_claim_in_transaction
scrub_subscriber_billing_data: Removes the canonical mutable billing PII for one subscriber.
stage_gateway_lifecycle_evidence
store_compensating_processor_charge
submit_admitted_host_charge
submit_admitted_subscription_enrollment: Performs the one provider sale authorized by a committed final admission, then applies or durably parks its result.
submit_admitted_subscription_payment_method_replacement: Performs the one Customer Vault mutation authorized by committed admission.
submit_admitted_subscription_recovery: Performs the one provider sale authorized by committed recovery admission, then applies or durably parks its result without holding a database lock across provider I/O.
submit_admitted_subscription_renewal: Performs the one recurring sale authorized by committed renewal admission.
subscription_billing_portal: Loads a provider-neutral customer billing portal from one PostgreSQL snapshot.
subscription_payment_history_page: Returns one strict descending page of exact-plan subscription payment history.
transition_processor_charge_in_transaction
update_subscription_discount_code
update_subscription_discount_code_in_transaction: Updates a durable administrative record. Active records are validated against the locked current offer. Disabled records remain administrable without requiring their historical terms to be quoteable today.
validate_subscription_discount_code
validate_subscription_discount_code_in_transaction