senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(subscription): pending_payment state machine + mandatory provider (v1.0.9 item G — Phase 1)

Browse source 
First instalment of Item G from docs/audit-2026-04/v107-plan.md §G.
This commit lands the state machine + create-flow change. Phase 2
(webhook handler + recovery endpoint + reconciler sweep) follows.

What changes :
  - **`models.go`** — adds `StatusPendingPayment` to the
    SubscriptionStatus enum. Free-text VARCHAR(30) so no DDL needed
    for the value itself; Phase 2's reconciler index lives in
    migration 986 (additive, partial index on `created_at` WHERE
    status='pending_payment').
  - **`service.go`** — `PaymentProvider.CreateSubscriptionPayment`
    interface gains an `idempotencyKey string` parameter, mirroring
    the marketplace.refundProvider contract added in v1.0.7 item D.
    Callers pass the new subscription row's UUID so a retried HTTP
    request collapses to one PSP charge instead of duplicating it.
  - **`createNewSubscription`** — refactored state machine :
      * Free plan → StatusActive (unchanged, in subscribeToFreePlan).
      * Paid plan, trial available, first-time user → StatusTrialing,
        no PSP call (no invoice either — Phase 2 will create the
        first paid invoice on trial expiry).
      * Paid plan, no trial / repeat user → **StatusPendingPayment**
        + invoice + PSP CreateSubscriptionPayment with idempotency
        key = subscription.ID.String(). Webhook
        subscription.payment_succeeded (Phase 2) flips to active;
        subscription.payment_failed flips to expired.
  - **`if s.paymentProvider != nil` short-circuit removed**. Paid
    plans now require a configured PaymentProvider — without one,
    `createNewSubscription` returns ErrPaymentProviderRequired. The
    handler maps this to HTTP 503 "Payment provider not configured —
    paid plans temporarily unavailable", surfacing env misconfig to
    ops instead of silently giving away paid plans (the v1.0.6.2
    fantôme bug class).
  - **`GetUserSubscription` query unchanged** — already filters on
    `status IN ('active','trialing')`, so pending_payment rows
    correctly read as "no active subscription" for feature-gate
    purposes. The v1.0.6.2 hasEffectivePayment filter is kept as
    defence-in-depth for legacy rows.
  - **`hyperswitch.Provider`** — implements
    `subscription.PaymentProvider` by delegating to the existing
    `CreatePaymentSimple`. Compile-time interface assertion added
    (`var _ subscription.PaymentProvider = (*Provider)(nil)`).
  - **`routes_subscription.go`** — wires the Hyperswitch provider
    into `subscription.NewService` when HyperswitchEnabled +
    HyperswitchAPIKey + HyperswitchURL are all set. Without those,
    the service falls back to no-provider mode (paid subscribes
    return 503).
  - **Tests** : new TestSubscribe_PendingPaymentStateMachine in
    gate_test.go covers all five visible outcomes (free / paid+
    provider / paid+no-provider / first-trial / repeat-trial) with a
    fakePaymentProvider that records calls. Asserts on idempotency
    key = subscription.ID.String(), PSP call counts, and the
    Subscribe response shape (client_secret + payment_id surfaced).
    5/5 green, sqlite :memory:.

Phase 2 backlog (next session) :
  - `ProcessSubscriptionWebhook(ctx, payload)` — flip pending_payment
    → active on success / expired on failure, idempotent against
    replays.
  - Recovery endpoint `POST /api/v1/subscriptions/complete/:id` —
    return the existing client_secret to resume a stalled flow.
  - Reconciliation sweep for rows stuck in pending_payment past the
    webhook-arrival window (uses the new partial index from
    migration 986).
  - Distribution.checkEligibility explicit pending_payment branch
    (today it's already handled implicitly via the active/trialing
    filter).
  - E2E @critical : POST /subscribe → POST /distribution/submit
    asserts 403 with "complete payment" until webhook fires.

Backward compat : clients on the previous flow that called
/subscribe expecting an immediately-active row will now see
status=pending_payment + a client_secret. They must drive the PSP
confirm step before the row is granted feature access. The
v1.0.6.2 voided_subscriptions cleanup migration (980) handles
pre-existing fantôme rows.

go build ./... clean. Subscription + handlers test suites green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
senke 2026-04-26 10:02:00 +02:00
parent ed1bb4084a
commit 2a96766ae3
8 changed files with 346 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
veza-backend-api/internal/api/routes_subscription.go
View file

@ -5,11 +5,23 @@ import (
"veza-backend-api/internal/core/subscription"
"veza-backend-api/internal/handlers"
"veza-backend-api/internal/services/hyperswitch"
)
// setupSubscriptionRoutes configures routes for subscription plans management (v0.12.1)
// setupSubscriptionRoutes configures routes for subscription plans management (v0.12.1).
//
// v1.0.9 item G — when Hyperswitch is configured, the subscription
// service is built with a PaymentProvider. Without it, paid-plan
// subscribe attempts fail with HTTP 503 "payment provider not
// configured" (replaces the v1.0.6.2 silent fantôme creation).
func (r *APIRouter) setupSubscriptionRoutes(router *gin.RouterGroup) {
svc := subscription.NewService(r.db.GormDB, r.logger)
opts := []subscription.ServiceOption{}
if r.config.HyperswitchEnabled && r.config.HyperswitchAPIKey != "" && r.config.HyperswitchURL != "" {
hsClient := hyperswitch.NewClient(r.config.HyperswitchURL, r.config.HyperswitchAPIKey)
hsProvider := hyperswitch.NewProvider(hsClient)
opts = append(opts, subscription.WithPaymentProvider(hsProvider))
}
svc := subscription.NewService(r.db.GormDB, r.logger, opts...)
handler := handlers.NewSubscriptionHandler(svc, r.logger)
group := router.Group("/subscriptions")

198
veza-backend-api/internal/core/subscription/gate_test.go
View file

@ -167,3 +167,201 @@ func TestGetUserSubscription_PaymentGate(t *testing.T) {
})
}
}
// fakePaymentProvider records the calls it received so the tests can
// assert on idempotency-key threading + arg shapes. Returns
// deterministic payment_id / client_secret pairs.
type fakePaymentProvider struct {
calls []fakePaymentCall
createErr error
getStatusValue string
}
type fakePaymentCall struct {
idempotencyKey string
amountCents int
currency string
subscriptionID string
metadata map[string]string
}
func (f *fakePaymentProvider) CreateSubscriptionPayment(_ context.Context, idempotencyKey string, amountCents int, currency, subscriptionID, _ string, metadata map[string]string) (string, string, error) {
f.calls = append(f.calls, fakePaymentCall{
idempotencyKey: idempotencyKey,
amountCents: amountCents,
currency: currency,
subscriptionID: subscriptionID,
metadata: metadata,
})
if f.createErr != nil {
return "", "", f.createErr
}
return "pay_" + idempotencyKey[:8], "sec_" + idempotencyKey[:8], nil
}
func (f *fakePaymentProvider) GetPayment(_ context.Context, _ string) (string, error) {
return f.getStatusValue, nil
}
// TestSubscribe_PendingPaymentStateMachine exercises v1.0.9 item G's
// state machine on the new-subscription path. Covers the visible
// outcomes : free plan stays active, paid plan with provider goes to
// pending_payment + idempotency-key threaded, paid plan without
// provider returns ErrPaymentProviderRequired (mapped to 503 in the
// handler), trial-eligible first-time user gets trialing without a
// PSP call, and a repeat user (already used trial) falls through to
// pending_payment.
func TestSubscribe_PendingPaymentStateMachine(t *testing.T) {
ctx := context.Background()
freePlan := Plan{
ID: uuid.New(),
Name: PlanFree,
DisplayName: "Free",
PriceMonthly: 0,
IsActive: true,
}
paidPlan := Plan{
ID: uuid.New(),
Name: PlanCreator,
DisplayName: "Creator",
PriceMonthly: 999,
PriceYearly: 9990,
Currency: "USD",
IsActive: true,
}
paidPlanWithTrial := Plan{
ID: uuid.New(),
Name: PlanPremium,
DisplayName: "Premium",
PriceMonthly: 1999,
Currency: "USD",
TrialDays: 14,
IsActive: true,
}
type setup struct {
plan Plan
provider *fakePaymentProvider
seedTrial bool // pre-seed a trial row so the trial-eligibility branch is exercised
}
cases := []struct {
name string
setup setup
expectStatus SubscriptionStatus
expectPSP bool
expectErr error
}{
{
name: "free plan stays active and skips provider",
setup: setup{
plan: freePlan,
provider: &fakePaymentProvider{},
},
expectStatus: StatusActive,
expectPSP: false,
},
{
name: "paid plan + provider configured -> pending_payment + PSP call",
setup: setup{
plan: paidPlan,
provider: &fakePaymentProvider{},
},
expectStatus: StatusPendingPayment,
expectPSP: true,
},
{
name: "paid plan + no provider -> ErrPaymentProviderRequired",
setup: setup{
plan: paidPlan,
provider: nil,
},
expectErr: ErrPaymentProviderRequired,
},
{
name: "trial-eligible first-time user -> trialing, no PSP call",
setup: setup{
plan: paidPlanWithTrial,
provider: &fakePaymentProvider{},
},
expectStatus: StatusTrialing,
expectPSP: false,
},
{
name: "trial repeat user -> falls through to pending_payment",
setup: setup{
plan: paidPlanWithTrial,
provider: &fakePaymentProvider{},
seedTrial: true,
},
expectStatus: StatusPendingPayment,
expectPSP: true,
},
}
for _, tc := range cases {
t.Run(tc.name, func(t *testing.T) {
db, err := gorm.Open(sqlite.Open(":memory:"), &gorm.Config{})
require.NoError(t, err)
require.NoError(t, db.AutoMigrate(&Plan{}, &UserSubscription{}, &Invoice{}))
require.NoError(t, db.Create(&tc.setup.plan).Error)
opts := []ServiceOption{}
if tc.setup.provider != nil {
opts = append(opts, WithPaymentProvider(tc.setup.provider))
}
svc := NewService(db, zap.NewNop(), opts...)
userID := uuid.New()
if tc.setup.seedTrial {
past := time.Now().Add(-30 * 24 * time.Hour)
old := UserSubscription{
UserID: userID, PlanID: tc.setup.plan.ID,
Status: StatusExpired,
BillingCycle: BillingMonthly,
CurrentPeriodStart: past,
CurrentPeriodEnd: past.Add(time.Hour),
TrialStart: &past,
TrialEnd: &past,
}
require.NoError(t, db.Create(&old).Error)
}
resp, err := svc.Subscribe(ctx, userID, SubscribeRequest{
PlanID: tc.setup.plan.ID,
BillingCycle: BillingMonthly,
})
if tc.expectErr != nil {
require.Error(t, err)
require.True(t, errors.Is(err, tc.expectErr),
"expected %v, got %v", tc.expectErr, err)
return
}
require.NoError(t, err)
require.NotNil(t, resp.Subscription)
require.Equal(t, tc.expectStatus, resp.Subscription.Status)
if tc.expectPSP {
require.Len(t, tc.setup.provider.calls, 1,
"expected exactly one PSP call")
call := tc.setup.provider.calls[0]
// Idempotency key must be the new subscription row's
// UUID — protects against retried HTTP requests
// collapsing into one PSP charge.
require.Equal(t, resp.Subscription.ID.String(), call.idempotencyKey)
require.NotEmpty(t, call.idempotencyKey)
require.Equal(t, resp.Subscription.ID.String(), call.subscriptionID)
require.Equal(t, "USD", call.currency)
require.Equal(t, tc.setup.plan.PriceMonthly, call.amountCents)
require.Equal(t, userID.String(), call.metadata["user_id"])
require.NotEmpty(t, resp.ClientSecret, "client_secret returned to caller")
require.NotEmpty(t, resp.PaymentID, "payment_id returned to caller")
} else if tc.setup.provider != nil {
require.Len(t, tc.setup.provider.calls, 0,
"expected zero PSP calls when expectPSP=false")
}
})
}
}

7
veza-backend-api/internal/core/subscription/models.go
View file

@ -25,6 +25,13 @@ const (
StatusCanceled SubscriptionStatus = "canceled"
StatusPastDue SubscriptionStatus = "past_due"
StatusExpired SubscriptionStatus = "expired"
// StatusPendingPayment (v1.0.9 item G) — paid-plan subscription
// row created but the PSP charge has not been confirmed yet.
// Webhook subscription.payment_succeeded → flip to active.
// Webhook subscription.payment_failed → flip to expired.
// Replaces the v1.0.6.2 "active row without PSP linkage" fantôme
// pattern that hasEffectivePayment had to filter retroactively.
StatusPendingPayment SubscriptionStatus = "pending_payment"
)
// BillingCycle represents the billing frequency

118
veza-backend-api/internal/core/subscription/service.go
View file

@ -27,13 +27,29 @@ var (
// being invoked (e.g., HYPERSWITCH_ENABLED=false). Callers that gate features
// by subscription should treat this as ineligible. The /me/subscription
// handler surfaces a specific message so honest-path users know to contact
// support.
// support. Item G makes new code paths skip this state altogether by
// using StatusPendingPayment instead — but the filter is kept as
// defence-in-depth for legacy rows that pre-date the migration.
ErrSubscriptionNoPayment = errors.New("subscription has no effective payment linkage")
// ErrPaymentProviderRequired (v1.0.9 item G): a paid plan subscribe
// attempt was made without a configured PaymentProvider. v1.0.6.2
// silently let this through, leaving rows in `active` with no PSP
// linkage. Item G fail-closes — the handler maps this to HTTP 503
// "payment provider not configured" so an env misconfiguration is
// loud instead of silently giving away paid plans.
ErrPaymentProviderRequired = errors.New("paid plan requires a configured payment provider")
)
// PaymentProvider defines the interface for subscription payments
// PaymentProvider defines the interface for subscription payments.
//
// idempotencyKey (v1.0.9 item G) — must be unique per logical
// subscription creation; passed through to the PSP's `Idempotency-Key`
// HTTP header. Callers pass the new subscription row's UUID so a
// retried HTTP request from the same Subscribe() call collapses to one
// PSP charge. Empty key MUST cause a loud failure rather than a silent
// header omission, mirroring the marketplace.refundProvider contract.
type PaymentProvider interface {
CreateSubscriptionPayment(ctx context.Context, amountCents int, currency, subscriptionID, returnURL string, metadata map[string]string) (paymentID, clientSecret string, err error)
CreateSubscriptionPayment(ctx context.Context, idempotencyKey string, amountCents int, currency, subscriptionID, returnURL string, metadata map[string]string) (paymentID, clientSecret string, err error)
GetPayment(ctx context.Context, paymentID string) (status string, err error)
}
@ -257,7 +273,24 @@ func (s *Service) subscribeToFreePlan(ctx context.Context, userID uuid.UUID, pla
return &SubscribeResponse{Subscription: sub}, nil
}
// createNewSubscription creates a subscription for a paid plan
// createNewSubscription creates a subscription for a paid plan.
//
// v1.0.9 item G — state machine:
// - Trial available + first-time user → status=trialing, no PSP call,
// no invoice. Trial expiry will require a follow-up flow that
// creates the first paid invoice and transitions the row.
// - Trial available + repeat user (already used trial) → falls
// through to the paid-plan branch with status=pending_payment.
// - Paid plan, no trial / repeat → status=pending_payment, invoice
// created with PSP payment_id, client_secret returned for the
// frontend to drive the payment UI. Webhook
// subscription.payment_succeeded flips to active. Webhook
// subscription.payment_failed flips to expired.
//
// PaymentProvider is now mandatory for any paid-plan subscribe path
// that hits the PSP (replaces the v1.0.6.2 silent short-circuit). The
// handler maps ErrPaymentProviderRequired to HTTP 503 so misconfig is
// surfaced to ops, not silently absorbed.
func (s *Service) createNewSubscription(ctx context.Context, userID uuid.UUID, plan *Plan, cycle BillingCycle) (*SubscribeResponse, error) {
now := time.Now()
var periodEnd time.Time
@ -285,31 +318,46 @@ func (s *Service) createNewSubscription(ctx context.Context, userID uuid.UUID, p
// SECURITY(REM-015): Trial check + subscription creation in single transaction to prevent
// race condition where two concurrent requests both see previousTrialCount=0.
err := s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
// Apply trial if available — checked INSIDE transaction for atomicity
// Apply trial if available — checked INSIDE transaction for atomicity.
// First-time trial users get StatusTrialing (no immediate PSP call).
// Repeat users (or no trial offered) fall through to the paid path
// which creates the row in StatusPendingPayment.
var inTrial bool
if plan.TrialDays > 0 {
var previousTrialCount int64
tx.Model(&UserSubscription{}).
Where("user_id = ? AND trial_start IS NOT NULL", userID).
Count(&previousTrialCount)
if previousTrialCount > 0 {
sub.Status = StatusActive
} else {
if previousTrialCount == 0 {
trialEnd := now.AddDate(0, 0, plan.TrialDays)
sub.Status = StatusTrialing
sub.TrialStart = &now
sub.TrialEnd = &trialEnd
sub.CurrentPeriodEnd = trialEnd
inTrial = true
}
} else {
sub.Status = StatusActive
}
if !inTrial {
// Paid plan, no trial → row enters pending_payment state.
// Will transition to active on subscription.payment_succeeded
// webhook, or to expired on subscription.payment_failed.
sub.Status = StatusPendingPayment
}
if err := tx.Create(sub).Error; err != nil {
return fmt.Errorf("failed to create subscription: %w", err)
}
// Create invoice (for paid plans, not during trial)
if !sub.IsTrialing() && amountCents > 0 {
// Create invoice + open PSP charge (paid plans not in trial).
if !inTrial && amountCents > 0 {
// v1.0.9 item G: payment provider is mandatory here. The
// previous silent `if s.paymentProvider != nil` branch left
// the row in `active` without PSP linkage when Hyperswitch
// was disabled — effectively giving the plan away.
if s.paymentProvider == nil {
return ErrPaymentProviderRequired
}
invoice := &Invoice{
SubscriptionID: sub.ID,
UserID: userID,
@ -323,31 +371,27 @@ func (s *Service) createNewSubscription(ctx context.Context, userID uuid.UUID, p
return fmt.Errorf("failed to create invoice: %w", err)
}
// TODO(v1.0.7-item-G): make payment provider mandatory for paid plans.
// Today `if s.paymentProvider != nil` short-circuits silently when
// Hyperswitch is disabled, leaving the row `active` with no PSP
// linkage. Item G replaces this with a mandatory pending_payment
// state + webhook-driven activation. Until then, v1.0.6.2
// compensates via the `GetUserSubscription` filter.
if s.paymentProvider != nil {
var err error
paymentID, clientSecret, err = s.paymentProvider.CreateSubscriptionPayment(
ctx, amountCents, plan.Currency, sub.ID.String(),
"", // returnURL to be set by frontend
map[string]string{
"user_id": userID.String(),
"subscription_id": sub.ID.String(),
"plan": string(plan.Name),
"billing_cycle": string(cycle),
},
)
if err != nil {
return fmt.Errorf("failed to create payment: %w", err)
}
invoice.HyperswitchPaymentID = paymentID
if err := tx.Save(invoice).Error; err != nil {
return fmt.Errorf("failed to update invoice with payment ID: %w", err)
}
var psErr error
paymentID, clientSecret, psErr = s.paymentProvider.CreateSubscriptionPayment(
ctx,
sub.ID.String(), // idempotency key (item G + item D pattern)
amountCents,
plan.Currency,
sub.ID.String(),
"", // returnURL — the frontend sets it on the confirm step
map[string]string{
"user_id": userID.String(),
"subscription_id": sub.ID.String(),
"plan": string(plan.Name),
"billing_cycle": string(cycle),
},
)
if psErr != nil {
return fmt.Errorf("failed to create payment: %w", psErr)
}
invoice.HyperswitchPaymentID = paymentID
if err := tx.Save(invoice).Error; err != nil {
return fmt.Errorf("failed to update invoice with payment ID: %w", err)
}
}

7
veza-backend-api/internal/handlers/subscription_handler.go
View file

@ -111,6 +111,13 @@ func (h *SubscriptionHandler) Subscribe(c *gin.Context) {
RespondWithAppError(c, apperrors.NewValidationError("Already subscribed to this plan"))
case errors.Is(err, subscription.ErrInvalidBillingCycle):
RespondWithAppError(c, apperrors.NewValidationError("Invalid billing cycle: must be 'monthly' or 'yearly'"))
case errors.Is(err, subscription.ErrPaymentProviderRequired):
// v1.0.9 item G: paid plan attempted but no PaymentProvider
// is wired (HYPERSWITCH_ENABLED=false in dev, or missing
// credentials in staging). Surface the misconfig as 503 so
// ops sees it instead of silently absorbing it as a free
// active subscription.
RespondWithAppError(c, apperrors.NewServiceUnavailableError("Payment provider not configured — paid plans temporarily unavailable"))
default:
RespondWithAppError(c, apperrors.NewInternalErrorWrap("Failed to subscribe", err))
}

15
veza-backend-api/internal/services/hyperswitch/provider.go
View file

@ -4,11 +4,15 @@ import (
"context"
"veza-backend-api/internal/core/marketplace"
"veza-backend-api/internal/core/subscription"
)
// Ensure Provider implements marketplace.PaymentProvider
var _ marketplace.PaymentProvider = (*Provider)(nil)
// Ensure Provider implements subscription.PaymentProvider (v1.0.9 item G).
var _ subscription.PaymentProvider = (*Provider)(nil)
// Provider adapts the Hyperswitch client to marketplace.PaymentProvider.
type Provider struct {
client *Client
@ -67,3 +71,14 @@ func (p *Provider) CreateRefund(ctx context.Context, idempotencyKey, paymentID s
}
return resp.RefundID, resp.Status, nil
}
// CreateSubscriptionPayment opens a payment intent for a subscription
// invoice (v1.0.9 item G). Same wire shape as CreatePayment — the
// difference is semantic: the metadata carries `subscription_id` and
// the idempotency key is the new subscription row's UUID, so the row
// can be correlated back from the subsequent webhook.
//
// Implements subscription.PaymentProvider.
func (p *Provider) CreateSubscriptionPayment(ctx context.Context, idempotencyKey string, amountCents int, currency, subscriptionID, returnURL string, metadata map[string]string) (paymentID, clientSecret string, err error) {
return p.client.CreatePaymentSimple(ctx, idempotencyKey, int64(amountCents), currency, subscriptionID, returnURL, metadata)
}

22
veza-backend-api/migrations/986_user_subscriptions_pending_payment_index.sql Normal file
View file

@ -0,0 +1,22 @@
-- v1.0.9 Item G — subscription pending_payment state machine.
--
-- The user_subscriptions.status column is a free-text VARCHAR(30) with
-- no DB-level enum, so the new 'pending_payment' value introduced by
-- the Go const StatusPendingPayment requires no DDL. This migration is
-- documentation + an index that the future reconciliation worker
-- (Phase 2) needs to find rows stuck in pending_payment past the
-- webhook-arrival window.
--
-- Index strategy : a partial index on (created_at) WHERE status =
-- 'pending_payment' is the smallest possible footprint that still
-- gives the reconciler an O(log N) scan for "rows older than 30m
-- that haven't transitioned yet". A non-partial composite index would
-- pay storage cost for every row in the table; partial keeps it
-- proportional to the in-flight set.
CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_user_subscriptions_pending_payment
ON user_subscriptions (created_at)
WHERE status = 'pending_payment';
COMMENT ON INDEX idx_user_subscriptions_pending_payment IS
'v1.0.9 Item G — feeds the subscription reconciliation sweep that catches rows stuck in pending_payment past the webhook deadline.';

2
veza-backend-api/migrations/rollback/986_user_subscriptions_pending_payment_index_down.sql Normal file
View file

@ -0,0 +1,2 @@
-- Rollback for 986 — drop the partial index.
DROP INDEX IF EXISTS idx_user_subscriptions_pending_payment;