docs: replicating the system database with a constrained topology (5.2) - #583
docs: replicating the system database with a constrained topology (5.2)#583kriszyp wants to merge 9 commits into
Conversation
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the replication documentation and release notes for version 5.2.0, introducing the ability to replicate the system database under controlled flow with a constrained topology and scope replication flow per database. A review comment correctly identifies that the YAML configuration example uses the invalid property 'host' instead of 'hostname'.
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-583 This preview will update automatically when you push new commits. |
Controlled-flow replication can now include the `system` database while keeping a constrained topology (directional self-record). Update the replication overview (Controlling Replication Flow) — the previous "avoid replicating system" note no longer applies for directional routes — and add a 5.2 release note. Documents per-database directional routes, the add_node database-scoping behavior change, and the central-visibility caveat. Companion to the harper-pro core change (branch kris/systemdb-routing-repro). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
4ecc02d to
a290435
Compare
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-583 This preview will update automatically when you push new commits. |
- Fix heading-hierarchy skip (h4 -> h3) and hostname/host key inconsistency in the controlled-flow example. - Extend the per-database routing example to actually route `system`, matching the section it introduces. - Soften "discovered non-neighbor nodes therefore do not open direct connections" to the actual guarantee (no subscription/replication connection), and call out that on-demand residency/retrieval connections are a separate, unaffected mechanism. - Document add_node/set_node's sendsTo/receivesFrom fields in the Clustering reference (previously undocumented) and note the config-authority limitation: dynamic Operations API scoping doesn't make a node advertise a directional self-record — that's derived only from harper-config.yaml routes. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-583 This preview will update automatically when you push new commits. |
Ethan-Arrowood
left a comment
Ethan-Arrowood
left a comment
There was a problem hiding this comment.
The core 5.2 constrained-topology content is accurate — I traced every major claim to merged harper-pro#572 and its source (computeSelfReplicates, shouldReplicateFromNode, setNode.ts) and it holds up. The host:→hostname: fix the Gemini bot asked for is in at this head too.
The problem is concentrated in the new add_node parameter bullet, which has a factual error serious enough to break a user's setup silently: a bare-string sendsTo entry is matched as a peer name, not a database name, so the documented "sendsTo": ["cardata"] authorizes nothing and replication just doesn't happen. Details inline, along with a direction-perspective problem and an overstated containment claim.
One of these may actually be an implementation-intent question rather than a docs bug — see the sendsTo direction comment. Since no test pins add_node's direction, it'd be worth confirming with you directly which behavior is intended; the doc needs to state a direction explicitly either way, and a pinning integration test would settle it permanently.
sent with Claude Opus 5
Ethan-Arrowood's review traced the actual behavior in harper-pro's knownNodes.ts/setNode.ts: a bare-string sendsTo/receivesFrom entry is matched as a peer name, not a database, and silently authorizes nothing; and add_node's sendsTo/receivesFrom describe the *added* node's perspective (opposite of a config route's local-node perspective) with no peer/target scoping, so the resulting hdb_nodes record is visible cluster-wide rather than confined to one connection. Corrects both the clustering.md reference and the matching 5.2 release note bullet to describe this accurately. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…-docs # Conflicts: # release-notes/v5-lincoln/5.2.md
…esFrom
Independent review (codex/grok) caught that the previous wording said
entries "carry no peer scoping" and must be `{ database, excludeTables? }`
objects — both incomplete. harper-pro's RouteEntry type and matcher
(knownNodes.ts routeEntriesIncludePeer) support target/source fields that
do scope an entry to one peer; the docs just never mentioned them. Also
clarifies that the per-database YAML example pushes system/config
downstream, whereas the roadside-to-core narrative right after it
describes the opposite (upstream) direction, and how to flip it.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…gregation example Independent review (codex/gemini/grok) flagged two more issues: - add_node's sendsTo/receivesFrom are new in v5.2 (harper-pro#572, commit 0b49587f) but the parameter list had no VersionBadge, and the "must be an object" wording incorrectly implied a bare string is never valid (it is — it just matches a peer name across all databases, not a database name). - The "aggregate upstream" guidance didn't say which node's config route needs the receivesFrom entry, so it could be misread as "configure receivesFrom on the leaf's route to the core" (which would do the opposite of what's intended). Spelled out the roadside/middle example explicitly. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…by review - The roadside-to-middle upstream aggregation example only described the middle tier's receivesFrom entry. replicationConnection.ts's send-side authority gate (harper-pro#498) independently checks the SENDER's own directional config route, so roadside also needs a matching sendsTo entry or the subscription is rejected as unauthorized. Documented both sides. - The 5.2 release note still said a bare-string entry "authorizes nothing," contradicting the corrected clustering.md wording (a string names a peer and authorizes all databases for it). Aligned. - Added a caveat that routing `system` upstream from an edge node propagates hdb_user/hdb_role along with everything else, so a compromised or careless edge node's changes reach every node downstream of it. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…ken) Traced setNode.ts's reciprocal add_node_back registration: it swaps sendsTo/receivesFrom wholesale onto the peer (targetAddNodeObj.sendsTo = req.receivesFrom, etc.) without rewriting each entry's target/source for the new direction. A target/source value that's correct for the calling side ends up wrong on the peer's copy, so the send-authority gate (replicationConnection.ts's shouldCloseSendAuthWatch) rejects the subscription — replication silently doesn't happen. The docs previously told users to set target/source to scope an add_node entry to one peer; that's not a reliable fix given this behavior. Removed the recommendation and pointed to config routes instead, which don't have this problem (computeSelfReplicates stamps target/source correctly on both sides). Also fixed an overstated "rejected as unauthorized" claim for the roadside/middle example: omitting the receiver's half means no subscription is attempted at all, not a rejection. This is a real harper-pro implementation gap, not just a docs issue — noting it in the dispatch Findings for a follow-up. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…ion bug as target/source
Traced the failure Grok/codex flagged: add_node's bare-string form
(entry === peerName) has the identical swap-without-rewrite problem as
target/source — a string that's correct for the caller's own send
authorization becomes wrong once add_node_back copies it unmodified
onto the peer's record, so the peer's send-authority gate rejects the
subscription. Consolidated the guidance: only the unscoped object form
{ database?, excludeTables? } is reliable; steered both the string
form and target/source into the same "don't rely on this" warning
instead of presenting the string as a working (if blunt) alternative.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-583 This preview will update automatically when you push new commits. |
|
Reviewed — |
3 participants
Summary
Documents the 5.2 replication change that lets the
systemdatabase replicate while keeping a constrained (non-mesh) topology.reference/replication/overview.md(Controlling Replication Flow): the previous "avoid replicating thesystemdatabase" note no longer applies when a node uses directional routes. Adds a per-databasesendsTo/receivesFromexample and a<VersionBadge type="changed" version="v5.2.0" />subsection explaining constrainedsystemreplication, its opt-in nature, and the central-visibility caveat.release-notes/v5-lincoln/5.2.md: adds a "Replicating the System Database with a Constrained Topology" section (also documents theadd_nodedatabase-scoping behavior change).Companion PR
Documents the harper-pro core change on branch
kris/systemdb-routing-repro(feature PR to be opened; this docs PR will be cross-linked once it is).Where to look
The behavior-change framing in the reference doc and the
add_nodedatabase-scoping note in the release note — please sanity-check the wording against the intended product behavior.Drafted by an LLM (Claude Opus 4.8).