@mark1russell7/service 0.6.3 → 0.6.5
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 +28 -3
- package/build/grpc.js +1 -1
- package/build/host.js +1 -1
- package/build/http-client.js +1 -1
- package/build/index.d.ts +26 -1
- package/build/index.js +4 -582
- package/build/index.js.map +1 -1
- package/build/{machine-DKWLZOqu.js → machine-p4lENJ86.js} +2 -2
- package/build/{machine-DKWLZOqu.js.map → machine-p4lENJ86.js.map} +1 -1
- package/build/mongodb.js +1 -1
- package/build/pg.js +1 -1
- package/build/rabbitmq.js +1 -1
- package/build/redis.js +1 -1
- package/build/requests-BIq9Tr4P.js +586 -0
- package/build/requests-BIq9Tr4P.js.map +1 -0
- package/build/retrier-Nt6r4r6R.js +92 -0
- package/build/retrier-Nt6r4r6R.js.map +1 -0
- package/build/testing.d.ts +54 -3
- package/build/testing.js +259 -12
- package/build/testing.js.map +1 -1
- package/build/websocket.js +1 -1
- package/package.json +5 -4
- package/build/retrier-Bzkme_yM.js +0 -51
- package/build/retrier-Bzkme_yM.js.map +0 -1
package/README.md
CHANGED
|
@@ -328,10 +328,13 @@ The clock, the heartbeat and the backoff have their own entries. Each entry impo
|
|
|
328
328
|
- **The retrier.** `retrier({ base, factor, cap, jitter, clock, signal })` starts a function again after the backoff of each try. The root of the package gives it, and the entry `./backoff` does not.
|
|
329
329
|
- **The calls of a retrier.** `schedule(run)` counts one more try, and starts `run` after the delay of that try, on the clock. It gives the delay, and `attempts` gives the count. A second `schedule` stops the retry that waits.
|
|
330
330
|
- **The end of a retrier.** `reset()` sets the count to 0, for example after a start that succeeded. `cancel()` stops the retry that waits. The abort of `signal` cancels the retrier, for example the `signal` of the lifecycle in the drain.
|
|
331
|
+
- **One call with retries.** `retry(run, { tries, retryable, delayOf, ...backoff })` starts an async `run`, and starts it again after an error. It stops at `tries` tries, the first included.
|
|
332
|
+
- **The errors of a retry.** `retryable(error)` tells which errors get a new try. After the last try, `retry` throws the last error. The abort of `signal` stops the wait.
|
|
333
|
+
- **Retry-After.** `delayOf(error, attempt)` gives a delay in place of the backoff. `retryAfterDelay(header, now)` reads the seconds or the HTTP date of a `Retry-After` header.
|
|
331
334
|
- **Milliseconds.** These functions take times in milliseconds, as the clock does. The declaration and the law keep their amounts (`Quantity`).
|
|
332
335
|
|
|
333
336
|
```ts
|
|
334
|
-
import { retrier } from "@mark1russell7/service";
|
|
337
|
+
import { retrier, retry, retryAfterDelay } from "@mark1russell7/service";
|
|
335
338
|
import { backoffDelay } from "@mark1russell7/service/backoff";
|
|
336
339
|
import { heartbeat } from "@mark1russell7/service/heartbeat";
|
|
337
340
|
|
|
@@ -357,6 +360,28 @@ const watch = (): void => {
|
|
|
357
360
|
() => rewatch.schedule(watch),
|
|
358
361
|
);
|
|
359
362
|
};
|
|
363
|
+
|
|
364
|
+
// one read with 4 tries at most: a 429 or a 5xx gets a new try, and a 429 waits for its Retry-After
|
|
365
|
+
class Busy extends Error {
|
|
366
|
+
constructor(readonly response: Response) {
|
|
367
|
+
super(`HTTP ${response.status}`);
|
|
368
|
+
}
|
|
369
|
+
}
|
|
370
|
+
const response = await retry(
|
|
371
|
+
async () => {
|
|
372
|
+
const res = await fetch(url);
|
|
373
|
+
if (res.status === 429 || res.status >= 500) throw new Busy(res);
|
|
374
|
+
return res;
|
|
375
|
+
},
|
|
376
|
+
{
|
|
377
|
+
tries: 4,
|
|
378
|
+
base: 1000,
|
|
379
|
+
factor: 2,
|
|
380
|
+
cap: 15_000,
|
|
381
|
+
jitter: { kind: "subtract", fraction: 1 },
|
|
382
|
+
delayOf: (error) => (error instanceof Busy ? retryAfterDelay(error.response.headers.get("retry-after"), Date.now()) : null),
|
|
383
|
+
},
|
|
384
|
+
);
|
|
360
385
|
```
|
|
361
386
|
|
|
362
387
|
## The keyed limiter
|
|
@@ -632,7 +657,7 @@ console.log(outcome.kind);
|
|
|
632
657
|
- `quietServer()` starts a TCP echo server that can go quiet. Its connections stay open while it is quiet, as with a frozen peer.
|
|
633
658
|
- `detachedLifecycle()` gives a lifecycle with no service, for the start of a transport in a test.
|
|
634
659
|
- `fakeHost(options)` gives the ports of the host entry on a fake clock, a fake file system and fake processes. It records each command and each signal. A test ends a child with `exit(code)`, and `polite` makes each child obey a staged stop.
|
|
635
|
-
- `transportConformance(make, options)` generates the conformance test of a transport. `make` gives a subject: the transport, a way to offer new work and a way to hold work in flight. The cases check that `stopIntake` refuses new work, and that the count is correct and comes from events. They also check that `drain` holds to its deadline and gives the cooperative abort, and that `close` is idempotent and bounded. The fake clock makes the cases fast, and the real clock measures them.
|
|
660
|
+
- `transportConformance(make, options)` generates the conformance test of a transport. `make` gives a subject: the transport, a way to offer new work and a way to hold work in flight. The cases check that `stopIntake` refuses new work, and that the count is correct and comes from events. They also check that `drain` holds to its deadline and gives the cooperative abort, and that `close` is idempotent and bounded. The fake clock makes the cases fast, and the real clock measures them. The option `streams` adds six cases of the streams (S6 D4). Then the subject also gives `call`, which sends the work of the kit through `life.request`. A unary call gives one value and its status. A stream stays in flight until its end, and a failure after its first item is an error line, not a status. The drain waits for an open stream, and its cooperative abort and its cut end the stream with an end that the caller gets.
|
|
636
661
|
- `contractCases(declare)` generates the contract test of a declaration. The cases are the service at rest, each dependency unavailable, each dependency degraded by 100 ms, each recovery, and a negative control. A dependency that no check exercises is a finding, and so is a check whose timeout a latency of 100 ms fails.
|
|
637
662
|
|
|
638
663
|
## The Redis client
|
|
@@ -893,7 +918,7 @@ for await (const event of stream) {
|
|
|
893
918
|
- **The idle close of a slow answer (SYS-33).** A client that does not read gets each byte of a body of 64 MB. The stop of the intake and a sweep after it come before the client reads. These tests use real sockets of the loopback, but not on Windows.
|
|
894
919
|
- **The headers of the outcomes.** Each path of the request tracker gets its status. Each 503 gets `Retry-After`: the refusals, the retryable cut and the cut of a unary stream. No 500 gets it.
|
|
895
920
|
- **The headers on the port.** The transport adds `Retry-After` to each 503 of a probe and of a handler that writes its own status, in each form of `writeHead`. It takes `Retry-After` from each 500. The probe server gives its 503s the time of its knob.
|
|
896
|
-
- **The conformance of a transport.** A reference transport passes each case, and each of
|
|
921
|
+
- **The conformance of a transport.** A reference transport passes each case, and each of 14 mutations of it fails the case of its part. Five of the mutations break a stream. The HTTP transport passes each case on a fake server, for its requests and its upgrades, and for the streams of its requests.
|
|
897
922
|
- **The worker loop.** These tests use the fake clock. They cover the sleep, `"more"`, the backoff and its jitter, `wake()`, the stop of the intake and the drain with its cooperative abort. They also cover the bound of an iteration, the lanes, the setup, the teardown, the close bound and the law (O20).
|
|
898
923
|
- **The queue drain.** These tests cover the slots, the poll, the policy of A11 and the count of deliveries. They also cover a job that goes back at the stop, an async iterable and a failed take. A cut job of each kind of route, the close bound and the refusals of the service have tests too.
|
|
899
924
|
- **The conformance of the helpers.** The worker loop passes each case of the kit with three lanes, and the queue drain with three slots. Each one passes with the request tracking and without it. With one lane, the loop passes each case that holds one work.
|
package/build/grpc.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { realClock } from "./clock.js";
|
|
2
2
|
import { i as heartbeatDetection } from "./timing-DGRi3XCI.js";
|
|
3
|
-
import { B as zeroProblems, C as notSent, D as readyWait, F as timeProblems, G as immediate, H as NEVER, L as wholeProblems, M as sendWithReissue, N as socketEnds, P as stepChecks, R as withinBound, S as ms, U as WHAT, V as MANIFESTATIONS, W as firstDetector, X as unwatched, Y as kernelGiveUp, _ as inFlight, a as helloDial, b as message, c as ageProblems, d as clientProblems, f as clientRecorder, g as idleCloseProblem, h as finiteMs, i as authority, j as roundTripCheck, k as retryProblems, l as attachClient, m as dialCheck, n as closeTimer, r as transition, s as STARTING_POLL, t as clientKnob, u as clientBounds, w as operationTable, y as localStateCheck, z as wrapperTimerProblems } from "./machine-
|
|
3
|
+
import { B as zeroProblems, C as notSent, D as readyWait, F as timeProblems, G as immediate, H as NEVER, L as wholeProblems, M as sendWithReissue, N as socketEnds, P as stepChecks, R as withinBound, S as ms, U as WHAT, V as MANIFESTATIONS, W as firstDetector, X as unwatched, Y as kernelGiveUp, _ as inFlight, a as helloDial, b as message, c as ageProblems, d as clientProblems, f as clientRecorder, g as idleCloseProblem, h as finiteMs, i as authority, j as roundTripCheck, k as retryProblems, l as attachClient, m as dialCheck, n as closeTimer, r as transition, s as STARTING_POLL, t as clientKnob, u as clientBounds, w as operationTable, y as localStateCheck, z as wrapperTimerProblems } from "./machine-p4lENJ86.js";
|
|
4
4
|
//#region src/grpc/connection.ts
|
|
5
5
|
/** These states are in the sequence of the enum of grpc-js: the index of a state is its value. */
|
|
6
6
|
const GRPC_STATES = [
|
package/build/host.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { realClock } from "./clock.js";
|
|
2
2
|
import { s as isMessageShape } from "./process-DG_im2zc.js";
|
|
3
3
|
import { backoffProblems } from "./backoff.js";
|
|
4
|
-
import { t as retrier } from "./retrier-
|
|
4
|
+
import { t as retrier } from "./retrier-Nt6r4r6R.js";
|
|
5
5
|
import { convertible, isQuantity, valueIn } from "@mark1russell7/quantity";
|
|
6
6
|
import { connect } from "node:net";
|
|
7
7
|
import { execFile, spawn } from "node:child_process";
|
package/build/http-client.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { realClock } from "./clock.js";
|
|
2
2
|
import { heartbeat } from "./heartbeat.js";
|
|
3
|
-
import { B as zeroProblems, C as notSent, E as poolProblems, F as timeProblems, G as immediate, I as trackWithTimer, J as keepaliveSilent, K as keepaliveAnswered, L as wholeProblems, M as sendWithReissue, N as socketEnds, P as stepChecks, R as withinBound, S as ms, U as WHAT, V as MANIFESTATIONS, W as firstDetector, X as unwatched, Y as kernelGiveUp, _ as inFlight, a as helloDial, b as message, c as ageProblems, d as clientProblems, f as clientRecorder, g as idleCloseProblem, i as authority, j as roundTripCheck, l as attachClient, m as dialCheck, n as closeTimer, o as statusLineJudge, q as keepaliveReset, r as transition, s as STARTING_POLL, t as clientKnob, u as clientBounds, v as keepaliveOnProblems, w as operationTable, y as localStateCheck, z as wrapperTimerProblems } from "./machine-
|
|
3
|
+
import { B as zeroProblems, C as notSent, E as poolProblems, F as timeProblems, G as immediate, I as trackWithTimer, J as keepaliveSilent, K as keepaliveAnswered, L as wholeProblems, M as sendWithReissue, N as socketEnds, P as stepChecks, R as withinBound, S as ms, U as WHAT, V as MANIFESTATIONS, W as firstDetector, X as unwatched, Y as kernelGiveUp, _ as inFlight, a as helloDial, b as message, c as ageProblems, d as clientProblems, f as clientRecorder, g as idleCloseProblem, i as authority, j as roundTripCheck, l as attachClient, m as dialCheck, n as closeTimer, o as statusLineJudge, q as keepaliveReset, r as transition, s as STARTING_POLL, t as clientKnob, u as clientBounds, v as keepaliveOnProblems, w as operationTable, y as localStateCheck, z as wrapperTimerProblems } from "./machine-p4lENJ86.js";
|
|
4
4
|
import { quantity } from "@mark1russell7/quantity";
|
|
5
5
|
//#region src/http-client/connection.ts
|
|
6
6
|
/**
|
package/build/index.d.ts
CHANGED
|
@@ -249,6 +249,31 @@ interface Retrier {
|
|
|
249
249
|
* with a problem of `backoffProblems`.
|
|
250
250
|
*/
|
|
251
251
|
export declare const retrier: (options: RetrierOptions) => Retrier;
|
|
252
|
+
/** These options make one call with retries: the most tries, the errors to retry, and the policy of a retrier. */
|
|
253
|
+
interface RetryOptions extends RetrierOptions {
|
|
254
|
+
/** This number is the most tries of the call, the first try included. It is 1 or more. */
|
|
255
|
+
readonly tries: number;
|
|
256
|
+
/** This function tells if a try starts again after this error. The default retries each error. */
|
|
257
|
+
readonly retryable?: ((error: unknown) => boolean) | undefined;
|
|
258
|
+
/**
|
|
259
|
+
* This function gives the delay in milliseconds before the next try, in place of the backoff. An example
|
|
260
|
+
* is the `Retry-After` header of an HTTP 429. Null, undefined, NaN, an infinite or a negative number keeps
|
|
261
|
+
* the backoff delay. The retry puts no cap on this delay, so the caller caps it, for example at 60 s.
|
|
262
|
+
*/
|
|
263
|
+
readonly delayOf?: ((error: unknown, attempt: number) => number | null | undefined) | undefined;
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* This function gives the wait of a `Retry-After` header (RFC 9110) in milliseconds: a count of seconds,
|
|
267
|
+
* or an HTTP date after `now`. It gives null for a header with no valid value. A date before `now` gives 0.
|
|
268
|
+
*/
|
|
269
|
+
export declare const retryAfterDelay: (header: string | null | undefined, now: number) => number | null;
|
|
270
|
+
/**
|
|
271
|
+
* This function starts `run`, and starts it again after an error, to the count of `tries`. The delay
|
|
272
|
+
* before try n + 1 is `delayOf(error, n)`, else the `backoffDelay` of try n, on the clock. The call gives
|
|
273
|
+
* the value of the first try that succeeds. After the last try, an error that is not retryable, or the
|
|
274
|
+
* abort of the signal, it throws the last error. It refuses a policy with a problem of `backoffProblems`.
|
|
275
|
+
*/
|
|
276
|
+
export declare const retry: <T>(run: (attempt: number) => Promise<T>, options: RetryOptions) => Promise<T>;
|
|
252
277
|
//#endregion
|
|
253
278
|
//#region src/worker.d.ts
|
|
254
279
|
/**
|
|
@@ -379,5 +404,5 @@ export declare const drainMachine: (description: ServiceDescription) => Machine;
|
|
|
379
404
|
/** These are the static machines of the runtime, by the name that their events carry. */
|
|
380
405
|
export declare const MACHINES: Readonly<Record<Exclude<MachineName, "drain" | "client">, Machine>>;
|
|
381
406
|
//#endregion
|
|
382
|
-
export { type Allowed, type Backoff, type Binding, type Bound, type Cancel, type Change, type Check, type CheckFn, type CheckMetrics, type CheckVerdict, type Claim, type Clock, type Compressed, type Compression, type ConsoleLoggerOptions, type ConsoleTarget, type Controller, type ControllerBuilder, type CooperativeFloor, type Coupling, DRAIN_RULES, DURATION_FRACTIONS, type Decision, type DelayBand, type Dependency, type DependencyHandle, type DurationHistogram, EPISODES_KEPT, EXIT_SIGNALS, type EmbeddedProcess, type Episode, type Epochs, type Evaluated, type ExitCodes, type ExitSignal, type ExitTrigger, FORMAT, type FailsBy, type Finding, type Gate, type Health, type HealthMetrics, type HealthServer, type HealthVerdict, type Heartbeat, type HeartbeatOptions, type HostStream, type Idempotency, type Inequality, type IterationContext, type Jitter, type JobAction, type JobContext, type JobFailure, type JobSettle, type JobSource, type KeyState, type KeyedLimiter, LOG_LEVELS, type Lifecycle, type LifecycleEvent, type LifecycleState, type LimitPolicy, type LimitRule, type Limiter, type LimiterEviction, type LimiterSpec, type LimiterState, type LimiterStore, type LimiterStoreSpec, type LocalLimiter, type LogEntry, type LogFields, type LogFormat, type LogLevel, type Logger, type MachineName, type MemoryStore, type MessageShape, type MessageTrigger, O04, O09, O10, O16, type Operation, type OperationOf, type Outcome, PROCESS_TRIGGERS, type Phase, type PhaseContext, type PhaseWork, type PlatformClockOptions, type PodTiming, type Poll, type ProbeAnswer, type ProbeKind, type ProcessHost, type ProcessPort, type ProcessTrigger, type Profile, type ProgressMarks, type QueueDrain, type QueueDrainOptions, type QueueKnobs, type Recorder, type RedeliveryPolicy, type RefusalCause, type Refused, type RepeatSignal, type RequestEnd, type RequestEvent, type RequestFn, type RequestOptions, type RequestStream, type RequestWork, type RequeueCause, type Result, type Retrier, type RetrierOptions, type RoutePattern, type RouteRequest, type Rule, type RunOptions, SLIDING_WINDOW_MACHINE, STAGES, type Scenario, type ScenarioValue, type ScopedChange, type ServiceBuilder, type ServiceDescription, type ShutdownOptions, type Side, type SlidingWindow, type Span, type Stage, type StartOptions, type Statistic, type Step, type Stop, type StopWay, type StoreFailure, TOKEN_BUCKET_MACHINE, type TakeRequest, type TakeStep, type Term, type TimerMark, type TimerMarks, type Timing, type TokenBucket, type Transport, type TransportImpl, UNCAUGHT_ORIGINS, type UncaughtOptions, type UncaughtOrigin, type UnitRequest, type Verdict, type Watchdog, type WatchdogSpec, type WorkerKnobs, type WorkerLoop, type WorkerLoopOptions, asDebounce, asWindow, atLeast, backoffBand, backoffDelay, backoffProblems, compress, compression, consoleLogger, cooperativeAbortAt, daemon, decide, detectionTime, embeddedProcess, ephemeral, evaluate, failSpan, freeAt, heartbeat, heartbeatDetection, idleSpan, inequalities, isExitCode, isExitSignal, isMessageShape, keyedLimiter, kubernetes, limitRule, limiterMachine, limiterProblems, limiterStateOf, localDev, logEvents, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redact, redeliverOnce, replay, retryAfterSeconds, service, stageRank, symbolsOf, verdictOf, watchdog };
|
|
407
|
+
export { type Allowed, type Backoff, type Binding, type Bound, type Cancel, type Change, type Check, type CheckFn, type CheckMetrics, type CheckVerdict, type Claim, type Clock, type Compressed, type Compression, type ConsoleLoggerOptions, type ConsoleTarget, type Controller, type ControllerBuilder, type CooperativeFloor, type Coupling, DRAIN_RULES, DURATION_FRACTIONS, type Decision, type DelayBand, type Dependency, type DependencyHandle, type DurationHistogram, EPISODES_KEPT, EXIT_SIGNALS, type EmbeddedProcess, type Episode, type Epochs, type Evaluated, type ExitCodes, type ExitSignal, type ExitTrigger, FORMAT, type FailsBy, type Finding, type Gate, type Health, type HealthMetrics, type HealthServer, type HealthVerdict, type Heartbeat, type HeartbeatOptions, type HostStream, type Idempotency, type Inequality, type IterationContext, type Jitter, type JobAction, type JobContext, type JobFailure, type JobSettle, type JobSource, type KeyState, type KeyedLimiter, LOG_LEVELS, type Lifecycle, type LifecycleEvent, type LifecycleState, type LimitPolicy, type LimitRule, type Limiter, type LimiterEviction, type LimiterSpec, type LimiterState, type LimiterStore, type LimiterStoreSpec, type LocalLimiter, type LogEntry, type LogFields, type LogFormat, type LogLevel, type Logger, type MachineName, type MemoryStore, type MessageShape, type MessageTrigger, O04, O09, O10, O16, type Operation, type OperationOf, type Outcome, PROCESS_TRIGGERS, type Phase, type PhaseContext, type PhaseWork, type PlatformClockOptions, type PodTiming, type Poll, type ProbeAnswer, type ProbeKind, type ProcessHost, type ProcessPort, type ProcessTrigger, type Profile, type ProgressMarks, type QueueDrain, type QueueDrainOptions, type QueueKnobs, type Recorder, type RedeliveryPolicy, type RefusalCause, type Refused, type RepeatSignal, type RequestEnd, type RequestEvent, type RequestFn, type RequestOptions, type RequestStream, type RequestWork, type RequeueCause, type Result, type Retrier, type RetrierOptions, type RetryOptions, type RoutePattern, type RouteRequest, type Rule, type RunOptions, SLIDING_WINDOW_MACHINE, STAGES, type Scenario, type ScenarioValue, type ScopedChange, type ServiceBuilder, type ServiceDescription, type ShutdownOptions, type Side, type SlidingWindow, type Span, type Stage, type StartOptions, type Statistic, type Step, type Stop, type StopWay, type StoreFailure, TOKEN_BUCKET_MACHINE, type TakeRequest, type TakeStep, type Term, type TimerMark, type TimerMarks, type Timing, type TokenBucket, type Transport, type TransportImpl, UNCAUGHT_ORIGINS, type UncaughtOptions, type UncaughtOrigin, type UnitRequest, type Verdict, type Watchdog, type WatchdogSpec, type WorkerKnobs, type WorkerLoop, type WorkerLoopOptions, asDebounce, asWindow, atLeast, backoffBand, backoffDelay, backoffProblems, compress, compression, consoleLogger, cooperativeAbortAt, daemon, decide, detectionTime, embeddedProcess, ephemeral, evaluate, failSpan, freeAt, heartbeat, heartbeatDetection, idleSpan, inequalities, isExitCode, isExitSignal, isMessageShape, keyedLimiter, kubernetes, limitRule, limiterMachine, limiterProblems, limiterStateOf, localDev, logEvents, longestRetryAfter, matchesMessage, mayReissue, memoryStore, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redact, redeliverOnce, replay, retryAfterSeconds, service, stageRank, symbolsOf, verdictOf, watchdog };
|
|
383
408
|
//# sourceMappingURL=index.d.ts.map
|