@ultimabase/maintenance 0.0.0-stage → 0.4.0-canary.0

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @ultimabase/maintenance
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Maintenance for UltimaBase. While it is on, every server answers each request and WebSocket upgrade with 503 `MAINTENANCE` and `Retry-After`, and closes the sockets open with 1012; Master's requests still pass.
+
+Documentation: [Maintenance](https://ultimabase.dev/docs/maintenance).

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+import type { Http } from '@ultimabase/http';
+import type { PluginOf, PluginTypes } from 'ultimabase';
+/** What `maintenancePlugin` takes. */
+export interface MaintenanceOptions {
+    /** In milliseconds, how long a client waits before it tries again: 60 000 by default. */
+    readonly retryAfter?: number;
+}
+/** What the maintenance plugin offers other plugins. */
+export interface MaintenanceApi {
+    /** Begins the maintenance on every server, once stored. */
+    lock(): Promise<void>;
+    /** Ends it on every server, once stored. */
+    unlock(): Promise<void>;
+    /** Whether this server is in maintenance. */
+    locked(): boolean;
+}
+/** The maintenance plugin's types (D-57). */
+export interface Maintenance extends PluginTypes {
+    readonly name: 'maintenance';
+    readonly appOptions: MaintenanceOptions;
+    readonly requires: Http;
+    readonly api: MaintenanceApi;
+    readonly errors: 'MAINTENANCE';
+}
+/** Maintenance, on every server at once (D-205). */
+export declare const maintenancePlugin: PluginOf<Maintenance>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +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"}

package/dist/index.js

@@ -0,0 +1,104 @@
+import { httpPlugin, routes } from '@ultimabase/http';
+import { definePlugin, master, PublicError } from 'ultimabase';
+import manifest from '../package.json' with { type: 'json' };
+import { MaintenanceState } from './state.js';
+/** The route Master turns it on and off with, which it never refuses. */
+const path = '/_ultimabase/maintenance';
+const key = 'state';
+/** Follows the stored state: as it begins, the sockets open close. */
+function follow(state, locked) {
+    if (locked && !state.locked)
+        state.close();
+    state.locked = locked;
+}
+async function stored() {
+    const row = await MaintenanceState.findUnique({ where: { key } }, { as: master });
+    return row?.enabled ?? false;
+}
+async function store(state, locked) {
+    await MaintenanceState.upsert({
+        where: { key },
+        create: { key, enabled: locked },
+        update: { enabled: locked },
+    }, { as: master });
+    follow(state, locked);
+}
+/** Reads the state again; keeps the last one when it cannot. */
+async function reload(state) {
+    try {
+        follow(state, await stored());
+    }
+    catch (error) {
+        state.logger.error({ err: error }, 'The maintenance state could not be read: it stays as it was.');
+    }
+}
+const states = new WeakMap();
+function stateOf(context) {
+    const state = states.get(context);
+    if (state === undefined)
+        throw new Error('The maintenance plugin has no api.');
+    return state;
+}
+/** The body of `PUT /_ultimabase/maintenance`, `{ enabled }`. */
+function enabledIn(body) {
+    const enabled = typeof body === 'object' && body !== null
+        ? Reflect.get(body, 'enabled')
+        : undefined;
+    if (typeof enabled !== 'boolean') {
+        throw new PublicError('VALIDATION_FAILED', 'The body is { "enabled": true } or { "enabled": false }.');
+    }
+    return enabled;
+}
+const maintenance = definePlugin({
+    name: 'maintenance',
+    manifest,
+    requires: { http: httpPlugin },
+    models: [MaintenanceState],
+    api: (context) => {
+        const { plugins, options, identify, logger } = context;
+        const state = {
+            locked: false,
+            close: () => plugins.http.closeUpgrades({ code: 1012, reason: 'Maintenance' }),
+            logger,
+        };
+        states.set(context, state);
+        const seconds = Math.ceil((options.retryAfter ?? 60_000) / 1000);
+        plugins.http.gate(async (request) => {
+            if (!state.locked || new URL(request.url).pathname === path) {
+                return undefined;
+            }
+            const caller = await identify(request).catch(() => undefined);
+            if (caller?.kind === 'master')
+                return undefined;
+            return Response.json({
+                code: 'MAINTENANCE',
+                message: 'The application is under maintenance.',
+                details: { retryAfter: seconds },
+            }, { 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.');
+            }
+            const enabled = enabledIn(await c.req.json().catch(() => undefined));
+            await store(state, enabled);
+            return c.json({ enabled });
+        }));
+        return {
+            lock: () => store(state, true),
+            unlock: () => store(state, false),
+            locked: () => state.locked,
+        };
+    },
+    start: async (context) => {
+        stateOf(context).locked = await stored();
+    },
+    changed: (changes, context) => {
+        if (changes.some((change) => change.model === MaintenanceState.name)) {
+            void reload(stateOf(context));
+        }
+    },
+    missed: (context) => void reload(stateOf(context)),
+});
+/** Maintenance, on every server at once (D-205). */
+export const maintenancePlugin = maintenance.plugin;

package/dist/state.d.ts

@@ -0,0 +1,11 @@
+import type { Field, ModelOf } from 'ultimabase';
+type StateFields = {
+    readonly key: Field<string, {
+        readonly unique: true;
+    }>;
+    readonly enabled: Field<boolean, {}>;
+};
+/** maintenance's own model (D-110). */
+export declare const MaintenanceState: ModelOf<'MaintenanceState', StateFields, []>;
+export {};
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAGhD,KAAK,WAAW,GAAG;IAClB,QAAQ,CAAC,GAAG,EAAE,KAAK,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;KAAE,CAAC,CAAA;IACtD,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;CACpC,CAAA;AAED,uCAAuC;AACvC,eAAO,MAAM,gBAAgB,EAAE,OAAO,CAAC,kBAAkB,EAAE,WAAW,EAAE,EAAE,CAOvE,CAAA"}

package/dist/state.js

@@ -0,0 +1,9 @@
+import { defineModel } from 'ultimabase';
+/** maintenance's own model (D-110). */
+export const MaintenanceState = defineModel({
+    name: 'MaintenanceState',
+    fields: (f) => ({
+        key: f.string({ unique: true }),
+        enabled: f.boolean(),
+    }),
+});

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@ultimabase/maintenance",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.4.0-canary.0",
+  "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",
+  "homepage": "https://ultimabase.dev/docs/maintenance",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrEkinox/ultimabase.git",
+    "directory": "packages/maintenance"
+  },
+  "engines": {
+    "node": ">=24.7.0"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test"
+  ],
+  "scripts": {
+    "prepack": "rm -rf dist && yarn run -T tsc --project tsconfig.build.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@ultimabase/http": "^0.3.0",
+    "ultimabase": "^0.3.0"
+  },
+  "devDependencies": {
+    "@ultimabase/http": "0.3.0",
+    "@ultimabase/testing": "0.3.0",
+    "ultimabase": "0.3.0",
+    "vite": "8.3.4",
+    "vitest": "5.0.5"
+  }
 }

package/src/index.ts

@@ -0,0 +1,168 @@
+// 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.
+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 manifest from '../package.json' with { type: 'json' }
+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
+}
+
+/** What the maintenance plugin offers other plugins. */
+export interface MaintenanceApi {
+	/** Begins the maintenance on every server, once stored. */
+	lock(): Promise<void>
+	/** Ends it on every server, once stored. */
+	unlock(): Promise<void>
+	/** Whether this server is in maintenance. */
+	locked(): boolean
+}
+
+/** The maintenance plugin's types (D-57). */
+export interface Maintenance extends PluginTypes {
+	readonly name: 'maintenance'
+	readonly appOptions: MaintenanceOptions
+	readonly requires: Http
+	readonly api: MaintenanceApi
+	readonly errors: 'MAINTENANCE'
+}
+
+/** The route Master turns it on and off with, which it never refuses. */
+const path = '/_ultimabase/maintenance'
+const key = 'state'
+
+/** This server's state, and how it closes the sockets open. */
+interface State {
+	locked: boolean
+	readonly close: () => void
+	readonly logger: Logger
+}
+
+/** Follows the stored state: as it begins, the sockets open close. */
+function follow(state: State, locked: boolean): void {
+	if (locked && !state.locked) state.close()
+	state.locked = locked
+}
+
+async function stored(): Promise<boolean> {
+	const row = await MaintenanceState.findUnique(
+		{ where: { key } },
+		{ as: master },
+	)
+	return row?.enabled ?? false
+}
+
+async function store(state: State, locked: boolean): Promise<void> {
+	await MaintenanceState.upsert(
+		{
+			where: { key },
+			create: { key, enabled: locked },
+			update: { enabled: locked },
+		},
+		{ as: master },
+	)
+	follow(state, locked)
+}
+
+/** Reads the state again; keeps the last one when it cannot. */
+async function reload(state: State): Promise<void> {
+	try {
+		follow(state, await stored())
+	} catch (error) {
+		state.logger.error(
+			{ err: error },
+			'The maintenance state could not be read: it stays as it was.',
+		)
+	}
+}
+
+const states = new WeakMap<object, State>()
+function stateOf(context: object): State {
+	const state = states.get(context)
+	if (state === undefined) throw new Error('The maintenance plugin has no api.')
+	return state
+}
+
+/** The body of `PUT /_ultimabase/maintenance`, `{ enabled }`. */
+function enabledIn(body: unknown): boolean {
+	const enabled: unknown =
+		typeof body === 'object' && body !== null
+			? Reflect.get(body, 'enabled')
+			: undefined
+	if (typeof enabled !== 'boolean') {
+		throw new PublicError(
+			'VALIDATION_FAILED',
+			'The body is { "enabled": true } or { "enabled": false }.',
+		)
+	}
+	return enabled
+}
+
+const maintenance = definePlugin<Maintenance>({
+	name: 'maintenance',
+	manifest,
+	requires: { http: httpPlugin },
+	models: [MaintenanceState],
+	api: (context) => {
+		const { plugins, options, identify, logger } = context
+		const state: State = {
+			locked: false,
+			close: () =>
+				plugins.http.closeUpgrades({ code: 1012, reason: 'Maintenance' }),
+			logger,
+		}
+		states.set(context, state)
+		const seconds = Math.ceil((options.retryAfter ?? 60_000) / 1000)
+		plugins.http.gate(async (request) => {
+			if (!state.locked || new URL(request.url).pathname === path) {
+				return undefined
+			}
+			const caller = await identify(request).catch(() => undefined)
+			if (caller?.kind === 'master') return undefined
+			return Response.json(
+				{
+					code: 'MAINTENANCE',
+					message: 'The application is under maintenance.',
+					details: { retryAfter: seconds },
+				},
+				{ 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.',
+					)
+				}
+				const enabled = enabledIn(await c.req.json().catch(() => undefined))
+				await store(state, enabled)
+				return c.json({ enabled })
+			}),
+		)
+		return {
+			lock: () => store(state, true),
+			unlock: () => store(state, false),
+			locked: () => state.locked,
+		}
+	},
+	start: async (context) => {
+		stateOf(context).locked = await stored()
+	},
+	changed: (changes, context) => {
+		if (changes.some((change) => change.model === MaintenanceState.name)) {
+			void reload(stateOf(context))
+		}
+	},
+	missed: (context) => void reload(stateOf(context)),
+})
+
+/** Maintenance, on every server at once (D-205). */
+export const maintenancePlugin: PluginOf<Maintenance> = maintenance.plugin

package/src/state.ts

@@ -0,0 +1,18 @@
+// The maintenance's one row (D-110, D-205), which no transport exposes.
+import type { Field, ModelOf } from 'ultimabase'
+import { defineModel } from 'ultimabase'
+
+type StateFields = {
+	readonly key: Field<string, { readonly unique: true }>
+	readonly enabled: Field<boolean, {}>
+}
+
+/** maintenance's own model (D-110). */
+export const MaintenanceState: ModelOf<'MaintenanceState', StateFields, []> =
+	defineModel({
+		name: 'MaintenanceState',
+		fields: (f) => ({
+			key: f.string({ unique: true }),
+			enabled: f.boolean(),
+		}),
+	})