Files
sor/SOR.Bazaar.12FactorPlan.md
2026-07-02 13:09:05 -04:00

18 KiB

SOR.Bazaar 12-Factor Refactor Plan

Date: 2026-06-10

Scope reviewed:

  • Server/src/SOR.Bazaar
  • Bazaar persistence in Server/src/SOR.Database/Contexts/BazaarDbContext.cs
  • Bazaar entities and migrations under Server/src/SOR.Database
  • Bazaar wiring in Server/src/SOR.Host

Reference: https://12factor.net/

Executive Summary

SOR.Bazaar is a compact service module that registers marketplace and store message handlers when ENABLED_SERVICES includes bazaar. It handles store browsing, Origin Point balances, booster pack purchases, prebuilt deck purchases, cosmetic purchases, player listings, listing purchases, auction bids, transactions, storefronts, and price suggestions.

The service already has useful 12-Factor foundations:

  • It is enabled by host process formation instead of running as a separate custom executable.
  • It uses explicit database contexts for bazaar, collection, catalog, and identity data.
  • High-value P2P listing purchases use a shared Postgres transaction across contexts.
  • Origin Point debits use conditional SQL updates to prevent overspending.
  • Message contracts are centralized in BazaarMessages.cs.
  • The module has no local filesystem state and no direct port binding.

The main gaps are structural and operational:

  • Message handlers contain transport handling, validation, business rules, data access, transaction orchestration, DTO mapping, and response mapping.
  • Store purchases mutate identity, collection, and bazaar data without a single shared transaction boundary.
  • Auction bid and cancellation flows should use the same atomic transaction discipline as fixed-price listing purchases.
  • Pricing, page-size limits, foil odds, supported currencies, sale-history windows, and listing rules are hardcoded.
  • There is no visible idempotency model for purchase commands, which matters for client retry and message redelivery.
  • There is no explicit auction settlement/expiration process.
  • Marketplace audit data exists through transactions and purchase records, but there is no central audit boundary for all money/card mutations.
  • Readiness is host-level only; Bazaar needs dependency-aware checks for Postgres schemas and any catalog/collection/identity dependencies.

The plan is to keep SOR.Bazaar as the marketplace module, but split handlers into thin transport adapters backed by application services, repositories, typed options, and explicit transaction/idempotency boundaries.

Current Structure Observations

Strong Foundations

  • AddBazaarService clearly registers Bazaar handlers from one place.
  • BazaarDbContext owns store products, listings, transactions, purchase records, booster grants, and auction bids.
  • BazaarHandlerBase centralizes Origin Point debit/credit helpers.
  • BazaarBuyListingHandler uses a shared Npgsql transaction across BazaarDbContext, CollectionDbContext, and SorIdentityDbContext.
  • P2P listing claim uses a conditional SQL update to avoid duplicate sale claims.
  • Listing browsing clamps page size to a maximum of 100.
  • Store products support active windows through AvailableFrom and AvailableUntil.
  • Masked listings avoid exposing card definition data to clients.

Main Problems

  • Each handler owns too much business logic.
  • BazaarBuyBoosterPackHandler is large and combines pack validation, slot JSON parsing, random card grants, Origin Point debiting, collection writes, purchase records, grant records, and response enrichment.
  • BazaarBuyPrebuiltDeckHandler grants cards/decks and records purchases after debiting Origin Points, but does not use the shared transaction helper.
  • BazaarBuyCosmeticHandler follows the same store-purchase risk pattern.
  • BazaarCancelListingHandler can refund an auction winner and cancel a listing without a shared transaction across identity and bazaar contexts.
  • BazaarPlaceBidHandler uses a shared transaction but loads the current winning bid without a row lock or conditional update pattern.
  • BazaarListCardHandler checks for active listings before insert, but this should be backed by a database constraint or transactional claim to prevent duplicate active listings under concurrency.
  • Auction expiration is checked when placing bids, but there is no obvious background job or admin process that closes expired auctions and settles winners.
  • BazaarBuyListingHandler creates an unused PurchaseRecord object and adds the same BazaarTransaction twice before saving.
  • Origin Point amounts are cast from decimal to int in several flows.
  • Currency is hardcoded to Gold in marketplace flows while the balance field is OriginPoints, so naming and rules need to be reconciled.
  • There is no visible Server/tests/SOR.Bazaar.Tests project.

Target Bazaar Shape

Keep SOR.Bazaar as the marketplace service module, but split it into focused layers:

Server/src/SOR.Bazaar/
  Configuration/
    BazaarOptions.cs
    BazaarListingOptions.cs
    BazaarStoreOptions.cs
    BazaarAuctionOptions.cs
    BazaarOptionsValidator.cs
  Bootstrap/
    BazaarRegistration.cs
    BazaarHandlersRegistration.cs
    BazaarJobsRegistration.cs
    BazaarHealthChecks.cs
  Contracts/
    BazaarMessages.cs
    BazaarErrors.cs
  Application/
    Store/
      StoreQueryService.cs
      BoosterPackPurchaseService.cs
      PrebuiltDeckPurchaseService.cs
      CosmeticPurchaseService.cs
    Marketplace/
      ListingQueryService.cs
      ListingCommandService.cs
      ListingPurchaseService.cs
      AuctionBidService.cs
      AuctionSettlementService.cs
      PriceSuggestionService.cs
  Persistence/
    IBazaarRepository.cs
    ICollectionInventoryRepository.cs
    ICatalogLookupRepository.cs
    IOriginPointLedger.cs
    IBazaarUnitOfWork.cs
    BazaarTransactionRunner.cs
  Idempotency/
    IBazaarCommandIdempotencyStore.cs
  Mapping/
    BazaarDtoMapper.cs
  Handlers/
    BazaarGetStoreHandler.cs
    BazaarBuyBoosterPackHandler.cs
    ...
  Jobs/
    SettleExpiredAuctionsJob.cs
    RebuildPriceSuggestionsJob.cs

Desired handler shape:

  • Deserialize request.
  • Read authenticated account ID.
  • Call one application service.
  • Map domain result to ServerMessage.
  • Avoid direct EF queries in handlers.

12-Factor Gap Map

1. Codebase

Mostly aligned. SOR.Bazaar is one module in the server codebase, but responsibilities are concentrated in message handlers.

Plan:

  • Keep one Bazaar module.
  • Split business workflows into application services.
  • Keep message handlers as transport adapters.
  • Add Bazaar tests alongside other server tests.

2. Dependencies

Partially aligned. Dependencies are explicit through project references and DI, but business logic depends directly on EF contexts everywhere.

Plan:

  • Keep EF Core and Postgres as explicit dependencies.
  • Introduce repositories for bazaar, collection, catalog, and identity operations.
  • Introduce an IOriginPointLedger for all balance changes.
  • Introduce IBazaarUnitOfWork or BazaarTransactionRunner for cross-context transactions.

3. Config

Weakly aligned. Bazaar runtime rules are mostly code constants.

Plan:

  • Add typed BazaarOptions.
  • Validate options at startup.
  • Move operational rules into config where appropriate.

Candidate config shape:

{
  "Bazaar": {
    "Listings": {
      "DefaultPageSize": 24,
      "MaxPageSize": 100,
      "MaxAuctionDurationHours": 168,
      "AllowMaskedListings": true
    },
    "Store": {
      "FoilChance": 0.05,
      "AllowUsdPrices": false
    },
    "Pricing": {
      "SuggestedPriceSaleWindowDays": 30,
      "SuggestedPriceMinimumSales": 3,
      "SalvageFloorMultiplier": 4
    },
    "Auctions": {
      "SettlementBatchSize": 100,
      "SettlementIntervalSeconds": 60
    }
  }
}

4. Backing Services

Mostly aligned. Bazaar uses Postgres schemas as attached backing services. Catalog CDN URLs are data references, not direct Bazaar network dependencies.

Plan:

  • Treat BazaarDbContext, CollectionDbContext, CatalogDbContext, and SorIdentityDbContext as required attached resources.
  • Add readiness checks for required schemas/tables.
  • Document that multi-context transactions require the same Postgres database/connection target.
  • If any future payment provider is added, isolate it as an attached external service with retries, idempotency, and reconciliation.

5. Build, Release, Run

Partially aligned. Bazaar runtime does not apply migrations directly, but marketplace data and store products need release discipline.

Plan:

  • Keep schema migrations outside normal runtime startup.
  • Treat store catalog changes as admin/release data changes.
  • Add release checks for active product data, pack slot JSON validity, deck card validity, and cosmetic asset URLs.
  • Add seed/import jobs for store product data instead of hand-editing production data.

6. Processes

Partially aligned. Bazaar is a request/response service module. Auction settlement is not clearly represented as a process.

Plan:

  • Keep request handlers in the bazaar service role.
  • Add a separate bazaar-jobs role for auction settlement, price cache rebuilds, and store-data validation.
  • Avoid starting job loops in normal gateway/game/bazaar request workers unless explicitly enabled.

7. Port Binding

Aligned through SOR.Host. Bazaar does not bind a port directly.

Plan:

  • Keep port binding in SOR.Host.
  • Expose Bazaar readiness through host health checks.
  • Do not add a Bazaar-specific HTTP listener.

8. Concurrency

Partially aligned. Fixed-price purchases use an atomic claim pattern, but other flows need equivalent guarantees.

Plan:

  • Use one transaction runner for all high-value mutations.
  • Add database constraints or conditional updates for:
    • one active listing per player card
    • one winning bid per auction
    • listing status transitions
    • idempotent purchase command execution
  • Use row locks or conditional updates when replacing the winning bid.
  • Make auction settlement idempotent.
  • Define retry behavior for serialization/deadlock errors.

9. Disposability

Mostly aligned for request handlers. There are no long-running loops in SOR.Bazaar today.

Plan:

  • Continue passing cancellation tokens to EF operations.
  • Add cancellation-aware job processing if auction settlement or price rebuild jobs are introduced.
  • Keep mutation workflows short and transactional.
  • Avoid partial writes by ensuring store purchases and auction cancellation use shared transactions.

10. Dev/Prod Parity

Partially aligned. The same Postgres-backed code runs everywhere, but product data and pack JSON validity can drift.

Plan:

  • Provide local seed/import data for packs, decks, cosmetics, and listings.
  • Add validation commands that run in every environment.
  • Keep store product rules environment-neutral unless explicitly configured.
  • Use the same auction settlement path locally and in production.

11. Logs

Weakly aligned. Handlers do not visibly log business events.

Plan:

  • Add structured logs through application services, not every handler.
  • Log high-value events: purchase completed, listing created/cancelled/sold, bid placed/refunded, auction settled, insufficient funds, invalid store config.
  • Add metrics for purchase latency, listing count, bid failures, settlement lag, transaction rollback count, and idempotency replay count.
  • Avoid logging full account inventory or sensitive account details.

Suggested fields:

  • accountId
  • listingId
  • purchaseId
  • productId
  • playerCardId
  • amount
  • currency
  • messageSeq
  • idempotencyKey

12. Admin Processes

Partially aligned. Store product and auction operations need explicit admin/job surfaces.

Plan:

  • Add admin processes for importing store products, validating pack slot JSON, validating prebuilt decks, and settling expired auctions.
  • Add an audit surface for Origin Point changes and item ownership changes.
  • Keep admin-triggered jobs durable and retryable.
  • Document operational recovery for failed purchase, failed settlement, and inconsistent listing state.

Refactor Phases

Phase 0: Baseline Tests and Bug Cleanup

Goals:

  • Capture current behavior before structural changes.
  • Fix obvious high-risk issues behind tests.

Work:

  • Add tests for listing creation, fixed-price purchase, auction bid replacement, auction cancellation refund, booster purchase, prebuilt deck purchase, and cosmetic purchase.
  • Add tests for insufficient funds, duplicate listing attempts, own-listing purchase prevention, and expired auctions.
  • Cover BazaarBuyListingHandler transaction creation so duplicate transaction insertion cannot regress.
  • Add tests for invalid booster slot JSON and empty card pools.

Done when:

  • Bazaar mutation behavior has executable coverage.
  • Refactoring can proceed without relying only on manual client testing.

Phase 1: Typed Options and Validation

Goals:

  • Move operational Bazaar rules into validated config.

Work:

  • Add BazaarOptions, BazaarListingOptions, BazaarStoreOptions, BazaarPricingOptions, and BazaarAuctionOptions.
  • Bind and validate options in Bazaar registration.
  • Replace hardcoded page-size limits, foil chance, suggested-price windows, and auction duration limits with options.
  • Keep defaults equivalent to current behavior.

Done when:

  • Bazaar starts with validated options.
  • Operators can tune marketplace rules without code changes.

Phase 2: Application Services

Goals:

  • Make handlers thin and workflows testable.

Work:

  • Extract store purchase workflows:
    • BoosterPackPurchaseService
    • PrebuiltDeckPurchaseService
    • CosmeticPurchaseService
  • Extract marketplace workflows:
    • ListingCommandService
    • ListingPurchaseService
    • AuctionBidService
    • PriceSuggestionService
  • Keep public message contracts unchanged.

Done when:

  • Handlers mostly deserialize, call services, and return mapped responses.
  • Business workflows can be unit/integration tested without transport boilerplate.

Phase 3: Transaction Runner and Ledger

Goals:

  • Make all money/card mutations atomic and consistent.

Work:

  • Create BazaarTransactionRunner for shared cross-context transactions.
  • Create IOriginPointLedger for debit, credit, balance reads, and audit metadata.
  • Route all store purchases, listing purchases, bids, refunds, and cancellations through the transaction runner.
  • Add explicit transaction result types for rollback-safe errors.

Done when:

  • No high-value mutation writes across contexts without a single transaction boundary.
  • Origin Point changes have one implementation path.

Phase 4: Idempotency

Goals:

  • Make purchase and bid commands safe under retries.

Work:

  • Add an idempotency key to mutating Bazaar requests or derive one from a message envelope if available.
  • Store command execution results for purchase/listing/bid commands.
  • Return the original result on duplicate command replay.
  • Add unique constraints where appropriate.

Done when:

  • Client retry cannot double-purchase, double-grant, or double-bid.
  • Message redelivery behavior is documented and tested.

Phase 5: Marketplace Concurrency Hardening

Goals:

  • Make P2P marketplace operations safe under high contention.

Work:

  • Add a database-backed guarantee that one player card cannot have multiple active listings.
  • Make listing status transitions conditional and auditable.
  • Make winning bid replacement atomic with row locks or conditional updates.
  • Add retry policy for known transient Postgres failures.
  • Add settlement-safe state transitions for auctions.

Done when:

  • Concurrent listing, buying, bidding, and cancellation tests pass.
  • Database constraints enforce the same invariants as application code.

Phase 6: Auction Settlement Jobs

Goals:

  • Represent expired auction processing as a 12-Factor admin process.

Work:

  • Add SettleExpiredAuctionsJob.
  • Transfer card ownership, credit seller, mark listing sold/expired, and create transaction records in one transaction.
  • Make settlement idempotent and batch-based.
  • Register the job only in a dedicated bazaar-jobs role or admin process.

Done when:

  • Expired auctions settle without waiting for a user action.
  • Settlement can be safely retried.

Phase 7: Store Data Validation and Import

Goals:

  • Treat store product data as release/admin data.

Work:

  • Add validation for booster SlotsJson.
  • Validate that prebuilt deck cards reference published catalog cards.
  • Validate cosmetic asset URLs and product availability windows.
  • Add import/seed commands for packs, decks, and cosmetics.

Done when:

  • Bad store data is caught before players can purchase it.
  • Store content can be promoted across environments repeatably.

Phase 8: Observability and Readiness

Goals:

  • Make Bazaar operations diagnosable in production.

Work:

  • Add Bazaar readiness checks for required DbContexts.
  • Add metrics for purchase success/failure, bid success/failure, settlement lag, active listings, active auctions, and rollback count.
  • Add structured audit logs for every Origin Point and ownership mutation.
  • Add dashboards or runbook notes for marketplace health.

Done when:

  • Operators can answer what purchases, listings, bids, refunds, and settlements occurred and whether any are stuck.

Suggested Work Order

  1. Add baseline tests for high-value mutation flows.
  2. Fix obvious duplicate transaction/audit issues under tests.
  3. Add typed Bazaar options with current defaults.
  4. Extract application services behind existing handlers.
  5. Introduce a transaction runner and Origin Point ledger.
  6. Add idempotency for purchase/listing/bid commands.
  7. Add database constraints and concurrency tests.
  8. Add auction settlement as a dedicated job/admin process.
  9. Add store data validation/import commands.
  10. Add readiness checks, logs, metrics, and runbook documentation.

Completion Criteria

The refactor is complete when:

  • Bazaar handlers are thin transport adapters.
  • Store purchases, listing purchases, bids, refunds, and cancellations use one transaction strategy.
  • Mutating commands are idempotent under retry/redelivery.
  • Database constraints enforce critical marketplace invariants.
  • Auction expiration and settlement are handled by a dedicated, retryable process.
  • Store product data is validated before release.
  • Runtime config is typed and validated.
  • Bazaar readiness accounts for required database schemas.
  • Tests cover high-value purchase, listing, bidding, and settlement workflows.

Immediate Low-Risk Next Steps

  • Add a BazaarOptions class and bind it without changing behavior.
  • Add tests around BazaarBuyListingHandler to lock down transaction/audit behavior.
  • Extract IOriginPointLedger while preserving the current SQL update logic.
  • Add a validation command for booster pack SlotsJson.
  • Document the current assumption that all Bazaar-related DbContexts point at the same Postgres database for shared transactions.