160 lines
4.3 KiB
TypeScript
160 lines
4.3 KiB
TypeScript
export const BOUNDED_POLLING_CEILINGS = Object.freeze({
|
|
minimumIntervalMs: 5_000,
|
|
maxIntervalMs: 60_000,
|
|
maxAttempts: 120,
|
|
maxElapsedMs: 30 * 60 * 1_000,
|
|
maxResponseBytes: 8 * 1_024 * 1_024,
|
|
maxTerminalStates: 32,
|
|
});
|
|
|
|
export type PollFallbackReason =
|
|
| "CONVERGENCE"
|
|
| "RELAXED_FRESHNESS"
|
|
| "STREAM_DEGRADED"
|
|
| "STREAM_UNAVAILABLE";
|
|
|
|
export type PollLeasePolicy = Readonly<{
|
|
operationId: string;
|
|
owner: string;
|
|
minimumIntervalMs: number;
|
|
successIntervalMs: number;
|
|
maxIntervalMs: number;
|
|
maxAttempts: number;
|
|
maxElapsedMs: number;
|
|
maxResponseBytes: number;
|
|
visibility: "VISIBLE_ONLY";
|
|
fallbackReason: PollFallbackReason;
|
|
terminalStates: readonly string[];
|
|
}>;
|
|
|
|
/**
|
|
* The HTTP executor used by a poll lease must represent exactly one physical
|
|
* request. Transport retry, credential replay and cumulative retry sleep stay
|
|
* disabled so a poll attempt cannot hide additional requests.
|
|
*/
|
|
export type BoundedPollOperationContract = Readonly<{
|
|
operationId: string;
|
|
contractVersion: 2;
|
|
protocol: "REST";
|
|
semantics: "QUERY";
|
|
method: "GET" | "HEAD";
|
|
replayPolicy: "SAFE" | "IDEMPOTENT";
|
|
retry: "never";
|
|
maxResponseBytes: number;
|
|
transportMaxAttempts: 1;
|
|
authRecoveryCount: 0;
|
|
maxCumulativeSleepMs: 0;
|
|
serverStream: false;
|
|
}>;
|
|
|
|
const OPERATION_ID = /^[A-Z][A-Z0-9_]{2,79}$/u;
|
|
const OWNER_ID = /^[A-Za-z][A-Za-z0-9._:-]{0,127}$/u;
|
|
const TERMINAL_STATE = /^[A-Z][A-Z0-9_]{0,63}$/u;
|
|
|
|
export function definePollLeasePolicy(
|
|
input: PollLeasePolicy,
|
|
): PollLeasePolicy {
|
|
if (
|
|
!input ||
|
|
typeof input !== "object" ||
|
|
!OPERATION_ID.test(input.operationId) ||
|
|
!OWNER_ID.test(input.owner) ||
|
|
input.visibility !== "VISIBLE_ONLY" ||
|
|
![
|
|
"CONVERGENCE",
|
|
"RELAXED_FRESHNESS",
|
|
"STREAM_DEGRADED",
|
|
"STREAM_UNAVAILABLE",
|
|
].includes(input.fallbackReason) ||
|
|
!isIntegerWithin(
|
|
input.minimumIntervalMs,
|
|
BOUNDED_POLLING_CEILINGS.minimumIntervalMs,
|
|
BOUNDED_POLLING_CEILINGS.maxIntervalMs,
|
|
) ||
|
|
!isIntegerWithin(
|
|
input.successIntervalMs,
|
|
input.minimumIntervalMs,
|
|
BOUNDED_POLLING_CEILINGS.maxIntervalMs,
|
|
) ||
|
|
!isIntegerWithin(
|
|
input.maxIntervalMs,
|
|
input.successIntervalMs,
|
|
BOUNDED_POLLING_CEILINGS.maxIntervalMs,
|
|
) ||
|
|
!isIntegerWithin(
|
|
input.maxAttempts,
|
|
1,
|
|
BOUNDED_POLLING_CEILINGS.maxAttempts,
|
|
) ||
|
|
!isIntegerWithin(
|
|
input.maxElapsedMs,
|
|
input.minimumIntervalMs,
|
|
BOUNDED_POLLING_CEILINGS.maxElapsedMs,
|
|
) ||
|
|
!isIntegerWithin(
|
|
input.maxResponseBytes,
|
|
1,
|
|
BOUNDED_POLLING_CEILINGS.maxResponseBytes,
|
|
) ||
|
|
!Array.isArray(input.terminalStates) ||
|
|
input.terminalStates.length >
|
|
BOUNDED_POLLING_CEILINGS.maxTerminalStates ||
|
|
input.terminalStates.some(
|
|
(state) =>
|
|
typeof state !== "string" || !TERMINAL_STATE.test(state),
|
|
) ||
|
|
new Set(input.terminalStates).size !== input.terminalStates.length ||
|
|
(input.fallbackReason === "CONVERGENCE" &&
|
|
input.terminalStates.length === 0)
|
|
) {
|
|
throw new TypeError("Invalid bounded polling lease policy.");
|
|
}
|
|
|
|
return Object.freeze({
|
|
...input,
|
|
terminalStates: Object.freeze([...input.terminalStates]),
|
|
});
|
|
}
|
|
|
|
export function assertBoundedPollOperation(
|
|
policy: PollLeasePolicy,
|
|
operation: BoundedPollOperationContract,
|
|
): void {
|
|
if (
|
|
!operation ||
|
|
typeof operation !== "object" ||
|
|
operation.operationId !== policy.operationId ||
|
|
operation.contractVersion !== 2 ||
|
|
operation.protocol !== "REST" ||
|
|
operation.semantics !== "QUERY" ||
|
|
!["GET", "HEAD"].includes(operation.method) ||
|
|
!["SAFE", "IDEMPOTENT"].includes(operation.replayPolicy) ||
|
|
operation.retry !== "never" ||
|
|
operation.serverStream !== false ||
|
|
operation.transportMaxAttempts !== 1 ||
|
|
operation.authRecoveryCount !== 0 ||
|
|
operation.maxCumulativeSleepMs !== 0 ||
|
|
!isIntegerWithin(
|
|
operation.maxResponseBytes,
|
|
1,
|
|
BOUNDED_POLLING_CEILINGS.maxResponseBytes,
|
|
)
|
|
) {
|
|
throw new TypeError(
|
|
"Bounded polling operation must be one terminal replay-safe REST request.",
|
|
);
|
|
}
|
|
}
|
|
|
|
function isIntegerWithin(
|
|
value: number,
|
|
minimum: number,
|
|
maximum: number,
|
|
): boolean {
|
|
return (
|
|
Number.isSafeInteger(value) &&
|
|
value >= minimum &&
|
|
value <= maximum
|
|
);
|
|
}
|