@astrale-os/kernel-protocol 0.5.0-beta.61 → 0.5.0-beta.62

package/dist/errors/index.d.ts

@@ -3,3 +3,4 @@ export { httpStatusOf } from './http-status.js';
 export { acceptPayload, type ErrorPayload } from './payload.js';
 export { ProtocolError } from './protocol-error.js';
 export { acceptReason, reasonOf, type ErrorReason } from './reason.js';
+export { MAXIMUM_RETRY_AFTER_MS, RETRY_REASONS, retryAfterField, retryAfterOf, retryReason, type RetryReason, type RetryReasonCode, } from './retry.js';

package/dist/errors/index.js

@@ -3,3 +3,4 @@ export { httpStatusOf } from './http-status.js';
 export { acceptPayload } from './payload.js';
 export { ProtocolError } from './protocol-error.js';
 export { acceptReason, reasonOf } from './reason.js';
+export { MAXIMUM_RETRY_AFTER_MS, RETRY_REASONS, retryAfterField, retryAfterOf, retryReason, } from './retry.js';

package/dist/errors/retry.d.ts

@@ -0,0 +1,23 @@
+import type { ErrorPayload } from './payload.js';
+import type { ErrorReason } from './reason.js';
+/**
+ * Reasons for a request refused before any work was admitted. The same request may be sent again
+ * once `retryAfterMs` has elapsed; every other public error keeps its own retry meaning.
+ */
+export declare const RETRY_REASONS: Readonly<{
+    /** A bounded Kernel resource is exhausted. */
+    readonly CAPACITY_EXHAUSTED: 'CAPACITY_EXHAUSTED';
+    /** The server stopped admitting work before it shuts down. */
+    readonly SERVER_DRAINING: 'SERVER_DRAINING';
+}>;
+export type RetryReasonCode = (typeof RETRY_REASONS)[keyof typeof RETRY_REASONS];
+export type RetryReason<Code extends RetryReasonCode = RetryReasonCode> = ErrorReason<Code, {
+    readonly retryAfterMs: number;
+}>;
+/** One hour bounds a hint that only schedules the next attempt. */
+export declare const MAXIMUM_RETRY_AFTER_MS = 3600000;
+export declare function retryReason<Code extends RetryReasonCode>(code: Code, retryAfterMs: number): RetryReason<Code>;
+/** Return the retry delay of a back-pressure or draining refusal, and nothing for other errors. */
+export declare function retryAfterOf(error: ErrorPayload): number | undefined;
+/** Present a retry delay as an HTTP `Retry-After` delta in whole seconds, rounded up. */
+export declare function retryAfterField(retryAfterMs: number): string;

package/dist/errors/retry.js

@@ -0,0 +1,44 @@
+import { CODES } from './codes.js';
+import { reasonOf } from './reason.js';
+/**
+ * Reasons for a request refused before any work was admitted. The same request may be sent again
+ * once `retryAfterMs` has elapsed; every other public error keeps its own retry meaning.
+ */
+export const RETRY_REASONS = Object.freeze({
+    /** A bounded Kernel resource is exhausted. */
+    CAPACITY_EXHAUSTED: 'CAPACITY_EXHAUSTED',
+    /** The server stopped admitting work before it shuts down. */
+    SERVER_DRAINING: 'SERVER_DRAINING',
+});
+/** One hour bounds a hint that only schedules the next attempt. */
+export const MAXIMUM_RETRY_AFTER_MS = 3_600_000;
+const CODES_SET = new Set(Object.values(RETRY_REASONS));
+export function retryReason(code, retryAfterMs) {
+    if (!CODES_SET.has(code))
+        throw new TypeError('Retry reason code is invalid.');
+    if (!isRetryAfter(retryAfterMs))
+        throw new TypeError('Retry reason retryAfterMs is invalid.');
+    return Object.freeze({ code, details: Object.freeze({ retryAfterMs }) });
+}
+/** Return the retry delay of a back-pressure or draining refusal, and nothing for other errors. */
+export function retryAfterOf(error) {
+    if (error.code !== CODES.BACKEND_UNAVAILABLE)
+        return undefined;
+    const reason = reasonOf(error.data);
+    if (reason === undefined || !CODES_SET.has(reason.code))
+        return undefined;
+    const retryAfterMs = reason.details.retryAfterMs;
+    return isRetryAfter(retryAfterMs) ? retryAfterMs : undefined;
+}
+/** Present a retry delay as an HTTP `Retry-After` delta in whole seconds, rounded up. */
+export function retryAfterField(retryAfterMs) {
+    if (!isRetryAfter(retryAfterMs))
+        throw new TypeError('Retry-After delay is invalid.');
+    return String(Math.ceil(retryAfterMs / 1_000));
+}
+function isRetryAfter(input) {
+    return (typeof input === 'number' &&
+        Number.isSafeInteger(input) &&
+        input >= 0 &&
+        input <= MAXIMUM_RETRY_AFTER_MS);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrale-os/kernel-protocol",
-  "version": "0.5.0-beta.61",
+  "version": "0.5.0-beta.62",
   "description": "Portable Astrale invocation, publication, installation, routing, and issuer protocols",
   "license": "Apache-2.0",
   "repository": {
@@ -137,8 +137,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@astrale-os/kernel-core": "0.9.0-beta.55",
-    "@astrale-os/kernel-dsl": "0.2.0-beta.40",
+    "@astrale-os/kernel-core": "0.9.0-beta.56",
+    "@astrale-os/kernel-dsl": "0.2.0-beta.41",
     "@noble/hashes": "2.3.0"
   },
   "devDependencies": {