@harperfast/harper 5.2.13 → 5.3.0-beta.1

package/server/loadRootComponents.js

@@ -1,19 +1,62 @@
 const { isMainThread } = require('worker_threads');
 const { getTables } = require('../resources/databases.ts');
-const { loadComponentDirectories, loadComponent } = require('../components/componentLoader.ts');
+const { loadComponentDirectories, loadComponent, readyComponentModules } = require('../components/componentLoader.ts');
 const { resetResources } = require('../resources/Resources.ts');
 const configUtils = require('../config/configUtils.ts');
 const { dirname } = require('path');
 const { loadCertificates } = require('../security/keys.ts');
-const { installApplications } = require('../components/Application.ts');
+const { installApplications, recoverInterruptedActivations } = require('../components/Application.ts');
 const { errorForLog } = require('../utility/logging/harper_logger.ts');
+const { CONFIG_PARAMS } = require('../utility/hdbTerms.ts');
 
 let loadedComponents = new Map();
+
+/**
+ * Map every component directory to the reason activation recovery could not run. Used only when the scan
+ * fails globally, where the safe answer is "none of these are known-good" rather than "all of these are".
+ */
+async function failEveryComponentClosed(cause) {
+	const failures = new Map();
+	const reason = cause instanceof Error ? cause : new Error(`Activation recovery could not run: ${String(cause)}`);
+	try {
+		const { readdir } = require('node:fs/promises');
+		const componentsRoot = configUtils.getConfigPath(CONFIG_PARAMS.COMPONENTSROOT);
+		for (const entry of await readdir(componentsRoot, { withFileTypes: true })) {
+			if (!entry.name.startsWith('.') && (entry.isDirectory() || entry.isSymbolicLink())) {
+				failures.set(entry.name, reason);
+			}
+		}
+	} catch (error) {
+		console.error(errorForLog(error));
+	}
+	return failures;
+}
 /**
  * This is main entry point for loading the main set of global server modules that power Harper.
  * @returns {Promise<void>}
  */
 async function loadRootComponents(isWorkerThread = false) {
+	// Interrupted activations are settled FIRST, before installApplications() — not merely before the
+	// component scan. installApplications() installs whatever the root config names, so a candidate left
+	// half-swapped by a crash has to be resolved before that runs, or boot reinstalls over it. Failures are
+	// per component and returned, not thrown: the loader fails those components closed and loads the rest.
+	// Undefined, not an empty Map: a worker skips this branch entirely, and handing the loader an empty map
+	// would assert "nothing is unreconciled" on a thread that never checked. The loader treats undefined as
+	// "no verdict from boot" instead.
+	let interruptedActivationFailures;
+	try {
+		if (isMainThread && !process.env.HARPER_SAFE_MODE) {
+			interruptedActivationFailures = await recoverInterruptedActivations(
+				configUtils.getConfigPath(CONFIG_PARAMS.COMPONENTSROOT)
+			);
+		}
+	} catch (error) {
+		// The scan itself failed, so WHICH components are unsettled is unknown — loading them all would
+		// defeat the fail-closed contract this pass exists for. Every component present is failed closed
+		// instead, and a later reload cycle retries once the cause is gone.
+		console.error(errorForLog(error));
+		interruptedActivationFailures = await failEveryComponentClosed(error);
+	}
 	try {
 		if (isMainThread && !process.env.HARPER_SAFE_MODE) await installApplications();
 	} catch (error) {
@@ -33,13 +76,12 @@ async function loadRootComponents(isWorkerThread = false) {
 	});
 	if (!process.env.HARPER_SAFE_MODE) {
 		// once the global plugins are loaded, we now load all the CF and run applications (and their components)
-		await loadComponentDirectories(loadedComponents, resources);
-	}
-	let allReady = [];
-	for (let [serverModule] of loadedComponents) {
-		if (serverModule.ready) allReady.push(serverModule.ready());
+		const readyComponentPromises = new WeakMap();
+		await loadComponentDirectories(loadedComponents, resources, readyComponentPromises, interruptedActivationFailures);
+		await readyComponentModules(loadedComponents.keys(), readyComponentPromises);
+		return;
 	}
-	if (allReady.length > 0) await Promise.all(allReady);
+	await readyComponentModules(loadedComponents.keys());
 }
 
 module.exports.loadRootComponents = loadRootComponents;

package/server/mqtt.ts

@@ -3,7 +3,13 @@
 import { parser as makeParser, generate } from 'mqtt-packet';
 import { getSession, DurableSubscriptionsSession } from './DurableSubscriptionsSession.ts';
 import { getSuperUser } from '../security/user.ts';
-import { serializeMessage, getDeserializer } from './serverHelpers/contentTypes.ts';
+import { getDeserializer } from './serverHelpers/contentTypes.ts';
+import {
+	getSharedMessageEncoding,
+	getSharedFrame,
+	setSharedFrame,
+	resolveSharedPayload,
+} from './serverHelpers/sharedMessageEncoding.ts';
 import { recordAction, addAnalyticsListener, recordActionBinary } from '../resources/analytics/write.ts';
 import { server } from '../server/Server.ts';
 import { get } from '../utility/environment/environmentManager.ts';
@@ -12,6 +18,14 @@ import { loggerWithTag } from '../utility/logging/logger.ts';
 import { forComponent as loggerForComponent } from '../utility/logging/harper_logger.ts';
 import { EventEmitter } from 'events';
 import { verifyCertificate } from '../security/certificateVerification/index.ts';
+import { registerShutdownDrain } from '../components/shutdownDrain.ts';
+import {
+	assertNoDeferredCredentialRejection,
+	getDeferredCredentialRejection,
+} from '../security/deferredAuthentication.ts';
+
+/** RFC 6455 private-use close code Harper already maps HTTP 401 to (see server/REST.ts). */
+const WEBSOCKET_UNAUTHORIZED_CLOSE_CODE = 3000;
 const authEventLog = loggerWithTag('auth-event');
 const mqttLog = loggerForComponent('mqtt');
 
@@ -40,6 +54,7 @@ export function handleApplication(scope: import('../components/Scope.ts').Scope)
 		};
 		// a no-op error handler to prevent unhandled error events from being rethrown
 		(server as any).mqtt.events.on('error', () => {});
+		registerShutdownDisconnect();
 	}
 	const mqttSettings = (server as any).mqtt;
 	function emitEvent(type: string, ...args: any[]) {
@@ -60,13 +75,29 @@ export function handleApplication(scope: import('../components/Scope.ts').Scope)
 
 				emitEvent('connection', ws);
 				mqttLog.debug?.('Received WebSocket connection for MQTT from', ws._socket.remoteAddress);
+				// Both WebSocket entry points invoke this listener synchronously with the HTTP chain still
+				// pending (server/http.ts), so authentication has not recorded a credential rejection yet.
+				// It settles on the same promise the session principal comes from, which onSocket awaits
+				// before it processes any packet — the handlers below still attach synchronously, so no
+				// frame that arrives in the meantime is dropped.
+				const authenticated = Promise.resolve(chainCompletion).then(() => {
+					assertNoDeferredCredentialRejection(request);
+					return request?.user;
+				});
+				authenticated.catch((error) => {
+					mqttLog.info?.('Closing MQTT WebSocket connection, authentication was rejected', error);
+					ws.close(
+						WEBSOCKET_UNAUTHORIZED_CLOSE_CODE,
+						getDeferredCredentialRejection(request)?.message ?? 'Unauthorized'
+					);
+				});
 				const { onMessage, onClose } = onSocket(
 					ws,
 					(message) => {
 						ws.send(message);
 					},
 					request,
-					Promise.resolve(chainCompletion).then(() => request?.user),
+					authenticated,
 					mqttSettings
 				);
 				ws.on('message', onMessage);
@@ -168,6 +199,50 @@ export function handleApplication(scope: import('../components/Scope.ts').Scope)
 		);
 	}
 }
+const SERVER_SHUTTING_DOWN = 0x8b; // MQTT v5 DISCONNECT reason code
+const REASON_STRING_LIMIT = 256; // bytes
+/** Fixed header, message id and reason code, plus the property identifier and its length prefix. */
+const ACK_PACKET_OVERHEAD = 16;
+
+/**
+ * Every live MQTT connection on this worker, so a shutdown can announce itself: a bare socket close
+ * is indistinguishable to the client from a network failure.
+ */
+const liveConnections = new Set<{ protocolVersion: () => number; send: (data: any) => void; close: () => void }>();
+let shutdownDisconnectRegistered = false;
+
+/** v3.1.1 has no server-to-client DISCONNECT, so those connections are only closed. */
+export function disconnectClientsForShutdown() {
+	if (liveConnections.size === 0) return;
+	const disconnectPacket = generate({ cmd: 'disconnect', reasonCode: SERVER_SHUTTING_DOWN } as any, {
+		protocolVersion: 5,
+	});
+	for (const connection of liveConnections) {
+		try {
+			if (connection.protocolVersion() >= 5) connection.send(disconnectPacket);
+		} catch (error) {
+			mqttLog.debug?.('Could not notify MQTT connection of shutdown', error);
+		} finally {
+			try {
+				connection.close();
+			} catch (error) {
+				mqttLog.debug?.('Could not close MQTT connection during shutdown', error);
+			}
+		}
+	}
+	liveConnections.clear();
+}
+
+function registerShutdownDisconnect() {
+	if (shutdownDisconnectRegistered) return;
+	shutdownDisconnectRegistered = true;
+	registerShutdownDrain({
+		// Notifying clients is bounded and synchronous; it must never extend the shutdown deadline.
+		hasWork: () => false,
+		drain: async () => disconnectClientsForShutdown(),
+	});
+}
+
 let addingMetrics,
 	numberOfConnections = 0;
 function onSocket(socket, send, request, user, mqttSettings) {
@@ -191,7 +266,17 @@ function onSocket(socket, send, request, user, mqttSettings) {
 	}
 	let disconnected;
 	numberOfConnections++;
+	const connection = {
+		protocolVersion: () => mqttOptions.protocolVersion,
+		send,
+		close: () => (socket.close ? socket.close() : socket.end()),
+	};
+	liveConnections.add(connection);
 	let session: DurableSubscriptionsSession;
+	// [MQTT-3.1.2-29]: a client that asks for no problem information must not be sent a reason
+	// string on a PUBACK/PUBREC, and [MQTT-3.1.2-24] caps what it will accept at all.
+	let sendProblemInformation = true;
+	let maximumPacketSize: number | undefined;
 	const mqttOptions = { protocolVersion: 4 };
 	const parser = makeParser({ protocolVersion: 5 });
 	function onMessage(data) {
@@ -199,6 +284,7 @@ function onSocket(socket, send, request, user, mqttSettings) {
 	}
 	function onClose() {
 		numberOfConnections--;
+		liveConnections.delete(connection);
 		if (!disconnected) {
 			disconnected = true;
 			session?.disconnect?.(false);
@@ -236,6 +322,10 @@ function onSocket(socket, send, request, user, mqttSettings) {
 			switch (command) {
 				case 'connect':
 					mqttOptions.protocolVersion = packet.protocolVersion;
+					// mqtt-packet parses this byte into a boolean, and a client may also send the raw 0.
+					const requestProblemInformation = packet.properties?.requestProblemInformation;
+					sendProblemInformation = requestProblemInformation !== false && requestProblemInformation !== 0;
+					maximumPacketSize = packet.properties?.maximumPacketSize;
 					if (packet.username) {
 						try {
 							user = await server.getUser(packet.username, packet.password.toString(), request);
@@ -260,7 +350,7 @@ function onSocket(socket, send, request, user, mqttSettings) {
 							}
 							emitEvent('auth-failed', packet, socket, error);
 							recordActionBinary(false, 'connection', 'mqtt', 'connect');
-							return sendPacket({
+							return generateAndSendPacket({
 								// Send a connection acknowledgment with indication of auth failure
 								cmd: 'connack',
 								reasonCode: 0x04, // bad username or password, v3.1.1
@@ -271,7 +361,7 @@ function onSocket(socket, send, request, user, mqttSettings) {
 					if (!user && mqttSettings.requireAuthentication) {
 						emitEvent('auth-failed', packet, socket);
 						recordActionBinary(false, 'connection', 'mqtt', 'connect');
-						return sendPacket({
+						return generateAndSendPacket({
 							// Send a connection acknowledgment with indication of auth failure
 							cmd: 'connack',
 							reasonCode: 0x04, // bad username or password, v3.1.1
@@ -307,7 +397,7 @@ function onSocket(socket, send, request, user, mqttSettings) {
 						mqttLog.error?.(error);
 						emitEvent('auth-failed', packet, socket, error);
 						recordActionBinary(false, 'connection', 'mqtt', 'connect');
-						return sendPacket({
+						return generateAndSendPacket({
 							// Send a connection acknowledgment with indication of auth failure
 							cmd: 'connack',
 							reasonCode: error.code || 0x05,
@@ -316,28 +406,55 @@ function onSocket(socket, send, request, user, mqttSettings) {
 					}
 					emitEvent('connected', session, socket);
 					recordActionBinary(true, 'connection', 'mqtt', 'connect');
-					sendPacket({
+					generateAndSendPacket({
 						// Send a connection acknowledgment
 						cmd: 'connack',
 						sessionPresent: session.sessionWasPresent,
 						reasonCode: 0,
 						returnCode: 0, // success
 					});
-					const listener = async (topic, message, messageId, subscription) => {
+					const listener = async (topic, message, messageId, subscription, version) => {
 						try {
 							if (disconnected) throw new Error('Session disconnected while trying to send message to', topic);
 							const slashIndex = topic.indexOf('/', 1);
 							const generalTopic = slashIndex > 0 ? topic.slice(0, slashIndex) : topic;
-							sendPacket(
-								{
+							const qos = subscription.qos || 0;
+							// Every subscriber of a topic serializes the same message to the same bytes, so the
+							// payload is encoded once per (message, content type) and reused across all of them.
+							const encoding = getSharedMessageEncoding(message, request, version);
+							const encoded = encoding.payload;
+							// only pay for a microtask when the serialization is genuinely still pending
+							const payload =
+								typeof (encoded as any)?.then === 'function'
+									? await resolveSharedPayload(encoding, message, request, version)
+									: (encoded as Buffer | string);
+							if (qos > 0) {
+								// mqtt-packet requires a numeric message identifier once qos is non-zero
+								const packetData: any = {
 									cmd: 'publish',
 									topic,
-									payload: await serialize(message),
+									payload,
 									messageId: messageId || Math.floor(Math.random() * 100000000),
-									qos: subscription.qos,
-								},
-								generalTopic
-							);
+									qos,
+								};
+								sendPacket(generate(packetData, mqttOptions), packetMethodName(packetData), generalTopic);
+							} else {
+								// A QoS 0 PUBLISH carries no message identifier, so the whole packet depends only on
+								// the payload, the topic, and the protocol version (v5 emits a properties field that
+								// v3.1.1 omits) — share it across every QoS 0 subscriber that matches on those.
+								// The frame also varies on dup/retain/properties, which are fixed below; anything
+								// that starts varying them per subscriber (RETAIN propagation, v5 subscription
+								// identifiers) has to join the key or subscribers will be served the wrong flags.
+								const protocolVersion = mqttOptions.protocolVersion;
+								let packet = getSharedFrame(encoding, protocolVersion, topic);
+								if (packet === undefined) {
+									packet = generate({ cmd: 'publish', topic, payload, qos: 0, dup: false, retain: false }, mqttOptions);
+									// only worth retaining once a second subscriber has shown up; caching a packet
+									// for a fan-out of one just pins a whole buffer nothing will read
+									if (encoding.hits > 0) setSharedFrame(encoding, protocolVersion, topic, packet);
+								}
+								sendPacket(packet, 'publish', generalTopic);
+							}
 							// wait if there is back-pressure
 							const rawSocket = socket._socket ?? socket;
 							if (rawSocket.writableNeedDrain) {
@@ -351,7 +468,7 @@ function onSocket(socket, send, request, user, mqttSettings) {
 							return false;
 						}
 					};
-					session.setListener(listener as any);
+					session.setListener(listener);
 					if (session.sessionWasPresent) await session.resume();
 					break;
 				case 'subscribe':
@@ -383,7 +500,7 @@ function onSocket(socket, send, request, user, mqttSettings) {
 						granted.push(grantedQos);
 					}
 					await session.committed;
-					sendPacket({
+					generateAndSendPacket({
 						// Send a subscription acknowledgment
 						cmd: 'suback',
 						granted,
@@ -395,7 +512,7 @@ function onSocket(socket, send, request, user, mqttSettings) {
 					for (const subscription of packet.unsubscriptions) {
 						granted.push(session.removeSubscription(subscription) ? 0 : 17);
 					}
-					sendPacket({
+					generateAndSendPacket({
 						// Send a subscription acknowledgment
 						cmd: 'unsuback',
 						granted,
@@ -404,7 +521,7 @@ function onSocket(socket, send, request, user, mqttSettings) {
 					break;
 				}
 				case 'pubrel':
-					sendPacket({
+					generateAndSendPacket({
 						// Send a publish response
 						cmd: 'pubcomp',
 						messageId: packet.messageId,
@@ -426,20 +543,44 @@ function onSocket(socket, send, request, user, mqttSettings) {
 						emitEvent('error', error, socket, packet, session);
 						mqttLog.warn?.(error);
 						if (packet.qos > 0) {
-							sendPacket(
-								{
-									// Send a publish acknowledgment
-									cmd: responseCmd,
-									messageId: packet.messageId,
-									reasonCode: 0x80, // unspecified error (only MQTT v5 supports error codes)
-								},
-								packet.topic
-							);
+							// A publish to a topic no resource handles is the same miss addSubscription already
+							// answers with a specific code; reporting it as "unspecified error" leaves it
+							// indistinguishable from an internal failure.
+							const publishPacket: any = {
+								// Send a publish acknowledgment
+								cmd: responseCmd,
+								messageId: packet.messageId,
+								reasonCode:
+									mqttOptions.protocolVersion < 5
+										? 0x80 // the only error code in v3.1.1
+										: error?.statusCode === 403
+											? 0x87 // not authorized
+											: error?.statusCode === 404
+												? 0x90 // topic name invalid
+												: 0x80, // unspecified error
+							};
+							// Only errors this layer maps to a code of their own are safe to describe: any other
+							// failure carries an internal message that a client must not be handed. Both limits
+							// are in encoded bytes, so measure and trim the string in bytes too.
+							const describable =
+								mqttOptions.protocolVersion >= 5 &&
+								sendProblemInformation &&
+								error?.message &&
+								(error.statusCode === 403 || error.statusCode === 404);
+							const reasonString = describable
+								? Buffer.from(String(error.message), 'utf8').subarray(0, REASON_STRING_LIMIT).toString('utf8')
+								: undefined;
+							if (
+								reasonString &&
+								(!maximumPacketSize || maximumPacketSize >= Buffer.byteLength(reasonString) + ACK_PACKET_OVERHEAD)
+							)
+								publishPacket.properties = { reasonString };
+							generateAndSendPacket(publishPacket, packet.topic);
 						}
 						break;
 					}
 					if (packet.qos > 0) {
-						sendPacket(
+						generateAndSendPacket(
 							{
 								// Send a publish acknowledgment
 								cmd: responseCmd,
@@ -454,7 +595,7 @@ function onSocket(socket, send, request, user, mqttSettings) {
 					}
 					break;
 				case 'pubrec':
-					sendPacket({
+					generateAndSendPacket({
 						// Send a publish response
 						cmd: 'pubrel',
 						messageId: packet.messageId,
@@ -467,7 +608,7 @@ function onSocket(socket, send, request, user, mqttSettings) {
 					emitEvent('acknowledged', session, packet);
 					break;
 				case 'pingreq':
-					sendPacket({ cmd: 'pingresp' });
+					generateAndSendPacket({ cmd: 'pingresp' });
 					break;
 				case 'disconnect':
 					disconnected = true;
@@ -483,22 +624,22 @@ function onSocket(socket, send, request, user, mqttSettings) {
 		} catch (error) {
 			emitEvent('error', error, socket, packet, session);
 			mqttLog.error?.(error);
-			sendPacket({
+			generateAndSendPacket({
 				// Send a subscription acknowledgment
 				cmd: 'disconnect',
 			});
 		}
-		function sendPacket(packetData, path?) {
-			const send_packet = generate(packetData, mqttOptions);
-			send(send_packet);
-			recordAction(send_packet.length, 'bytes-sent', path, packetMethodName(packetData), 'mqtt');
+		// analytics stay per subscriber even when the packet itself is shared across them
+		function sendPacket(packet, methodName, path?) {
+			send(packet);
+			recordAction(packet.length, 'bytes-sent', path, methodName, 'mqtt');
+		}
+		function generateAndSendPacket(packetData, path?) {
+			sendPacket(generate(packetData, mqttOptions), packetMethodName(packetData), path);
 		}
 		function packetMethodName(packet) {
 			return packet.qos > 0 ? packet.cmd + ',qos=' + packet.qos : packet.cmd;
 		}
-		function serialize(data) {
-			return serializeMessage(data, request);
-		}
 	});
 	parser.on('error', (error) => {
 		mqttLog.warn('MQTT parsing error, closing connection:', error.message);

package/server/nodeName.ts

@@ -1,8 +1,10 @@
 import { readFileSync } from 'node:fs';
 import { X509Certificate } from 'node:crypto';
+import { isIP } from 'node:net';
 import { CONFIG_PARAMS } from '../utility/hdbTerms.ts';
 import * as env from '../utility/environment/environmentManager.ts';
 import { logger } from '../utility/logging/logger.ts';
+import { bareHostViolation } from '../utility/nodeIdentity.ts';
 import { server } from './Server.ts';
 
 Object.defineProperty(server, 'hostname', {
@@ -17,20 +19,26 @@ function getCommonNameFromCert() {
 	const certificatePath: string | undefined =
 		env.get(CONFIG_PARAMS.OPERATIONSAPI_TLS_CERTIFICATE) || env.get(CONFIG_PARAMS.TLS_CERTIFICATE);
 	if (certificatePath) {
-		// we can use this to get the hostname if it isn't provided by config
-		const certParsed = new X509Certificate(readFileSync(certificatePath));
-		const subject = certParsed.subject;
-		return (commonNameFromCert = subject?.match(/CN=(.*)/)?.[1] ?? null);
+		try {
+			// use this to get the hostname if it isn't provided by config
+			const subject = new X509Certificate(readFileSync(certificatePath)).subject;
+			return (commonNameFromCert = subject?.match(/CN=(.*)/)?.[1] ?? null);
+		} catch {
+			// a missing/unparseable cert file must not throw out of identity resolution — the caller
+			// falls back to another source. Do NOT cache the failure, so a later read (e.g. after the
+			// cert is created) can still pick up its common name.
+			return undefined;
+		}
 	}
 }
 
 let nodeName: string | undefined;
 export function getThisNodeName(): string {
 	if (nodeName) return nodeName; // if already determined, just return
-	nodeName = env.get(CONFIG_PARAMS.NODE_HOSTNAME); // standard config
-	if (nodeName) {
+	const configured = env.get(CONFIG_PARAMS.NODE_HOSTNAME);
+	if (configured) {
 		const replicationHostname = env.get('replication_hostname');
-		if (replicationHostname && replicationHostname !== nodeName) {
+		if (replicationHostname && replicationHostname !== configured) {
 			// If these are both set and differ, the node identity is ambiguous. node.hostname
 			// wins (it is what this node identifies as), but if it doesn't match the name this
 			// node is registered under in hdb_nodes, replication for that name silently turns
@@ -38,18 +46,21 @@ export function getThisNodeName(): string {
 			// node.hostname value — that's how a wrong identity (e.g. 'localhost') gets locked
 			// in. Steer the operator to reconcile against the registered node name instead.
 			logger.warn?.(
-				`The node.hostname (${nodeName}) and replication.hostname (${replicationHostname}) configuration values are both set and differ. This node will identify as "${nodeName}". Ensure that name matches this node's row in system.hdb_nodes; if it does not, set node.hostname (or remove it to fall back to replication.hostname) to match the registered node name, otherwise replication for this node will be disabled.`
+				`The node.hostname (${configured}) and replication.hostname (${replicationHostname}) configuration values are both set and differ. This node will identify as "${configured}". Ensure that name matches this node's row in system.hdb_nodes; if it does not, set node.hostname (or remove it to fall back to replication.hostname) to match the registered node name, otherwise replication for this node will be disabled.`
 			);
 		}
-		return nodeName;
 	}
-	// fallback to other means of getting the node name
+	// Use the first source that is a valid bare host (harper#2218). node.hostname and
+	// replication.hostname are rejected at the config boundary when invalid; the remaining derived
+	// sources are validated here and skipped — not fatal — if unusable, so a descriptive certificate
+	// common name or an empty value can never cache a corrupt identity or crash a request-time caller.
 	nodeName =
-		env.get('replication_hostname') ?? // for backwards compatibility
-		urlToNodeName(env.get('replication_url') as string) ??
-		getCommonNameFromCert() ??
-		getHostFromListeningPort('operationsapi_network_secureport') ??
-		getHostFromListeningPort('operationsapi_network_port') ??
+		asBareHost(configured, 'node.hostname') ??
+		asBareHost(env.get('replication_hostname'), 'replication.hostname') ?? // for backwards compatibility
+		asBareHost(replicationUrlHost(), 'the host in replication.url') ??
+		asBareHost(getCommonNameFromCert(), 'the certificate common name') ??
+		asBareHost(getHostFromListeningPort('operationsapi_network_secureport'), 'the operations API host') ??
+		asBareHost(getHostFromListeningPort('operationsapi_network_port'), 'the operations API host') ??
 		'127.0.0.1';
 	return nodeName;
 }
@@ -58,10 +69,66 @@ export function clearThisNodeName() {
 	nodeName = undefined;
 }
 
+// Reduce a node name to a host safe to compose a display URL from: strip a scheme/port (defensive —
+// a configured node.hostname carrying those is now rejected at the config boundary) and bracket a
+// bare IPv6 literal, without which the composed startup URLs are unparseable.
+export function nodeNameToDisplayHost(name: string): string {
+	if (!name) return name;
+	const hasScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(name);
+	const candidates = hasScheme ? [name] : [`http://${name}`, `http://[${name}]`];
+	for (const candidate of candidates) {
+		try {
+			const { hostname } = new URL(candidate);
+			if (hostname) return hostname;
+		} catch {}
+	}
+	return name;
+}
+
+export function getThisNodeHostname(): string {
+	return nodeNameToDisplayHost(getThisNodeName());
+}
+
+/**
+ * The host of replication.url, or undefined when it is unset or carries no usable host. Warns in the
+ * latter case for the same reason asBareHost does: a typo'd URL must not silently cost this node its
+ * identity. urlToNodeName itself stays quiet — it is also used for peer URLs, not just this node's.
+ */
+function replicationUrlHost(): string | undefined {
+	const url: string | undefined = env.get(CONFIG_PARAMS.REPLICATION_URL);
+	if (!url) return undefined;
+	const host = urlToNodeName(url);
+	if (host === undefined) {
+		logger.warn?.(
+			`Ignoring replication.url (${JSON.stringify(url)}) as this node's identity: it is not a URL with a host. Falling back to the next available source, which may leave this node identifying as 127.0.0.1 and unable to replicate.`
+		);
+	}
+	return host;
+}
+
+/**
+ * A candidate identity source, or undefined when it is unset or not a bare host. Skipping is
+ * deliberate (see getThisNodeName) but silence is a diagnosis trap: a typo'd source that quietly
+ * resolves identity to 127.0.0.1 looks like a working node until replication fails, so say so.
+ */
+function asBareHost(value: unknown, source: string): string | undefined {
+	if (value === undefined || value === null || value === '') return undefined;
+	const violation = bareHostViolation(value);
+	if (!violation) return value as string;
+	logger.warn?.(
+		`Ignoring ${source} (${JSON.stringify(value)}) as this node's identity: it ${violation}. Falling back to the next available source, which may leave this node identifying as 127.0.0.1 and unable to replicate. Set it to a bare hostname or IP literal.`
+	);
+	return undefined;
+}
+
 function getHostFromListeningPort(key: string) {
 	const port: string | undefined = env.get(key);
 	const lastColon = port?.lastIndexOf?.(':');
-	if (lastColon > 0) return port.slice(0, lastColon);
+	if (lastColon > 0) {
+		const host = port.slice(0, lastColon);
+		// A listen address stores IPv6 bracketed ("[::1]:9925"); the node identity is unbracketed.
+		return host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+	}
 }
 function getPortFromListeningPort(key: string) {
 	const port: string | undefined = env.get(key);
@@ -72,18 +139,33 @@ function getPortFromListeningPort(key: string) {
 
 export function hostnameToUrl(hostname) {
 	if (!hostname) return undefined;
+	// A bare IPv6 literal must be bracketed for the authority to parse: "ws://::1:9925" is rejected by
+	// the URL parser, "ws://[::1]:9925" is not. Hostnames and IPv4 pass through unchanged.
+	const host = isIP(hostname) === 6 ? `[${hostname}]` : hostname;
 	let port = getPortFromListeningPort('replication_port');
-	if (port) return `ws://${hostname}:${port}`;
+	if (port) return `ws://${host}:${port}`;
 	port = getPortFromListeningPort('replication_secureport');
-	if (port) return `wss://${hostname}:${port}`;
+	if (port) return `wss://${host}:${port}`;
 	port = getPortFromListeningPort('operationsapi_network_port');
-	if (port) return `ws://${hostname}:${port}`;
+	if (port) return `ws://${host}:${port}`;
 	port = getPortFromListeningPort('operationsapi_network_secureport');
-	if (port) return `wss://${hostname}:${port}`;
+	if (port) return `wss://${host}:${port}`;
 }
 
 export function urlToNodeName(nodeUrl?: string | URL): string | undefined {
-	if (nodeUrl) return new URL(nodeUrl).hostname; // this the part of the URL that is the node name, as we want it to match common name in the certificate
+	if (!nodeUrl) return undefined;
+	try {
+		// the part of the URL that is the node name, matched against the certificate common name. URL
+		// keeps an IPv6 host bracketed ("[::1]"); the identity is stored unbracketed so it stays one
+		// canonical string across sources and net.isIP types it as an IP certificate SAN.
+		const host = new URL(nodeUrl).hostname;
+		// A hostless scheme ("mailto:", "data:", "file:", "urn:") parses but has an empty hostname —
+		// that is no name at all, not an identity, so treat it like a malformed URL.
+		if (host === '') return undefined;
+		return host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
+	} catch {
+		return undefined; // a malformed URL yields no name — callers skip this source rather than crash
+	}
 }
 
 export function getThisNodeUrl() {