socketduct 0.1.19 → 0.1.21

package/src/client/virtual-socket.js

@@ -7,7 +7,10 @@ import {Duplex} from "node:stream"
  * @property {(streamId: number, callback: (error?: Error | null) => void) => void} _endStream - End the writable side.
  * @property {(streamId: number, error: Error | null) => void} _destroyStream - Destroy the virtual stream.
  * @property {(streamId: number) => void} _resumeReadable - Resume inbound flow.
+ * @property {(streamId: number, data: Buffer, callback: (error?: Error | null) => void) => void} [_writeDurableStream] - Atomically admit one durable application operation.
+ * @property {(streamId: number, bytes: number) => void} [_deliverReadable] - Report bytes exposed to the application.
  * @property {(streamId: number, bytes: number) => void} [_consumeReadable] - Report bytes returned to the application.
+ * @property {(streamId: number, bytes: number) => Promise<number>} [_acknowledgeReadable] - Durably acknowledge application bytes.
  * @property {() => {address?: string, port?: number}} physicalAddress - Current physical endpoint.
  * @property {() => unknown} ref - Reference owner resources.
  * @property {() => unknown} unref - Unreference owner resources.
@@ -15,6 +18,16 @@ import {Duplex} from "node:stream"
 
 /** A stream-local failure where the physical connection may remain usable. */
 export class SocketductStreamError extends Error {
+  /** @type {string | undefined} */ disconnectIncidentId
+  /** @type {string | undefined} */ disconnectReason
+  /** @type {'reverse_hub' | 'reverse_client' | 'reverse_gateway' | undefined} */ incidentOrigin
+  /** @type {'client' | 'gateway' | undefined} */ physicalRole
+  /** @type {number | undefined} */ clientConnectionGeneration
+  /** @type {number | undefined} */ gatewayConnectionGeneration
+  /** @type {number | undefined} */ fanOutCount
+  /** @type {number | undefined} */ resumeSuccessCount
+  /** @type {number | undefined} */ terminalStreamCount
+
   /**
    * @param {string} message - Safe description.
    * @param {string} code - Stable code.
@@ -64,6 +77,18 @@ export class VirtualSocket extends Duplex {
   /** @type {number} */
   #emittedDataBytes = 0
 
+  /** @type {boolean} */
+  #manualReceiveAck
+
+  /** @type {number} */
+  #deliveredReadableBytes = 0
+
+  /** @type {number} */
+  #requestedReceiveAckBytes = 0
+
+  /** @type {WeakMap<Buffer, {resolve: () => void, reject: (error: Error) => void}>} */
+  #durableWrites = new WeakMap()
+
   /** @type {boolean} */
   connecting = true
 
@@ -94,7 +119,7 @@ export class VirtualSocket extends Duplex {
   /**
    * @param {VirtualSocketOwner} connection - Owner.
    * @param {number} streamId - Allocated stream ID.
-   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number}} options - Socket metadata/options.
+   * @param {{host: string, port: number, allowHalfOpen?: boolean, readableHighWaterMark?: number, writableHighWaterMark?: number, manualReceiveAck?: boolean}} options - Socket metadata/options.
    */
   constructor(connection, streamId, options) {
     super({
@@ -104,6 +129,7 @@ export class VirtualSocket extends Duplex {
     })
     this.#connection = connection
     this.#streamId = streamId
+    this.#manualReceiveAck = options.manualReceiveAck ?? false
     this.remoteAddress = options.host
     this.remotePort = options.port
     this.remoteFamily = options.host.includes(":") ? "IPv6" : "IPv4"
@@ -114,6 +140,11 @@ export class VirtualSocket extends Duplex {
     return this.#streamId
   }
 
+  /** @returns {boolean} Whether application-controlled receive ACK is enabled. */
+  get manualReceiveAck() {
+    return this.#manualReceiveAck
+  }
+
   /** @returns {this} Socket-style no-op connect; opening starts at construction. */
   connect() {
     return this
@@ -141,7 +172,11 @@ export class VirtualSocket extends Duplex {
     if (chunk !== null) {
       const bytes = typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length
       const emittedBytes = this.#emittedDataBytes - emittedBefore
-      if (bytes > emittedBytes) this.#connection._consumeReadable?.(this.#streamId, bytes - emittedBytes)
+      if (bytes > emittedBytes) {
+        this.#deliveredReadableBytes += bytes - emittedBytes
+        this.#connection._deliverReadable?.(this.#streamId, bytes - emittedBytes)
+        this.#connection._consumeReadable?.(this.#streamId, bytes - emittedBytes)
+      }
     }
     return chunk
   }
@@ -155,14 +190,57 @@ export class VirtualSocket extends Duplex {
    * @override
    */
   emit(event, ...args) {
-    const emitted = super.emit(event, ...args)
     const chunk = args[0]
     if (event === "data" && (typeof chunk === "string" || Buffer.isBuffer(chunk))) {
       const bytes = typeof chunk === "string" ? Buffer.byteLength(chunk) : chunk.length
       this.#emittedDataBytes += bytes
+      this.#deliveredReadableBytes += bytes
+      this.#connection._deliverReadable?.(this.#streamId, bytes)
+      const emitted = super.emit(event, ...args)
       this.#connection._consumeReadable?.(this.#streamId, bytes)
+      return emitted
     }
-    return emitted
+    return super.emit(event, ...args)
+  }
+
+  /**
+   * Durably admits one complete application operation before any of its bytes
+   * become eligible for transmission.
+   * @param {string | ArrayBufferView} chunk - Complete serialized operation.
+   * @param {BufferEncoding} [encoding] - String encoding.
+   * @returns {Promise<void>} Resolves after all bytes and recovery metadata are committed.
+   */
+  writeDurable(chunk, encoding = "utf8") {
+    if (this.destroyed) return Promise.reject(contractError("Socketduct stream is destroyed", "ERR_STREAM_DESTROYED"))
+    if (this.writableEnded || this.writableFinished) return Promise.reject(contractError("Socketduct stream has ended", "ERR_STREAM_WRITE_AFTER_END"))
+    if (this.#connection._writeDurableStream === undefined) return Promise.reject(contractError("Durable write admission is unavailable for this Socketduct transport", "SOCKETDUCT_DURABLE_WRITE_UNSUPPORTED"))
+    const data = bufferFromView(chunk, encoding)
+    this.#resetTimeout()
+    return new Promise((resolve, reject) => {
+      this.#durableWrites.set(data, {resolve, reject})
+      this.write(data, (error) => {
+        if (error !== undefined && error !== null) reject(error)
+      })
+    })
+  }
+
+  /**
+   * Advances the durable receive ACK by application bytes after parser/journal
+   * state is durable.
+   * @param {number} bytes - Newly durable application bytes.
+   * @returns {Promise<number>} New cumulative durable receive sequence.
+   */
+  acknowledgeReceive(bytes) {
+    if (!this.#manualReceiveAck) throw contractError("Manual receive acknowledgement is not enabled for this socket", "SOCKETDUCT_MANUAL_ACK_DISABLED")
+    if (!Number.isSafeInteger(bytes) || bytes <= 0) throw contractError("Receive acknowledgement bytes must be a positive safe integer", "SOCKETDUCT_INVALID_RECEIVE_ACK")
+    if (this.destroyed) return Promise.reject(contractError("Socketduct stream is destroyed", "ERR_STREAM_DESTROYED"))
+    if (this.#requestedReceiveAckBytes + bytes > this.#deliveredReadableBytes) throw contractError("Receive acknowledgement exceeds bytes delivered to the application", "SOCKETDUCT_INVALID_RECEIVE_ACK")
+    if (this.#connection._acknowledgeReadable === undefined) return Promise.reject(contractError("Manual receive acknowledgement is unavailable for this Socketduct transport", "SOCKETDUCT_MANUAL_ACK_UNSUPPORTED"))
+    this.#requestedReceiveAckBytes += bytes
+    return this.#connection._acknowledgeReadable(this.#streamId, bytes).catch((error) => {
+      this.#requestedReceiveAckBytes -= bytes
+      throw error
+    })
   }
 
   /**
@@ -173,6 +251,24 @@ export class VirtualSocket extends Duplex {
    * @returns {void}
    */
   _write(chunk, encoding, callback) {
+    const durableChunk = Buffer.isBuffer(chunk) ? /** @type {Buffer} */ (chunk) : undefined
+    const durable = durableChunk === undefined ? undefined : this.#durableWrites.get(durableChunk)
+    if (durable !== undefined) {
+      const data = /** @type {Buffer} */ (durableChunk)
+      this.#durableWrites.delete(data)
+      this.#resetTimeout()
+      this.#connection._writeDurableStream?.(this.#streamId, data, (error) => {
+        if (error !== undefined && error !== null) durable.reject(error)
+        else {
+          this.bytesWritten += data.length
+          durable.resolve()
+        }
+        // Admission failures reject writeDurable() but remain retryable, so the
+        // Writable queue advances without turning the whole socket terminal.
+        callback()
+      })
+      return
+    }
     const data = typeof chunk === "string" ? Buffer.from(chunk, encoding) : Buffer.from(chunk)
     this.#resetTimeout()
     this.#connection._writeStream(this.#streamId, data, (error) => {
@@ -296,3 +392,22 @@ export class VirtualSocket extends Duplex {
     this.#timeoutTimer.unref?.()
   }
 }
+
+/**
+ * @param {string} message - Safe message.
+ * @param {string} code - Stable code.
+ */
+function contractError(message, code) {
+  return new SocketductStreamError(message, code)
+}
+
+/**
+ * @param {string | ArrayBufferView} value - Bytes.
+ * @param {BufferEncoding} encoding - String encoding.
+ * @returns {Buffer} Owned bytes.
+ */
+function bufferFromView(value, encoding) {
+  if (typeof value === "string") return Buffer.from(value, encoding)
+  if (!ArrayBuffer.isView(value)) throw new TypeError("Durable write requires a string, TypedArray, or DataView")
+  return Buffer.from(value.buffer, value.byteOffset, value.byteLength)
+}

package/src/config/environment.js

@@ -1,6 +1,16 @@
 import {isIP} from "node:net"
 
-import {DEFAULT_LOG_MAX_FILE_BYTES, DEFAULT_LOG_MAX_FILES, MAX_LOG_FILES, MIN_LOG_MAX_FILE_BYTES} from "../logging/structured-logger.js"
+import {
+  DEFAULT_LOG_COMPRESSION_LEVEL,
+  DEFAULT_LOG_CRITICAL_FLUSH_INTERVAL_MS,
+  DEFAULT_LOG_CRITICAL_RESERVE_BYTES,
+  DEFAULT_LOG_FLUSH_INTERVAL_MS,
+  DEFAULT_LOG_FRAME_BYTES,
+  DEFAULT_LOG_QUEUE_BYTES,
+  DEFAULT_LOG_RETENTION_BYTES,
+  DEFAULT_LOG_RETENTION_DAYS,
+  DEFAULT_LOG_SEGMENT_BYTES
+} from "../logging/compressed-log-writer.js"
 
 const DEFAULT_RELAY_HOST = "127.0.0.1"
 const DEFAULT_RELAY_PORT = 3100
@@ -52,7 +62,8 @@ const SUPPORTED_PROTOCOL_VERSIONS = new Set([2, 3])
  * @property {number} handshakeTimeoutMs - Milliseconds to wait for auth after TCP/TLS connect before closing the socket. Default 10000.
  * @property {number} maxInputBytesPerConnection - Per-connection input byte budget before the first authenticated session frame. Default 65536.
  * @property {number} [statusIntervalMs] - Safe status-log interval; zero disables periodic status logs.
- * @property {{directory: string, maxFileBytes: number, maxFiles: number}} [fileLogging] - Optional persistent JSONL logging configuration.
+ * @property {{directory: string, frameMaxBytes: number, flushIntervalMs: number, criticalFlushIntervalMs: number, maxSegmentBytes: number, retentionDays: number, retentionBytes: number, maxQueueBytes: number, criticalReserveBytes: number, compressionLevel: number}} [fileLogging] - Optional durable compressed JSONL logging configuration.
+ * @property {{key: Buffer, keyEpoch: string}} [connectionFingerprint] - Hub-only keyed diagnostic correlation configuration.
  * @property {'auto' | 'off'} [compression] - Whether to negotiate stream.data compression when the runtime supports it. Defaults to auto.
  * @property {2 | 3} [protocolVersion] - Relay wire protocol; defaults to rollback-compatible v2.
  * @property {number} [minCompressBytes] - Payloads smaller than this are sent raw.
@@ -133,13 +144,34 @@ export function loadEnvironmentConfig(env = process.env) {
     ...(env.SOCKETDUCT_REVERSE_HUB_SERVERNAME?.trim() ? {servername: env.SOCKETDUCT_REVERSE_HUB_SERVERNAME.trim()} : {})
   }
   const logDirectory = env.SOCKETDUCT_LOG_DIRECTORY?.trim() || undefined
+  if (env.SOCKETDUCT_LOG_MAX_FILE_BYTES !== undefined || env.SOCKETDUCT_LOG_MAX_FILES !== undefined) throw new Error("SOCKETDUCT_LOG_MAX_FILE_BYTES and SOCKETDUCT_LOG_MAX_FILES were replaced by compressed log frame, segment, and retention settings")
   let fileLogging
   if (logDirectory !== undefined) {
-    const maxFileBytes = parsePositiveInteger(env.SOCKETDUCT_LOG_MAX_FILE_BYTES, "SOCKETDUCT_LOG_MAX_FILE_BYTES", DEFAULT_LOG_MAX_FILE_BYTES)
-    if (!Number.isSafeInteger(maxFileBytes) || maxFileBytes < MIN_LOG_MAX_FILE_BYTES) throw new Error(`SOCKETDUCT_LOG_MAX_FILE_BYTES must be a safe integer of at least ${MIN_LOG_MAX_FILE_BYTES}`)
-    const maxFiles = parsePositiveInteger(env.SOCKETDUCT_LOG_MAX_FILES, "SOCKETDUCT_LOG_MAX_FILES", DEFAULT_LOG_MAX_FILES)
-    if (maxFiles > MAX_LOG_FILES) throw new Error(`SOCKETDUCT_LOG_MAX_FILES must be no greater than ${MAX_LOG_FILES}`)
-    fileLogging = {directory: logDirectory, maxFileBytes, maxFiles}
+    const frameMaxBytes = parseBoundedInteger(env.SOCKETDUCT_LOG_FRAME_MAX_BYTES, "SOCKETDUCT_LOG_FRAME_MAX_BYTES", DEFAULT_LOG_FRAME_BYTES, 128, 16 * 1024 * 1024)
+    const flushIntervalMs = parseBoundedInteger(env.SOCKETDUCT_LOG_FLUSH_INTERVAL_MS, "SOCKETDUCT_LOG_FLUSH_INTERVAL_MS", DEFAULT_LOG_FLUSH_INTERVAL_MS, 1, 60_000)
+    const criticalFlushIntervalMs = parseBoundedInteger(env.SOCKETDUCT_LOG_CRITICAL_FLUSH_INTERVAL_MS, "SOCKETDUCT_LOG_CRITICAL_FLUSH_INTERVAL_MS", DEFAULT_LOG_CRITICAL_FLUSH_INTERVAL_MS, 1, 60_000)
+    const maxSegmentBytes = parseBoundedInteger(env.SOCKETDUCT_LOG_SEGMENT_MAX_BYTES, "SOCKETDUCT_LOG_SEGMENT_MAX_BYTES", DEFAULT_LOG_SEGMENT_BYTES, 1024, 4 * 1024 * 1024 * 1024)
+    const retentionDays = parseBoundedInteger(env.SOCKETDUCT_LOG_RETENTION_DAYS, "SOCKETDUCT_LOG_RETENTION_DAYS", DEFAULT_LOG_RETENTION_DAYS, 1, 3650)
+    const retentionBytes = parseBoundedInteger(env.SOCKETDUCT_LOG_RETENTION_MAX_BYTES, "SOCKETDUCT_LOG_RETENTION_MAX_BYTES", DEFAULT_LOG_RETENTION_BYTES, 1024, 1024 * 1024 * 1024 * 1024)
+    const maxQueueBytes = parseBoundedInteger(env.SOCKETDUCT_LOG_QUEUE_MAX_BYTES, "SOCKETDUCT_LOG_QUEUE_MAX_BYTES", DEFAULT_LOG_QUEUE_BYTES, 1024, 1024 * 1024 * 1024)
+    const criticalReserveBytes = parseBoundedInteger(env.SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES, "SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES", DEFAULT_LOG_CRITICAL_RESERVE_BYTES, 0, maxQueueBytes - 1)
+    const compressionLevel = parseBoundedInteger(env.SOCKETDUCT_LOG_COMPRESSION_LEVEL, "SOCKETDUCT_LOG_COMPRESSION_LEVEL", DEFAULT_LOG_COMPRESSION_LEVEL, 1, 22)
+    if (maxQueueBytes - criticalReserveBytes < 512) throw new Error("SOCKETDUCT_LOG_CRITICAL_RESERVE_BYTES must leave at least 512 noncritical queue bytes")
+    if (maxSegmentBytes > retentionBytes) throw new Error("SOCKETDUCT_LOG_SEGMENT_MAX_BYTES must not exceed SOCKETDUCT_LOG_RETENTION_MAX_BYTES")
+    fileLogging = {directory: logDirectory, frameMaxBytes, flushIntervalMs, criticalFlushIntervalMs, maxSegmentBytes, retentionDays, retentionBytes, maxQueueBytes, criticalReserveBytes, compressionLevel}
+  }
+  const fingerprintKeyText = env.SOCKETDUCT_CONNECTION_FINGERPRINT_KEY?.trim() || undefined
+  const fingerprintKeyEpoch = env.SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH?.trim() || undefined
+  if (mode !== "reverse-hub" && (fingerprintKeyText !== undefined || fingerprintKeyEpoch !== undefined)) throw new Error("SOCKETDUCT_CONNECTION_FINGERPRINT_KEY is hub-only")
+  if ((fingerprintKeyText === undefined) !== (fingerprintKeyEpoch === undefined)) throw new Error("SOCKETDUCT_CONNECTION_FINGERPRINT_KEY and SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH must be supplied together")
+  if (mode === "reverse-hub" && fileLogging !== undefined && fingerprintKeyText === undefined) throw new Error("SOCKETDUCT_CONNECTION_FINGERPRINT_KEY is required for reverse-hub persistent logging")
+  let connectionFingerprint
+  if (fingerprintKeyText !== undefined && fingerprintKeyEpoch !== undefined) {
+    if (!/^[A-Za-z0-9_-]+$/.test(fingerprintKeyText)) throw new Error("SOCKETDUCT_CONNECTION_FINGERPRINT_KEY must be unpadded base64url")
+    const key = Buffer.from(fingerprintKeyText, "base64url")
+    if (key.length < 32 || key.toString("base64url") !== fingerprintKeyText) throw new Error("SOCKETDUCT_CONNECTION_FINGERPRINT_KEY must encode at least 32 bytes")
+    if (!/^[A-Za-z0-9_-]{1,32}$/.test(fingerprintKeyEpoch)) throw new Error("SOCKETDUCT_CONNECTION_FINGERPRINT_KEY_EPOCH must be 1-32 URL-safe characters")
+    connectionFingerprint = {key, keyEpoch: fingerprintKeyEpoch}
   }
 
   return {
@@ -184,6 +216,7 @@ export function loadEnvironmentConfig(env = process.env) {
       DEFAULT_STATUS_INTERVAL_MS
     ),
     ...(fileLogging === undefined ? {} : {fileLogging}),
+    ...(connectionFingerprint === undefined ? {} : {connectionFingerprint}),
     compression,
     protocolVersion,
     minCompressBytes: parsePositiveInteger(
@@ -343,6 +376,22 @@ function parseNonNegativeInteger(value, name, defaultValue) {
   return parsed
 }
 
+/**
+ * Parses one bounded integer environment setting.
+ * @param {string | undefined} value - Raw value.
+ * @param {string} name - Environment variable name.
+ * @param {number} defaultValue - Default value.
+ * @param {number} minimum - Inclusive minimum.
+ * @param {number} maximum - Inclusive maximum.
+ * @returns {number} Parsed bounded integer.
+ */
+function parseBoundedInteger(value, name, defaultValue, minimum, maximum) {
+  if (value === undefined || value === "") return defaultValue
+  const parsed = Number(value)
+  if (!Number.isSafeInteger(parsed) || parsed < minimum || parsed > maximum) throw new Error(`${name} must be an integer from ${minimum} to ${maximum}`)
+  return parsed
+}
+
 /**
  * @param {string} value - Comma-separated username:token entries.
  * @returns {StaticTokenConfig[]} Parsed static tokens.

package/src/index.js

@@ -1,14 +1,15 @@
 import {loadEnvironmentConfig} from "./config/environment.js"
-import {createJsonlFileLogger} from "./logging/structured-logger.js"
+import {createCompressedJsonlFileLogger} from "./logging/compressed-log-writer.js"
 import {startRelayRuntime} from "./server/relay-runtime.js"
 import {startOutboundReverseGatewayRuntime, startReverseHubRuntime} from "./reverse/runtime.js"
 
 export {createSocketductConnectionFactory} from "./client/connect.js"
 export {createJsonlFileLogger, createStructuredLogger} from "./logging/structured-logger.js"
+export {createCompressedJsonlFileLogger, CompressedJsonlFileLogger} from "./logging/compressed-log-writer.js"
 export {SocketductHttpAgent} from "./client/http-agent.js"
 export {connectSocketduct, SocketductRelayError, SocketductSocket} from "./client/socketduct-socket.js"
 export {createMultiplexedSocketductConnection, MultiplexedSocketductConnection} from "./client/multiplexed-connection.js"
-export {createMultiplexedSocketductTransportSet, MultiplexedSocketductTransportSet, SocketductTransportSetLimitError, SocketductTransportSetNotReadyError, SocketductTransportSetTerminalError} from "./client/multiplexed-transport-set.js"
+export {createMultiplexedSocketductTransportSet, MultiplexedSocketductTransportSet, SocketductRecoveryLookupError, SocketductTransportSetLimitError, SocketductTransportSetNotReadyError, SocketductTransportSetTerminalError} from "./client/multiplexed-transport-set.js"
 export {SocketductSessionLostError, SocketductStreamError, VirtualSocket} from "./client/virtual-socket.js"
 export {createOutboundReverseGateway, createReverseGatewayConnection, OutboundReverseGateway, ReverseGatewayConnection, startReverseGatewayHub} from "./reverse/index.js"
 
@@ -33,11 +34,12 @@ export function getStartupSummary() {
  */
 async function main() {
   const config = loadEnvironmentConfig()
-  const logger = config.fileLogging === undefined ? undefined : createJsonlFileLogger({...config.fileLogging, role: config.mode})
+  const logger = config.fileLogging === undefined ? undefined : createCompressedJsonlFileLogger({...config.fileLogging, role: config.mode})
   if (config.mode === "summary") {
     const summary = getStartupSummary()
     console.log(`${summary.name} starting in ${summary.mode} mode on ${summary.runtime}`)
-    logger?.log("process.started", {runtimeMode: config.mode})
+    logger?.log("process.started", {runtimeMode: config.mode, ...loggingConfigurationFields(config.fileLogging)})
+    await logger?.close()
     return
   }
 
@@ -45,31 +47,29 @@ async function main() {
   let service
   /** @type {() => Promise<void>} */
   let closeRuntime
-  if (config.mode === "relay") {
-    const runtime = await startRelayRuntime(config)
-    service = runtime.relay
-    closeRuntime = runtime.close
-  } else if (config.mode === "reverse-hub") {
-    const runtime = await startReverseHubRuntime(config)
-    service = runtime.hub
-    closeRuntime = runtime.close
-  } else {
-    const runtime = await startOutboundReverseGatewayRuntime(config, logger)
-    service = runtime.gateway
-    closeRuntime = runtime.close
+  try {
+    if (config.mode === "relay") {
+      const runtime = await startRelayRuntime(config)
+      service = runtime.relay
+      closeRuntime = runtime.close
+    } else if (config.mode === "reverse-hub") {
+      const runtime = await startReverseHubRuntime(config, logger)
+      service = runtime.hub
+      closeRuntime = runtime.close
+    } else {
+      const runtime = await startOutboundReverseGatewayRuntime(config, logger)
+      service = runtime.gateway
+      closeRuntime = runtime.close
+    }
+  } catch (startupError) {
+    try {
+      await logger?.close()
+    } catch (loggerError) {
+      throw new AggregateError([startupError, loggerError], "Socketduct startup and diagnostic logger shutdown both failed", {cause: loggerError})
+    }
+    throw startupError
   }
   const tlsStatus = config.mode === "relay" && config.relayTls === undefined ? "plaintext" : "TLS"
-  console.log(JSON.stringify({
-    event: `${config.mode}.started`,
-    ...(config.mode === "reverse-gateway" ? {gatewayId: config.reverseGatewayId} : {host: config.relayHost, port: service.port}),
-    transportSecurity: tlsStatus,
-    compression: config.mode.startsWith("reverse-") ? "zstd" : config.compression
-  }))
-  logger?.log("process.started", {
-    runtimeMode: config.mode,
-    transportSecurity: tlsStatus,
-    compression: config.mode.startsWith("reverse-") ? "zstd" : config.compression
-  })
   const statusIntervalMs = config.statusIntervalMs ?? 30_000
   const statusTimer = statusIntervalMs > 0
     ? setInterval(() => {
@@ -80,9 +80,15 @@ async function main() {
     : undefined
   statusTimer?.unref()
 
+  let shuttingDown = false
   const shutdown = () => {
+    if (shuttingDown) return
+    shuttingDown = true
     if (statusTimer !== undefined) clearInterval(statusTimer)
     closeRuntime()
+      .then(() => { logger?.log("process.stopped", {runtimeMode: config.mode}) })
+      .then(() => logger?.flush())
+      .then(() => logger?.close())
       .then(() => process.exit(0))
       .catch((error) => {
         console.error(error)
@@ -91,6 +97,38 @@ async function main() {
   }
   process.once("SIGINT", shutdown)
   process.once("SIGTERM", shutdown)
+  logger?.log("process.started", {
+    runtimeMode: config.mode,
+    transportSecurity: tlsStatus,
+    compression: config.mode.startsWith("reverse-") ? "zstd" : config.compression,
+    ...loggingConfigurationFields(config.fileLogging)
+  })
+  console.log(JSON.stringify({
+    event: `${config.mode}.started`,
+    ...(config.mode === "reverse-gateway" ? {gatewayId: config.reverseGatewayId} : {host: config.relayHost, port: service.port}),
+    transportSecurity: tlsStatus,
+    compression: config.mode.startsWith("reverse-") ? "zstd" : config.compression
+  }))
+}
+
+/**
+ * Returns only non-sensitive effective logger settings for the startup record.
+ * @param {import('./config/environment.js').RelayEnvironmentConfig['fileLogging']} fileLogging - Managed sink settings.
+ * @returns {Record<string, number>} Safe numeric settings.
+ */
+function loggingConfigurationFields(fileLogging) {
+  if (fileLogging === undefined) return {}
+  return {
+    frameMaxBytes: fileLogging.frameMaxBytes,
+    flushIntervalMs: fileLogging.flushIntervalMs,
+    criticalFlushIntervalMs: fileLogging.criticalFlushIntervalMs,
+    maxSegmentBytes: fileLogging.maxSegmentBytes,
+    retentionDays: fileLogging.retentionDays,
+    retentionBytes: fileLogging.retentionBytes,
+    maxQueueBytes: fileLogging.maxQueueBytes,
+    criticalReserveBytes: fileLogging.criticalReserveBytes,
+    compressionLevel: fileLogging.compressionLevel
+  }
 }
 
 if (import.meta.url === `file://${process.argv[1]}`) {