@ultimabase/maintenance 0.4.0-canary.0 → 0.4.0-canary.20261102201751

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# @ultimabase/maintenance
+
+## 0.4.0-canary.20261102201751
+
+### Minor Changes
+
+- 7accc26: Each plugin declares the codes its errors carry in its types' `errors`, and `ultimabase` exports `ErrorCodeOf<typeof app>`: the kernel's codes and those of each plugin the application lists, for a client to type its messages against (D-206). A GraphQL document the schema refuses, as an unknown field, now carries `extensions.code: 'BAD_USER_INPUT'`, as REST's refused query.
+- 9cebf63: New package, `@ultimabase/maintenance`: `maintenancePlugin()` answers 503
+  `MAINTENANCE`, with `Retry-After`, to every request and WebSocket upgrade
+  but Master's, and closes the open sockets with 1012, while the maintenance
+  is on. `PUT /_ultimabase/maintenance { enabled }`, with the master key or
+  the `key` option sent in `x-ultimabase-maintenance-key`, turns it on and
+  off, and so do `plugins.maintenance.lock()` and `unlock()`; every server
+  follows the stored state, or `initial` while none is stored, and a start
+  that cannot read it fails (D-207). `/health` and `/ready` are left
+  alone. Plugins add their own gates with `plugins.http.gate(gate)`, run on
+  each request past CORS and on each upgrade (D-205).
+
+### Patch Changes
+
+- Updated dependencies [67d5152]
+- Updated dependencies [7accc26]
+- Updated dependencies [8dca2cf]
+- Updated dependencies [4e1a966]
+- Updated dependencies [9b491fb]
+- Updated dependencies [9b491fb]
+- Updated dependencies [9cebf63]
+- Updated dependencies [1d7fda8]
+- Updated dependencies [a778695]
+- Updated dependencies [e61e1c2]
+  - ultimabase@0.4.0-canary.20261102201751
+  - @ultimabase/http@0.4.0-canary.20261102201751

package/dist/index.d.ts

@@ -4,6 +4,10 @@ import type { PluginOf, PluginTypes } from 'ultimabase';
 export interface MaintenanceOptions {
     /** In milliseconds, how long a client waits before it tries again: 60 000 by default. */
     readonly retryAfter?: number;
+    /** Sent in `x-ultimabase-maintenance-key`, it switches the maintenance and nothing else. */
+    readonly key?: string | undefined;
+    /** The state while none is stored: `'unlocked'` by default. */
+    readonly initial?: 'locked' | 'unlocked';
 }
 /** What the maintenance plugin offers other plugins. */
 export interface MaintenanceApi {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAE5C,OAAO,KAAK,EAAU,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAK/D,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IAClC,yFAAyF;IACzF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC5B;AAED,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC9B,2DAA2D;IAC3D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,4CAA4C;IAC5C,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,6CAA6C;IAC7C,MAAM,IAAI,OAAO,CAAA;CACjB;AAED,6CAA6C;AAC7C,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAA;IACvC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAC9B;AAqID,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,WAAW,CAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAE5C,OAAO,KAAK,EAAU,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAM/D,sCAAsC;AACtC,MAAM,WAAW,kBAAkB;IAClC,yFAAyF;IACzF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,4FAA4F;IAC5F,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,GAAG,UAAU,CAAA;CACxC;AAED,wDAAwD;AACxD,MAAM,WAAW,cAAc;IAC9B,2DAA2D;IAC3D,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACrB,4CAA4C;IAC5C,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;IACvB,6CAA6C;IAC7C,MAAM,IAAI,OAAO,CAAA;CACjB;AAED,6CAA6C;AAC7C,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAA;IAC5B,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAA;IACvC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAA;CAC9B;AA+ID,oDAAoD;AACpD,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,WAAW,CAAsB,CAAA"}

package/dist/index.js

@@ -1,6 +1,7 @@
 import { httpPlugin, routes } from '@ultimabase/http';
-import { definePlugin, master, PublicError } from 'ultimabase';
+import { definePlugin, master, PublicError, Refused } from 'ultimabase';
 import manifest from '../package.json' with { type: 'json' };
+import { keyed } from './key.js';
 import { MaintenanceState } from './state.js';
 /** The route Master turns it on and off with, which it never refuses. */
 const path = '/_ultimabase/maintenance';
@@ -11,9 +12,9 @@ function follow(state, locked) {
         state.close();
     state.locked = locked;
 }
-async function stored() {
+async function stored(state) {
     const row = await MaintenanceState.findUnique({ where: { key } }, { as: master });
-    return row?.enabled ?? false;
+    return row?.enabled ?? state.initial;
 }
 async function store(state, locked) {
     await MaintenanceState.upsert({
@@ -26,7 +27,7 @@ async function store(state, locked) {
 /** Reads the state again; keeps the last one when it cannot. */
 async function reload(state) {
     try {
-        follow(state, await stored());
+        follow(state, await stored(state));
     }
     catch (error) {
         state.logger.error({ err: error }, 'The maintenance state could not be read: it stays as it was.');
@@ -56,8 +57,14 @@ const maintenance = definePlugin({
     models: [MaintenanceState],
     api: (context) => {
         const { plugins, options, identify, logger } = context;
+        const { initial = 'unlocked' } = options;
+        if (initial !== 'locked' && initial !== 'unlocked') {
+            throw new Refused("The maintenance's initial is 'locked' or 'unlocked'.");
+        }
+        const switches = keyed(options.key);
         const state = {
             locked: false,
+            initial: initial === 'locked',
             close: () => plugins.http.closeUpgrades({ code: 1012, reason: 'Maintenance' }),
             logger,
         };
@@ -77,8 +84,8 @@ const maintenance = definePlugin({
             }, { status: 503, headers: { 'retry-after': String(seconds) } });
         });
         plugins.http.mount(routes().put(path, async (c) => {
-            if (c.var.caller.kind !== 'master') {
-                throw new PublicError('ACCESS_DENIED', 'Only the master key turns the maintenance on or off.');
+            if (c.var.caller.kind !== 'master' && !switches(c.req.raw)) {
+                throw new PublicError('ACCESS_DENIED', 'Only the master key or the maintenance key turns the maintenance on or off.');
             }
             const enabled = enabledIn(await c.req.json().catch(() => undefined));
             await store(state, enabled);
@@ -91,7 +98,10 @@ const maintenance = definePlugin({
         };
     },
     start: async (context) => {
-        stateOf(context).locked = await stored();
+        // A read that fails fails the start: the server must not serve
+        // while it does not know whether it is in maintenance (D-207).
+        const state = stateOf(context);
+        state.locked = await stored(state);
     },
     changed: (changes, context) => {
         if (changes.some((change) => change.model === MaintenanceState.name)) {

package/dist/key.d.ts

@@ -0,0 +1,5 @@
+/** The header a request sends the maintenance key in. */
+export declare const keyHeader = "x-ultimabase-maintenance-key";
+/** Whether a request sends `key`; never, when it is unset. */
+export declare function keyed(key: string | undefined): (request: Request) => boolean;
+//# sourceMappingURL=key.d.ts.map

package/dist/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../src/key.ts"],"names":[],"mappings":"AAOA,yDAAyD;AACzD,eAAO,MAAM,SAAS,iCAAiC,CAAA;AAMvD,8DAA8D;AAC9D,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAiB5E"}

package/dist/key.js

@@ -0,0 +1,26 @@
+// The maintenance key (D-207): it switches the maintenance, nothing else, so a
+// deployment pipeline does not hold the master key. It follows the master
+// key's rules: unset when empty, a header's characters only, and 32
+// characters at least in production.
+import { createHash, timingSafeEqual } from 'node:crypto';
+import { Refused } from 'ultimabase';
+/** The header a request sends the maintenance key in. */
+export const keyHeader = 'x-ultimabase-maintenance-key';
+// Digests have one length, so the comparison takes the same time for any key.
+const digest = (text) => createHash('sha256').update(text).digest();
+/** Whether a request sends `key`; never, when it is unset. */
+export function keyed(key) {
+    if (key === undefined || key === '')
+        return () => false;
+    if (!/^[\x21-\x7e]+$/.test(key)) {
+        throw new Refused('The maintenance key holds a space or a character outside ASCII, which a header cannot carry: use letters, digits and symbols only.');
+    }
+    if (process.env['NODE_ENV'] === 'production' && key.length < 32) {
+        throw new Refused(`The maintenance key is ${key.length} characters long; production needs 32 at least: \`openssl rand -base64 32\` gives one.`);
+    }
+    const expected = digest(key);
+    return (request) => {
+        const sent = request.headers.get(keyHeader);
+        return sent !== null && timingSafeEqual(digest(sent), expected);
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimabase/maintenance",
-  "version": "0.4.0-canary.0",
+  "version": "0.4.0-canary.20261102201751",
   "description": "Maintenance for UltimaBase: every server answers 503 and closes its WebSockets until it ends, Master's requests aside.",
   "type": "module",
   "license": "Apache-2.0",
@@ -31,13 +31,13 @@
     }
   },
   "peerDependencies": {
-    "@ultimabase/http": "^0.3.0",
-    "ultimabase": "^0.3.0"
+    "@ultimabase/http": "0.4.0-canary.20261102201751",
+    "ultimabase": "0.4.0-canary.20261102201751"
   },
   "devDependencies": {
-    "@ultimabase/http": "0.3.0",
-    "@ultimabase/testing": "0.3.0",
-    "ultimabase": "0.3.0",
+    "@ultimabase/http": "0.4.0-canary.20261102201751",
+    "@ultimabase/testing": "0.4.0-canary.20261102201751",
+    "ultimabase": "0.4.0-canary.20261102201751",
     "vite": "8.3.4",
     "vitest": "5.0.5"
   }

package/src/index.ts

@@ -1,17 +1,23 @@
 // Maintenance (D-205): while it is on, every request and WebSocket upgrade but
 // Master's answers 503 `MAINTENANCE`, and the sockets open close with 1012.
-// Its state is a row: every server follows it through the change feed.
+// Its state is a row: every server follows it through the change feed, and
+// starts from `initial` while there is none (D-207).
 import type { Http } from '@ultimabase/http'
 import { httpPlugin, routes } from '@ultimabase/http'
 import type { Logger, PluginOf, PluginTypes } from 'ultimabase'
-import { definePlugin, master, PublicError } from 'ultimabase'
+import { definePlugin, master, PublicError, Refused } from 'ultimabase'
 import manifest from '../package.json' with { type: 'json' }
+import { keyed } from './key.ts'
 import { MaintenanceState } from './state.ts'
 
 /** What `maintenancePlugin` takes. */
 export interface MaintenanceOptions {
 	/** In milliseconds, how long a client waits before it tries again: 60 000 by default. */
 	readonly retryAfter?: number
+	/** Sent in `x-ultimabase-maintenance-key`, it switches the maintenance and nothing else. */
+	readonly key?: string | undefined
+	/** The state while none is stored: `'unlocked'` by default. */
+	readonly initial?: 'locked' | 'unlocked'
 }
 
 /** What the maintenance plugin offers other plugins. */
@@ -37,9 +43,10 @@ export interface Maintenance extends PluginTypes {
 const path = '/_ultimabase/maintenance'
 const key = 'state'
 
-/** This server's state, and how it closes the sockets open. */
+/** This server's state, the one while none is stored, and how it closes the sockets open. */
 interface State {
 	locked: boolean
+	readonly initial: boolean
 	readonly close: () => void
 	readonly logger: Logger
 }
@@ -50,12 +57,12 @@ function follow(state: State, locked: boolean): void {
 	state.locked = locked
 }
 
-async function stored(): Promise<boolean> {
+async function stored(state: State): Promise<boolean> {
 	const row = await MaintenanceState.findUnique(
 		{ where: { key } },
 		{ as: master },
 	)
-	return row?.enabled ?? false
+	return row?.enabled ?? state.initial
 }
 
 async function store(state: State, locked: boolean): Promise<void> {
@@ -73,7 +80,7 @@ async function store(state: State, locked: boolean): Promise<void> {
 /** Reads the state again; keeps the last one when it cannot. */
 async function reload(state: State): Promise<void> {
 	try {
-		follow(state, await stored())
+		follow(state, await stored(state))
 	} catch (error) {
 		state.logger.error(
 			{ err: error },
@@ -111,8 +118,14 @@ const maintenance = definePlugin<Maintenance>({
 	models: [MaintenanceState],
 	api: (context) => {
 		const { plugins, options, identify, logger } = context
+		const { initial = 'unlocked' } = options
+		if (initial !== 'locked' && initial !== 'unlocked') {
+			throw new Refused("The maintenance's initial is 'locked' or 'unlocked'.")
+		}
+		const switches = keyed(options.key)
 		const state: State = {
 			locked: false,
+			initial: initial === 'locked',
 			close: () =>
 				plugins.http.closeUpgrades({ code: 1012, reason: 'Maintenance' }),
 			logger,
@@ -136,10 +149,10 @@ const maintenance = definePlugin<Maintenance>({
 		})
 		plugins.http.mount(
 			routes().put(path, async (c) => {
-				if (c.var.caller.kind !== 'master') {
+				if (c.var.caller.kind !== 'master' && !switches(c.req.raw)) {
 					throw new PublicError(
 						'ACCESS_DENIED',
-						'Only the master key turns the maintenance on or off.',
+						'Only the master key or the maintenance key turns the maintenance on or off.',
 					)
 				}
 				const enabled = enabledIn(await c.req.json().catch(() => undefined))
@@ -154,7 +167,10 @@ const maintenance = definePlugin<Maintenance>({
 		}
 	},
 	start: async (context) => {
-		stateOf(context).locked = await stored()
+		// A read that fails fails the start: the server must not serve
+		// while it does not know whether it is in maintenance (D-207).
+		const state = stateOf(context)
+		state.locked = await stored(state)
 	},
 	changed: (changes, context) => {
 		if (changes.some((change) => change.model === MaintenanceState.name)) {

package/src/key.ts

@@ -0,0 +1,33 @@
+// The maintenance key (D-207): it switches the maintenance, nothing else, so a
+// deployment pipeline does not hold the master key. It follows the master
+// key's rules: unset when empty, a header's characters only, and 32
+// characters at least in production.
+import { createHash, timingSafeEqual } from 'node:crypto'
+import { Refused } from 'ultimabase'
+
+/** The header a request sends the maintenance key in. */
+export const keyHeader = 'x-ultimabase-maintenance-key'
+
+// Digests have one length, so the comparison takes the same time for any key.
+const digest = (text: string): Buffer =>
+	createHash('sha256').update(text).digest()
+
+/** Whether a request sends `key`; never, when it is unset. */
+export function keyed(key: string | undefined): (request: Request) => boolean {
+	if (key === undefined || key === '') return () => false
+	if (!/^[\x21-\x7e]+$/.test(key)) {
+		throw new Refused(
+			'The maintenance key holds a space or a character outside ASCII, which a header cannot carry: use letters, digits and symbols only.',
+		)
+	}
+	if (process.env['NODE_ENV'] === 'production' && key.length < 32) {
+		throw new Refused(
+			`The maintenance key is ${key.length} characters long; production needs 32 at least: \`openssl rand -base64 32\` gives one.`,
+		)
+	}
+	const expected = digest(key)
+	return (request) => {
+		const sent = request.headers.get(keyHeader)
+		return sent !== null && timingSafeEqual(digest(sent), expected)
+	}
+}