@mandateops/cli-linux-x64 0.7.4 → 0.7.6

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.
Binary file
@@ -90,6 +90,14 @@ test provider ignores it; the run record carries it as `run.provider.name` (`lab
90
90
  declared routes and are not repeated here. A route not listed is never assumed to move no money: a
91
91
  request to it is reported as unplaced.
92
92
 
93
+ - `lookup` (optional): `{ path, notFound }`, the provider's status lookup by the payment's key. `path` uses
94
+ route syntax, names the step `:key` and is not the payment route. A `GET` to it names the key as the client
95
+ wrote it, held to the format's key shape and length. A key bound to an effect is answered with the `paid`
96
+ reply for that effect; any other key with `notFound`, whose tokens may only be `{{key}}` (empty for a key
97
+ the format would refuse). A declined key binds nothing, so it is not found. A format whose credential is
98
+ signed over the body cannot declare a lookup. A lookup reads the store and moves no money; it is never held,
99
+ refused or dropped.
100
+
93
101
  Every reply must be answerable once the ledger has acted, so anything a reply could not carry is
94
102
  refused before it. A format whose replies hold `{{amount:number}}` refuses amounts above 2^53 - 1.
95
103
  A key already bound keeps its outcome: a refusal armed for it stays armed for the next new key.
@@ -238,13 +246,14 @@ Direct on-chain sending is not supported. The test provider records an effect as
238
246
  came through the fault proxy, and those that left no record because they were refused before reaching the store
239
247
  (bad credentials, the rate limit, a malformed body). `flow` places every request the test provider received,
240
248
  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" }`.
249
+ `{ "providers": [{ "provider", "operation", "expected", "steps", "lookups" }], "expected", "steps", "lookups", "unsupported": [{ "provider", "method", "route", "operation", "count" }], "ambiguous": [{ "provider", "method", "path", "count" }], "omittedRequests" }`.
242
250
  Each request is placed against the flow of the provider whose host it named, and each listed entry
243
251
  names that provider, so a call routed to a provider whose format does not declare it is reported
244
252
  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
253
+ `providers` gives each provider's declared operation and counts; the top-level `expected`,
254
+ `steps` and `lookups` are summed over them; `expected` counts `POST` requests to the payment route; `steps`
255
+ counts requests to the other routes the format declares; `lookups` counts `GET` requests to its
256
+ declared `lookup`; `unsupported` lists each `POST` to a declared
248
257
  money route by method and route with its operation; `ambiguous` lists each other request by method and
249
258
  path (repeated slashes collapsed, trailing slash removed, query removed, cut to 128 characters).
250
259
  A flow declares at most 32 money routes, so `unsupported` holds at most 32 entries per provider
@@ -12,6 +12,7 @@ import {
12
12
  instructionSchema,
13
13
  ProviderError,
14
14
  providerHostname,
15
+ recordKey,
15
16
  } from "./domain.js";
16
17
  import { providerLedger, settle } from "./payment.js";
17
18
  import type { PaymentStep, SharedLedger } from "./payment.js";
@@ -214,6 +215,7 @@ export async function createApp(
214
215
  flow: new FlowLog(name, {
215
216
  payment: wire.path,
216
217
  steps: wire.preparatory.map((route) => route.path),
218
+ lookup: wire.lookup?.path,
217
219
  flow: wire.financialFlow,
218
220
  }),
219
221
  step: {
@@ -228,6 +230,7 @@ export async function createApp(
228
230
  const unknownHost = new FlowLog(UNKNOWN_HOST, {
229
231
  payment: CONTROL_PREFIX,
230
232
  steps: [],
233
+ lookup: undefined,
231
234
  flow: { operation: "unknown", moneyRoutes: {} },
232
235
  });
233
236
  const isControl = (request: FastifyRequest): boolean =>
@@ -447,6 +450,22 @@ export async function createApp(
447
450
  ),
448
451
  });
449
452
  }
453
+ const { lookup } = wire;
454
+ // A lookup reads the ledger: it is never paced, held or dropped.
455
+ if (lookup)
456
+ app.get(lookup.path, { constraints }, async (request, reply) => {
457
+ const sentKey = lookup.key(request.params);
458
+ const effect =
459
+ sentKey === undefined
460
+ ? undefined
461
+ : await step.ledger.lookup(recordKey(sentKey));
462
+ // A key the format would refuse is never echoed back.
463
+ const shown = sentKey ?? "";
464
+ return answer(
465
+ reply,
466
+ effect ? lookup.found(effect, shown) : lookup.notFound(shown),
467
+ );
468
+ });
450
469
  app.post(wire.path, { constraints }, async (request, reply) =>
451
470
  answer(
452
471
  reply,
@@ -22,6 +22,8 @@ const DEFAULT_TOKEN_AGE_SECONDS = 60;
22
22
  /** A field path of this form reads a route parameter, not the body. */
23
23
  export const ROUTE_PARAMETER = ":";
24
24
  const ARRAY_STEP = /^[0-9]+$/;
25
+ /** The route step a status lookup reads the payment's key from. */
26
+ export const LOOKUP_KEY_STEP = ":key";
25
27
 
26
28
  const headerName = z.string().regex(/^[a-z0-9-]{1,64}$/);
27
29
  const bodyPath = z.string().min(1).max(128);
@@ -177,6 +179,20 @@ const declaredSchema = z
177
179
  })
178
180
  .strict()
179
181
  .optional(),
182
+ /**
183
+ * The provider's status lookup by the payment's key. A known key is
184
+ * answered with the paid reply, any other with `notFound`.
185
+ */
186
+ lookup: z
187
+ .object({
188
+ path: routeSchema.refine(
189
+ (path) => path.split("/").includes(LOOKUP_KEY_STEP),
190
+ `a lookup route names ${LOOKUP_KEY_STEP}`,
191
+ ),
192
+ notFound: replySchema,
193
+ })
194
+ .strict()
195
+ .optional(),
180
196
  /** What the format's flow is, so each request can be placed against it. */
181
197
  financialFlow: financialFlowSchema,
182
198
  })
@@ -234,6 +250,7 @@ function requireReplyTokens(declared: DeclaredWire): void {
234
250
  const words = (reply: DeclaredReply | undefined) =>
235
251
  reply ? tokensIn([reply.body, reply.headers]) : [];
236
252
  const unknown = [
253
+ ...words(declared.lookup?.notFound).filter((name) => name !== "key"),
237
254
  ...[paid, duplicate]
238
255
  .flatMap(words)
239
256
  .filter((name) => !EFFECT_TOKENS.has(name)),
@@ -266,5 +283,10 @@ export function validated(declaration: unknown): DeclaredWire {
266
283
  requireDeclaredEntries(declared);
267
284
  requireRouteParameters(declared);
268
285
  requireReplyTokens(declared);
286
+ if (declared.lookup?.path === declared.path)
287
+ throw new Error("a lookup route is not the payment route");
288
+ // A signed credential covers a body, and a lookup sends none.
289
+ if (declared.lookup && "signedJwt" in declared.credential)
290
+ throw new Error("a lookup cannot be signed over a body");
269
291
  return declared;
270
292
  }
@@ -17,6 +17,7 @@ import { instructionSchema, ProviderError, recordKey } from "./domain.js";
17
17
  import type { Instruction } from "./domain.js";
18
18
  import {
19
19
  keyOf,
20
+ lookupKeyOf,
20
21
  recordedDigits,
21
22
  requireShape,
22
23
  statedAmount,
@@ -133,8 +134,21 @@ export function declaredWire(declaration: unknown, token: string): PaymentWire {
133
134
  reply !== undefined &&
134
135
  tokensIn([reply.body, reply.headers]).includes(AMOUNT_NUMBER_TOKEN),
135
136
  );
137
+ const { lookup } = declared;
136
138
  const wire: PaymentWire = {
137
139
  preparatory: [],
140
+ ...(lookup && {
141
+ lookup: {
142
+ path: lookup.path,
143
+ key: (params) => lookupKeyOf(declared, params),
144
+ found: (effect, sentKey) =>
145
+ answer(declared.replies.paid, {
146
+ ...replyTerms(effect.instruction, sentKey),
147
+ effectId: effect.effectId,
148
+ }),
149
+ notFound: (sentKey) => answer(lookup.notFound, { key: sentKey }),
150
+ },
151
+ }),
138
152
  reset: authenticator.reset,
139
153
  path: declared.path,
140
154
  financialFlow: declared.financialFlow,
@@ -67,6 +67,8 @@ export type FlowView = Readonly<{
67
67
  operation: string;
68
68
  expected: number;
69
69
  steps: number;
70
+ /** Requests reading a payment's status on the format's lookup route. */
71
+ lookups: number;
70
72
  unsupported: readonly UnsupportedCall[];
71
73
  ambiguous: readonly UnplacedCall[];
72
74
  /** Unplaced requests whose entry was beyond {@link MAX_AMBIGUOUS_ENTRIES}. */
@@ -77,6 +79,7 @@ export type FlowView = Readonly<{
77
79
  export type Placement =
78
80
  | Readonly<{ kind: "expected" }>
79
81
  | Readonly<{ kind: "step" }>
82
+ | Readonly<{ kind: "lookup" }>
80
83
  | Readonly<{ kind: "unsupported"; route: string; operation: string }>
81
84
  | Readonly<{ kind: "ambiguous" }>;
82
85
 
@@ -107,6 +110,8 @@ function onRoute(route: string, path: string): boolean {
107
110
  export type ServedRoutes = Readonly<{
108
111
  payment: string;
109
112
  steps: readonly string[];
113
+ /** The format's status-lookup route, served only as a `GET`, if any. */
114
+ lookup: string | undefined;
110
115
  flow: FinancialFlow;
111
116
  }>;
112
117
 
@@ -131,6 +136,8 @@ export function placed(
131
136
  return { kind: "expected" };
132
137
  if (matched !== undefined && served.steps.includes(matched))
133
138
  return { kind: "step" };
139
+ if (matched !== undefined && matched === served.lookup && method === "GET")
140
+ return { kind: "lookup" };
134
141
  if (method === "POST") {
135
142
  const money = Object.entries(served.flow.moneyRoutes).find(([route]) =>
136
143
  onRoute(route, path),
@@ -145,6 +152,7 @@ export function placed(
145
152
  export class FlowLog {
146
153
  private expected = 0;
147
154
  private steps = 0;
155
+ private lookups = 0;
148
156
  private omittedRequests = 0;
149
157
  private readonly unsupported = new Map<string, UnsupportedCall>();
150
158
  private readonly ambiguous = new Map<string, UnplacedCall>();
@@ -161,6 +169,7 @@ export class FlowLog {
161
169
  const placement = placed(this.served, { method, matched, path });
162
170
  if (placement.kind === "expected") this.expected += 1;
163
171
  else if (placement.kind === "step") this.steps += 1;
172
+ else if (placement.kind === "lookup") this.lookups += 1;
164
173
  else if (placement.kind === "unsupported") {
165
174
  const entry = `${method} ${placement.route}`;
166
175
  const earlier = this.unsupported.get(entry);
@@ -193,6 +202,7 @@ export class FlowLog {
193
202
  operation: this.served.flow.operation,
194
203
  expected: this.expected,
195
204
  steps: this.steps,
205
+ lookups: this.lookups,
196
206
  unsupported: [...this.unsupported.values()],
197
207
  ambiguous: [...this.ambiguous.values()],
198
208
  omittedRequests: this.omittedRequests,
@@ -202,6 +212,7 @@ export class FlowLog {
202
212
  reset(): void {
203
213
  this.expected = 0;
204
214
  this.steps = 0;
215
+ this.lookups = 0;
205
216
  this.omittedRequests = 0;
206
217
  this.unsupported.clear();
207
218
  this.ambiguous.clear();
@@ -214,6 +225,7 @@ export type ProviderFlowShare = Readonly<{
214
225
  operation: string;
215
226
  expected: number;
216
227
  steps: number;
228
+ lookups: number;
217
229
  }>;
218
230
 
219
231
  /** Every provider's flow as one reading, for `GET /_control/traffic`. */
@@ -222,6 +234,7 @@ export type RunFlowView = Readonly<{
222
234
  providers: readonly ProviderFlowShare[];
223
235
  expected: number;
224
236
  steps: number;
237
+ lookups: number;
225
238
  unsupported: readonly UnsupportedCall[];
226
239
  ambiguous: readonly UnplacedCall[];
227
240
  omittedRequests: number;
@@ -243,14 +256,18 @@ export function combinedFlow(
243
256
  .slice(MAX_AMBIGUOUS_ENTRIES)
244
257
  .reduce((total, call) => total + call.count, 0);
245
258
  return {
246
- providers: views.map(({ provider, operation, expected, steps }) => ({
247
- provider,
248
- operation,
249
- expected,
250
- steps,
251
- })),
259
+ providers: views.map(
260
+ ({ provider, operation, expected, steps, lookups }) => ({
261
+ provider,
262
+ operation,
263
+ expected,
264
+ steps,
265
+ lookups,
266
+ }),
267
+ ),
252
268
  expected: views.reduce((total, view) => total + view.expected, 0),
253
269
  steps: views.reduce((total, view) => total + view.steps, 0),
270
+ lookups: views.reduce((total, view) => total + view.lookups, 0),
254
271
  unsupported: views.flatMap((view) => view.unsupported),
255
272
  ambiguous: listed,
256
273
  omittedRequests:
@@ -24,6 +24,8 @@ export type PaymentLedger = Readonly<{
24
24
  ) => Promise<ExecutionResult>;
25
25
  /** Records a refusal a format made before any money step. */
26
26
  reject: (request: PaymentRequest, reason: RejectionReason) => Promise<void>;
27
+ /** The effect bound to a recorded key, if any; it never writes. */
28
+ lookup: (key: string) => Promise<Effect | undefined>;
27
29
  }>;
28
30
  /** A payment request and the provider in the run's list that it reached. */
29
31
  export type ProviderPayment = PaymentRequest & Readonly<{ provider: string }>;
@@ -39,6 +41,8 @@ export type SharedLedger = Readonly<{
39
41
  declines: DeclineCheck,
40
42
  ) => Promise<ExecutionResult>;
41
43
  reject: (payment: ProviderPayment, reason: RejectionReason) => Promise<void>;
44
+ /** The effect `provider` bound to a recorded key, if any. */
45
+ lookup: (provider: string, key: string) => Promise<Effect | undefined>;
42
46
  }>;
43
47
 
44
48
  /** The shared ledger as one provider of the run writes to it. */
@@ -49,6 +53,7 @@ export const providerLedger = (
49
53
  execute: (request, refusals, declines) =>
50
54
  shared.execute({ ...request, provider }, refusals, declines),
51
55
  reject: (request, reason) => shared.reject({ ...request, provider }, reason),
56
+ lookup: (key) => shared.lookup(provider, key),
52
57
  });
53
58
 
54
59
  /** Says whether the next request is declined; one attempt per request. */
@@ -1,4 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
+ import type { z } from "zod";
2
3
  import { KEY_SHAPES, ROUTE_PARAMETER } from "./declaration.js";
3
4
  import type { DeclaredWire, Terms } from "./declaration.js";
4
5
  import { ProviderError, providerKeySchema } from "./domain.js";
@@ -112,14 +113,37 @@ export function requireShape(request: RequestReader): void {
112
113
  }
113
114
  }
114
115
 
116
+ /** What a format accepts as a key: its declared shape, then its length. */
117
+ function keyRules({ key }: DeclaredWire): z.ZodType<string> {
118
+ const bounded = providerKeySchema.max(key.maxLength);
119
+ return "shape" in key && key.shape
120
+ ? KEY_SHAPES[key.shape].pipe(bounded)
121
+ : bounded;
122
+ }
123
+
115
124
  export function keyOf(request: RequestReader, headers: RequestHeaders): string {
116
125
  const { key } = request.declared;
117
126
  const sent =
118
127
  "header" in key ? headers[key.header] : valueAt(request, key.field);
119
128
  if (sent === undefined && "optional" in key)
120
129
  if (key.optional) return randomUUID();
121
- if ("shape" in key && key.shape) KEY_SHAPES[key.shape].parse(sent);
122
- return providerKeySchema.max(key.maxLength).parse(sent);
130
+ return keyRules(request.declared).parse(sent);
131
+ }
132
+
133
+ /**
134
+ * The key a status lookup names in its route, held to the same rules a
135
+ * payment's key is; `undefined` when the format would refuse it.
136
+ */
137
+ export function lookupKeyOf(
138
+ declared: DeclaredWire,
139
+ params: unknown,
140
+ ): string | undefined {
141
+ const sent =
142
+ typeof params === "object" && params !== null && "key" in params
143
+ ? params.key
144
+ : undefined;
145
+ const parsed = keyRules(declared).safeParse(sent);
146
+ return parsed.success ? parsed.data : undefined;
123
147
  }
124
148
 
125
149
  const onePart = (part: string | undefined): boolean =>
@@ -384,6 +384,22 @@ export class Store {
384
384
  }, "repeatable read");
385
385
  }
386
386
 
387
+ /** The effect `provider` bound to a recorded key, if any. */
388
+ async lookup(provider: string, key: string): Promise<Effect | undefined> {
389
+ return this.transaction(async (client) => {
390
+ const bound = await client
391
+ .selectFrom("idempotency_bindings")
392
+ .select("effect_id")
393
+ .where("provider", "=", provider)
394
+ .where("provider_account", "=", this.config.providerAccount)
395
+ .where("idempotency_key", "=", key)
396
+ .executeTakeFirst();
397
+ return bound
398
+ ? loadEffect(client, bound.effect_id, this.config.idempotencyScope)
399
+ : undefined;
400
+ });
401
+ }
402
+
387
403
  /** The committed effect a notification is about; 404 when none is. */
388
404
  async effect(effectId: string): Promise<Effect> {
389
405
  return this.transaction(async (client) => {
@@ -52,6 +52,18 @@ export type PreparatoryRoute = Readonly<{
52
52
  headers?: RequestHeaders,
53
53
  ) => PreparatoryAnswer;
54
54
  }>;
55
+ /**
56
+ * A provider's status lookup by the payment's key. It reads the ledger and
57
+ * moves no money; an unknown key is answered as not found.
58
+ */
59
+ export type LookupRoute = Readonly<{
60
+ /** Served as a `GET`; its `:key` step is the key as the client wrote it. */
61
+ path: string;
62
+ /** The key a request names, or `undefined` when the format allows none. */
63
+ key: (params: unknown) => string | undefined;
64
+ found: (effect: Effect, sentKey: string) => WireReply;
65
+ notFound: (sentKey: string) => WireReply;
66
+ }>;
55
67
  /**
56
68
  * One payout a format paid out of a balance its payments funded. It is not
57
69
  * a payment effect: it moves money that a committed payment already moved,
@@ -96,6 +108,8 @@ export type PaymentWire = Readonly<{
96
108
  declined: (request: PaymentRequest) => WireReply;
97
109
  conflict: (request: PaymentRequest) => WireReply;
98
110
  preparatory: readonly PreparatoryRoute[];
111
+ /** The format's status lookup, when it declares one. */
112
+ lookup?: LookupRoute;
99
113
  /**
100
114
  * Told once of each new payment as it commits, before any fault can drop
101
115
  * its reply; a replay or refusal is never told.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mandateops/cli-linux-x64",
3
- "version": "0.7.4",
3
+ "version": "0.7.6",
4
4
  "description": "The mandateops binary and lab for linux-x64, installed by @mandateops/cli.",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://getmandateops.com",