@eco-foundation/api-schemas 0.12.0 → 0.14.0

package/dist/v1/maintenance/schema.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaintenanceConfigSchema = exports.MaintenanceWindowSchema = exports.MAINTENANCE_MESSAGE_MAX_LENGTH = void 0;
+const zod_1 = require("zod");
+const ISO_UTC_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+function isRealUtcInstant(value) {
+    const ms = Date.parse(value);
+    if (!Number.isFinite(ms))
+        return false;
+    return new Date(ms).toISOString().slice(0, 19) === value.slice(0, 19);
+}
+function utcMillis(value) {
+    return ISO_UTC_PATTERN.test(value) && isRealUtcInstant(value) ? Date.parse(value) : undefined;
+}
+const IsoUtcTimestamp = zod_1.z
+    .string({
+    error: 'must be an ISO-8601 UTC timestamp string; quote it in YAML',
+})
+    .regex(ISO_UTC_PATTERN, 'must be an ISO-8601 UTC timestamp ending in Z, e.g. 2026-10-04T02:00:00Z')
+    .refine((value) => !ISO_UTC_PATTERN.test(value) || utcMillis(value) !== undefined, 'is not a real calendar instant');
+exports.MAINTENANCE_MESSAGE_MAX_LENGTH = 200;
+function rejectUnknownKeys(allowedKeys) {
+    const allowed = new Set(allowedKeys);
+    return (raw, ctx) => {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw))
+            return raw;
+        const extra = Object.keys(raw).filter((key) => !allowed.has(key));
+        if (extra.length === 0)
+            return raw;
+        const quoted = extra.map((key) => `"${key}"`).join(', ');
+        ctx.addIssue({
+            code: 'custom',
+            message: extra.length === 1 ? `Unrecognized key: ${quoted}` : `Unrecognized keys: ${quoted}`,
+        });
+        return raw;
+    };
+}
+const MaintenanceWindowShape = zod_1.z
+    .object({
+    startsAt: IsoUtcTimestamp,
+    endsAt: IsoUtcTimestamp,
+    message: zod_1.z
+        .string()
+        .max(exports.MAINTENANCE_MESSAGE_MAX_LENGTH)
+        .refine((value) => value.trim().length > 0, 'must not be blank'),
+})
+    .superRefine((window, ctx) => {
+    const startsMs = utcMillis(window.startsAt);
+    const endsMs = utcMillis(window.endsAt);
+    if (startsMs === undefined || endsMs === undefined)
+        return;
+    if (endsMs <= startsMs) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['endsAt'],
+            message: `endsAt ${window.endsAt} must be after startsAt ${window.startsAt}`,
+        });
+    }
+});
+exports.MaintenanceWindowSchema = zod_1.z.preprocess(rejectUnknownKeys(['startsAt', 'endsAt', 'message']), MaintenanceWindowShape);
+const MaintenanceConfigShape = zod_1.z.object({
+    windows: zod_1.z.array(exports.MaintenanceWindowSchema).default([]),
+});
+exports.MaintenanceConfigSchema = zod_1.z.preprocess(rejectUnknownKeys(['windows']), MaintenanceConfigShape);
+//# sourceMappingURL=schema.js.map

package/dist/v1/maintenance/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/v1/maintenance/schema.ts"],"names":[],"mappings":"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"}

package/errors/catalog.lock.json

@@ -258,5 +258,10 @@
     "code": "service-unavailable",
     "status": 503,
     "legacyCodes": []
+  },
+  {
+    "code": "maintenance",
+    "status": 503,
+    "legacyCodes": []
   }
 ]

package/fixtures/maintenance-boundaries.json

@@ -0,0 +1,405 @@
+[
+  {
+    "name": "empty window list",
+    "windows": [],
+    "nowIso": "2026-10-04T03:00:00.000Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "one millisecond before startsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T01:59:59.999Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "exactly startsAt (start is inclusive)",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T02:00:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "Scheduled maintenance: database upgrade",
+      "retryAfterSeconds": 7200
+    }
+  },
+  {
+    "name": "mid-window",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T03:00:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "Scheduled maintenance: database upgrade",
+      "retryAfterSeconds": 3600
+    }
+  },
+  {
+    "name": "one millisecond before endsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T03:59:59.999Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "Scheduled maintenance: database upgrade",
+      "retryAfterSeconds": 1
+    }
+  },
+  {
+    "name": "exactly endsAt (end is exclusive)",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T04:00:00.000Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "fractional remainder rounds up: 1.5 s before endsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T03:59:58.500Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "Scheduled maintenance: database upgrade",
+      "retryAfterSeconds": 2
+    }
+  },
+  {
+    "name": "whole-second remainder does not round up: 2 s before endsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "Scheduled maintenance: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T03:59:58.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "Scheduled maintenance: database upgrade",
+      "retryAfterSeconds": 2
+    }
+  },
+  {
+    "name": "past-only window",
+    "windows": [
+      {
+        "startsAt": "2026-10-01T02:00:00Z",
+        "endsAt": "2026-10-01T04:00:00Z",
+        "message": "Last week's maintenance"
+      }
+    ],
+    "nowIso": "2026-10-04T03:00:00.000Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "future-only window",
+    "windows": [
+      {
+        "startsAt": "2026-10-11T02:00:00Z",
+        "endsAt": "2026-10-11T04:00:00Z",
+        "message": "Next week's maintenance"
+      }
+    ],
+    "nowIso": "2026-10-04T03:00:00.000Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "past and future windows, now between them",
+    "windows": [
+      {
+        "startsAt": "2026-10-01T02:00:00Z",
+        "endsAt": "2026-10-01T04:00:00Z",
+        "message": "Last week's maintenance"
+      },
+      {
+        "startsAt": "2026-10-11T02:00:00Z",
+        "endsAt": "2026-10-11T04:00:00Z",
+        "message": "Next week's maintenance"
+      }
+    ],
+    "nowIso": "2026-10-04T03:00:00.000Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "overlapping windows, only the first active",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "A: database upgrade"
+      },
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T05:00:00Z",
+        "message": "B: key rotation"
+      }
+    ],
+    "nowIso": "2026-10-04T02:30:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "A: database upgrade",
+      "retryAfterSeconds": 5400
+    }
+  },
+  {
+    "name": "overlapping windows, both active: latest endsAt wins",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "A: database upgrade"
+      },
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T05:00:00Z",
+        "message": "B: key rotation"
+      }
+    ],
+    "nowIso": "2026-10-04T03:30:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T03:00:00Z",
+      "endsAt": "2026-10-04T05:00:00Z",
+      "message": "B: key rotation",
+      "retryAfterSeconds": 5400
+    }
+  },
+  {
+    "name": "overlapping windows, both active, list reversed: latest endsAt still wins",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T05:00:00Z",
+        "message": "B: key rotation"
+      },
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "A: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T03:30:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T03:00:00Z",
+      "endsAt": "2026-10-04T05:00:00Z",
+      "message": "B: key rotation",
+      "retryAfterSeconds": 5400
+    }
+  },
+  {
+    "name": "overlapping windows, after the first ends",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "A: database upgrade"
+      },
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T05:00:00Z",
+        "message": "B: key rotation"
+      }
+    ],
+    "nowIso": "2026-10-04T04:00:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T03:00:00Z",
+      "endsAt": "2026-10-04T05:00:00Z",
+      "message": "B: key rotation",
+      "retryAfterSeconds": 3600
+    }
+  },
+  {
+    "name": "overlapping windows with equal endsAt: first in list wins",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "A: database upgrade"
+      },
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "B: key rotation"
+      }
+    ],
+    "nowIso": "2026-10-04T03:30:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "A: database upgrade",
+      "retryAfterSeconds": 1800
+    }
+  },
+  {
+    "name": "overlapping windows with equal endsAt, list reversed: first in list wins",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "B: key rotation"
+      },
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "A: database upgrade"
+      }
+    ],
+    "nowIso": "2026-10-04T03:30:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T03:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "B: key rotation",
+      "retryAfterSeconds": 1800
+    }
+  },
+  {
+    "name": "adjacent windows, one millisecond before the handoff",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T03:00:00Z",
+        "message": "A: database upgrade"
+      },
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "B: key rotation"
+      }
+    ],
+    "nowIso": "2026-10-04T02:59:59.999Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00Z",
+      "endsAt": "2026-10-04T03:00:00Z",
+      "message": "A: database upgrade",
+      "retryAfterSeconds": 1
+    }
+  },
+  {
+    "name": "adjacent windows at the handoff instant: the second window",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00Z",
+        "endsAt": "2026-10-04T03:00:00Z",
+        "message": "A: database upgrade"
+      },
+      {
+        "startsAt": "2026-10-04T03:00:00Z",
+        "endsAt": "2026-10-04T04:00:00Z",
+        "message": "B: key rotation"
+      }
+    ],
+    "nowIso": "2026-10-04T03:00:00.000Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T03:00:00Z",
+      "endsAt": "2026-10-04T04:00:00Z",
+      "message": "B: key rotation",
+      "retryAfterSeconds": 3600
+    }
+  },
+  {
+    "name": "sub-second bounds, one millisecond before startsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00.250Z",
+        "endsAt": "2026-10-04T02:00:01.750Z",
+        "message": "Sub-second window"
+      }
+    ],
+    "nowIso": "2026-10-04T02:00:00.249Z",
+    "expected": {
+      "active": false
+    }
+  },
+  {
+    "name": "sub-second bounds, exactly startsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00.250Z",
+        "endsAt": "2026-10-04T02:00:01.750Z",
+        "message": "Sub-second window"
+      }
+    ],
+    "nowIso": "2026-10-04T02:00:00.250Z",
+    "expected": {
+      "active": true,
+      "startsAt": "2026-10-04T02:00:00.250Z",
+      "endsAt": "2026-10-04T02:00:01.750Z",
+      "message": "Sub-second window",
+      "retryAfterSeconds": 2
+    }
+  },
+  {
+    "name": "sub-second bounds, exactly endsAt",
+    "windows": [
+      {
+        "startsAt": "2026-10-04T02:00:00.250Z",
+        "endsAt": "2026-10-04T02:00:01.750Z",
+        "message": "Sub-second window"
+      }
+    ],
+    "nowIso": "2026-10-04T02:00:01.750Z",
+    "expected": {
+      "active": false
+    }
+  }
+]