5.3 Release Notes
Patch Releases
All patch release notes for 5.3.x are available on the releases page.
Deployment
Two-Phase Cluster Deploys
deploy_component now runs across a cluster in two phases separated by an all-nodes staging barrier. The incoming version is downloaded, extracted, and npm installed into a hidden staging directory on every node before any node touches its live component; only once every node reports a successful stage does the swap happen. A node that can't fetch the package or fails its install now fails during staging, leaving the live component untouched everywhere, instead of leaving part of the cluster half-updated. The request and response shape are unchanged.
Activation is still per node, so this is a staging barrier rather than an all-or-nothing go-live: a swap that fails on one node after others have gone live leaves the cluster on mixed versions, reported as an activating deployment for a human to roll forward or back. There is deliberately no automatic rollback — past the barrier, a peer reporting failure does not prove it did not activate, so reverting "the failed nodes" can split the cluster three ways instead of converging it.
Two-phase deploy requires operation replication and replication of the system database. A cluster with system excluded from replication silently takes the legacy one-shot path, with no staging barrier and no rollback target; the staged-phase parameters are rejected outright rather than downgraded. See deploy_component.
Stage Now, Activate Later
deploy_component accepts activate: false to prepare and verify a release on every node without going live, returning a staged deployment ID. A later call passing that deployment_id swaps it in cluster-wide, turning go-live into a fast, separate step — normally with no re-fetch and no re-install, though a node whose staged tree went missing in between rebuilds it first. Harper retains the most recent staged builds per component (default 5, deployment_stagingRetention_maxCount); a deployment_id that has aged out fails rather than silently rebuilding. harper stage and harper activate are the CLI verbs. See Deploy modes.
Component Rollback
The new revert_component operation puts a component's retained previous version back in service across the cluster. A two-phase activation retains the version it displaced, so a rollback normally resolves no package, decrypts no secret, downloads no artifact and runs no install — every node already has the bytes. Retention accompanies an activation that records its activation spec, which is the normal deploy path; a one-shot deploy retains nothing, so confirm the deploy took the two-phase path rather than assuming a rollback target exists. It rewrites the stored package: reference and the boot-time application lock in the same operation, so a newly joined peer or a rebuilt components directory installs the version the cluster is actually running.
to_deployment_id is required and names the deployment you expect to be live afterwards, which makes the operation idempotent: a client that loses the response and retries cannot flip a rejected release back in. Only the immediately previous version is retained, and only a two-phase activation creates that retained copy. harper revert is the CLI verb. See revert_component.
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).
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.