feat(purchases): in-app revocation within free-cancel window (closes #290)

[cristim]

Summary

Implements in-app purchase revocation with two complementary layers:

1. Pre-fire delay (primary path, new): defer the cloud-provider SDK call by a configurable window (default 48h). Revoking during that window is a local DB cancel — zero provider involvement, zero cost, works identically for AWS / Azure / GCP.
2. Provider-cancel API fallback (the original feat(purchases): in-app revocation within free-cancel window (closes #290) #804 design): if the row has already moved past the delay window to completed, the existing Azure CalculateRefund + Return SDK call still applies. AWS/GCP return 422 here (no public cancel API).

Closes #290.

The Gmail-style pre-fire delay (primary path)

Setting	Default	Range	Where
PurchaseDelayHours	48	[0, 168]	global config (Settings UI)

Flow

approve  ─►  DB row {status=scheduled, scheduled_execution_at=now+delay}  ─►  email user immediately
                                                                       ╲
                                                                        ╲ within window: user clicks revoke ─► status=cancelled, no SDK call, $0 spent
                                                                        ╱
                                                       scheduler tick (scheduled_execution_at <= now)
                                                                        ╲
                                                                         ╲ SDK call ─► status=completed ─► confirmation email (no revoke link)
                                                                        past window: revoke falls through to provider-API path (Azure works, AWS/GCP 422)

• PurchaseDelayHours = 0 preserves the legacy immediate-execute behavior — opt-in for users who don't want any delay.
• Idempotent scheduler: tick scans WHERE status='scheduled' AND scheduled_execution_at <= NOW(). Uses an owner-token compare-and-clear pattern so two overlapping ticks can't fire the same row twice.

Why this is the right shape

The original #804 design called the provider cancel API after the SDK purchase had already settled. That works on Azure (7-day refund window) but not on AWS / GCP, which have no public cancel API. Deferring our own SDK call sidesteps the asymmetry entirely — for the common case ("I just clicked approve and changed my mind"), no provider cooperation is needed.

Provider-cancel API fallback (the original #804 design)

Still wired up for rows that pass scheduled_execution_at without being revoked. Useful when the user wants delay=0, or returns a week later.

• Azure: two-step CalculateRefund + Return via armreservations SDK, 7-day window. Button shown only for Azure rows within the window.
• AWS / GCP: no public cancel API; endpoint returns 422 and the History UI hides the button.

Schema (migration 000065)

ALTER TABLE purchase_history ADD COLUMN IF NOT EXISTS (idempotent):

• revocation_window_closes_at TIMESTAMPTZ — set at write-path per provider policy (pre-fire delay) OR per provider's published window (fallback).
• scheduled_execution_at TIMESTAMPTZ — when the deferred SDK call should fire (pre-fire delay only).
• revoked_at TIMESTAMPTZ, revoked_via VARCHAR(32) — stamped on revoke.
• support_case_id TEXT — reserved for Phase 2 AWS Support case (feat(email): post-execution notification email with one-click revocation link valid for the AWS cancel window #291).

CHECK constraints enforce audit consistency:

• revoked_via ∈ {known values, …} or NULL.
• support_case_id non-null only when revoked_via = 'support-case'.
• revoked_at and revoked_via are jointly null or jointly non-null.

Backend

• POST /api/purchases/{id}/revoke route at AuthUser level.
• Fail-closed: auth nil → 403 ClientError before any store or session call.
• RBAC: revoke-own:purchases / revoke-any:purchases. revoke-own granted by default to all users (mirrors approve-own). Ownership uses account-access (GetAllowedAccountsAPI) because history rows pre-date created_by_user_id.
• Idempotency: revoked_at IS NULL guard in MarkPurchaseRevoked. Already-revoked returns status: already_revoked without re-firing.
• Azure error classification: 400/409/422 + policy keywords map to 400; transient faults propagate as 5xx.
• Scheduler: new periodic task in internal/scheduler/scheduler.go for scheduled-purchase fire. Owner-token CAS protects against overlapping ticks.

Frontend

• canRevokeCompletedRow: provider-agnostic for scheduled status (pre-fire window); Azure-only for completed status (provider window). Both gated on session + not yet revoked.
• Revoke button rendered in History action cell; escapeHtml on purchase_id.
• Destructive confirm dialog + api.revokePurchase() + success toast + history refresh.
• New row state badge for scheduled (e.g. "Scheduled to execute in 47h — revoke link sent to email").

Tests

• 10+ unit tests for the revoke handler (nil auth, empty ID, not found, already revoked, AWS 422, GCP 422, Azure outside window, Azure success via injected stubs, Azure calc-refund client error, Azure return server error).
• Pre-fire delay path: scheduled status set on approve, SDK NOT called, revoke during window flips to cancelled.
• Scheduler tick: scheduled_execution_at <= now fires SDK, transitions to completed.
• parseAzureReservationIDs table tests, authorizeSessionRevoke RBAC matrix.
• Frontend: regression test for legacy blank-status Azure rows + scheduled-state rendering.

Test plan

• go test ./... — all packages green
• npm test in frontend/ — all suites green
• Manual: approve a purchase with PurchaseDelayHours = 1h, verify email arrives immediately, status is scheduled. Click revoke from email → status flips to cancelled, no SDK call.
• Manual: approve with PurchaseDelayHours = 0, verify legacy immediate-execute behavior unchanged.
• Manual: let a scheduled purchase pass its scheduled_execution_at; verify scheduler fires SDK, status → completed, confirmation email arrives without revoke link.
• Manual: completed Azure row within 7 days still shows Revoke button (fallback path); AWS/GCP completed rows don't.

Related

• Closes feat(purchases): in-app revocation flow — direct API for free-cancel window + AWS Support case drafter for week window #290.
• Phase 2 (support:CreateCase drafter for post-window AWS revocation): tracked separately at feat(email): post-execution notification email with one-click revocation link valid for the AWS cancel window #291.
• Post-execution email + token UX (separate concern): PR feat(email): post-execution notification with one-click revoke (closes #291) #889.

Summary by CodeRabbit

• New Features
  • Revoke completed Azure purchases from History during a free‑cancel window (includes revoke button, confirmation flow, success/error toasts).
  • Scheduled (delayed) approvals: approval can be scheduled, with email notifications containing a one‑click revoke link and window timing.
  • Role‑based revoke controls: users with revoke permissions see the inline Revoke control; admins retain broader revoke capabilities.

[cristim]

@coderabbitai review

[coderabbitai]

Warning

Review limit reached

@cristim, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 2 minutes and 9 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: efd8b648-cdf3-49ee-848e-b394ed049e07

📥 Commits

Reviewing files that changed from the base of the PR and between 6486e1e and ee14a18.

📒 Files selected for processing (9)

• internal/analytics/collector_test.go
• internal/api/handler_history.go
• internal/api/handler_purchases_revoke.go
• internal/api/handler_purchases_revoke_test.go
• internal/email/coverage_test.go
• internal/email/templates.go
• internal/server/handler.go
• internal/server/handler_ri_exchange_test.go
• internal/server/test_helpers_test.go

📝 Walkthrough

Walkthrough

Adds in-app revoke for Azure completed purchases plus a Gmail-style pre-fire delay that schedules approved purchases, stamps revoke windows, implements Azure CalculateRefund/Return revoke flow with TOCTOU and in-flight reconciliation, extends DB/store/schema and scheduler to fire scheduled executions and finalize revocations, updates frontend revoke UI/permissions/API, and aligns tests/mocks across suites.

Changes

Purchase Revocation & Pre-Fire Delay Feature

Layer / File(s)	Summary
Contracts and permissions internal/config/types.go, internal/auth/types.go, internal/auth/types_test.go, internal/auth/service_group_test.go	Adds PurchaseDelayHours, ScheduledExecutionAt, AzureRevocationWindowDays, RevocationWindowClosesAtFor, purchase-history revocation fields, and new permission actions revoke-own/revoke-any; updates default user permissions and tests.
Database schema and migrations internal/database/postgres/migrations/000070_*, 000071_*, 000072_*, 000073_*	Adds purchase_delay_hours to global_config, scheduled_execution_at to purchase_executions and new scheduled status, revocation_window_closes_at, revoked_at, revoked_via, support_case_id, refund-audit columns, and revocation_in_flight with partial indexes and adjusted constraints.
Store interface and Postgres implementation internal/config/interfaces.go, internal/config/store_postgres.go, internal/config/store_postgres_pgxmock_test.go	Extends StoreInterface with atomic cancellation and revocation helpers, implements SQL projections/scan updates, nullable-time mapping, GetScheduledExecutionsDue, CancelScheduledExecutionAtomic, MarkPurchaseRevoked, GetPurchaseHistoryByPurchaseID, and in-flight helpers; updates pgxmock tests.
Configuration validation internal/config/validation.go	Validates PurchaseDelayHours within allowed range.
Authorization actions and permissions internal/auth/types.go	Adds ActionRevokeOwn/ActionRevokeAny and grants revoke-own:purchases to default users.
Purchase revocation API handler internal/api/handler_purchases_revoke.go, internal/api/handler_purchases_revoke_test.go, internal/api/router.go	Adds POST /api/purchases/{id}/revoke and GET /api/purchases/{id}/revoke/calculate, scheduled pre-fire cancel, completed-purchase Azure revoke (CalculateRefund+Return), window/safety checks, TOCTOU quote epsilon, in-flight reconciliation (207), RBAC/account scoping, and extensive tests.
Approval handler: pre-fire delay path internal/api/handler_purchases.go, internal/api/handler_purchases_test.go	Refactors approval to schedule execution when PurchaseDelay enabled, atomically transitions to scheduled, stamps ScheduledExecutionAt and ApprovedBy, persists, and triggers scheduled-notification email; adds tests for scheduling and CAS behaviors.
Email system: scheduled notification internal/email/interfaces.go, internal/email/nop_sender.go, internal/email/smtp_sender.go, internal/email/sender.go, internal/email/templates.go	Adds SendPurchaseScheduledNotification API, implements no-op and SMTP paths, extends NotificationData with RevocationWindowClosesAt and RevokeURL, and adds the scheduled-delay email template and sender logic.
Scheduler: fire scheduled purchases internal/purchase/scheduled_fire.go, internal/purchase/scheduled_fire_test.go, internal/scheduler/scheduler.go	Implements FireScheduledDelayedPurchases to fetch and fire due scheduled executions via CAS transition and returns FireResult; adds unit tests and scheduler interface wiring.
Scheduler: finalize in-flight revocations internal/purchase/finalize_revocations.go	Adds sweep to finalize revocation_in_flight rows with retry/backoff and returns FinalizeResult.
Scheduler and server integration internal/server/handler.go, internal/server/handler_test.go, internal/server/interfaces.go, internal/testutil/mocks.go	Adds scheduled-task constants fire_scheduled_purchases and finalize_revocations, maps actions to tasks, dispatches to new handlers that call purchase manager methods, and updates test wiring and mocks.
Frontend permissions and types frontend/src/permissions.ts, frontend/src/permissions.generated.ts, frontend/src/types.ts	Adds revoke-own/revoke-any action literals, includes revoke-own:purchases in generated USER_PERMS, and extends HistoryPurchase with optional revocation fields.
Frontend API and history UI frontend/src/api/purchases.ts, frontend/src/api/index.ts, frontend/src/history.ts	Adds RevokePurchaseResult and revokePurchase() client, re-exports in API barrel, renders Revoke button gated by canRevokeCompletedRow, disables sibling row actions on in-flight, wires confirm dialog and API call, toasts, and history reload.
Frontend tests frontend/src/__tests__/history-revoke-button.test.ts, frontend/src/__tests__/permissions.test.ts	Adds tests covering revoke button render matrix and permission expectations.
Purchase history stamping internal/purchase/execution.go, internal/purchase/coverage_extra_test.go	Stamps Timestamp once per purchase and writes RevocationWindowClosesAt for Azure rows; adds regression test verifying the window computation.
Mock store refactor and test alignment internal/mocks/stores.go, internal/api/mocks_test.go, internal/purchase/mocks_test.go, internal/scheduler/scheduler_test.go, internal/analytics/collector_test.go, internal/api/coverage_gaps_test.go, internal/server/*	Centralizes MockConfigStore, adds default-or-dispatch Fn overrides and revocation/scheduling methods, replaces local mocks with aliases, and adds email/store stubs across tests.
Go dependency go.mod	Promotes armreservations Azure SDK to a direct dependency.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• LeanerCloud/CUDly#613: Overlaps approval-handler logic and scheduling/execute paths.
• LeanerCloud/CUDly#924: Touches permission-gating layer used by History UI.
• LeanerCloud/CUDly#168: Overlaps History row-action rendering/wiring.

Suggested labels

enhancement, urgency/this-sprint, impact/all-users, effort/l

🐰 I scheduled a revoke and hopped away,
Seven days for Azure, two days to sway,
Buttons that guard, emails that chime,
A rabbit's small cheer for reclaiming time.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/290-wave3

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai full review

[coderabbitai]

✅ Actions performed

Full review triggered.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

Rebased onto feat/multicloud-web-frontend (was 3 commits behind base; mergeStateStatus was DIRTY). Conflict resolution:

• internal/auth/service_group_test.go: dropped the PR's stale BuildAuthContext assertions that pre-dated Revamp authorization: group-membership-only (remove roles), require >=1 group per user #907 (group-membership-only authz). Kept the PR's updated GetUserPermissions counts (11 -> 12 / 13 -> 14 for the +revoke-own permission).
• internal/auth/service_test.go: dropped the PR's stale "user permissions even if group fetch fails" assertion. Under Revamp authorization: group-membership-only (remove roles), require >=1 group per user #907 a failing single-group fetch yields an empty permission set (no role fallback exists).

Fixed CI red lights from the previous push:

• gofmt: realigned struct-field padding in TestRevokePurchase_AzureReturnClientError.
• go mod tidy: promoted armreservations from indirect to direct (the revoke handler imports it directly post-rebase).
• go vet / build: replaced session.Role == "admin" in authorizeSessionRevoke with session.UserID == apiKeyAdminUserID. The Role field was removed from api.Session by Revamp authorization: group-membership-only (remove roles), require >=1 group per user #907; the new short-circuit mirrors the sibling authorizeSessionCancel / authorizeSessionApprove patterns. Group-based admins still pass via the HasPermissionAPI({admin, *}) wildcard match further down. Test sessions updated accordingly.

Free-cancel window enforcement (AzureRevocationWindowDays + windowClosesAt) and revoke-call idempotency (early-return on record.RevokedAt != nil) are unchanged.

go build ./..., go vet ./..., go test ./... (5043 tests / 38 packages), gofmt -l ., and npx tsc --noEmit are all clean locally.

@coderabbitai review

[coderabbitai]

@cristim: Thanks for the detailed rebase notes. The conflict resolutions look sound — dropping the stale BuildAuthContext assertions that pre-dated #907 and the role-fallback assertion are the right calls given the group-membership-only authz model. The session.Role == "admin" → session.UserID == apiKeyAdminUserID fix in authorizeSessionRevoke mirrors the established sibling patterns correctly. Kicking off a fresh review now.

---

🧠 Learnings used

Learnt from: cristim
Repo: LeanerCloud/CUDly PR: 0
File: :0-0
Timestamp: 2026-05-05T15:44:54.463Z
Learning: In the LeanerCloud/CUDly repository, when a CodeRabbit review flags something as "outside-diff" that was already implemented in an earlier commit of the same PR, it is likely a stale-snapshot artifact where the review diff was generated against a pre-fix view. The inline comment convention `(CR pass on PR #<number> Finding N)` is used by the maintainer (cristim) to mark lines that were changed in direct response to a prior CodeRabbit review pass.

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

@cristim: Both fixes are solid:

• The security fix on SendPurchaseScheduledNotification is the critical one — the broadcast fallback path would have sent a live, execution-scoped revoke link to every alert subscriber, bypassing the RBAC model entirely. Returning ErrNoRecipient and adding the PurchaseScheduledDelay_no_recipient regression test closes that gap correctly and mirrors the smtp_sender.go contract.
• The test correction (rename + docstring) is clean hygiene — the safety-margin gate coverage split is now accurate: TestCallAzureReturn_JustOutsideSafetyMargin tests callAzureReturn directly, and TestRevokePurchase_AzureWithinSafetyMarginRejected covers the gate end-to-end. No gap in coverage.
• The ClearRevocationInFlight build-break fix on the standalone mocks is the right approach.

Triggering a fresh incremental review now.

🐇 🔐

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[cristim]

@coderabbitai review

Follow-up: the Run pre-commit hooks CI check was failing on the gocyclo gate (threshold 10) for four functions the #290 work grew past the limit. Pushed ee14a181 to refactor them into focused helpers with no behavior change:

• calculateAzureRevoke (21) -> validateAzureRevokeRequest + azureRevokeWindowAndIDs + extractAzureRefundQuote
• callAzureReturn (21) -> azureCalculateRefund + handleAzureReturnError + persistAzureRevocation
• annotateHistoryRowByStatus (12) -> annotateInFlightOrAuditGapRow
• dispatchTask (11) -> map-based dispatch

gocyclo -over 10 now reports nothing; go test ./internal/... green except the pre-existing CSRF flake that also fails on base.

[coderabbitai]

@cristim: Clean gocyclo remediation — the decompositions follow natural sub-task boundaries (validate → compute window/IDs → extract quote for the Azure revoke path; calculate → error classify → persist for the return path), so the behavior-neutral claim is credible. The map-based dispatch for dispatchTask is the standard Go idiom for this pattern. Triggering a fresh incremental review now.

🐇 🔧

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.