Files
tech-log-frontend/src/application/policies/bounded-polling.ts
T

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
);
}