@mark1russell7/service 0.6.2 → 0.6.4
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/README.md +90 -4
- package/build/{builder-0OlfomVU.d.ts → builder-bXJqMe2p.d.ts} +3 -2
- package/build/{core-Iy9rIXOT.d.ts → core-B1zbS4WY.d.ts} +4 -3
- package/build/{dial-DLT7bTlA.d.ts → dial-CSGKVlZe.d.ts} +2 -2
- package/build/grpc.d.ts +3 -3
- package/build/grpc.js +1 -1
- package/build/host.d.ts +556 -0
- package/build/host.js +1738 -0
- package/build/host.js.map +1 -0
- package/build/http-client.d.ts +3 -3
- package/build/http-client.js +1 -1
- package/build/http.d.ts +1 -1
- package/build/index.d.ts +4 -3
- package/build/index.js +5 -749
- package/build/index.js.map +1 -1
- package/build/lifecycle-Ks9Yd5CM.d.ts +387 -0
- package/build/{lifecycle-DXK880vG.d.ts → logger-DhFgh48y.d.ts} +2 -385
- package/build/{machine-Dq2OlzCG.js → machine-DKWLZOqu.js} +3 -2
- package/build/{machine-Dq2OlzCG.js.map → machine-DKWLZOqu.js.map} +1 -1
- package/build/mongodb.d.ts +3 -3
- package/build/mongodb.js +1 -1
- package/build/operation-DL5RxFds.js +25 -0
- package/build/operation-DL5RxFds.js.map +1 -0
- package/build/pg.d.ts +2 -2
- package/build/pg.js +1 -1
- package/build/ports-CZLzYK5d.d.ts +125 -0
- package/build/process-DG_im2zc.js +171 -0
- package/build/process-DG_im2zc.js.map +1 -0
- package/build/{queue-CvBNNZZJ.d.ts → queue-BjiGodqh.d.ts} +3 -2
- package/build/rabbitmq.d.ts +4 -4
- package/build/rabbitmq.js +1 -1
- package/build/redis.d.ts +2 -2
- package/build/redis.js +1 -1
- package/build/requests-BIq9Tr4P.js +586 -0
- package/build/requests-BIq9Tr4P.js.map +1 -0
- package/build/{retrier-CRda6z9G.js → retrier-Bzkme_yM.js} +2 -24
- package/build/retrier-Bzkme_yM.js.map +1 -0
- package/build/testing.d.ts +136 -4
- package/build/testing.js +485 -13
- package/build/testing.js.map +1 -1
- package/build/websocket.d.ts +3 -3
- package/build/websocket.js +1 -1
- package/package.json +7 -2
- package/build/retrier-CRda6z9G.js.map +0 -1
|
@@ -1,27 +1,5 @@
|
|
|
1
1
|
import { realClock } from "./clock.js";
|
|
2
2
|
import { backoffDelay, backoffProblems } from "./backoff.js";
|
|
3
|
-
import { compare, convertible } from "@mark1russell7/quantity";
|
|
4
|
-
//#region src/operation.ts
|
|
5
|
-
/**
|
|
6
|
-
* This function tells if an operation can go again `since` its first issue. An idempotent
|
|
7
|
-
* operation can always go again, and other operations cannot. A keyed operation can go again
|
|
8
|
-
* while the server keeps its key.
|
|
9
|
-
*/
|
|
10
|
-
const mayReissue = (operation, since) => {
|
|
11
|
-
const { idempotent } = operation;
|
|
12
|
-
if (typeof idempotent === "boolean") return idempotent;
|
|
13
|
-
return compare(since, idempotent.window) < 0;
|
|
14
|
-
};
|
|
15
|
-
/** This function gives the problems in the declaration of an operation that `describe()` refuses. */
|
|
16
|
-
const operationProblems = (owner, name, operation) => {
|
|
17
|
-
const { idempotent } = operation;
|
|
18
|
-
if (typeof idempotent === "boolean") return [];
|
|
19
|
-
const problems = [];
|
|
20
|
-
if (idempotent.key.trim().length === 0) problems.push(`${owner}'s ${name} names no key`);
|
|
21
|
-
if (!convertible(idempotent.window.unit, "s")) problems.push(`${owner}'s ${name} holds its key for a span that is not a time`);
|
|
22
|
-
return problems;
|
|
23
|
-
};
|
|
24
|
-
//#endregion
|
|
25
3
|
//#region src/retrier.ts
|
|
26
4
|
/** This function makes a retrier with no check of its policy. A client of the package uses it with its own knobs. */
|
|
27
5
|
const retrierOn = (clock, backoff, random, signal) => {
|
|
@@ -68,6 +46,6 @@ const retrier = (options) => {
|
|
|
68
46
|
return retrierOn(clock, backoff, random, signal);
|
|
69
47
|
};
|
|
70
48
|
//#endregion
|
|
71
|
-
export {
|
|
49
|
+
export { retrierOn as n, retrier as t };
|
|
72
50
|
|
|
73
|
-
//# sourceMappingURL=retrier-
|
|
51
|
+
//# sourceMappingURL=retrier-Bzkme_yM.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"retrier-Bzkme_yM.js","names":[],"sources":["../src/retrier.ts"],"sourcesContent":["import type { Backoff } from \"./backoff.ts\";\nimport { backoffDelay, backoffProblems } from \"./backoff.ts\";\nimport type { Cancel, Clock } from \"./clock.ts\";\nimport { realClock } from \"./clock.ts\";\n\n/** These options make a retrier: a backoff policy, the clock of its timers, and the signal that cancels it. */\nexport interface RetrierOptions extends Backoff {\n /** This clock starts each retry. The default is the real clock. A test gives a fake clock. */\n readonly clock?: Clock | undefined;\n /** This function gives a number in [0, 1) for the jitter of each delay. The default is `Math.random`. */\n readonly random?: (() => number) | undefined;\n /**\n * This signal cancels the retrier when it aborts, for example the `signal` of the lifecycle, which\n * aborts in the drain. After the abort, `schedule` starts nothing.\n */\n readonly signal?: AbortSignal | undefined;\n}\n\n/** A retrier starts a function again after the backoff of each try, on its clock. */\nexport interface Retrier {\n /** This count is the number of tries since the last reset. */\n readonly attempts: number;\n /** This flag tells if a retry waits for its timer. */\n readonly pending: boolean;\n /**\n * This method counts one more try, and starts `run` after the backoff delay of that try. It gives\n * the delay in milliseconds. A retry that waits stops, thus one retry at most waits. After the\n * abort of the signal, it starts nothing and gives null. The function catches its own errors.\n */\n schedule(run: () => void): number | null;\n /** This method sets the count of tries to 0, for example after a start that succeeded. A retry that waits stays. */\n reset(): void;\n /** This method stops the retry that waits. The count of tries stays. */\n cancel(): void;\n}\n\n/** This function makes a retrier with no check of its policy. A client of the package uses it with its own knobs. */\nexport const retrierOn = (clock: Clock, backoff: Backoff, random: () => number, signal?: AbortSignal): Retrier => {\n let tries = 0;\n let timer: Cancel | null = null;\n const cancel = (): void => {\n timer?.();\n timer = null;\n };\n signal?.addEventListener(\"abort\", cancel, { once: true });\n return {\n get attempts() {\n return tries;\n },\n get pending() {\n return timer !== null;\n },\n schedule(run) {\n if (signal?.aborted === true) return null;\n tries += 1;\n const delay = Math.round(backoffDelay(backoff, tries, random));\n timer?.();\n timer = clock.after(delay, () => {\n timer = null;\n run();\n });\n return delay;\n },\n cancel,\n reset() {\n tries = 0;\n },\n };\n};\n\n/**\n * This function makes a retrier over `backoffDelay`. The first try waits `base`, and each try after\n * it waits `factor` times more, to the `cap`, with the jitter of the policy. It refuses a policy\n * with a problem of `backoffProblems`.\n */\nexport const retrier = (options: RetrierOptions): Retrier => {\n const { clock = realClock, random = Math.random, signal, ...backoff } = options;\n const problems = backoffProblems(backoff);\n if (problems.length > 0) throw new Error(`the retrier has a bad backoff: ${problems.join(\"; \")}`);\n return retrierOn(clock, backoff, random, signal);\n};\n"],"mappings":";;;;AAqCA,MAAa,aAAa,OAAc,SAAkB,QAAsB,WAAkC;CAChH,IAAI,QAAQ;CACZ,IAAI,QAAuB;CAC3B,MAAM,eAAqB;EACzB,QAAQ;EACR,QAAQ;CACV;CACA,QAAQ,iBAAiB,SAAS,QAAQ,EAAE,MAAM,KAAK,CAAC;CACxD,OAAO;EACL,IAAI,WAAW;GACb,OAAO;EACT;EACA,IAAI,UAAU;GACZ,OAAO,UAAU;EACnB;EACA,SAAS,KAAK;GACZ,IAAI,QAAQ,YAAY,MAAM,OAAO;GACrC,SAAS;GACT,MAAM,QAAQ,KAAK,MAAM,aAAa,SAAS,OAAO,MAAM,CAAC;GAC7D,QAAQ;GACR,QAAQ,MAAM,MAAM,aAAa;IAC/B,QAAQ;IACR,IAAI;GACN,CAAC;GACD,OAAO;EACT;EACA;EACA,QAAQ;GACN,QAAQ;EACV;CACF;AACF;;;;;;AAOA,MAAa,WAAW,YAAqC;CAC3D,MAAM,EAAE,QAAQ,WAAW,SAAS,KAAK,QAAQ,QAAQ,GAAG,YAAY;CACxE,MAAM,WAAW,gBAAgB,OAAO;CACxC,IAAI,SAAS,SAAS,GAAG,MAAM,IAAI,MAAM,kCAAkC,SAAS,KAAK,IAAI,GAAG;CAChG,OAAO,UAAU,OAAO,SAAS,QAAQ,MAAM;AACjD"}
|
package/build/testing.d.ts
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { n as Clock } from "./clock-mVqhXD0b.js";
|
|
2
|
-
import {
|
|
3
|
-
import {
|
|
2
|
+
import { $ as UncaughtOrigin, G as ExitTrigger, W as ExitSignal, X as ProcessPort, c as Logger, i as LogEntry, s as LogLevel } from "./logger-DhFgh48y.js";
|
|
3
|
+
import { D as CheckFn, F as Outcome, _ as RequestFn, d as TransportImpl, h as RequestEnd, r as Lifecycle } from "./lifecycle-Ks9Yd5CM.js";
|
|
4
|
+
import { n as ServiceBuilder } from "./builder-bXJqMe2p.js";
|
|
5
|
+
import { c as ProcessMark, d as StopSignal, i as CommandResult, n as CommandOptions, o as HostPorts, t as ChildHandle, u as SpawnRequest } from "./ports-CZLzYK5d.js";
|
|
4
6
|
//#region src/fakes.d.ts
|
|
5
7
|
/** A fake clock moves only when a test tells it to. */
|
|
6
8
|
interface FakeClock extends Clock {
|
|
@@ -50,7 +52,10 @@ interface FakeProcessOptions {
|
|
|
50
52
|
}
|
|
51
53
|
/** This function makes a fake process. */
|
|
52
54
|
export declare const fakeProcess: (options?: FakeProcessOptions) => FakeProcess;
|
|
53
|
-
/**
|
|
55
|
+
/**
|
|
56
|
+
* This function gives a seeded random number generator (mulberry32), with numbers in [0, 1). It is
|
|
57
|
+
* `mulberry32` of @mark1russell7/rigor-generators.
|
|
58
|
+
*/
|
|
54
59
|
export declare const seeded: (seed: number) => (() => number);
|
|
55
60
|
//#endregion
|
|
56
61
|
//#region src/contract.d.ts
|
|
@@ -102,9 +107,42 @@ interface TransportSubject {
|
|
|
102
107
|
offer(): Promise<boolean>;
|
|
103
108
|
/** This method starts one unit of work that stays in flight until its release. The promise ends when the transport has it. */
|
|
104
109
|
hold(): Promise<HeldWork>;
|
|
110
|
+
/**
|
|
111
|
+
* This method sends one call through the transport, for the stream cases (option `streams`). The
|
|
112
|
+
* handler of the call gives `call.work` to `life.request(call.controller, call.route, ...)` of the
|
|
113
|
+
* lifecycle of the start, and writes its stream to the caller. It gives what the caller sees.
|
|
114
|
+
*/
|
|
115
|
+
call?(call: StreamCall): CallerView | Promise<CallerView>;
|
|
105
116
|
/** This method frees what the subject holds outside the transport: its clients and their sockets. */
|
|
106
117
|
dispose?(): Promise<void> | void;
|
|
107
118
|
}
|
|
119
|
+
/** A stream call is one request of the stream cases. The kit gives its work, and the subject sends it. */
|
|
120
|
+
interface StreamCall {
|
|
121
|
+
/** This name is the controller of the request in the lifecycle of the kit. */
|
|
122
|
+
readonly controller: string;
|
|
123
|
+
/** This name is the route of the request in the lifecycle of the kit. */
|
|
124
|
+
readonly route: string;
|
|
125
|
+
/** This function is the work of the request: one value, or a stream of values. */
|
|
126
|
+
readonly work: RequestFn<unknown>;
|
|
127
|
+
/** True tells that the answer is a stream of items. False tells that the answer is unary: one status and one value. */
|
|
128
|
+
readonly stream: boolean;
|
|
129
|
+
}
|
|
130
|
+
/** A seen end is the end of a call, as its caller read it. */
|
|
131
|
+
interface SeenEnd {
|
|
132
|
+
readonly kind: RequestEnd["kind"];
|
|
133
|
+
/**
|
|
134
|
+
* True tells that the end came in the body of the answer, after its status, for example as the
|
|
135
|
+
* last line of a stream. False tells that the end came as the status of the answer.
|
|
136
|
+
*/
|
|
137
|
+
readonly inBand: boolean;
|
|
138
|
+
}
|
|
139
|
+
/** A caller view is what the caller of a call has read so far. The kit reads it again until it changes. */
|
|
140
|
+
interface CallerView {
|
|
141
|
+
/** These values are the items that the caller read, in their sequence. */
|
|
142
|
+
readonly items: readonly unknown[];
|
|
143
|
+
/** This end is the end that the caller read, or null while the call is open. */
|
|
144
|
+
readonly end: SeenEnd | null;
|
|
145
|
+
}
|
|
108
146
|
/**
|
|
109
147
|
* This function gives a detached lifecycle: a lifecycle with no service, for the start of a
|
|
110
148
|
* transport in a test. Its state is `running`, it keeps each connection, and nothing is in flight. Each request
|
|
@@ -138,6 +176,11 @@ interface ConformanceOptions {
|
|
|
138
176
|
readonly cooperative?: boolean | undefined;
|
|
139
177
|
/** This count is the number of works that the count case holds. The default is 3. */
|
|
140
178
|
readonly holds?: number | undefined;
|
|
179
|
+
/**
|
|
180
|
+
* True adds the stream cases (S6 D4). Then the subject gives `call`, and the kit gives the
|
|
181
|
+
* transport a lifecycle with request tracking. The default is false.
|
|
182
|
+
*/
|
|
183
|
+
readonly streams?: boolean | undefined;
|
|
141
184
|
/** This function receives each measurement, for the raw records of a run. */
|
|
142
185
|
readonly record?: ((record: ConformanceRecord) => void) | undefined;
|
|
143
186
|
}
|
|
@@ -151,9 +194,98 @@ interface ConformanceOptions {
|
|
|
151
194
|
* past it. It gives the cooperative abort to the work, and it does not throw.
|
|
152
195
|
* - `close` ends the work in flight in its bound, and a second close has no effect.
|
|
153
196
|
* - The stages in their sequence, as the lifecycle does them.
|
|
197
|
+
*
|
|
198
|
+
* The option `streams` adds the cases of the streams (S6 D4). Each request is a stream, and a
|
|
199
|
+
* unary call is a stream of one item. The kit gives the transport a lifecycle with request
|
|
200
|
+
* tracking. It also does the stages of the shutdown on the tracker, as the lifecycle does them.
|
|
201
|
+
* - A unary call gives one value, and its end comes as the status of the answer.
|
|
202
|
+
* - A stream stays in flight until its end, not until its first item.
|
|
203
|
+
* - A failure after the first item ends the stream with an error line in the body, not a status.
|
|
204
|
+
* A failure before the first item gets a status.
|
|
205
|
+
* - `drain` waits for an open stream. The cooperative abort ends the stream, and its caller gets the end.
|
|
206
|
+
* - At the deadline of the drain, the cut ends an open stream, and its caller gets the end.
|
|
154
207
|
*/
|
|
155
208
|
export declare const transportConformance: (make: SubjectFactory, options?: ConformanceOptions) => ContractCase[];
|
|
156
209
|
//#endregion
|
|
210
|
+
//#region src/host/fakes.d.ts
|
|
211
|
+
/** A fake child is a child process of a fake host. A test ends it, or a stop ends it. */
|
|
212
|
+
interface FakeChild extends ChildHandle {
|
|
213
|
+
readonly request: SpawnRequest;
|
|
214
|
+
/** These are the messages that went on its IPC channel. */
|
|
215
|
+
readonly sent: readonly unknown[];
|
|
216
|
+
/** This flag tells if the child ended. */
|
|
217
|
+
readonly ended: boolean;
|
|
218
|
+
/** This method ends the child with a code, or with a signal and a null code. A second use does nothing. */
|
|
219
|
+
exit(code: number | null, signal?: string | null): void;
|
|
220
|
+
/** This method sends data on the output of the child. */
|
|
221
|
+
output(stream: "stdout" | "stderr", chunk: string | Uint8Array): void;
|
|
222
|
+
}
|
|
223
|
+
/** A recorded command is one command that went through the fake command port. */
|
|
224
|
+
interface RecordedCommand {
|
|
225
|
+
readonly file: string;
|
|
226
|
+
readonly args: readonly string[];
|
|
227
|
+
readonly options: CommandOptions | undefined;
|
|
228
|
+
}
|
|
229
|
+
/** A recorded signal is one signal that went through the fake process port. */
|
|
230
|
+
interface RecordedSignal {
|
|
231
|
+
readonly pid: number;
|
|
232
|
+
readonly signal: StopSignal;
|
|
233
|
+
readonly group: boolean;
|
|
234
|
+
}
|
|
235
|
+
/** These options go with a fake host. */
|
|
236
|
+
interface FakeHostOptions {
|
|
237
|
+
/** This text is the platform. The default is `linux`. */
|
|
238
|
+
readonly platform?: string | undefined;
|
|
239
|
+
readonly env?: Readonly<Record<string, string | undefined>> | undefined;
|
|
240
|
+
/** The default is `/home/test`. */
|
|
241
|
+
readonly homeDir?: string | undefined;
|
|
242
|
+
/** The default is `test`. */
|
|
243
|
+
readonly user?: string | undefined;
|
|
244
|
+
/** This record names the host process. The default is the ID 100, which started at the wall time 0. */
|
|
245
|
+
readonly self?: ProcessMark | undefined;
|
|
246
|
+
/** This time is the wall time at the clock time 0, in milliseconds after the epoch. The default is 1 000 000 000 000. */
|
|
247
|
+
readonly wallStart?: number | undefined;
|
|
248
|
+
/** These files are in the fake file system at the start. */
|
|
249
|
+
readonly files?: Readonly<Record<string, string | Uint8Array>> | undefined;
|
|
250
|
+
/**
|
|
251
|
+
* This function gives the result of a command. When it gives undefined, the fake answers. `taskkill`
|
|
252
|
+
* with `/F` ends the process and gives 0. `taskkill` without `/F` gives 1, or ends a polite child. Each other command gives 0.
|
|
253
|
+
*/
|
|
254
|
+
readonly answer?: ((command: RecordedCommand) => CommandResult | undefined) | undefined;
|
|
255
|
+
readonly logger?: Logger | undefined;
|
|
256
|
+
}
|
|
257
|
+
/**
|
|
258
|
+
* A fake host is the host ports of a test, and the state behind them. It starts no process, writes no
|
|
259
|
+
* file and installs no task. Each effect is a record or a change of its state.
|
|
260
|
+
*/
|
|
261
|
+
interface FakeHost {
|
|
262
|
+
readonly ports: HostPorts;
|
|
263
|
+
readonly clock: FakeClock;
|
|
264
|
+
/** These are the files of the fake file system. */
|
|
265
|
+
readonly files: Map<string, string | Uint8Array>;
|
|
266
|
+
readonly commands: RecordedCommand[];
|
|
267
|
+
readonly signals: RecordedSignal[];
|
|
268
|
+
readonly children: FakeChild[];
|
|
269
|
+
/** This table holds each live process: its ID, and its start time or null. */
|
|
270
|
+
readonly processes: Map<number, number | null>;
|
|
271
|
+
/** This map gives the HTTP status of each address. An address that it does not have gives no answer. */
|
|
272
|
+
readonly http: Map<string, number | null>;
|
|
273
|
+
/** This set holds each `host:port` that takes a TCP connection. */
|
|
274
|
+
readonly tcp: Set<string>;
|
|
275
|
+
/** True makes each child end with the code 0 at a staged stop: SIGTERM, SIGINT, an IPC message or `taskkill` without `/F`. */
|
|
276
|
+
polite: boolean;
|
|
277
|
+
/** This function makes a file operation fail. It gets the name of the operation and the path. */
|
|
278
|
+
failFiles: ((operation: string, path: string) => boolean) | null;
|
|
279
|
+
/** This function makes a spawn fail, thus the child has no ID and ends. */
|
|
280
|
+
failSpawn: ((request: SpawnRequest) => boolean) | null;
|
|
281
|
+
/** This method gives the text of a file, or null. */
|
|
282
|
+
text(path: string): string | null;
|
|
283
|
+
/** This method lets the promises that are ready continue, without a move of the clock. */
|
|
284
|
+
settle(): Promise<void>;
|
|
285
|
+
}
|
|
286
|
+
/** This function makes a fake host. Give its `ports` to the host functions in a test. */
|
|
287
|
+
export declare const fakeHost: (options?: FakeHostOptions) => FakeHost;
|
|
288
|
+
//#endregion
|
|
157
289
|
//#region src/testing.d.ts
|
|
158
290
|
/**
|
|
159
291
|
* A behavior is what a scripted check does when the runtime starts it:
|
|
@@ -206,5 +338,5 @@ export interface QuietServer {
|
|
|
206
338
|
*/
|
|
207
339
|
export declare const quietServer: () => Promise<QuietServer>;
|
|
208
340
|
//#endregion
|
|
209
|
-
export type { ConformanceOptions, ConformanceRecord, ContractCase, ContractOptions, FakeClock, FakeProcess, FakeProcessOptions, HeldWork, SubjectFactory, TransportSubject };
|
|
341
|
+
export type { CallerView, ConformanceOptions, ConformanceRecord, ContractCase, ContractOptions, FakeChild, FakeClock, FakeHost, FakeHostOptions, FakeProcess, FakeProcessOptions, HeldWork, RecordedCommand, RecordedSignal, SeenEnd, StreamCall, SubjectFactory, TransportSubject };
|
|
210
342
|
//# sourceMappingURL=testing.d.ts.map
|