diff --git a/reference/configuration/options.md b/reference/configuration/options.md index e8fdf3c7..cde51375 100644 --- a/reference/configuration/options.md +++ b/reference/configuration/options.md @@ -205,6 +205,19 @@ logging: --- +## `node` + +This node's identity within the cluster. See [Replication](../replication/overview.md). + +```yaml +node: + hostname: server-one +``` + +- `hostname` — This node's identity: it becomes the node's TLS certificate common name and the host that replication advertises to peers and dials to reach this node. Must be a **bare hostname or IP literal** (e.g. `server-one`, `10.0.0.5`, or the unbracketed IPv6 form `::1`) — **not** a URL and **not** `host:port`. Harper **fails to start** if the value carries a scheme, port, path, credentials, query string, or fragment, is a bracketed IPv6 literal (`[::1]`), or is not a string; the startup error names the offending value and the reason. Earlier versions accepted such values and silently corrupted certificate matching and replication — a node configured as `http://host:9926` advertised and dialed a host literally named `http`. The same requirement applies to [`replication.hostname`](#replication). If unset, Harper uses the first valid bare host among `replication.hostname`, the host in `replication.url`, the TLS certificate common name, and the Operations API host, falling back to `127.0.0.1`. + +--- + ## `replication` Native WebSocket-based replication (Plexus). Added in: v4.4.0. See [Replication](../replication/overview.md) and [Clustering](../replication/clustering.md). @@ -218,7 +231,7 @@ replication: - wss://server-two:9933 ``` -- `hostname` — This instance's hostname within the cluster +- `hostname` — This instance's hostname within the cluster. Subject to the same bare hostname or IP literal requirement as [`node.hostname`](#node) — a URL, `host:port`, or non-string value fails startup. When both are set, `node.hostname` wins. - `url` — WebSocket URL peers use to connect to this instance - `databases` — Databases to replicate; _Default_: `"*"` (all). Each entry supports `name` and `sharded` - `routes` — Peer nodes; URL strings or `{hostname, port, startTime, revokedCertificates}` objects diff --git a/release-notes/v5-lincoln/5.3.md b/release-notes/v5-lincoln/5.3.md new file mode 100644 index 00000000..e75d5505 --- /dev/null +++ b/release-notes/v5-lincoln/5.3.md @@ -0,0 +1,21 @@ +--- +title: '5.3' +--- + +# 5.3 Release Notes + +### Patch Releases + +All patch release notes for 5.3.x are available on the [releases page](https://github.com/HarperFast/harper/releases?q=v5.3&expanded=true). + +## Node Identity + +`node.hostname` and `replication.hostname` must now be a bare hostname or IP literal. This value is the node's identity — it becomes the node's TLS certificate common name and the host that replication advertises to peers and dials to reach the node — so a URL or `host:port` value corrupted certificate matching and replication without surfacing an error: a node configured as `http://host:9926` advertised and dialed a host literally named `http` ([harper#2218](https://github.com/HarperFast/harper/issues/2218)). + +Configuration validation now rejects these values at startup, so **an existing install whose `node.hostname` or `replication.hostname` is a URL, `host:port`, or a non-string value will fail to start until it is corrected to a bare host.** The startup error names the offending value and the reason it was rejected. A bare hostname (`server-one`), an IPv4 literal (`10.0.0.5`), and an unbracketed IPv6 literal (`::1`) are valid; a scheme, port, path, credentials, query string, fragment, bracketed IPv6 literal (`[::1]`), or non-string value is rejected. Route entries under `replication.routes` are unaffected and may still be URLs. + +When `node.hostname` is unset, Harper resolves the identity to the first valid bare host among `replication.hostname`, the host in `replication.url`, the TLS certificate common name, and the Operations API host, falling back to `127.0.0.1`. A derived source that is empty or unusable is skipped rather than failing startup. + +Replication URLs now also bracket a bare IPv6 literal correctly (`::1` becomes `ws://[::1]:9933`), which the URL parser previously rejected. + +See [Configuration Options](/reference/v5/configuration/options#node).