G2A Import Channel

G2A is an inbound sales channel where Octopus is the HTTP server and OAuth2 token issuer — the mirror image of the vendor-adapter pattern (there Octopus is the client). The G2A marketplace calls in to reserve stock, confirm orders, and pull voucher codes. Spec of record: docs/g2a/api.yml (the full G2A Merchant/Import contract) + docs/g2a/RUNBOOK.md.

The inbound API contract

Routes under app.Group("g2a") (routes.go:62); the token endpoint is public, everything else sits behind G2AAuthMiddleware(). The error envelope is G2A's {code, message} shape (g2aError()), distinct from the app-wide handler.

The lifecycle

Requests/responses are bare JSON arrays (reservation items in, stock out) — matching the G2A contract.

Auth — OAuth2 client-credentials

• Token issuance (G2ATokenHandler): grant_type/client_id/client_secret as query params (per G2A contract). Looks up creds by public g2a_client_id; an unknown client_id returns the same 401 invalid_client as a bad secret (anti-enumeration). bcrypt compare; disabled channel → 403 after secret validation. Mints {access_token, token_type:"bearer", expires_in}.
• Token (utils/jwt.go:45): HS256, Subject:"g2a", 15-min TTL, signed with the shared JWT_SECRET.
• Validation (G2AAuthMiddleware): stateless — signature + expiry + Subject=="g2a", no per-request DB lookup (keeps healthcheck cheap). Parses bearer case-insensitively (G2A sends lowercase). Sets client_id + TenantIDKey — the token is the tenant anchor.
• Subject separation: a g2a token is rejected by /api/v1 (which requires Subject:"access") and vice-versa — tested (CrossUseRejected). See Auth & Access Control.

Credential provisioning — two paths, both generate g2a_client_id = "g2a_"+random(24) + a random(48) secret (bcrypt-hashed, plaintext returned once), default is_enabled=false (operator must explicitly enable):

• Admin (admin_g2a.go) — operator generates for any client via :id.
• Client self-service (client_g2a.go) — cookie-scoped, client manages its own creds (no URL :id). Clients cannot manage product mappings — admin-only.

Reservation model

Table g2a_reservations + g2a_reservation_items, statuses RESERVED|EXPIRED|ORDERED|RELEASED.

• id is a server-supplied UUID that also serves as the external order_id.
• TTL = 30 min; inventory_size is the fixed 1_000_000 constant — no stock is actually held, so there's no row/stock locking (nothing finite to lock).
• Expiry two ways: the G2AReservationExpiryTask sweeper (@every 5m, UPDATE …EXPIRED WHERE status=RESERVED AND expires_at<now, backed by a partial index) and a lazy order-time check (410). Renew and sweeper both gate on status=RESERVED, so ordered/expired transitions are mutually safe — a renew-vs-sweep race resolves via rows-affected==0 → 410.

Order + code delivery

G2ACreateOrderHandler:

1. Idempotency pre-check: same g2a_order_id + same reservation → return same codes (200); bound to a different reservation → 409.
2. Reservation state/expiry checks (409/410).
3. Mint per item: require Denomination.Valid (else 400), build refCode = G2A_<g2a_order_id>_<reservation_item_id>, call CreateVoucherOrderForJob — idempotent on ClientReference (pre-check + unique index), so retries never double-mint.
4. Sync vs async: all units have codes → DELIVERED, 200 with inline codes; else → PENDING, 202 with empty stock (G2A re-pulls later).
5. Persist g2a_orders + g2a_order_items (each a fresh inventory_uuid, kind=text) + reservation→ORDERED, all in one tx.

Code reveal (buildG2AInventoryGroups): loads the linked Octopus order_items, skips code-less units, decrypts code/PIN via utils.DecryptVoucherData, renders with formatG2AValue (PIN present → {"Card": code, "PIN": pin}; else bare code). Secrets are never duplicated into G2A tables — code/PIN live encrypted only on the Octopus order_items.

DELETE …/inventory always returns 400 — minted codes can't be clawed back; refunds are manual reconciliation / cost-absorbed.

Data model

Migrations 20260611000001..05. Models in database/models/g2a.go.

Multi-tenancy

Every inbound call is scoped by client_id from the JWT's ClientID claim (set at token issuance from the matched credentials row). The middleware puts it in c.Locals("client_id") + TenantIDKey; every handler threads it into every repo call; every query filters WHERE client_id = $. The token is the tenant — no header, no per-request lookup. This is the pattern Shopify's write path should follow (contrast the Shopify client_id=0 bug).

Test coverage

Notably strong — the reference example for inbound-channel testing:

Gaps: the async (202) branch has no dedicated unit test beyond the mint-failure chaos test; the concurrency loser-500 behavior is untested/unspecified.

Spec-vs-impl gaps & dead code

Spec features not implemented in v1 (present in api.yml, no handlers): /inapp/validate, /inapp/top-up, file/account inventory kinds (kind file/account exist in the model but only text is ever emitted), per-item inventory sub-routes.

Dead / reserved: g2a_credentials.webhook_secret (never read/written), G2AReservation.G2AOrderID (link lives on g2a_orders.reservation_id instead), G2AOrderStatusFailed / G2AOrderItemStatusReturned constants (never assigned).

Smells: CreateVoucherOrderForJob builds a throwaway fiber.New() per order item (a per-item Fiber app under load — the same fake-context hack Shopify uses), and its doc comment still says "the Shopify ingest path" (now stale — G2A uses it too). buildG2AStock reports 1_000_000 unconditionally — fine only while GH mints on demand.

Key files

• Docs: docs/g2a/{api.yml,RUNBOOK.md,IMPLEMENTATION_PLAN.md}
• Handlers: http/handler/{g2a,g2a_order,g2a_reservation,admin_g2a,client_g2a}.go
• Auth: middleware/g2a_auth.go, utils/jwt.go
• Model/repo/migrations: database/models/g2a.go, database/repo/g2a_*.go, database/migration/20260611*
• Jobs: jobs/g2a_reservation_expiry_job.go, scheduler/g2a_reservation_expiry_task.go
• Tests: test/clientapi/g2a_orchestration_test.go