@mandateops/cli-linux-x64 0.0.0-stage → 0.7.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +55 -0
- package/README.md +175 -2
- package/audit-lab/README.md +194 -0
- package/audit-lab/bin/mandateops +0 -0
- package/audit-lab/contracts/contact-plain-text.vectors.json +85 -0
- package/audit-lab/contracts/history-reading.md +185 -0
- package/audit-lab/contracts/history-reading.vectors.json +284 -0
- package/audit-lab/contracts/profiles.md +161 -0
- package/audit-lab/contracts/properties.md +512 -0
- package/audit-lab/contracts/sdk-config.md +155 -0
- package/audit-lab/contracts/system-under-test.md +385 -0
- package/audit-lab/contracts/test-provider.md +350 -0
- package/audit-lab/lab/compose.audit.yml +181 -0
- package/audit-lab/lab/config/fault-control.json +14 -0
- package/audit-lab/lab/examples/agents/Dockerfile +28 -0
- package/audit-lab/lab/examples/agents/codeloc.cjs +199 -0
- package/audit-lab/lab/examples/agents/load.cjs +9 -0
- package/audit-lab/lab/examples/agents/package-lock.json +2840 -0
- package/audit-lab/lab/examples/agents/package.json +9 -0
- package/audit-lab/lab/examples/agents/python/mandateops_codeloc.py +271 -0
- package/audit-lab/lab/examples/agents/python/sitecustomize.py +51 -0
- package/audit-lab/lab/examples/agents/requirements-python.txt +522 -0
- package/audit-lab/lab/examples/agents/telemetry-router.cjs +272 -0
- package/audit-lab/lab/examples/test-provider/.dockerignore +4 -0
- package/audit-lab/lab/examples/test-provider/Dockerfile +28 -0
- package/audit-lab/lab/examples/test-provider/bun.lock +405 -0
- package/audit-lab/lab/examples/test-provider/package.json +42 -0
- package/audit-lab/lab/examples/test-provider/src/amount.ts +32 -0
- package/audit-lab/lab/examples/test-provider/src/app.ts +538 -0
- package/audit-lab/lab/examples/test-provider/src/auth.ts +30 -0
- package/audit-lab/lab/examples/test-provider/src/barrier.ts +262 -0
- package/audit-lab/lab/examples/test-provider/src/codeloc.ts +27 -0
- package/audit-lab/lab/examples/test-provider/src/config.ts +311 -0
- package/audit-lab/lab/examples/test-provider/src/connect.ts +204 -0
- package/audit-lab/lab/examples/test-provider/src/declaration.ts +270 -0
- package/audit-lab/lab/examples/test-provider/src/declared.ts +198 -0
- package/audit-lab/lab/examples/test-provider/src/domain.ts +193 -0
- package/audit-lab/lab/examples/test-provider/src/egress.ts +396 -0
- package/audit-lab/lab/examples/test-provider/src/flow.ts +263 -0
- package/audit-lab/lab/examples/test-provider/src/gate.ts +301 -0
- package/audit-lab/lab/examples/test-provider/src/main.ts +31 -0
- package/audit-lab/lab/examples/test-provider/src/notify.ts +157 -0
- package/audit-lab/lab/examples/test-provider/src/owner.ts +60 -0
- package/audit-lab/lab/examples/test-provider/src/payment.ts +103 -0
- package/audit-lab/lab/examples/test-provider/src/profile.ts +417 -0
- package/audit-lab/lab/examples/test-provider/src/request.ts +201 -0
- package/audit-lab/lab/examples/test-provider/src/rows.ts +173 -0
- package/audit-lab/lab/examples/test-provider/src/schema.ts +114 -0
- package/audit-lab/lab/examples/test-provider/src/signature.ts +86 -0
- package/audit-lab/lab/examples/test-provider/src/staged.ts +318 -0
- package/audit-lab/lab/examples/test-provider/src/store.ts +432 -0
- package/audit-lab/lab/examples/test-provider/src/traffic.ts +50 -0
- package/audit-lab/lab/examples/test-provider/src/webauthn.d.ts +11 -0
- package/audit-lab/lab/examples/test-provider/src/wire.ts +153 -0
- package/audit-lab/lab/examples/test-provider/tsconfig.build.json +9 -0
- package/audit-lab/lab/examples/test-provider/tsconfig.json +24 -0
- package/audit-lab/lab/images/capture/Dockerfile +15 -0
- package/audit-lab/lab/images/capture/LICENSE +201 -0
- package/audit-lab/lab/images/fault-control/Dockerfile +13 -0
- package/audit-lab/lab/images/fault-control/LICENSE +21 -0
- package/audit-lab/lab/images/provider-store/Dockerfile +4 -0
- package/audit-lab/lab/images/provider-store/LICENSE +23 -0
- package/audit-lab/lab/images/telemetry/Dockerfile +14 -0
- package/audit-lab/lab/images/telemetry/LICENSE +201 -0
- package/audit-lab/lab/scripts/compose-down.sh +143 -0
- package/audit-lab/lab/scripts/compose-lib.sh +632 -0
- package/audit-lab/lab/scripts/compose-up.sh +240 -0
- package/package.json +16 -4
|
@@ -0,0 +1,350 @@
|
|
|
1
|
+
# MandateOps test provider contract (V2)
|
|
2
|
+
|
|
3
|
+
V2 names the fault-control proxy service `mandateops-relay`, its file `config/fault-control.json`
|
|
4
|
+
and its API port setting `MANDATEOPS_FAULT_CONTROL_PORT`; the payment and control endpoints are unchanged.
|
|
5
|
+
|
|
6
|
+
Shared by the MandateOps test provider and the runner.
|
|
7
|
+
The provider and the fault-control proxy are lab infrastructure for every backend under test; backends are reached
|
|
8
|
+
through adapters ([adapter contract](system-under-test.md)).
|
|
9
|
+
Change only by agreement of both sides.
|
|
10
|
+
|
|
11
|
+
## Payment endpoint (called by the backend through the fault-control proxy)
|
|
12
|
+
|
|
13
|
+
`POST /payouts`
|
|
14
|
+
- Headers: `authorization: Bearer $PROVIDER_TOKEN`, `idempotency-key: KEY`, `content-type: application/json`.
|
|
15
|
+
- Body: the exact instruction JSON (payment, tenant, agent, delegation, account, destination,
|
|
16
|
+
currency, asset, network, amount as decimal string).
|
|
17
|
+
- Same provider account + key + identical instruction -> same effect, no new effect.
|
|
18
|
+
- Same key, different instruction -> 422, no effect; the refused request and its terms are recorded.
|
|
19
|
+
- New key -> new effect with a fresh unique `effectId`.
|
|
20
|
+
- Binding of (key, instruction hash) and the effect row are written in ONE transaction.
|
|
21
|
+
- 200 response: `{ "instruction": <exact instruction>, "effectId": "<id>" }`.
|
|
22
|
+
|
|
23
|
+
### Code-location header
|
|
24
|
+
|
|
25
|
+
A backend preload may add `x-mandateops-call: <lower-case UUID v4>` to a
|
|
26
|
+
payment request. The provider removes the header in its first request hook,
|
|
27
|
+
before authentication, key reading or any record sees it, and logs one line per
|
|
28
|
+
payment request: `mandateops-provider-call {"call":<id or null>,"effect":<effect id or null>}`.
|
|
29
|
+
A malformed value is dropped and logged as `null`. The header is never sent to
|
|
30
|
+
any other host: this provider is the end of the lab's provider path. The CLI
|
|
31
|
+
joins these lines to the preloads' stack lines by id alone (never by time or
|
|
32
|
+
order) and writes the result as the record's `code_locations` block.
|
|
33
|
+
|
|
34
|
+
## Declared payment formats
|
|
35
|
+
|
|
36
|
+
A provider's `format` in `system.providers` replaces the endpoint above with one provider's format, so a customer's
|
|
37
|
+
provider client can run against it within the subset stated below. The SDK ships declarations in `sdk/typescript/src/providers/`.
|
|
38
|
+
The test provider validates a declaration at startup and refuses to start on a bad one. Records, faults
|
|
39
|
+
and the checker are unchanged: each request is normalised into the instruction above.
|
|
40
|
+
|
|
41
|
+
Each shipped declaration names its provider in `provider`, as `config/plans.json` lists it. The
|
|
42
|
+
test provider ignores it; the run record carries it as `run.provider.name` (`lab` without a declaration,
|
|
43
|
+
`custom` for one that names no listed provider), and the API checks it against the workspace's plan.
|
|
44
|
+
|
|
45
|
+
- `path`: the POST route; nothing under `/_control`.
|
|
46
|
+
- `encoding`: `json` (default) or `form`. Form keys are read flat, and a repeated key keeps its last value.
|
|
47
|
+
- `jsonType`: a JSON media type besides `application/json` that the route accepts.
|
|
48
|
+
- `credential`: `{ header, prefix }`, default `authorization` with `Bearer `; `{ basic: true }`,
|
|
49
|
+
which compares the Basic password and ignores the user name; or `{ signedJwt: true, maxAgeSeconds? }`.
|
|
50
|
+
A credential is checked before the body is parsed, except a signed one, which covers the body. OAuth token calls are not imitated,
|
|
51
|
+
so a client of such a provider holds its bearer token directly.
|
|
52
|
+
- `key`: `{ header }` or `{ field }`, a dotted body path; a number step reads an array entry, which
|
|
53
|
+
must sit under a `singleEntry` array. With `optional: true` a request may leave the key out, and
|
|
54
|
+
is then a new payment every time, as a provider without idempotency treats it: a retry after a
|
|
55
|
+
lost reply pays again, and the checker sees each payment.
|
|
56
|
+
- `singleEntry`: arrays that must hold exactly one entry. A batch of any other size is refused and
|
|
57
|
+
leaves no record, so the run cannot pass.
|
|
58
|
+
- `urlFields`: terms sent as a URL, each with the path its identifier must sit under. The host is the
|
|
59
|
+
client's own and is not compared.
|
|
60
|
+
- `fields`, `joined` and `fixed`: every instruction term has exactly one source: a path, several paths
|
|
61
|
+
joined by `--` in order, or a declared constant. A joined part holding `--`, or starting or ending with `-`, is refused, so two parts cannot read as two others. A `fields` path is a dotted body path, or `:name` for
|
|
62
|
+
a route parameter. `payment` may have none, or be absent from the request, and then takes the key.
|
|
63
|
+
`amount` must be read from the request. A fixed term is not evidence: it says what the format cannot
|
|
64
|
+
carry, and the checker cannot see it differ. A term a format does carry is mapped, not fixed.
|
|
65
|
+
- `defaults`: what a mapped term means when the request omits it. A default answers absence only: a
|
|
66
|
+
term present in the wrong type is refused.
|
|
67
|
+
- `amountDefault`: the amount, in major units, that a request leaving it out means.
|
|
68
|
+
- `alternateAmount`: `{ path, currency }`, a second amount field and the field naming what it counts
|
|
69
|
+
in. Giving both amounts is refused. The currency term is then written `<counted>-from-<funding>`,
|
|
70
|
+
such as `usdc-from-eur`, so a changed funding currency changes the terms, and a run authorises it so.
|
|
71
|
+
- `pegged`: per term, the value an amount counts in, such as a stablecoin as the fiat it pegs. It sets amount scale only: Bridge reads a primary `amount` from `usdc` at USD scale, and the term stays `usdc`, so funding from `usd` and from `usdc` are different terms and a change between them is a key conflict.
|
|
72
|
+
- `amount`: `{ minorDigits }` (0 for integer minor units, otherwise exact decimal major units), or
|
|
73
|
+
`{ scaleTerm, scales, networks? }`. Inexact amounts are refused and leave no record, so the run
|
|
74
|
+
cannot pass. A JSON number is taken only below 10^15 minor units, where a double reads back digit for
|
|
75
|
+
digit; a larger amount must be a string.
|
|
76
|
+
- `replay`: `same_reply` (default) or `duplicate_reply`. A repeat never adds an effect.
|
|
77
|
+
- `refusals`: `retryable` (default), where a declined key may be tried again, or `final`, where the
|
|
78
|
+
same terms are declined again and changed terms are a conflict. A repeat adds a record only when it
|
|
79
|
+
meets an armed refusal, which it spends, so each arming shows its own declined record. Under `final`, the expected outcome `exactly_one_effect` needs the checker to
|
|
80
|
+
accept a new key after a definite refusal.
|
|
81
|
+
- `replies`: `paid`, `declined`, `conflict`, and `duplicate` when `replay` needs it, each
|
|
82
|
+
`{ status, body, headers? }`. Tokens: `{{term}}`, `{{key}}`, `{{amountMajor}}`, `{{amount:number}}` as a
|
|
83
|
+
whole value, and in `paid` and `duplicate` also `{{effectId}}`.
|
|
84
|
+
|
|
85
|
+
- `financialFlow` (required): `{ operation, moneyRoutes }`. `operation` names the money-moving call the format
|
|
86
|
+
imitates, such as `transfer`, in lowercase words (letters, spaces and hyphens, at most 64 characters).
|
|
87
|
+
`moneyRoutes` maps the provider's other money-moving `POST` routes known to the declaration (route
|
|
88
|
+
syntax as `path`, `:name` matching one non-empty segment) to the operation each performs; a
|
|
89
|
+
format with none declares `{}`. The steps the format answers, such as an account setup or a quote, are its own
|
|
90
|
+
declared routes and are not repeated here. A route not listed is never assumed to move no money: a
|
|
91
|
+
request to it is reported as unplaced.
|
|
92
|
+
|
|
93
|
+
Every reply must be answerable once the ledger has acted, so anything a reply could not carry is
|
|
94
|
+
refused before it. A format whose replies hold `{{amount:number}}` refuses amounts above 2^53 - 1.
|
|
95
|
+
A key already bound keeps its outcome: a refusal armed for it stays armed for the next new key.
|
|
96
|
+
|
|
97
|
+
A declaration imitates one call's shape. It says nothing of how that provider behaves.
|
|
98
|
+
|
|
99
|
+
### Supported subset
|
|
100
|
+
|
|
101
|
+
A key may be any printable ASCII up to `key.maxLength`, or the narrower `key.shape`: `paystack` takes
|
|
102
|
+
lowercase slugs, `circleMint` UUID v4, `revolut` 40 characters, `modernTreasury` 180, `stripe` and
|
|
103
|
+
`fireblocks` 255. Other formats state no limit and take 255. One the record format cannot hold is
|
|
104
|
+
recorded as `key-` and its SHA-256 in lowercase hex (a key already of that exact shape is digested too, so it cannot pose as another key; any other hex case is not that shape), and replies echo it from the request answered, so a restart
|
|
105
|
+
loses nothing. An EVM destination is
|
|
106
|
+
refused if it is not an address and recorded in EIP-55 checksum form, so an authorised destination
|
|
107
|
+
must be written in that form. Each format reads the fields below and refuses, or
|
|
108
|
+
does not see, anything else.
|
|
109
|
+
|
|
110
|
+
| Format | Account from | Destination | Client exercised live | Not imitated |
|
|
111
|
+
|---|---|---|---|---|
|
|
112
|
+
| `paystack` | fixed | `recipient` | hand-written | |
|
|
113
|
+
| `stripePayouts`, `stripeTransfers` | fixed | `destination` | real SDK (transfers) | a payout without `destination` |
|
|
114
|
+
| `flutterwave` | fixed | `account_bank_account_number` | none | amount's unit unverified |
|
|
115
|
+
| `adyen` | `balanceAccountId` | `counterparty.transferInstrumentId` | none | other counterparty forms |
|
|
116
|
+
| `checkout` | `source.id` | `destination.id` | none | |
|
|
117
|
+
| `paypal` | fixed | `items.0.receiver` | none | batches, email receivers |
|
|
118
|
+
| `razorpayx` | `account_number` | `fund_account_id` | none | |
|
|
119
|
+
| `molliePayouts` | `balanceId`, or `account` if omitted | fixed | none | |
|
|
120
|
+
| `peach` | `:merchantId` | `branchCode--accountNumber` | none | batches |
|
|
121
|
+
| `stitch` | fixed | `bankId--accountNumber` | none | currencies other than ZAR |
|
|
122
|
+
| `revolut` | `account_id` | `receiver.account_id` | none | |
|
|
123
|
+
| `modernTreasury` | `originating_account_id` | `receiving_account_id` | none | `currency` unless given in `defaults` |
|
|
124
|
+
| `airwallex` | fixed | `beneficiary_id` | none | |
|
|
125
|
+
| `dwolla` | `_links.source.href` | `_links.destination.href` | none | |
|
|
126
|
+
| `wise` | quote's profile | `targetAccount` | hand-written | rates, recipient creation |
|
|
127
|
+
| `bridge` | `on_behalf_of` | `destination.to_address` | hand-written | later transfer states |
|
|
128
|
+
| `circleMint` | `source.id`, or `account` if omitted | `destination.addressId` | real SDK | |
|
|
129
|
+
| `fireblocks` | `source.id` | `destination.oneTimeAddress.address` | real SDK | assets not listed below |
|
|
130
|
+
|
|
131
|
+
Formats with no live client are covered by HTTP tests of author-written samples only.
|
|
132
|
+
A hand-written client shows the declaration agrees with itself, not that it matches the provider.
|
|
133
|
+
|
|
134
|
+
## Staged formats
|
|
135
|
+
|
|
136
|
+
`{ "flow": "wise", "fixed": { tenant, agent, delegation, network }, "scales": { ... }, "routes": { quotes, transfers, fund } }`
|
|
137
|
+
declares Wise's three calls, which one route cannot express. The default routes are
|
|
138
|
+
`POST /v3/profiles/:profileId/quotes`, which records the profile (the account), the amount, the
|
|
139
|
+
source currency (the currency) and the target currency (the asset); `POST /v1/transfers`, which binds
|
|
140
|
+
`customerTransactionId` (the key) and `targetAccount` (the destination) to one quote; and
|
|
141
|
+
`POST /v3/profiles/:profileId/transfers/:transferId/payments`, which funds it under the quote's
|
|
142
|
+
profile. `GET /v1/transfers/:transferId` reads a transfer (waiting, funded or cancelled; the funded state is
|
|
143
|
+
`processing`) and `PUT /v1/transfers/:transferId/cancel`
|
|
144
|
+
cancels one still waiting; cancelling a funded transfer is refused with the lab's own code, as it was
|
|
145
|
+
never observed, and funding a cancelled one is refused before the store. A currency outside `scales` is refused. A quote by `targetAmount` is taken only when source
|
|
146
|
+
and target currency match, as no rate is imitated. Only the fund call is a payment: it alone is
|
|
147
|
+
counted in traffic, reaches the barrier and refusal, and commits an effect. A quote or an unfunded
|
|
148
|
+
transfer is process state, cleared by `reset`. A repeat of a `customerTransactionId` with the same
|
|
149
|
+
terms returns the same transfer, and a repeat fund adds no effect. With other terms it answers 422,
|
|
150
|
+
recorded under `rejected`. A quote may serve several transfers here whatever Wise does, so a second
|
|
151
|
+
payment stays visible to the checker. A refused fund may be funded again. Funding an unknown transfer,
|
|
152
|
+
or under another profile, is refused before the store, so it counts as unrecorded and the run cannot
|
|
153
|
+
pass. The replies for these repeats, the HTTP status of a refused fund, and recipient creation are
|
|
154
|
+
unverified or not imitated.
|
|
155
|
+
|
|
156
|
+
A declared format may add `"connect": { accounts, externalAccounts, payouts }` for Stripe Connect,
|
|
157
|
+
as `stripeConnect` declares it:
|
|
158
|
+
`POST /v1/accounts` creates a connected account, `POST /v1/accounts/:accountId/external_accounts`
|
|
159
|
+
attaches a bank account to one, the format's own path (`POST /v1/transfers`) is the payment to a
|
|
160
|
+
connected account, and `POST /v1/payouts` with a `Stripe-Account` header pays out of that account.
|
|
161
|
+
Only the transfer is a payment. Its destination must be an account created in this run, or it is
|
|
162
|
+
refused before the store. Each committed transfer adds its amount to the account's balance in its
|
|
163
|
+
currency, including one whose reply a fault then drops. A payout above that balance is answered 400
|
|
164
|
+
`balance_insufficient`. A payout under an `Idempotency-Key` it has used replays the first payout and
|
|
165
|
+
draws nothing more; the same key with other terms is answered 400 `idempotency_key_in_use`; without
|
|
166
|
+
a key each payout is new. Currencies compare in lower case. A payout is never an effect: each one
|
|
167
|
+
paid is listed under `payouts` in `GET /_control/effects`, once however often its key is replayed,
|
|
168
|
+
and a refused payout is not listed. The checker holds the payouts on an account against the
|
|
169
|
+
transfers to it, so a repeated payout of money already transferred is not a second payment, while
|
|
170
|
+
a second transfer, or payouts beyond what the transfers put there, are excess. Account fields beyond
|
|
171
|
+
the identifier, bank details and payout timing are not imitated, and the accounts are process state,
|
|
172
|
+
cleared by `reset`.
|
|
173
|
+
|
|
174
|
+
## Crypto formats
|
|
175
|
+
|
|
176
|
+
Supported, as imitated request and reply shapes only:
|
|
177
|
+
|
|
178
|
+
| Provider | Declaration | Asset | Network | Scale |
|
|
179
|
+
|---|---|---|---|---|
|
|
180
|
+
| Bridge | `bridge` | USDC | the `payment_rail` the request names, from a declared list | 6 |
|
|
181
|
+
| Circle Mint | `circleMint` | USDC, written as currency `USD` | declared in `fixed` | 6 |
|
|
182
|
+
| Fireblocks | `fireblocks` | USDC, ETH | declared in `fixed`, and must be `ethereum` | 6, 18 |
|
|
183
|
+
|
|
184
|
+
`amount.scales` names every asset a declaration takes and its decimal places, `amount.scaleTerm` names the term that identifies the asset, and `amount.networks` the networks each may sit on. Any other asset or network, or excess precision, is refused. There is no rounding. `amount.contracts` binds a token on each network to its EIP-55 contract, keyed `asset@network`: the declaration is sealed into the run record, and no shipped format carries a contract in its request, so a contract is declared, not observed. `amount.evmNetworks` names the networks with EVM destinations and is the single source for both sides: the test provider refuses anything else there and records the EIP-55 form, and an address in mixed case with a bad checksum, or in upper case unless that is its checksum, is refused. `fixtures/wire/vectors.json` pins this, and the digest a key takes when the record format cannot hold it (`key-<sha256>`, in lower-case hex, also taken by a key already in exactly that form, on every format including the lab's and Wise's), for both sides. No other provider, asset or network is supported, and nothing here claims general crypto execution. A reply of accepted or submitted does not show delivery, and later states and webhooks are not imitated.
|
|
185
|
+
|
|
186
|
+
`credential: { signedJwt: true }` verifies an RS256 token per request, as Fireblocks signs them: `uri` must be the request's path, `bodyHash` the SHA-256 of the exact body, `sub` the `x-api-key` header, and each `nonce`, string or number, is accepted once per run, within `maxAgeSeconds` (default 60) of `iat`. A body no parser captured is refused. The host generates a lab RSA key with the `rsa` crate for such a run and sends it down the provider token's path, as the hex of its PEM, so the test provider and the wired provider clients hold it and a test does not. A client decodes the hex before use. It is a lab key and signs nothing outside the run.
|
|
187
|
+
|
|
188
|
+
Direct on-chain sending is not supported. The test provider records an effect as durable once committed. A transaction is not: it can be replaced, dropped, expired or reorganised out, so a recorded hash cannot stand for a final payment. That needs an effect lifecycle and chain-specific retry identity, which do not exist here.
|
|
189
|
+
|
|
190
|
+
## Control endpoints (runner only, `authorization: Bearer $PROVIDER_CONTROL_TOKEN`)
|
|
191
|
+
|
|
192
|
+
- `GET /_control/ready` -> 200 `{ "ready": true }` once its database is reachable.
|
|
193
|
+
- `POST /_control/hold-next` -> arms the barrier: the NEXT payout request commits its effect, then
|
|
194
|
+
holds its response. 200 `{ "armed": true }`. An optional body `{ "match": { <instruction fields> } }`
|
|
195
|
+
limits the hold to a request carrying those exact terms; any other request is answered normally.
|
|
196
|
+
- `POST /_control/refuse-next` -> the NEXT payout request carrying `match` is answered with the format's
|
|
197
|
+
`declined` reply (402 on the lab's own), creates no effect and is recorded under `rejected` with reason
|
|
198
|
+
`declined`. A key that already holds an effect answers as a repeat and leaves the refusal armed. Several
|
|
199
|
+
may wait at once when each names other terms, at most 64; a request is taken by the first armed refusal
|
|
200
|
+
it carries. 409 when the same terms already wait, when one naming no terms waits or is asked for beside
|
|
201
|
+
others, or at the bound.
|
|
202
|
+
- `GET /_control/barrier` -> `{ "state": "idle" | "armed" | "committed" | "released", "effectId": string | null }`.
|
|
203
|
+
`committed` means the effect row is durably committed and the response is being held.
|
|
204
|
+
- `POST /_control/release` -> stop holding; the held response is discarded (never written to the
|
|
205
|
+
socket if the connection is gone). 200 `{ "released": true }`.
|
|
206
|
+
- `POST /_control/disarm` -> return an `armed` barrier that has not captured a response to `idle`, so
|
|
207
|
+
the next payout is answered normally. 200 `{ "disarmed": true }`; 409 in any other state (a
|
|
208
|
+
`committed` barrier is cleared only by `release` or `reset`). The runner calls it when its wait for
|
|
209
|
+
`committed` expires or fails, before joining the first attempt.
|
|
210
|
+
- `GET /_control/effects` -> `{ "effects": [ { "effectId", "provider", "key", "instruction", "providerAccount", "operation", "idempotencyScope", "committedAt" } ] }`
|
|
211
|
+
ordered by commit order. Notifications, if any, are listed separately in delivery order under
|
|
212
|
+
`{ "notifications": [ { "effectId", "deliveredAt", "deliveryId", "issued", "sentAt", "status" } ] }`
|
|
213
|
+
and are never effects: `issued` is the order the runner issued them in, `sentAt` and `deliveredAt`
|
|
214
|
+
when sending began and ended on the test provider's clock, to the microsecond, and `status` the
|
|
215
|
+
backend's HTTP answer. `sentAt` and `status` are null when nothing was sent or nothing answered.
|
|
216
|
+
Refused requests
|
|
217
|
+
are listed under `{ "rejected": [ { "provider", "key", "instruction", "providerAccount", "operation", "reason", "paymentFromKey", "rejectedAt" } ] }`
|
|
218
|
+
and are never effects either. Payouts drawn on a balance that effects funded (only a format with
|
|
219
|
+
`connect` pays any) are listed under `{ "payouts": [ { "payoutId", "account", "amount", "currency", "key", "paidAt" } ] }`,
|
|
220
|
+
always present and empty otherwise; they are never effects. The test provider's mapping
|
|
221
|
+
requires the list.
|
|
222
|
+
- `POST /_control/notify/:effectId` -> issues a notification of an existing effect. Body
|
|
223
|
+
`{ "copies"?: 1..8, "hold"?: boolean }`: `copies` deliveries are sent at once; `hold` keeps them
|
|
224
|
+
back. 200 `{ "notified": true, "held", "answers": [status | null] }`; 404 if unknown. When the
|
|
225
|
+
deployment declares `PROVIDER_NOTIFY_PATH`, each delivery is a JSON POST to that path on
|
|
226
|
+
`PROVIDER_NOTIFY_ORIGIN` (the gate's lab-side ingress to the declared service), body
|
|
227
|
+
`{ "deliveryId", "effectId", "event": "payout.paid", "payment", "amount", "currency", "asset", "network" }`,
|
|
228
|
+
header `x-provider-signature: sha256=<hex HMAC-SHA256 of the exact body under PROVIDER_NOTIFY_SECRET>`,
|
|
229
|
+
with a 5 second timeout, no redirect and no retry. Without a path nothing is sent. Every delivery
|
|
230
|
+
is recorded once it ends. The secret is its own: at least 32 characters, never equal to a token,
|
|
231
|
+
generated for each deployment (`MANDATEOPS_NOTIFY_SECRET`, by `scripts/compose-up.sh` or the
|
|
232
|
+
host's session), handed only to the test provider and to the service variable the deployment names in
|
|
233
|
+
`MANDATEOPS_SUT_NOTIFY_ENV`, and redacted from every kept log. A path without a secret refuses to
|
|
234
|
+
start.
|
|
235
|
+
- `POST /_control/notify-release` -> delivers every held notification in the order issued. 200
|
|
236
|
+
`{ "released": true, "answers": [...] }`.
|
|
237
|
+
- `GET /_control/traffic` -> `{ "proxied": n, "direct": n, "unrecorded": n, "flow": {...} }`: payment requests by whether they
|
|
238
|
+
came through the fault proxy, and those that left no record because they were refused before reaching the store
|
|
239
|
+
(bad credentials, the rate limit, a malformed body). `flow` places every request the test provider received,
|
|
240
|
+
except control requests, against the declared `financialFlow`:
|
|
241
|
+
`{ "providers": [{ "provider", "operation", "expected", "steps" }], "expected", "steps", "unsupported": [{ "provider", "method", "route", "operation", "count" }], "ambiguous": [{ "provider", "method", "path", "count" }], "omittedRequests" }`.
|
|
242
|
+
Each request is placed against the flow of the provider whose host it named, and each listed entry
|
|
243
|
+
names that provider, so a call routed to a provider whose format does not declare it is reported
|
|
244
|
+
against that provider; a request to a host naming no provider is listed under `(unknown host)`.
|
|
245
|
+
`providers` gives each provider's declared operation and counts; the top-level `expected` and
|
|
246
|
+
`steps` are summed over them; `expected` counts `POST` requests to the payment route; `steps`
|
|
247
|
+
counts requests to the other routes the format declares; `unsupported` lists each `POST` to a declared
|
|
248
|
+
money route by method and route with its operation; `ambiguous` lists each other request by method and
|
|
249
|
+
path (repeated slashes collapsed, trailing slash removed, query removed, cut to 128 characters).
|
|
250
|
+
A flow declares at most 32 money routes, so `unsupported` holds at most 32 entries per provider
|
|
251
|
+
(256 for the 8 providers a run may list) and is never capped. `ambiguous` lists at most 32 distinct
|
|
252
|
+
entries over the whole run; each request whose entry would exceed that bound is counted in
|
|
253
|
+
`omittedRequests`, not listed. The runner refuses a reading with more entries than either bound. A request in `unsupported` records the capture gap
|
|
254
|
+
`provider_operation_unsupported`; one in `ambiguous`, or any `omittedRequests`, records
|
|
255
|
+
`provider_request_unplaced` (see `contracts/properties.md`). The reading covers only requests that
|
|
256
|
+
reached the test provider: an empty `unsupported` and `ambiguous` does not show that the backend sent every
|
|
257
|
+
provider call here.
|
|
258
|
+
- `POST /_control/drop-next` -> the NEXT payment carrying `match` commits its effect, then its connection
|
|
259
|
+
closes unanswered: a reply lost after commit. Armed like `refuse-next`: several may wait for different
|
|
260
|
+
terms, at most 64. 200 `{ "armed": true }`.
|
|
261
|
+
- `POST /_control/withdraw` -> body `{ "match": {...} }` withdraws an armed refusal or lost reply with
|
|
262
|
+
exactly those terms that no request took. 200 `{ "refusal": bool, "drop": bool }`, each true when one
|
|
263
|
+
was waiting.
|
|
264
|
+
- `POST /_control/effect-counts` -> body `{ "keys": [...] }` (1 to 1000 keys) -> `{ "counts": { key: n } }`
|
|
265
|
+
for the keys holding effects.
|
|
266
|
+
- `GET /_control/effect-summary` -> `{ "effects", "keys", "duplicateKeys", "duplicateKeyCount" }` over the
|
|
267
|
+
whole run: at most 20 duplicate keys are named and all are counted.
|
|
268
|
+
- `POST /_control/reset` -> clears effects, bindings, notifications, traffic counts and barrier for a fresh run.
|
|
269
|
+
|
|
270
|
+
`PROVIDER_RECORD_LIMIT` (default 1000, at most 10,000,000) bounds the effects, refusals, deliveries, Wise
|
|
271
|
+
quotes and transfers one run keeps; a scaled run raises it. Past it a request is refused, never dropped.
|
|
272
|
+
|
|
273
|
+
Control bodies are JSON; a declared format may use form bodies. Bodies are limited to 8 KiB unless
|
|
274
|
+
`PROVIDER_BODY_LIMIT_BYTES` says otherwise. Amounts are decimal strings of integer minor units.
|
|
275
|
+
|
|
276
|
+
## Several providers
|
|
277
|
+
|
|
278
|
+
A run lists up to 8 providers by name (`PROVIDER_NAMES`, comma-separated; one provider named
|
|
279
|
+
`provider` when unset), and `PROVIDER_WIRE` holds the lowercase hex of one JSON array of
|
|
280
|
+
`{ "name", "format" }`, a `null` format for the lab's own, naming the run's providers in that order. The
|
|
281
|
+
list is at most 64 KiB (8 KiB per provider) before its hex; anything else refuses to start. One process
|
|
282
|
+
serves them all from one ledger:
|
|
283
|
+
|
|
284
|
+
- The provider at position `n` (from 1) is reached at `mandateops-provider` for the first and
|
|
285
|
+
`mandateops-provider-<n>` for each later one, on port 8666. The test provider tells them apart by the host
|
|
286
|
+
a request names. In a run of one provider any host reaches it; in a run of several, a host naming
|
|
287
|
+
none of them is answered 421 `misdirected_request` and listed as unplaced.
|
|
288
|
+
- Each provider holds its own credential: `PROVIDER_TOKEN` for the first and `PROVIDER_TOKEN_<n>` for
|
|
289
|
+
each later one, a signing key of its own for a format that signs requests. No provider accepts
|
|
290
|
+
another's.
|
|
291
|
+
- Each provider reads bodies only in its own format's media types; any other is 415.
|
|
292
|
+
- Lab-only: `PROVIDER_COMMIT_DELAYS` (`name=milliseconds` pairs, comma-separated, 1 to 120000 each)
|
|
293
|
+
makes a listed provider wait before committing the first request under each key that a reply fault is
|
|
294
|
+
armed for (an unfaulted request is never slowed), so a run can show
|
|
295
|
+
what a backend does while a provider has neither paid nor refused. A later request under the same key
|
|
296
|
+
does not wait. A backend that fails over safely asks the first provider again under the same key and
|
|
297
|
+
moves on only on a refusal of that key; a missing answer, a timeout or an empty reply never shows a
|
|
298
|
+
payment does not exist.
|
|
299
|
+
- Each provider binds its own idempotency keys: the same key on two providers is two effects, as two real
|
|
300
|
+
providers would hold. Every effect and refusal names the provider that recorded it.
|
|
301
|
+
- Money is counted across every provider: `effect-counts` and `effect-summary` sum a key's effects over
|
|
302
|
+
all of them, and the checker judges one payout's effects together, so a payout paid once on each of two
|
|
303
|
+
providers is an excess effect, not two healthy payments.
|
|
304
|
+
- One key reused across providers for different payouts is reported as a duplicate key: the summary
|
|
305
|
+
counts a key's effects over every provider, whatever payout each carries.
|
|
306
|
+
- Each effect and refusal is read by the format of the provider that recorded it: its destination's
|
|
307
|
+
spelling, its token contracts and its fixed and defaulted terms are that provider's. Terms not yet
|
|
308
|
+
bound to one provider, such as the authorised payout, take the spelling of any provider whose format
|
|
309
|
+
holds their network.
|
|
310
|
+
|
|
311
|
+
## Topology (Compose)
|
|
312
|
+
|
|
313
|
+
Services in `compose.audit.yml`: `provider-db`, `provider`, `mandateops-relay`, `gate`. The backend's own services run
|
|
314
|
+
in a separate Compose project on the internal `customer` network, from the Compose file its deployment names (for the example, `backend-db` and `backend` in
|
|
315
|
+
`examples/ts-payout-backend/compose.sut.yml`). A backend's provider URL is `http://mandateops-provider:8666`, the gate's route to
|
|
316
|
+
The fault-control proxy `provider`, which upstreams to `provider:8080`. The runner reaches the backend through the gate's ingress port, and provider control and the fault-control API on loopback ports
|
|
317
|
+
(`MANDATEOPS_PROVIDER_PORT`, `MANDATEOPS_FAULT_CONTROL_PORT`, default 0 = dynamic; `scripts/compose-up.sh` reads them back with `docker compose port`). Compose project name is
|
|
318
|
+
always `audit-lab-<run id>`; never reuse the MandateOps payments stack's ports, volumes or project names.
|
|
319
|
+
|
|
320
|
+
## Proposed amendments
|
|
321
|
+
|
|
322
|
+
Proposed by the Rust runner (crates/audit-adapter); not yet agreed.
|
|
323
|
+
|
|
324
|
+
1. Runner credentials. The runner reads `MANDATEOPS_AGENT_TOKEN`, `MANDATEOPS_CONTROL_TOKEN` (the backend's control API) and
|
|
325
|
+
`MANDATEOPS_PROVIDER_CONTROL_TOKEN` from its environment, never from `ports.env` or arguments. The entry
|
|
326
|
+
script should export the same values it gives the containers.
|
|
327
|
+
2. `ports.env` format. One `KEY=VALUE` per line with the three port keys above, each a resolved port in
|
|
328
|
+
1..=65535 (never 0). Other keys, such as `MANDATEOPS_BACKEND_ADAPTER`, are ignored by the runner; `#` comments and blank lines are allowed; at most 4 KiB.
|
|
329
|
+
3. `GET /_control/effects` returns the three lists in one body, `{ "effects": [...], "notifications": [...], "rejected": [...] }`,
|
|
330
|
+
with no other fields. The runner rejects unknown fields and any body that repeats an object member
|
|
331
|
+
name (for example two `effects` members); such a body is an interpretation failure.
|
|
332
|
+
4. Runner order for the lost-response barrier: `hold-next` → attempt → poll `/_control/barrier` until
|
|
333
|
+
`committed` → disable proxy `provider` (`PATCH /proxies/provider {"enabled": false}`) → backend attempt
|
|
334
|
+
returns → `release` → enable proxy. `release` is called only after `committed` was observed. On any
|
|
335
|
+
failure the runner calls `release` if `committed` was observed, otherwise `disarm` if `hold-next` was
|
|
336
|
+
requested, and `release` if that `disarm` is refused with 409; it re-enables proxy `provider`
|
|
337
|
+
whenever a disable was requested, whatever its reply, and tries once more at final cleanup if that
|
|
338
|
+
fails. After the payout is submitted the runner always captures history, capacity, effects and
|
|
339
|
+
history again, then effects once more, before the checker decides.
|
|
340
|
+
5. Provider account binding (adopted in V1.1). Each effect record carries `providerAccount` (the caller
|
|
341
|
+
identity behind the payment token), `operation` and `idempotencyScope`, configurable per deployment
|
|
342
|
+
(`MANDATEOPS_PROVIDER_ACCOUNT`, `MANDATEOPS_PROVIDER_OPERATION`; defaults the lab's own account,
|
|
343
|
+
`payout-create` and `provider-account`). The run input declares the expected provider binding and the checker's
|
|
344
|
+
`instruction_binding` property compares them.
|
|
345
|
+
6. Backend attempt evidence moved to the [adapter contract](system-under-test.md): the adapter maps a
|
|
346
|
+
provider timeout and each outcome's `ended_by`.
|
|
347
|
+
|
|
348
|
+
## Amount bound
|
|
349
|
+
|
|
350
|
+
The provider keeps amounts as decimal strings and holds at most 340282366920938463463374607431768211455 minor units, the core's `u128` maximum. That is about 3.4e20 whole units of an 18-decimal asset. Amounts above it are refused: the SDK refuses one before sending, and the host cannot parse one into an amount, so it is never authorised. There is no 256-bit amount type. `fixtures/wire/vectors.json` holds the boundary list that the Rust, SDK and provider tests all read.
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
# Financial Audit Lab infrastructure shared by every backend under test: the
|
|
2
|
+
# test provider, its database, the fault-control proxy and the gate. It
|
|
3
|
+
# is its own Compose project. A customer's services run in a second project on
|
|
4
|
+
# the internal `customer` network, with no egress; the gate is their only way
|
|
5
|
+
# out, and carries exactly two routes: mandateops-provider to the fault-control proxy, listening on
|
|
6
|
+
# the customer network only, and the ingress port from the host to the
|
|
7
|
+
# declared service, listening on the lab network only. A deployment against a
|
|
8
|
+
# real provider's sandbox adds egress: the sandbox host names the gate on the
|
|
9
|
+
# customer network (compose.egress.yml in the run directory), and the gate
|
|
10
|
+
# passes TLS for that exact host alone through its fault-control proxy, whose
|
|
11
|
+
# upstream config/fault-control.json fixes. Nothing here is reachable from a
|
|
12
|
+
# customer container except through these. Published
|
|
13
|
+
# ports bind to loopback; 0 asks Docker for a free port. Always start through
|
|
14
|
+
# scripts/compose-up.sh. Volumes are disposable and removed by compose-down.sh.
|
|
15
|
+
|
|
16
|
+
x-postgres: &postgres
|
|
17
|
+
# Every lab image runs under a MandateOps name, built FROM its pinned
|
|
18
|
+
# upstream digest by the thin Dockerfiles in images/, and tagged for this
|
|
19
|
+
# run alone: another run's build never moves the image this one starts.
|
|
20
|
+
image: mandateops/provider-store:17.6-${MANDATEOPS_LAB_IMAGE_RUN:?set by scripts/compose-lib.sh}
|
|
21
|
+
build:
|
|
22
|
+
context: ${MANDATEOPS_LAB_ROOT:?set by scripts/compose-lib.sh}/images/provider-store
|
|
23
|
+
environment: &postgres-environment
|
|
24
|
+
POSTGRES_PASSWORD: ${MANDATEOPS_PROVIDER_DB_PASSWORD:?generated per session}
|
|
25
|
+
healthcheck:
|
|
26
|
+
# TCP readiness excludes the initialisation server, which is socket-only.
|
|
27
|
+
test: ["CMD", "pg_isready", "--host", "127.0.0.1", "--username", "postgres"]
|
|
28
|
+
interval: 1s
|
|
29
|
+
timeout: 3s
|
|
30
|
+
retries: 60
|
|
31
|
+
|
|
32
|
+
services:
|
|
33
|
+
provider-db:
|
|
34
|
+
<<: *postgres
|
|
35
|
+
environment:
|
|
36
|
+
<<: *postgres-environment
|
|
37
|
+
POSTGRES_DB: audit_lab_provider
|
|
38
|
+
networks: [lab]
|
|
39
|
+
volumes:
|
|
40
|
+
- provider-db-data:/var/lib/postgresql/data
|
|
41
|
+
|
|
42
|
+
provider:
|
|
43
|
+
image: mandateops/test-provider:${MANDATEOPS_PROVIDER_IMAGE_TAG:?set by scripts/compose-lib.sh}-${MANDATEOPS_LAB_IMAGE_RUN:?set by scripts/compose-lib.sh}
|
|
44
|
+
build:
|
|
45
|
+
context: ${MANDATEOPS_LAB_ROOT:?set by scripts/compose-lib.sh}/examples/test-provider
|
|
46
|
+
environment:
|
|
47
|
+
MANDATEOPS_LAB: "1"
|
|
48
|
+
DATABASE_URL: postgres://postgres:${MANDATEOPS_PROVIDER_DB_PASSWORD:?generated per session}@provider-db:5432/audit_lab_provider
|
|
49
|
+
PROVIDER_TOKEN: ${MANDATEOPS_PROVIDER_TOKEN:?see config/lab.env}
|
|
50
|
+
# Each later provider's own credential, by its position in the run's list.
|
|
51
|
+
PROVIDER_TOKEN_2: ${MANDATEOPS_PROVIDER_TOKEN_2:?see config/lab.env}
|
|
52
|
+
PROVIDER_TOKEN_3: ${MANDATEOPS_PROVIDER_TOKEN_3:?see config/lab.env}
|
|
53
|
+
PROVIDER_TOKEN_4: ${MANDATEOPS_PROVIDER_TOKEN_4:?see config/lab.env}
|
|
54
|
+
PROVIDER_TOKEN_5: ${MANDATEOPS_PROVIDER_TOKEN_5:?see config/lab.env}
|
|
55
|
+
PROVIDER_TOKEN_6: ${MANDATEOPS_PROVIDER_TOKEN_6:?see config/lab.env}
|
|
56
|
+
PROVIDER_TOKEN_7: ${MANDATEOPS_PROVIDER_TOKEN_7:?see config/lab.env}
|
|
57
|
+
PROVIDER_TOKEN_8: ${MANDATEOPS_PROVIDER_TOKEN_8:?see config/lab.env}
|
|
58
|
+
PROVIDER_CONTROL_TOKEN: ${MANDATEOPS_PROVIDER_CONTROL_TOKEN:?see config/lab.env}
|
|
59
|
+
LISTEN_HOST: 0.0.0.0
|
|
60
|
+
PORT: "${MANDATEOPS_PROVIDER_CONTAINER_PORT:?set by scripts/compose-lib.sh}"
|
|
61
|
+
PROVIDER_ACCOUNT: ${MANDATEOPS_PROVIDER_ACCOUNT:?declared by the run}
|
|
62
|
+
PROVIDER_OPERATION: ${MANDATEOPS_PROVIDER_OPERATION:?declared by the run}
|
|
63
|
+
PROVIDER_IDEMPOTENCY_SCOPE: ${MANDATEOPS_PROVIDER_SCOPE:?declared by the run}
|
|
64
|
+
PROVIDER_NAMES: ${MANDATEOPS_PROVIDER_NAMES:-}
|
|
65
|
+
# Lab-only: providers that wait before committing a key's first request.
|
|
66
|
+
PROVIDER_COMMIT_DELAYS: ${MANDATEOPS_PROVIDER_COMMIT_DELAYS:-}
|
|
67
|
+
PROVIDER_WIRE: ${MANDATEOPS_PROVIDER_WIRE:-}
|
|
68
|
+
PROVIDER_RATE_LIMIT: ${MANDATEOPS_PROVIDER_RATE_LIMIT:-}
|
|
69
|
+
PROVIDER_RATE_WINDOW_MS: ${MANDATEOPS_PROVIDER_RATE_WINDOW_MS:-}
|
|
70
|
+
PROVIDER_BODY_LIMIT_BYTES: ${MANDATEOPS_PROVIDER_BODY_LIMIT_BYTES:-}
|
|
71
|
+
PROVIDER_MAX_CONNECTIONS: ${MANDATEOPS_PROVIDER_MAX_CONNECTIONS:-}
|
|
72
|
+
PROVIDER_REQUEST_TIMEOUT_MS: ${MANDATEOPS_PROVIDER_REQUEST_TIMEOUT_MS:-}
|
|
73
|
+
PROVIDER_POOL_CONNECTIONS: ${MANDATEOPS_PROVIDER_POOL_CONNECTIONS:-}
|
|
74
|
+
PROVIDER_POOL_CONNECTION_TIMEOUT_MS: ${MANDATEOPS_PROVIDER_POOL_CONNECTION_TIMEOUT_MS:-}
|
|
75
|
+
PROVIDER_STATEMENT_TIMEOUT_MS: ${MANDATEOPS_PROVIDER_STATEMENT_TIMEOUT_MS:-}
|
|
76
|
+
PROVIDER_IDLE_TRANSACTION_TIMEOUT_MS: ${MANDATEOPS_PROVIDER_IDLE_TRANSACTION_TIMEOUT_MS:-}
|
|
77
|
+
PROVIDER_PROXY_HOST: mandateops-relay
|
|
78
|
+
# Notifications go to the declared service through the gate's lab-side
|
|
79
|
+
# ingress, only when the deployment declares the path it takes them on.
|
|
80
|
+
PROVIDER_NOTIFY_ORIGIN: http://gate-lab:${MANDATEOPS_GATE_INGRESS_CONTAINER_PORT:?set by scripts/compose-lib.sh}
|
|
81
|
+
PROVIDER_NOTIFY_PATH: ${MANDATEOPS_PROVIDER_NOTIFY_PATH:-}
|
|
82
|
+
# Generated per deployment by scripts/compose-up.sh; never a token.
|
|
83
|
+
PROVIDER_NOTIFY_SECRET: ${MANDATEOPS_NOTIFY_SECRET:-}
|
|
84
|
+
networks: [lab]
|
|
85
|
+
ports:
|
|
86
|
+
- "127.0.0.1:${MANDATEOPS_PROVIDER_PORT:-0}:${MANDATEOPS_PROVIDER_CONTAINER_PORT:?set by scripts/compose-lib.sh}"
|
|
87
|
+
depends_on:
|
|
88
|
+
provider-db:
|
|
89
|
+
condition: service_healthy
|
|
90
|
+
healthcheck:
|
|
91
|
+
test:
|
|
92
|
+
- CMD
|
|
93
|
+
- bun
|
|
94
|
+
- -e
|
|
95
|
+
- >-
|
|
96
|
+
const response = await fetch("http://127.0.0.1:${MANDATEOPS_PROVIDER_CONTAINER_PORT:?set by scripts/compose-lib.sh}/_control/ready",
|
|
97
|
+
{ headers: { authorization: "Bearer " + process.env.PROVIDER_CONTROL_TOKEN } });
|
|
98
|
+
process.exit(response.ok ? 0 : 1);
|
|
99
|
+
interval: 1s
|
|
100
|
+
timeout: 3s
|
|
101
|
+
retries: 60
|
|
102
|
+
|
|
103
|
+
mandateops-relay:
|
|
104
|
+
image: mandateops/fault-control:2.13.0-${MANDATEOPS_LAB_IMAGE_RUN:?set by scripts/compose-lib.sh}
|
|
105
|
+
build:
|
|
106
|
+
context: ${MANDATEOPS_LAB_ROOT:?set by scripts/compose-lib.sh}/images/fault-control
|
|
107
|
+
command: ["-host=0.0.0.0", "-config=/config/fault-control.json"]
|
|
108
|
+
volumes:
|
|
109
|
+
- ${MANDATEOPS_LAB_ROOT:?set by scripts/compose-lib.sh}/config/fault-control.json:/config/fault-control.json:ro
|
|
110
|
+
networks: [lab]
|
|
111
|
+
ports:
|
|
112
|
+
- "127.0.0.1:${MANDATEOPS_FAULT_CONTROL_PORT:-0}:${MANDATEOPS_FAULT_CONTROL_CONTAINER_PORT:?set by scripts/compose-lib.sh}"
|
|
113
|
+
depends_on:
|
|
114
|
+
provider:
|
|
115
|
+
condition: service_healthy
|
|
116
|
+
healthcheck:
|
|
117
|
+
test: ["CMD", "/fault-control-cli", "--host", "http://127.0.0.1:${MANDATEOPS_FAULT_CONTROL_CONTAINER_PORT:?set by scripts/compose-lib.sh}", "inspect", "provider"]
|
|
118
|
+
interval: 1s
|
|
119
|
+
timeout: 3s
|
|
120
|
+
retries: 60
|
|
121
|
+
|
|
122
|
+
gate:
|
|
123
|
+
# The image `provider` builds, used as built: one build per tag, which
|
|
124
|
+
# the containerd image store requires, and never pulled from a registry.
|
|
125
|
+
image: mandateops/test-provider:${MANDATEOPS_PROVIDER_IMAGE_TAG:?set by scripts/compose-lib.sh}-${MANDATEOPS_LAB_IMAGE_RUN:?set by scripts/compose-lib.sh}
|
|
126
|
+
pull_policy: never
|
|
127
|
+
command: ["bun", "dist/gate.js"]
|
|
128
|
+
environment:
|
|
129
|
+
# Each route is `listen side:port=upstream side:host:port`. The gate
|
|
130
|
+
# listens on that side's address alone and connects only to an address
|
|
131
|
+
# on the upstream side, whatever a name resolves to.
|
|
132
|
+
GATE_ROUTES: customer:${MANDATEOPS_PROXY_CONTAINER_PORT:?set by scripts/compose-lib.sh}=lab:mandateops-relay:${MANDATEOPS_PROXY_CONTAINER_PORT:?set by scripts/compose-lib.sh},lab:${MANDATEOPS_GATE_INGRESS_CONTAINER_PORT:?set by scripts/compose-lib.sh}=customer:${MANDATEOPS_SUT_SERVICE:?declared by the run}:${MANDATEOPS_SUT_PORT:?declared by the run}
|
|
133
|
+
# The alias naming the gate on each network, and only there.
|
|
134
|
+
GATE_SIDES: lab=gate-lab,customer=mandateops-provider
|
|
135
|
+
# `host=lab:proxy-host:port/proxy`: the one sandbox host a deployment
|
|
136
|
+
# may reach, set by scripts/compose-lib.sh from config/fault-control.json.
|
|
137
|
+
GATE_EGRESS: ${MANDATEOPS_GATE_EGRESS:-}
|
|
138
|
+
# Where the gate reads reply faults armed on the egress proxy.
|
|
139
|
+
GATE_FAULT_CONTROL: http://mandateops-relay:${MANDATEOPS_FAULT_CONTROL_CONTAINER_PORT:?set by scripts/compose-lib.sh}
|
|
140
|
+
networks:
|
|
141
|
+
lab:
|
|
142
|
+
aliases: [gate-lab]
|
|
143
|
+
customer:
|
|
144
|
+
# Backends reach the first provider of the run through this hostname
|
|
145
|
+
# and each later one through its position, up to the eight a run may
|
|
146
|
+
# list; the test provider tells them apart by the host a request names.
|
|
147
|
+
aliases:
|
|
148
|
+
- mandateops-provider
|
|
149
|
+
- mandateops-provider-2
|
|
150
|
+
- mandateops-provider-3
|
|
151
|
+
- mandateops-provider-4
|
|
152
|
+
- mandateops-provider-5
|
|
153
|
+
- mandateops-provider-6
|
|
154
|
+
- mandateops-provider-7
|
|
155
|
+
- mandateops-provider-8
|
|
156
|
+
ports:
|
|
157
|
+
- "127.0.0.1:0:${MANDATEOPS_GATE_INGRESS_CONTAINER_PORT:?set by scripts/compose-lib.sh}"
|
|
158
|
+
depends_on:
|
|
159
|
+
mandateops-relay:
|
|
160
|
+
condition: service_healthy
|
|
161
|
+
healthcheck:
|
|
162
|
+
test:
|
|
163
|
+
- CMD
|
|
164
|
+
- bun
|
|
165
|
+
- -e
|
|
166
|
+
- >-
|
|
167
|
+
const socket = require("node:net").connect(${MANDATEOPS_PROXY_CONTAINER_PORT:?set by scripts/compose-lib.sh}, "mandateops-provider");
|
|
168
|
+
socket.on("connect", () => process.exit(0));
|
|
169
|
+
socket.on("error", () => process.exit(1));
|
|
170
|
+
interval: 1s
|
|
171
|
+
timeout: 3s
|
|
172
|
+
retries: 60
|
|
173
|
+
|
|
174
|
+
networks:
|
|
175
|
+
lab:
|
|
176
|
+
customer:
|
|
177
|
+
internal: true
|
|
178
|
+
name: ${MANDATEOPS_CUSTOMER_NETWORK:?set by scripts/compose-lib.sh}
|
|
179
|
+
|
|
180
|
+
volumes:
|
|
181
|
+
provider-db-data:
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# OpenTelemetry agents the lab mounts read-only into a backend's containers,
|
|
2
|
+
# so a Node, JVM or Python backend reports function-level spans with no change to it.
|
|
3
|
+
# Code locations (codeloc.cjs, python/mandateops_codeloc.py) have no
|
|
4
|
+
# dependencies. The agents are pinned: the Node packages by lockfile, the Java agent by digest.
|
|
5
|
+
FROM node:22-trixie-slim@sha256:2117f713a417f3aff682ac8f5bc2ebbdf1beed51f36e67ab1e0fd3866b6d2d8f AS node
|
|
6
|
+
WORKDIR /agents/node
|
|
7
|
+
COPY package.json package-lock.json load.cjs codeloc.cjs telemetry-router.cjs ./
|
|
8
|
+
RUN npm ci --omit=dev --ignore-scripts --no-audit --no-fund
|
|
9
|
+
|
|
10
|
+
FROM python:3.12-slim@sha256:5e2bdb1b0d542d5039cffb8181c65930093949194a65c365dfb1b0fe13a4fa5b AS python
|
|
11
|
+
COPY requirements-python.txt /tmp/
|
|
12
|
+
# Every package pinned by hash, wheels only: no build code runs, and --no-deps
|
|
13
|
+
# installs exactly the resolved set.
|
|
14
|
+
RUN pip install --no-cache-dir --no-deps --require-hashes --only-binary=:all: \
|
|
15
|
+
--target /agents/python/site -r /tmp/requirements-python.txt
|
|
16
|
+
COPY python/sitecustomize.py python/mandateops_codeloc.py /agents/python/
|
|
17
|
+
|
|
18
|
+
FROM node:22-trixie-slim@sha256:2117f713a417f3aff682ac8f5bc2ebbdf1beed51f36e67ab1e0fd3866b6d2d8f AS java
|
|
19
|
+
ADD --checksum=sha256:5f9d1f10056ed2b246fbb19543519b8066cda23d6aff19022dbdb84402d6c3ab \
|
|
20
|
+
https://repo1.maven.org/maven2/io/opentelemetry/javaagent/opentelemetry-javaagent/2.33.0/opentelemetry-javaagent-2.33.0.jar \
|
|
21
|
+
/agents/java/agent.jar
|
|
22
|
+
|
|
23
|
+
FROM node:22-trixie-slim@sha256:2117f713a417f3aff682ac8f5bc2ebbdf1beed51f36e67ab1e0fd3866b6d2d8f
|
|
24
|
+
COPY --from=node /agents/node /agents/node
|
|
25
|
+
COPY --from=java /agents/java /agents/java
|
|
26
|
+
COPY --from=python /agents/python /agents/python
|
|
27
|
+
# Copies the agents into the run's shared volume, then exits.
|
|
28
|
+
ENTRYPOINT ["cp", "-a", "/agents/.", "/out/"]
|