Mocky-Balboa — Vendor Mock

Mocky-balboa is a single Cloudflare Worker (Hono + one D1 database) that impersonates every real third-party vendor API so the Octopus backend's orchestration and vendor-contract tests run deterministically without touching live vendors. It self-describes as Vendor Mock Server v1.6.0 fronting [SEAGM, DT One, Runa, NeoCurrency, Wupex, iRewardify, EpinForce] (src/index.ts:36). Everything below is relative to frontend/mocky-balboa/.

This is "Track A" of the two faking tracks — the real third parties. The federated OCTO self-vendors use a separate in-process octopusfake instead. See also Frontends → mocky-balboa.

What it is & how Octopus points at it

Each real vendor row in Octopus carries a host attribute. The Go helper BindVendorToMocky (test/testhelpers/vendor_binding.go:63) rewrites that host to MockyVendorURL(path) (e.g. http://localhost:8788/runa/v2), forces is_active=true, and registers a t.Cleanup to restore it — so once bound, every vendor.CreateOrder/catalog call the adapter makes hits this worker's per-vendor sub-app instead of the real API.

• Local: wrangler dev on port 8788 (default MOCKY_BASE_URL).
• Deployed: CI sets MOCKY_BASE_URL=https://mocky-balboa.octopuscards.io — but note that hostname exists only in a Go comment; there is no routes/custom_domain block in wrangler.jsonc, so the custom domain is dashboard-managed and won't be re-established by a redeploy.

Architecture & middleware

Hono app (src/index.ts:21): cors() → a Drizzle-setup middleware that puts drizzle(c.env.DB) on context → seven vendor sub-apps (/seagm, /dtone, /runa, /neocurrency, /wupex, /irewardify, /epinforce) → the /_chaos management API mounted last.

Per-vendor emulation

Each vendor exposes /_mock/... seams (complete/:id, fail/:id, webhook-url, auto-fulfill, seed/delete rows) that let a contract test drive create→complete deterministically without waiting on the scheduler or chaos. EpinForce is the outlier — its /_mock/* seams require auth.

The chaos engine

Three parts: middleware/chaos.ts (injection), routes/_chaos.ts (management API), and the chaos_rules D1 table (migration 0009_chaos_rules.sql). This is what the Go mockychaos client drives.

Rule model

Firing & the MustHaveFired contract

Rules matching (vendor OR '*') AND enabled=1 are loaded in id order; the first that passes method+path match and shouldFire wins and short-circuits. The key mechanic:

Failure application: status (custom code/body + X-Chaos-* headers), delay_then_pass/delay_then_fail (sleep then continue/fail), malformed (truncated/html/empty/raw-0xff invalid-utf8/wrong-schema), drop (throw mid-request → bare 500, the closest Workers analog to a TCP RST), jitter (random delay then continue).

/_chaos management API

GET / (list+docs), POST / (create), GET /:vendor, GET /library, POST /:id/enable|disable, bulk enable|disable {label_like}, enable-all|disable-all, DELETE /:id|/vendor/:vendor|/, and POST /preset/:name (outage/flaky/slow/malformed-storm/drop-storm/unauth-storm).

D1 schema & seed

~34 tables, grouped by vendor (users/products/orders/codes per vendor, plus SEAGM's card+recharge split, DTOne operators/transactions, Runa idempotency_cache, EpinForce carts/deliveries) and the cross-cutting chaos_rules.

seed.sql is a 1.26 MB committed artifact run by wrangler d1 execute mocky --file=seed.sql. Contents: 74 dtone_products + 16 dtone_operators, 154 seagm_recharge_types + 30 card types, 12 runa products, 11 neo brands, 10 wupex, 15 irewardify variants, 9 epinforce — and ~201 chaos rows (27 INSERT statements), all low-probability probabilistic rules armed by default.

src/db/seed.ts is dead code (its own header says so) — it duplicates SEAGM data and is wired to no caller; the live seed is seed.sql. drizzle-seed is a devDependency but unused by the seed path.

Deploy & infra

wrangler.jsonc: worker mocky-balboa, D1 binding DB→mocky (6dad79fb-…), vars.APP_ENV=local, no routes/custom_domain/compat_flags. Scripts: deploy (wrangler deploy --minify), db:reset (local wipe+migrate+seed), db:seed[:remote], migrate:local|remote, db:reset:remote. 19 migrations 0000→0018 (VoucherKart dropped at 0008; auto-fulfil added for EpinForce 0017 and iRewardify 0018).

scripts/reset-remote.sh deletes+recreates the remote D1, auto-rewrites database_id in wrangler.jsonc via sed, re-migrates+seeds, then redeploys (a recreated D1 gets a new id the live worker must rebind).

How tests consume it

MOCKY_BASE_URL default http://localhost:8788, CI → deployed. BindVendorToMocky rewrites the host (Runa passes /v2 suffix, others ""); a per-vendor sync.Mutex serialises same-vendor host mutations; SetVendorAttribute aligns creds to the seeded values; SetVendorIsLinkEnabled(false) forces Runa off the link path so CreateOrder actually runs and chaos on /v2/order can fire.

Findings

Key files

• Entry/routing: src/index.ts; middleware src/middleware/{chaos,auth}.ts; chaos API src/routes/_chaos.ts
• Vendor routes: src/routes/{seagm,dtone,runa,neocurrency,wupex,irewardify,epinforce}.ts
• Libs: src/lib/{svix_sign,xlsx}.ts; schema src/db/schema.ts; seed seed.sql (+ dead src/db/seed.ts)
• Config: wrangler.jsonc, package.json, scripts/reset-remote.sh, drizzle/migrations/0000…0018
• Go side: test/testhelpers/{mocky.go,vendor_binding.go,mockychaos/client.go}