chore(repo): prune dead code and duplicate abstractions (#3413)

fluxer_docs/package.json

@@ -25,7 +25,8 @@
 		"astro": "catalog:",
 		"send": "catalog:",
 		"sharp": "catalog:",
-		"tsx": "catalog:"
+		"tsx": "catalog:",
+		"@fluxer/constants": "workspace:*"
 	},
 	"devDependencies": {
 		"@astrojs/check": "catalog:",

fluxer_docs/scripts/DocsSource.ts

@@ -103,3 +103,17 @@ export function slugifyHeading(heading: string): string {
 		.trim()
 		.replace(/\s+/gu, '-');
 }
+
+export function stripVersion(routePath: string): string {
+	if (routePath.startsWith('/v1/')) {
+		return routePath.slice(3);
+	}
+	return routePath;
+}
+
+export function pageSlug(relativePath: string): string {
+	return relativePath
+		.replace(/\.(mdx|md)$/u, '')
+		.replace(/\/index$/u, '')
+		.replace(/^index$/u, '');
+}

fluxer_docs/scripts/StartServer.ts

@@ -5,11 +5,7 @@ import {docsListenHost, docsListenPort, docsPublicEndpoint} from '@/server/DocsC
 
 await runAstroServer({
 	entrypoint: new URL('../dist/server/entry.mjs', import.meta.url),
-	initialize: null,
 	listenHost: docsListenHost(),
 	listenPort: docsListenPort(),
 	publicEndpoint: docsPublicEndpoint(),
-	readiness: null,
-	requestLocals: null,
-	shutdown: null,
 });

fluxer_docs/scripts/VerifyDocsCoverage.ts

@@ -1,3 +1,4 @@
+import {stripVersion as stripVersionPrefix} from './DocsSource.ts';
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
 import {spawnSync} from 'node:child_process';
@@ -279,16 +280,6 @@ interface EffectiveSpecSecurity {
 	readonly allowsAnonymous: boolean;
 }
 
-function stripVersionPrefix(routePath: string): string {
-	if (routePath === '/v1') {
-		return '/';
-	}
-	if (routePath.startsWith('/v1/')) {
-		return routePath.slice(3);
-	}
-	return routePath;
-}
-
 function indexDocumentedRoutes(routes: ReadonlyArray<DocsRouteHeader>): Map<string, DocsRouteHeader> {
 	const index = new Map<string, DocsRouteHeader>();
 	for (const route of routes) {

fluxer_docs/scripts/VerifyDocsSchemas.ts

@@ -13,23 +13,25 @@ import {
 	DOCS_ROOT,
 	HTTP_METHODS,
 	type MarkdownPage,
+	pageSlug,
 	readMarkdownPages,
 	routeShape,
 	slugifyHeading,
 	splitTableRow,
+	stripVersion,
 } from './DocsSource.ts';
 
 const REPO_ROOT = fileURLToPath(new URL('../../', import.meta.url));
 const MAIN_SPEC = path.join(REPO_ROOT, 'fluxer_api/src/api/openapi/openapi.json');
 const ADMIN_SPEC = path.join(REPO_ROOT, 'fluxer_admin/openapi-admin.json');
-export interface Mismatch {
+interface Mismatch {
 	readonly page: string;
 	readonly operation: string;
 	readonly kind: string;
 	readonly detail: string;
 }
 
-export interface SchemaCounters {
+interface SchemaCounters {
 	bodyTables: number;
 	bodiesByReference: number;
 	unionBodies: number;
@@ -111,13 +113,6 @@ interface ObjectBlock {
 	readonly declaredOnly: Set<string>;
 }
 
-function stripVersion(routePath: string): string {
-	if (routePath.startsWith('/v1/')) {
-		return routePath.slice(3);
-	}
-	return routePath;
-}
-
 function resolveSchemaPointer(spec: Spec, reference: string): SchemaNode | boolean {
 	if (!reference.startsWith('#')) throw new Error(`Unsupported schema reference: ${reference}`);
 	const pointer = decodeURIComponent(reference.slice(1));
@@ -384,13 +379,6 @@ function operationIndex(spec: Spec): Map<string, Operation> {
 	return index;
 }
 
-function pageSlug(relativePath: string): string {
-	return relativePath
-		.replace(/\.(mdx|md)$/u, '')
-		.replace(/\/index$/u, '')
-		.replace(/^index$/u, '');
-}
-
 function documentReferences(page: string, line: string): Set<string> {
 	const references = new Set<string>();
 	for (const link of line.matchAll(/\]\(([^)\s]*)#([a-z0-9-]+)\)/gu)) {

fluxer_docs/scripts/VerifyDocsSidebar.ts

@@ -3,7 +3,7 @@
 import {readFile} from 'node:fs/promises';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
-import {DOCS_ROOT, listDraftMarkdownFiles, listMarkdownFiles, slugifyHeading} from './DocsSource.ts';
+import {DOCS_ROOT, listDraftMarkdownFiles, listMarkdownFiles, pageSlug, slugifyHeading} from './DocsSource.ts';
 
 const ASTRO_CONFIG = fileURLToPath(new URL('../astro.config.ts', import.meta.url));
 
@@ -11,15 +11,6 @@ const SIDEBAR_START = 'sidebar: [';
 const QUOTED_ENTRY = /'([^']+)'/gu;
 const LINK_ENTRY = /link:\s*'([^']+)'/gu;
 
-function slugOf(file: string): string {
-	const relative = path.relative(DOCS_ROOT, file);
-	const withoutExtension = relative.replace(/\.(mdx|md)$/u, '');
-	if (withoutExtension === 'index') {
-		return '';
-	}
-	return withoutExtension.replace(/\/index$/u, '');
-}
-
 function sidebarBlock(source: string): string {
 	const start = source.indexOf(SIDEBAR_START);
 	if (start === -1) {
@@ -70,7 +61,7 @@ for (const match of block.matchAll(QUOTED_ENTRY)) {
 }
 
 const files = await listMarkdownFiles(DOCS_ROOT);
-const actual = new Set(files.map(slugOf));
+const actual = new Set(files.map((file) => pageSlug(path.relative(DOCS_ROOT, file))));
 
 const missingPages = [...referenced].filter((slug) => !actual.has(slug)).sort();
 const orphanPages = [...actual].filter((slug) => !referenced.has(slug)).sort();
@@ -107,7 +98,7 @@ const anchorable = new Set(actual);
 const anchorsByPage = new Map<string, Set<string>>();
 const ambiguousByPage = new Map<string, Set<string>>();
 for (const file of files) {
-	const slug = slugOf(file);
+	const slug = pageSlug(path.relative(DOCS_ROOT, file));
 	const source = await readFile(file, 'utf8');
 	const anchors = new Set<string>();
 	const counts = new Map<string, number>();
@@ -134,7 +125,7 @@ for (const file of files) {
 
 for (const file of files) {
 	const relative = path.relative(DOCS_ROOT, file);
-	const selfSlug = slugOf(file);
+	const selfSlug = pageSlug(path.relative(DOCS_ROOT, file));
 	const source = await readFile(file, 'utf8');
 	for (const match of source.matchAll(INTERNAL_LINK)) {
 		const target = match[1].replace(/^\//u, '').replace(/\/$/u, '');

fluxer_docs/src/content/docs/http-api/errors.md

@@ -174,10 +174,6 @@ You're already friends with this user
 
 This action is only available in announcement channels
 
-### `APPLICATION_NOT_OWNED`
-
-You don't own this application
-
 ### `BAD_GATEWAY`
 
 Bad gateway

fluxer_docs/src/content/docs/operator/configuration.mdx

@@ -1132,10 +1132,6 @@ Falls back to `FLUXER_GATEWAY_LOGGER_LEVEL`. The Gateway log level at runtime. O
 
 Default `dev`. The reported build. Baked into the images, so Compose does not set it. When `BUILD_VERSION` is unset or empty outside development, the process prints a warning.
 
-#### `RELEASE_CHANNEL`
-
-Default `stable`. The reported channel. Only `canary` is recognised as non-stable. Read by `app-proxy` only. It describes the shipped build, so Compose does not set it.
-
 #### `HOSTNAME`
 
 Set by Docker. Node identity in metrics and logs.
@@ -1746,7 +1742,7 @@ Compose writes each of these from the `.env` name given, so setting the name its
 
 #### Build and platform metadata
 
-`BUILD_VERSION`, `FLUXER_BUILD_VERSION` and `RELEASE_CHANNEL` describe the shipped build. `POD_NAME` and `HOSTNAME` come from the platform.
+`BUILD_VERSION` and `FLUXER_BUILD_VERSION` describe the shipped build. `POD_NAME` and `HOSTNAME` come from the platform.
 
 #### Test and development switches
 

fluxer_docs/src/server/AstroServer.ts

@@ -4,16 +4,15 @@ import {lstat} from 'node:fs/promises';
 import {createServer, type IncomingMessage, type Server, type ServerResponse} from 'node:http';
 import path from 'node:path';
 import {fileURLToPath} from 'node:url';
+import {HttpStatus, MimeType} from '@fluxer/constants/src/HttpConstants';
 import send from 'send';
-import {type AstroServerShutdown, AstroServerTermination} from '@/server/AstroServerTermination';
+import {AstroServerTermination} from '@/server/AstroServerTermination';
 import {
 	CanonicalNetworkProtocol,
 	getNodeErrorCode,
 	HTTPHeader,
 	HTTPMethod,
-	HTTPStatusCode,
 	isCanonicalHTTPNetworkProtocol,
-	MIMEType,
 	NodeErrorCode,
 	OUTBOUND_USER_AGENT,
 } from '@/server/HTTPConstants';
@@ -21,7 +20,6 @@ import {siteSecurityHeaders} from '@/server/SecurityHeaders';
 
 const HEALTH_PATH = '/_health';
 const HEALTH_RESPONSE_BODY = JSON.stringify({status: 'ok'});
-const NOT_READY_RESPONSE_BODY = JSON.stringify({status: 'not_ready'});
 const WELL_KNOWN_PATH_PREFIX = '.well-known/';
 const IMMUTABLE_ASSET_PATH_PREFIX = '_astro/';
 const PARENT_SEGMENT_PATTERN = /(?:^|[\\/])\.\.(?:[\\/]|$)/u;
@@ -41,11 +39,10 @@ const ASTRO_SERVER_KEEP_ALIVE_TIMEOUT_MS = 5_000;
 const ASTRO_SERVER_SOCKET_TIMEOUT_MS = 30_000;
 const ALLOWED_SITE_METHODS = `${HTTPMethod.GET}, ${HTTPMethod.HEAD}`;
 const NO_STORE_CACHE_CONTROL = 'no-store';
-const TEXT_CONTENT_TYPE = `${MIMEType.PLAIN}; charset=utf-8`;
+const TEXT_CONTENT_TYPE = `${MimeType.PLAIN}; charset=utf-8`;
 
 const AstroServerStartupPhase = Object.freeze({
 	ENTRYPOINT: 'entrypoint load',
-	INITIALIZE: 'initialization',
 	LISTEN: 'listener bind',
 } as const);
 
@@ -87,21 +84,11 @@ interface ResolvedPublicEndpoint {
 	readonly secureOrigin: boolean;
 }
 
-type AstroServerInitialize = () => Promise<void>;
-
-type AstroServerReadiness = () => boolean;
-
-type AstroServerRequestLocals = () => object;
-
 interface AstroServerOptions {
 	readonly entrypoint: URL;
-	readonly initialize: AstroServerInitialize | null;
 	readonly listenHost: string;
 	readonly listenPort: number;
 	readonly publicEndpoint: string;
-	readonly readiness: AstroServerReadiness | null;
-	readonly requestLocals: AstroServerRequestLocals | null;
-	readonly shutdown: AstroServerShutdown | null;
 }
 
 interface AstroServerHealthcheckOptions {
@@ -302,36 +289,21 @@ async function resolveStaticFile(clientDirectory: string, staticPath: string): P
 	return {isDirectory, normalizedPath};
 }
 
-function respondToHealthcheck(
-	request: IncomingMessage,
-	requestURL: URL,
-	response: ServerResponse,
-	readiness: AstroServerReadiness | null,
-): boolean {
+function respondToHealthcheck(request: IncomingMessage, requestURL: URL, response: ServerResponse): boolean {
 	if (requestURL.pathname !== HEALTH_PATH) {
 		return false;
 	}
-	if (isAstroServerReady(readiness)) {
-		return writeHealthcheckResponse(request, response, HTTPStatusCode.OK, HEALTH_RESPONSE_BODY);
-	}
-	return writeHealthcheckResponse(request, response, HTTPStatusCode.SERVICE_UNAVAILABLE, NOT_READY_RESPONSE_BODY);
-}
-
-function isAstroServerReady(readiness: AstroServerReadiness | null): boolean {
-	if (readiness == null) {
-		return true;
-	}
-	return readiness();
+	return writeHealthcheckResponse(request, response, HttpStatus.OK, HEALTH_RESPONSE_BODY);
 }
 
 function writeHealthcheckResponse(
 	request: IncomingMessage,
 	response: ServerResponse,
-	status: HTTPStatusCode,
+	status: number,
 	body: string,
 ): boolean {
 	response.writeHead(status, {
-		[HTTPHeader.CONTENT_TYPE]: MIMEType.JSON,
+		[HTTPHeader.CONTENT_TYPE]: MimeType.JSON,
 		[HTTPHeader.CONTENT_LENGTH]: Buffer.byteLength(body).toString(),
 		[HTTPHeader.CACHE_CONTROL]: NO_STORE_CACHE_CONTROL,
 	});
@@ -343,12 +315,7 @@ function writeHealthcheckResponse(
 	return true;
 }
 
-function writeTextResponse(
-	request: IncomingMessage,
-	response: ServerResponse,
-	status: HTTPStatusCode,
-	body: string,
-): void {
+function writeTextResponse(request: IncomingMessage, response: ServerResponse, status: number, body: string): void {
 	response.writeHead(status, {
 		[HTTPHeader.CONTENT_TYPE]: TEXT_CONTENT_TYPE,
 		[HTTPHeader.CONTENT_LENGTH]: Buffer.byteLength(body).toString(),
@@ -361,7 +328,7 @@ function writeTextResponse(
 	response.end(body);
 }
 
-function writeEmptyResponse(response: ServerResponse, status: HTTPStatusCode): void {
+function writeEmptyResponse(response: ServerResponse, status: number): void {
 	response.writeHead(status, {
 		[HTTPHeader.CONTENT_LENGTH]: '0',
 		[HTTPHeader.CACHE_CONTROL]: NO_STORE_CACHE_CONTROL,
@@ -369,7 +336,7 @@ function writeEmptyResponse(response: ServerResponse, status: HTTPStatusCode): v
 	response.end();
 }
 
-function rejectRequest(response: ServerResponse, status: HTTPStatusCode, allow: string | null): void {
+function rejectRequest(response: ServerResponse, status: number, allow: string | null): void {
 	response.shouldKeepAlive = false;
 	response.setHeader(HTTPHeader.CONTENT_LENGTH, '0');
 	response.setHeader(HTTPHeader.CACHE_CONTROL, NO_STORE_CACHE_CONTROL);
@@ -409,13 +376,12 @@ function sendFailure(request: IncomingMessage, response: ServerResponse, error:
 		response.destroy(resolvedError);
 		return;
 	}
-	writeTextResponse(request, response, HTTPStatusCode.INTERNAL_SERVER_ERROR, 'Internal server error');
+	writeTextResponse(request, response, HttpStatus.INTERNAL_SERVER_ERROR, 'Internal server error');
 }
 
 interface AstroHandlerRequest {
 	readonly handler: AstroRequestHandler;
 	readonly request: IncomingMessage;
-	readonly requestLocals: AstroServerRequestLocals | null;
 	readonly response: ServerResponse;
 }
 
@@ -425,22 +391,18 @@ interface StaticOrRenderRequest extends AstroHandlerRequest {
 	readonly requestURL: URL;
 }
 
-async function runAstroHandler({handler, request, requestLocals, response}: AstroHandlerRequest): Promise<void> {
+async function runAstroHandler({handler, request, response}: AstroHandlerRequest): Promise<void> {
 	const next = (error: unknown): void => {
 		if (error != null) {
 			sendFailure(request, response, error);
 			return;
 		}
 		if (!response.writableEnded) {
-			writeEmptyResponse(response, HTTPStatusCode.NOT_FOUND);
+			writeEmptyResponse(response, HttpStatus.NOT_FOUND);
 		}
 	};
 	try {
-		if (requestLocals == null) {
-			await handler(request, response, next, {});
-			return;
-		}
-		await handler(request, response, next, requestLocals());
+		await handler(request, response, next, {});
 	} catch (error) {
 		sendFailure(request, response, error);
 	}
@@ -456,21 +418,20 @@ async function serveStaticOrRender({
 	basePath,
 	request,
 	requestURL,
-	requestLocals,
 	response,
 }: StaticOrRenderRequest): Promise<void> {
 	const requestPath = resolveStaticRequestPath(request, requestURL, basePath);
 	if (requestPath == null) {
-		await runAstroHandler({handler, request, requestLocals, response});
+		await runAstroHandler({handler, request, response});
 		return;
 	}
 	const staticFile = await resolveStaticFile(clientDirectory, requestPath.staticPath);
 	if (staticFile == null) {
-		writeTextResponse(request, response, HTTPStatusCode.BAD_REQUEST, 'Bad request');
+		writeTextResponse(request, response, HttpStatus.BAD_REQUEST, 'Bad request');
 		return;
 	}
 	if (shouldRedirectStaticDirectory(staticFile, requestPath)) {
-		response.writeHead(HTTPStatusCode.MOVED_PERMANENTLY, {
+		response.writeHead(HttpStatus.MOVED_PERMANENTLY, {
 			[HTTPHeader.LOCATION]: `${requestPath.pathname}/${requestPath.search}`,
 			[HTTPHeader.CONTENT_LENGTH]: '0',
 			[HTTPHeader.CACHE_CONTROL]: 'no-cache',
@@ -505,7 +466,7 @@ async function serveStaticOrRender({
 	});
 	stream.on('error', (error) => {
 		if (!fileOpened) {
-			runAstroHandler({handler, request, requestLocals, response}).catch((handlerError: unknown) => {
+			runAstroHandler({handler, request, response}).catch((handlerError: unknown) => {
 				sendFailure(request, response, handlerError);
 			});
 			return;
@@ -551,10 +512,6 @@ export async function runAstroServer(options: AstroServerOptions): Promise<void>
 	process.on('beforeExit', requireStartupProgress);
 	try {
 		const entrypoint = await loadServerEntrypoint(options.entrypoint);
-		if (options.initialize != null) {
-			startupPhase = AstroServerStartupPhase.INITIALIZE;
-			await options.initialize();
-		}
 		const clientDirectory = fileURLToPath(new URL('../client/', options.entrypoint));
 		let activeRequests = 0;
 		const handleRequest = (request: IncomingMessage, response: ServerResponse): void => {
@@ -563,22 +520,22 @@ export async function runAstroServer(options: AstroServerOptions): Promise<void>
 			}
 			const parsedRequestURL = requestURL(request);
 			if (parsedRequestURL == null) {
-				rejectRequest(response, HTTPStatusCode.BAD_REQUEST, null);
+				rejectRequest(response, HttpStatus.BAD_REQUEST, null);
 				return;
 			}
 			if (request.method !== HTTPMethod.GET && request.method !== HTTPMethod.HEAD) {
-				rejectRequest(response, HTTPStatusCode.METHOD_NOT_ALLOWED, ALLOWED_SITE_METHODS);
+				rejectRequest(response, HttpStatus.METHOD_NOT_ALLOWED, ALLOWED_SITE_METHODS);
 				return;
 			}
 			if (requestDeclaresBody(request)) {
-				rejectRequest(response, HTTPStatusCode.PAYLOAD_TOO_LARGE, null);
+				rejectRequest(response, HttpStatus.PAYLOAD_TOO_LARGE, null);
 				return;
 			}
-			if (respondToHealthcheck(request, parsedRequestURL, response, options.readiness)) {
+			if (respondToHealthcheck(request, parsedRequestURL, response)) {
 				return;
 			}
 			if (activeRequests >= ASTRO_SERVER_MAX_ACTIVE_REQUESTS) {
-				rejectRequest(response, HTTPStatusCode.SERVICE_UNAVAILABLE, null);
+				rejectRequest(response, HttpStatus.SERVICE_UNAVAILABLE, null);
 				return;
 			}
 			activeRequests += 1;
@@ -598,7 +555,6 @@ export async function runAstroServer(options: AstroServerOptions): Promise<void>
 				basePath,
 				request,
 				requestURL: parsedRequestURL,
-				requestLocals: options.requestLocals,
 				response,
 			}).catch((error: unknown) => {
 				sendFailure(request, response, error);
@@ -620,7 +576,6 @@ export async function runAstroServer(options: AstroServerOptions): Promise<void>
 		new AstroServerTermination({
 			closeListener: () => closeServerListener(server),
 			serverName: ASTRO_SERVER_NAME,
-			shutdown: options.shutdown,
 			timeoutMs: ASTRO_SERVER_SHUTDOWN_TIMEOUT_MS,
 		}).install();
 		startupPhase = AstroServerStartupPhase.LISTEN;

fluxer_docs/src/server/AstroServerTermination.ts

@@ -1,11 +1,8 @@
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
-export type AstroServerShutdown = () => Promise<void>;
-
 interface AstroServerTerminationDependencies {
 	readonly closeListener: () => Promise<void>;
 	readonly serverName: string;
-	readonly shutdown: AstroServerShutdown | null;
 	readonly timeoutMs: number;
 }
 
@@ -64,15 +61,6 @@ export class AstroServerTermination {
 		} catch (cleanupFailure) {
 			failures.push(cleanupFailure);
 		}
-		const shutdown = this.dependencies.shutdown;
-		if (shutdown == null) {
-			return failures;
-		}
-		try {
-			await shutdown();
-		} catch (cleanupFailure) {
-			failures.push(cleanupFailure);
-		}
 		return failures;
 	}
 }

fluxer_docs/src/server/HTTPConstants.ts

@@ -7,24 +7,6 @@ export const HTTPMethod = Object.freeze({
 
 export type HTTPMethod = (typeof HTTPMethod)[keyof typeof HTTPMethod];
 
-export const HTTPStatusCode = Object.freeze({
-	OK: 200,
-	MOVED_PERMANENTLY: 301,
-	BAD_REQUEST: 400,
-	NOT_FOUND: 404,
-	METHOD_NOT_ALLOWED: 405,
-	PAYLOAD_TOO_LARGE: 413,
-	INTERNAL_SERVER_ERROR: 500,
-	SERVICE_UNAVAILABLE: 503,
-} as const);
-
-export type HTTPStatusCode = (typeof HTTPStatusCode)[keyof typeof HTTPStatusCode];
-
-export const MIMEType = Object.freeze({
-	JSON: 'application/json',
-	PLAIN: 'text/plain',
-} as const);
-
 export const HTTPHeader = Object.freeze({
 	ALLOW: 'Allow',
 	CACHE_CONTROL: 'Cache-Control',