Saltar a contenido

Local simulation (gateway + Prisma emulator, no POS)

Runs the gateway (profile local) and the prisma-emulator on this machine only. Every listener binds to 127.0.0.1; there is no tunnel and no outbound traffic (the gateway's Prisma base URL is the local emulator).

Works on Windows PowerShell 5.1 and pwsh 7. From the repo root:

powershell -NoProfile -ExecutionPolicy Bypass -File tools\local-sim\sim.ps1 <command> [options]
Command What it does
up [-NoBuild] [-FastWaits] [-BootUI] Drops and recreates the throwaway DB GatewayPrismaQR_SIM (fresh data every run). Builds the jars if missing (mvn -q package -DskipTests), starts the emulator (9090) and the gateway (callbacks 8443, POS 8090, admin 8091), checks that every listener of both processes is on 127.0.0.1, proves the gateway migrated the _SIM database (flyway_schema_history exists and has rows; aborts and cleans up otherwise), points the emulator at the gateway callbacks (the emulator is also started with EMULATOR_GATEWAY_CALLBACKSURL / EMULATOR_GATEWAY_APIKEY, so POST /emulator/reset keeps that target). Then creates the console ADMIN user admin with a random 20-character password (letters and digits), using the one-shot bootstrap of docs/RUNBOOK.md section 12 (the password goes only through the GPQR_ADMIN_BOOTSTRAP_PASSWORD environment variable of that short-lived process); it prints Console: http://127.0.0.1:5173/admin/ user: admin password: ... at the end and keeps the password in .state\state.json. If the bootstrap fails, up prints a warning with the log path (.state\admin-bootstrap.log) and keeps running; create the user by hand then. -FastWaits shortens the gateway waits for the dev cockpit: gateway.pos.wait.deadline 15s (default 45s), status-query-lead 5s (15s), caller-read-timeout 25s (59s), gateway.compensation.initial-backoff 1s (5s), poll-delay 2s (10s). The database name must match ^[A-Za-z0-9_]+_SIM$ (case-sensitive). -BootUI is opt-in (see "BootUI" below); without it up is unchanged.
down Stops exactly the processes recorded in .state\state.json, and only if PID, process name and start time (within 2 s) all match. A PID that now belongs to another process is never touched: down reports the state as stale and just removes the state file.
status Health of 9090 / 8090 / 8091 / 8443 and the recorded PIDs, each marked ours, gone or mismatch (stale state, PID reused), and the console login (user and password) of this run.
seed Optional: applies db\seed\seed-dev.sql (idempotent, dev DB only) when the demo merchant is missing. Credentials are read silently from the environment or config\application-local.yml and never printed.
trxid [-Merchant -Branch -Pos] POST /api/trxid (defaults: ALMACOR-DEMO, 1, 1).
pay -Id N [-Amount 100.00] [-Outcome APPROVED] POST /api/trxpago. With -Outcome the emulated wallet is played automatically once the gateway created the intention; without it the call waits for you to run scenario elsewhere.
poll -Id N GET /api/trxes/{id}.
cancel -Id N POST /api/trxanulacion.
scenario -Outcome X Plays the wallet for the checkout (-Cuit -BranchCode -CheckoutCode, defaults match the demo seed). Outcomes: APPROVED REJECTED MISSING_BINS MISSING_NOTIFICATION DUPLICATE_NOTIFICATION LATE_NOTIFICATION LATE_PAYMENT_AFTER_CANCEL APPROVED_AMOUNT_MISMATCH APPROVED_UNOFFERED_PLAN DOUBLE_CHARGE DOUBLE_CHARGE_OWN_NUMBERS.
fault -Operation O -Mode M [-HttpStatus 503 -Count 1 -DelayMillis 0 -ExecuteAnyway] Injects a Prisma failure. Operations: CREATE_INTENTION COMPLETE_INTENTION CANCEL_INTENTION QUERY_PAYMENT FORCED_ANNULMENT FORCED_REFUND QUERY_ANNULMENT QUERY_REFUND ANY. Modes: STATUS DELAY TIMEOUT CONFLICT GARBAGE_ID STALL_AFTER_HEADERS RESET_AFTER_REQUEST HUGE_BODY.
faults-clear, reset Clear the fault queue / forget all emulator state.
requests What the emulated Prisma received.
smoke Approved payment, rejected payment (also requires the emulated wallet to have played and rejected), annulment (incl. idempotent repeat) and a cashier cancel during the wait (requires an observed intention create and trxpago still pending at cancel time; trxpago must end denied with the cashier-cancel message); prints a PASS/FAIL table, exit code 1 on any FAIL. Connection resets or refusals become FAIL rows, never a stack trace.

Security notes

  • The emulator and callbacks keys are random per run (64 characters) and stored only in .state\state.json (this folder has its own .gitignore). They are passed to the child processes through environment variables (not the command line, so they do not appear in the process list) and are never printed.
  • Exception, on purpose: the QA console password of the user admin is printed by up and status and stored in .state\state.json. It protects a throwaway, loopback-only environment whose database is dropped on every up, and showing it keeps QA simple. It is random per run, never in the repository, and never on a command line. Never reuse this approach for a real environment.
  • Addresses are explicit overrides (server.address, gateway.listeners.pos.address, gateway.admin.address) and are verified after start with Get-NetTCPConnection; the run is aborted and cleaned up if anything listens elsewhere.
  • state.json records name and start time (UTC, ISO 8601) of each child next to its PID, so a recycled PID is never mistaken for ours. DB credentials are read only from the gpqr.db (or spring.datasource) block of the YAML.
  • Needs SQL Server reachable on localhost and the credentials in config\application-local.yml (or GPQR_DB_USER / GPQR_DB_PASSWORD). Logs: .state\gateway.log, .state\emulator.log (+ *.err.log).

BootUI (opt-in developer console)

up -BootUI rebuilds the jars with mvn -q clean package -DskipTests -P bootui (the Maven profile bootui adds the BootUI starter to the gateway), starts the gateway with --bootui.path=/admin/bootui and prints http://127.0.0.1:8091/admin/bootui/. BootUI turns itself on under the local profile and rejects non-loopback callers. It is mounted under /admin because every listener answers 404 outside its own prefix, so the default /bootui is unreachable. This jar is for your machine only: never release it (CI fails if the release jar holds BootUI). A later plain up reuses that jar and says so; rebuild it clean with mvn -q clean package -DskipTests. The sim keeps BootUI's overrides in .state\ on every up (.bootui/ is gitignored in case BootUI runs outside the sim). -BootUI always rebuilds, so it cannot be combined with -NoBuild unless the jar already holds BootUI. The jar keeps the release name (the sim finds it by that name): never copy a -P bootui jar out of target\.

Security, plainly. /admin/bootui/** bypasses the console login, the admin CSRF check and the admin remote-address filter: BootUI registers its own security chain (order Integer.MIN_VALUE) that permits its paths, and it is protected only by its own loopback filter and Host allow-list. Any local process or user can read the configuration, beans, mappings and logs and use its write actions (Flyway migrate, session clear, heap dump, configuration overrides, installers that write files). Never run it on a shared host. BootUI also sets an XSRF-TOKEN cookie with Path=/ next to the console's. Its overrides file (loaded above the command-line arguments, so it could redirect the database or undo -FastWaits) is moved to .state\bootui-overrides.properties for the gateway and the admin bootstrap, and up deletes it on every run.

Dev cockpit

The cockpit (a dev-only page of the admin console) talks to this simulation. Start it with up -FastWaits so cases that wait for the deadline finish in about 15 s, then in console\ run npm run dev and open http://127.0.0.1:5173/admin/ (Vite dev server; log in with the admin user and the password that up printed (or status shows again), and open the test bench entry; there is no manual admin step). Vite proxies /api/ to the POS API (8090) and /emulator/ to the emulator (9090). The callbacks key reaches the emulator only through the EMULATOR_GATEWAY_APIKEY environment variable of its process, never the browser or the command line.