@crouter/api 0.3.396 → 0.3.397

package/dist/api/index.d.ts

@@ -5,7 +5,8 @@ export type { ErrorBody } from './errors.js';
 export { errorCodes } from './error-codes.js';
 export type { ErrorCode, ErrorEnvelope, ErrorOrigin, ErrorType } from './error-codes.js';
 export { API_VERSION, routes } from './routes.js';
-export { RUNTIME_VERSION_HEADER, compareReleaseVersions } from './runtime-version.js';
+export { RUNTIME_VERSION_HEADER, MINIMUM_RUNTIME_VERSION_HEADER, compareReleaseVersions, minimumRuntimeRefusal } from './runtime-version.js';
+export type { MinimumRuntimeRefusal } from './runtime-version.js';
 export * from '../shared/generated-context.js';
 export * from './dto/common.js';
 export * from './dto/health.js';

package/dist/api/index.js

@@ -5,7 +5,7 @@ export { CrtrClient, waitForDaemonAvailability } from './client.js';
 export { APIError, ApiError, isErrorBody } from './errors.js';
 export { errorCodes } from './error-codes.js';
 export { API_VERSION, routes } from './routes.js';
-export { RUNTIME_VERSION_HEADER, compareReleaseVersions } from './runtime-version.js';
+export { RUNTIME_VERSION_HEADER, MINIMUM_RUNTIME_VERSION_HEADER, compareReleaseVersions, minimumRuntimeRefusal } from './runtime-version.js';
 export * from '../shared/generated-context.js';
 export * from './dto/common.js';
 export * from './dto/health.js';

package/dist/api/runtime-version.d.ts

@@ -4,3 +4,28 @@ export declare const RUNTIME_VERSION_HEADER = "Crouter-Runtime-Version";
  *  suffix is ignored). Negative when `a` is older, zero when equal, positive when
  *  newer. A version that does not parse sorts below every version that does. */
 export declare function compareReleaseVersions(a: string, b: string): number;
+/** Request header naming the oldest runtime release the caller accepts, e.g. `0.3.396`. The SDK sends its own
+ *  version on every request except `/healthz`. Optional: absent means no check. The router in front of a hosted
+ *  runtime and the runtime itself each refuse a request that names a newer release than the runtime's, before any
+ *  handler runs (so nothing is accepted and no idempotency key is recorded). */
+export declare const MINIMUM_RUNTIME_VERSION_HEADER = "Crouter-Minimum-Runtime-Version";
+/** The refusal a runtime answers instead of handling a request, or `null` when the request may be handled.
+ *  - `required` absent: handled.
+ *  - `required` not `major.minor.patch` (optional `v`, optional suffix): 400 `invalid_request`.
+ *  - `runtimeVersion` older than `required`, or not a release version: 426 `runtime_version_unsupported`
+ *    (details `{sdk_version, runtime_version}`, the SDK's `RuntimeVersionDetails`). */
+export type MinimumRuntimeRefusal = {
+    status: 400;
+    code: 'invalid_request';
+    message: string;
+    param: string;
+} | {
+    status: 426;
+    code: 'runtime_version_unsupported';
+    message: string;
+    details: {
+        sdk_version: string;
+        runtime_version: string | null;
+    };
+};
+export declare function minimumRuntimeRefusal(required: string | undefined, runtimeVersion: string | null): MinimumRuntimeRefusal | null;

package/dist/api/runtime-version.js

@@ -26,3 +26,25 @@ function parseRelease(version) {
     const match = /^v?(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/.exec(version.trim());
     return match === null ? null : [Number(match[1]), Number(match[2]), Number(match[3])];
 }
+/** Request header naming the oldest runtime release the caller accepts, e.g. `0.3.396`. The SDK sends its own
+ *  version on every request except `/healthz`. Optional: absent means no check. The router in front of a hosted
+ *  runtime and the runtime itself each refuse a request that names a newer release than the runtime's, before any
+ *  handler runs (so nothing is accepted and no idempotency key is recorded). */
+export const MINIMUM_RUNTIME_VERSION_HEADER = 'Crouter-Minimum-Runtime-Version';
+export function minimumRuntimeRefusal(required, runtimeVersion) {
+    if (required === undefined)
+        return null;
+    if (parseRelease(required) === null) {
+        return { status: 400, code: 'invalid_request', param: MINIMUM_RUNTIME_VERSION_HEADER, message: `${MINIMUM_RUNTIME_VERSION_HEADER} must be a release version like 0.3.396.` };
+    }
+    if (runtimeVersion !== null && parseRelease(runtimeVersion) !== null && compareReleaseVersions(runtimeVersion, required) >= 0)
+        return null;
+    const sdkVersion = required.trim();
+    return {
+        status: 426, code: 'runtime_version_unsupported',
+        message: runtimeVersion === null
+            ? `The runtime did not name its version; the caller requires a runtime at ${sdkVersion} or later. Roll the runtime forward.`
+            : `The runtime is ${runtimeVersion}; the caller requires a runtime at ${sdkVersion} or later. Roll the runtime forward.`,
+        details: { sdk_version: sdkVersion, runtime_version: runtimeVersion },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouter/api",
-  "version": "0.3.396",
+  "version": "0.3.397",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",