@serve.zone/interfaces 32.56.0 → 32.58.0

package/ts/data/runtimesessionrefusal.ts

@@ -0,0 +1,153 @@
+import { readExactDataRecord } from '../private/dataproperties.js';
+
+/**
+ * The refusal a controller states when it does not take a node's runtime session request.
+ *
+ * It travels as `TypedResponseError.errorData` on `registerPalletRuntimeSession` and on every
+ * session-scoped read and report a node sends its controller. `code` is a frozen wire value.
+ * `momentaryReasons` are the controller's own momentary state, not a judgement of the node: a
+ * registering node waits and offers the same registration again, keeping everything it runs.
+ * Every other reason, and an error that carries no such payload, is a verdict — on a registration
+ * it ends the node's session. Momentary against verdict governs only whether a node defers a
+ * registration: a node retries its session reads and reports regardless of the reason, so the
+ * reasons a report is refused with (`state-conflict`, `*-write-conflict`, a capacity limit such as
+ * `log-intake-saturated`) are unchanged by this contract.
+ *
+ * Who states which reason today, on a registration (Cloudly ≥33.19.1, `isBudgetRefusal`):
+ * - Cloudly states `controller-deadline` when the request ran out of
+ *   `runtimeSessionRequestBounds.controllerBudgetMs`, and `controller-unavailable` when it is
+ *   stopping. Every other failure, a transient one of its own included, is answered without a
+ *   payload and so reads as a verdict.
+ * - No relay states a refusal of its own yet.
+ *
+ * The rule producers adopt:
+ * - Cloudly states `controller-unavailable` on a registration for every transient failure of its
+ *   own: its database connection lost or unavailable, a registration write conflict, a race with a
+ *   credential being applied.
+ * - A relay states only `controller-unavailable`, and only when it cannot carry the request or its
+ *   answer: no Cloudly link, or its own bound (`runtimeSessionRequestBounds`) ran out. Every
+ *   answer Cloudly gave it forwards untouched; it never states a verdict or `controller-deadline`.
+ * - A verdict names the check that refused: a revoked or inactive credential, a deleted, retiring
+ *   or foreign node, an invalid body. It never carries a momentary reason.
+ *
+ * The payload is exactly `{ code, reason }`. Pallet 36.3.14 reads the two members and tolerates
+ * others, but every reader built on `readRuntimeSessionRefusal` refuses a payload with any other
+ * member, and a refused payload reads as no refusal — a momentary refusal would turn into a
+ * verdict. A producer therefore never adds a member without gating it on the peer's spoken
+ * interfaces version.
+ */
+export const runtimeSessionRefusalContract = Object.freeze({
+  code: 'runtime-session-report-refused',
+  momentaryReasons: Object.freeze(['controller-deadline', 'controller-unavailable'] as const),
+  /**
+   * A reason is one or more words of lowercase ASCII letters joined by single hyphens, at most
+   * this many characters. It names a check, never a value: no digit, case, dot, colon or other
+   * separator can carry an identifier, address, digest, count or credential across.
+   */
+  maximumReasonLength: 64,
+} as const);
+
+export type TRuntimeSessionMomentaryRefusalReason =
+  typeof runtimeSessionRefusalContract.momentaryReasons[number];
+
+/**
+ * `TypedResponseError.errorData` of a refused runtime session request. `reason` is a word naming
+ * the check that refused (see `runtimeSessionRefusalContract`), never a value.
+ */
+export interface IRuntimeSessionRefusal {
+  code: typeof runtimeSessionRefusalContract.code;
+  reason: string;
+}
+
+const isRefusalReason = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string'
+  && valueArg.length <= runtimeSessionRefusalContract.maximumReasonLength
+  && /^[a-z]+(?:-[a-z]+)*$/.test(valueArg)
+);
+
+const reasonRule = 'must be lowercase letter words joined by single hyphens, at most '
+  + `${runtimeSessionRefusalContract.maximumReasonLength} characters`;
+
+/** Validates one runtime session refusal and names every reason it is refused. */
+export const validateRuntimeSessionRefusal = (
+  valueArg: unknown,
+  pathArg = 'runtime session refusal',
+): string[] => {
+  const refusal = readExactDataRecord(valueArg, ['code', 'reason']);
+  if (refusal === null) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  if (refusal.code !== runtimeSessionRefusalContract.code) {
+    errors.push(`${pathArg} code must be ${runtimeSessionRefusalContract.code}`);
+  }
+  if (!isRefusalReason(refusal.reason)) {
+    errors.push(`${pathArg} reason ${reasonRule}`);
+  }
+  return errors;
+};
+
+/** The payload a controller or relay answers a refused request with; throws on a non-word reason. */
+export const buildRuntimeSessionRefusal = (reasonArg: string): IRuntimeSessionRefusal => {
+  if (!isRefusalReason(reasonArg)) {
+    throw new Error(`runtime session refusal reason ${reasonRule}`);
+  }
+  return Object.freeze({ code: runtimeSessionRefusalContract.code, reason: reasonArg });
+};
+
+/**
+ * The refusal inside an error payload, or `null` when the value is not exactly one.
+ *
+ * It reads a value that survived serialization, the way `protocol.readProtocolRefusal` does: own
+ * data properties only, exactly `code` and `reason`, nothing that runs.
+ */
+export const readRuntimeSessionRefusal = (valueArg: unknown): IRuntimeSessionRefusal | null => {
+  const refusal = readExactDataRecord(valueArg, ['code', 'reason']);
+  if (refusal === null || validateRuntimeSessionRefusal(refusal).length > 0) {
+    return null;
+  }
+  return Object.freeze({ code: runtimeSessionRefusalContract.code, reason: refusal.reason as string });
+};
+
+/**
+ * The momentary reason an error payload states, or `null` when it is a verdict: any other reason,
+ * a payload that is not exactly a refusal, or no payload at all.
+ */
+export const readMomentaryRuntimeSessionRefusal = (
+  valueArg: unknown,
+): TRuntimeSessionMomentaryRefusalReason | null => {
+  const refusal = readRuntimeSessionRefusal(valueArg);
+  if (refusal === null) {
+    return null;
+  }
+  const momentary = runtimeSessionRefusalContract.momentaryReasons
+    .find((reasonArg) => reasonArg === refusal.reason);
+  return momentary ?? null;
+};
+
+/**
+ * How long each hop may hold a node's runtime session request, so the hop nearest the decision
+ * answers first and the node always reads a stated refusal rather than its own timeout.
+ */
+export const runtimeSessionRequestBounds = Object.freeze({
+  /**
+   * Cloudly's budget for every node request, registration included. When it runs out Cloudly
+   * answers `controller-deadline`.
+   */
+  controllerBudgetMs: 6_000,
+  /**
+   * A relay's bound on a registration, from its arrival at the relay to the answer, including any
+   * wait for the relay's own Cloudly link. It exceeds `controllerBudgetMs` by more than a second so
+   * Cloudly's own `controller-deadline` reaches the node through the relay, and stays below
+   * TypedSocket's 10 s connection-restore deadline (`TYPEDSOCKET_MAX_CONNECTION_RESTORE_TIMEOUT_MS`,
+   * which a client can only lower) so the node reads an answer before its restore hook times out.
+   * When it runs out the relay answers `controller-unavailable`.
+   */
+  relayRegistrationBudgetMs: 9_000,
+  /**
+   * A relay's bound on forwarding a session read or report over its established Cloudly link.
+   * It exceeds `controllerBudgetMs` so Cloudly's answer arrives first; when it runs out the relay
+   * answers `controller-unavailable`.
+   */
+  relaySessionForwardMs: 8_000,
+} as const);