docs(http,ha): the retries default, the third verify outcome, and a withheld peer endpoint - #443
Merged
Conversation
…ing address is withheld The object form of arcadedb.ha.serverList gained bolt: (#5002) and grpc: (#6091), neither of which was documented outside the code. A new "Client Routing Ports" section says what they are for and the sentence that matters operationally: declare them whenever your nodes do not all listen on the same port for that protocol, because the fallback derives a peer's address from this node's port. It also documents what #6183 changed: when two peers derive to the same address - nodes that share a host and differ only by port - neither is advertised, because two listening sockets cannot own one host:port, and nothing at all is advertised when the leader is one of them. BOLT then answers ROUTE with itself as READ and ROUTE only. arcadedb.grpc.port is now a registered server setting, so unlike the other grpc.* keys it is resolved from environment variables too.
…ithheld peer endpoint
Three API-visible changes from arcadedb#6221 / #6226 / #6267 that the reference had not caught up with.
- POST /api/v1/command (and every auto-committing endpoint): `retries` now defaults to
arcadedb.txRetries (3) instead of a hard-coded 1. Documented with the caveat that matters:
only NeedRetryException/DuplicatedKeyException are retried and always after a rollback, but
the command itself runs again, so a SQL/JS function with a side effect OUTSIDE the database
can now perform it more than once per request. Send "retries": 1 to opt out.
- POST /api/v1/cluster/verify/{database}: a new "Verify Outcomes" table for the three
overallStatus values, including VERIFICATION_INCOMPLETE, with the note for alerting that
keys on INCONSISTENCY_DETECTED specifically.
- A "Peer-to-Peer Endpoints" section for the http/https twin of the routing-port ambiguity
already documented for bolt/grpc: what is withheld, the three places the refusal shows up
(the one-time WARNING, httpAddressAmbiguous in GET /api/v1/cluster and the Studio card,
and the error of whichever operation was refused), and why http and https are checked
independently.
Contributor
|
Tick the box to add this pull request to the merge queue (same as
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Item 5 of ArcadeData/arcadedb#6267 - three API-visible changes the HTTP/HA reference had not caught up with. The engine-side PR is ArcadeData/arcadedb#6284.
retriesonPOST /api/v1/command(and every other auto-committing endpoint) now defaults toarcadedb.txRetries(3) instead of a hard-coded 1 - the same attempt count the embedded and remote Java APIs take. Documented with the caveat that actually matters to a user: onlyNeedRetryException/DuplicatedKeyExceptionare retried, always after a full rollback, so nothing the failed attempt wrote survives - but the command runs again, so a SQL or JavaScript function with a side effect outside the database can now perform it more than once per request."retries": 1keeps the old single-attempt behaviour.overallStatusonPOST /api/v1/cluster/verify/{database}has a third value,VERIFICATION_INCOMPLETE("no divergence observed, but at least one peer could not be verified"). The endpoint had a one-line table cell and no description of its response at all, so this adds a "Verify Outcomes" section with all three values, why an unverified peer is deliberately not rolled up as an observed divergence, and the note for alerting: keying on!= ALL_CONSISTENTis unaffected, keying onINCONSISTENCY_DETECTEDneeds the new value added to keep catching an unreachable node.Peer-to-peer endpoints. The existing "Client Routing Ports" section documents what happens when two peers derive to the same
bolt/grpcaddress. The same thing happens to thehttp/httpsendpoints the nodes use to reach each other - a snapshot resync, a cluster verify, the presence matrix - and ArcadeData/arcadedb#6267 made that refusal visible instead of silent. The new section says what is withheld, the three places it now shows up (a one-time WARNING per protocol,httpAddressAmbiguousinGET /api/v1/clusterand on the Studio node card, and the error text of whichever operation was refused), and whyhttpandhttpsare checked independently.Anchors added:
ha-peer-endpoint-ambiguity,ha-verify-outcome. Both are referenced from within the same document; theretriesparagraph links the existingsetting-databaseanchor.