Repository navigation
docs: add Node.js runtime and naming runtime specs - #165
Conversation
Define addressing, connection, ability negotiation, and authentication for the shared runtime, and registration, discovery, subscription, and redo for naming. Record each difference from the Java client with its reason. Refs nacos-group#162 Assisted-by: Claude Code Signed-off-by: cxhello <caixiaohuichn@gmail.com>
|
The overall runtime/domain split fits the 3.x direction in #162. Before using these specs as the implementation baseline, please align failure handling and the discovery/subscription lifecycle with Java client 3.3.0, and make the Naming push ACK boundary explicit. Please update the related sections together so that the implementation and #166's scenarios follow one consistent contract. Reviewed head: 1. Failure handling: preserve the latest intent, as Java doesPlease revise Naming §2.3, §2.4 and §6 together with Runtime §3.5. Java caches ephemeral registration intent before sending the request. A failed call throws, but does not automatically restore the previous registration intent. Deregistration first marks the intent as unregistered; a failed request does not put the instance back into the desired registered state. The current rules—“every non-200 restores the previous desired set” and “a rejected deregistration returns the instance to the desired set”—are different from Java. In particular, Please use the Java behavior as the baseline:
This does not require introducing a new permanent/transient-error abandonment framework in this PR. Java does not provide the complete automatic-abandonment matrix previously considered in the review. Such a policy would be a separately documented behavioral difference. References: Java registration, deregistration, and RPC retry / UN_REGISTER handling. 2. Discovery and explicit listeners: use one Java-aligned lifecycleNaming §3 says a discovery-created subscription stays until
This is the combination of Java tryToSubscribe and doUnsubscribe, not just the unsubscribe half. 3. Make push ACK independent of application completionA Naming push ACK means the SDK has received and handled the view according to the protocol. It does not mean the application's listener has successfully completed its business processing. Please explicitly define the boundary in Naming §4–§5:
Also specify how malformed views, duplicate pushes, stale epochs and pushes after unsubscribe are handled. “No application callback” is not by itself an ACK failure. Scheduling notification must not be omitted merely because ACK has already been sent. Java's NamingPushRequestHandler processes the service view and returns the response; ServiceInfoHolder publishes the notification event. This is a responsibility boundary, not an unconditional timing/isolation guarantee. A synchronously blocked Node.js event loop can still delay ACKs and other work. Java also has finite execution resources and a synchronous delivery fallback when its event queue is full. No worker/Executor or forced cancellation of application code is required here. 4. Boundary clarification, not a P1: unconfirmed registration is not proof of absencePlease correct the explanation for However, Java has this boundary too. Java's RedoData can select Please align the complete direct deregistration / request-failure / redo / connection-cleanup flow and describe its limits. Do not skip the actual deregistration solely because registration was unconfirmed. This is not a Node-specific P1 and does not require a stronger unknown-result confirmation protocol than Java in this PR. A stronger guarantee can be discussed separately. Acceptance scenarios to carry into #166
Please update the runtime spec, naming state tables and test scenarios together. The aim is one consistent Java-aligned contract, with the ACK/application boundary stated explicitly, rather than separate fixes to individual rows. |
Align the runtime and naming specs with Java client 3.3.0, as requested in the nacos-group#165 review. - Runtime: replace "never retry a sent request" with Java's bounded retry loop. One initial attempt and up to three retries inside start + requestTimeout; any failed attempt is retried, including a server ErrorResponse; 301 switches server and retries within the same budget. The final error class is decided over the whole call so the "not sent" guarantee of the error model stays true. - Naming registration and deregistration keep the latest intent when a request fails, including a server rejection. Nothing restores the previous desired set. Redo owns the next attempt. - Discovery and explicit listeners share one lifecycle: cache and subscription are separate facts, the last listener removal unsubscribes but keeps the cache, and a later discovery re-establishes the subscription even when a cached view exists. - Push ACK is a protocol acknowledgement. It is sent after the view is accepted or ignored and notification is scheduled, never waits for a listener Promise, and survives a throwing listener. Ignored, duplicate, stale-epoch and post-unsubscribe pushes are specified per case. - Document that registered=false does not prove server-side absence, and map the redo table to RedoData#getRedoType. Assisted-by: Claude Code Signed-off-by: cxhello <caixiaohuichn@gmail.com>
Carry the nacos-group#165 conclusions into the test design, the scenario matrix, and the Config first-delivery contract, as requested in the nacos-group#166 review. - Config: define the first-subscription source-selection table in 9.5. A new listener seeds the effective record through the same path as getConfig; failover and snapshot fallback, confirmed absence, unknown, and authorization failure each have a stated outcome. Unknown entries are queried directly on connect or periodic sync. - Implementation spec: document the publish/CAS replay boundary and the post-close result of getServerStatus. - Test design: add a TLS fixture environment using an in-process @grpc/grpc-js server with fixed certificates, and require protocol responses such as a Naming push ACK to be observed directly. - Scenarios: replace the rows that contradicted the new naming contract (NAM-18/19/25/26, CON-11/14/15, CFG-50/51/36/57, ERR-03, PKG-05), add the failure-intent, subscription-lifecycle, push-ACK, Config first-delivery, retry-policy, coverage, and TLS cases. - Coverage registry: map the new scenarios to the public APIs and runtime behaviors they assert. Assisted-by: Claude Code Signed-off-by: cxhello <caixiaohuichn@gmail.com>
|
Thanks for the detailed review. All four points are addressed in 1. Failure handling. Naming 2.3 and 2.4 now keep the latest intent. Local validation runs first, then the intent is recorded, then the request is sent. A server rejection, a connection failure, and an unknown result all reject the caller without restoring the previous desired set or putting a deregistered instance back. Redo owns the next attempt; an explicit One deliberate difference: the final error class is decided over the whole call. If an earlier attempt was sent and a later attempt could not be, the call reports a result-unknown failure rather than connection-unavailable, so the error model's "request was not sent" guarantee stays true. Java surfaces the last exception. I have listed this as a question in the PR body. 2. Discovery and explicit listeners. Cache and subscription are now separate facts. The unconditional "until 3. Push ACK. Naming 5 now defines the boundary explicitly: decode and validate, accept or ignore under 4.1, update the cache and schedule notification, then send 4. Acceptance scenarios. Carried into #166 as NAM-59 to NAM-72, CON-11/14/15/19 to CON-22, and the Config first-delivery cases CFG-62 to CFG-67. |
KomachiSion
left a comment
There was a problem hiding this comment.
Follow-up on the updated specs, reviewed at 42059b33eac45e3bc810af0e12ba37c50c2d391b and #166 786997afdf2fc07413d6799a40cdbc3acba73093.
The main runtime/Naming direction and ACK boundary are now substantially addressed. The inline comments are scoped to (1) a state-definition clarification and (2-a/2-b) two concrete wording/acceptance refinements, rather than three new architecture defects.
Please prefer Java client 3.3.0 behavior wherever Node.js can implement it correctly and reliably. Any exception needs a concrete Node/Java mechanism constraint, an explicit observable contract, and tests; documentation alone is not a justification for divergence. The comments include Java source references and complete example sequences. Carry the matching scenario updates into #166. These documentation PRs do not need to implement every Pending test.
Address the follow-up review on the updated runtime and naming specs. - Naming 2.4/6.1: a deregistration removes the instance from the desired set and records the removal intent, but does not clear an existing registered=true on the live connection. Only a successful removal commits the change, and only a connection change resets the confirmation. A failed removal therefore stays on UNREGISTER rather than falling to a local REMOVE. Add the shared transition table and qualify the success rows per operation. - Naming 2.4: persistent instances do not participate in background redo or reconnect replay, but their foreground gRPC requests use the normal bounded RPC retry policy. - Runtime 3.5: separate a failed attempt, the final call outcome, and later background redo. Add the mixed-attempt sequences, distinguish a protocol ErrorResponse from a normal typed business response, and make the whole-call error classification an explicit documented difference with its reason and acceptance cases. - Runtime 5.2: a 403 fails the attempt, not necessarily the call. - Naming 2.3 and 8: distinguish a typed server rejection from a protocol ErrorResponse, and add the mixed attempt outcomes. Assisted-by: Claude Code Signed-off-by: cxhello <caixiaohuichn@gmail.com>
Carry the nacos-group#165 conclusions into the test design, the scenario matrix, and the Config first-delivery contract, as requested in the nacos-group#166 review. - Config: define the first-subscription source-selection table in 9.5. A new listener seeds the effective record through the same path as getConfig; failover and snapshot fallback, confirmed absence, unknown, and authorization failure each have a stated outcome. Unknown entries are queried directly on connect or periodic sync. - Implementation spec: document the publish/CAS replay boundary and the post-close result of getServerStatus. - Test design: add a TLS fixture environment using an in-process @grpc/grpc-js server with fixed certificates, and require protocol responses such as a Naming push ACK to be observed directly. - Scenarios: replace the rows that contradicted the new naming contract (NAM-18/19/25/26, CON-11/14/15, CFG-50/51/36/57, ERR-03, PKG-05), add the failure-intent, subscription-lifecycle, push-ACK, Config first-delivery, retry-policy, coverage, and TLS cases. - Coverage registry: map the new scenarios to the public APIs and runtime behaviors they assert. Assisted-by: Claude Code Signed-off-by: cxhello <caixiaohuichn@gmail.com>
Carry the nacos-group#165 conclusions into the test design, the scenario matrix, and the Config first-delivery contract, as requested in the nacos-group#166 review. - Config: define the first-subscription source-selection table in 9.5. A new listener seeds the effective record through the same path as getConfig; failover and snapshot fallback, confirmed absence, unknown, and authorization failure each have a stated outcome. Unknown entries are queried directly on connect or periodic sync. - Implementation spec: document the publish/CAS replay boundary and the post-close result of getServerStatus. - Test design: add a TLS fixture environment using an in-process @grpc/grpc-js server with fixed certificates, and require protocol responses such as a Naming push ACK to be observed directly. - Scenarios: replace the rows that contradicted the new naming contract (NAM-18/19/25/26, CON-11/14/15, CFG-50/51/36/57, ERR-03, PKG-05), add the failure-intent, subscription-lifecycle, push-ACK, Config first-delivery, retry-policy, coverage, and TLS cases. - Coverage registry: map the new scenarios to the public APIs and runtime behaviors they assert. Assisted-by: Claude Code Signed-off-by: cxhello <caixiaohuichn@gmail.com>
…trix (#166) * docs: add test design spec and scenario matrix Define the test layers, environments, and release gates for 3.0, with scenario coverage as the gate instead of line coverage. Add the scenario matrix and a registry that maps each public API to its scenarios and tracks the existing test files. Refs #162 Assisted-by: Claude Code Signed-off-by: cxhello <caixiaohuichn@gmail.com> * docs: align the test contract with the Java-aligned naming spec Carry the #165 conclusions into the test design, the scenario matrix, and the Config first-delivery contract, as requested in the #166 review. - Config: define the first-subscription source-selection table in 9.5. A new listener seeds the effective record through the same path as getConfig; failover and snapshot fallback, confirmed absence, unknown, and authorization failure each have a stated outcome. Unknown entries are queried directly on connect or periodic sync. - Implementation spec: document the publish/CAS replay boundary and the post-close result of getServerStatus. - Test design: add a TLS fixture environment using an in-process @grpc/grpc-js server with fixed certificates, and require protocol responses such as a Naming push ACK to be observed directly. - Scenarios: replace the rows that contradicted the new naming contract (NAM-18/19/25/26, CON-11/14/15, CFG-50/51/36/57, ERR-03, PKG-05), add the failure-intent, subscription-lifecycle, push-ACK, Config first-delivery, retry-policy, coverage, and TLS cases. - Coverage registry: map the new scenarios to the public APIs and runtime behaviors they assert. Assisted-by: Claude Code Signed-off-by: cxhello <caixiaohuichn@gmail.com> * docs: apply the naming review follow-up to the test contract Address the follow-up review on the test design and scenario matrix. - NAM-62: restoring the server subscription never restores an application listener. The final discovery re-establishes the subscription, a later service change is visible to later discovery calls, and the removed listener's invocation count stays unchanged. An explicit subscribe is a new registration, and a different listener does not revive the old one. - NAM-25/26: assert the removal intent, the preserved registration confirmation, and the next redo request for a failed deregistration on a live connection. - NAM-29: separate bounded foreground retries from background redo for persistent instances. - CON-19/20/21 and ERR-05: separate a failed attempt from a failed call. A later successful attempt may complete the call; a finally failed call never becomes success or an empty result. A typed business response is not a protocol ErrorResponse and is not retried by the runtime. - AUTH-13: the 403 attempt fails and may be followed by a successful attempt after refresh; the call rejects with NacosAuthError only when it ultimately fails. - Implementation spec: stage the error-model rules and the CAS outcome the same way. Assisted-by: Claude Code Signed-off-by: cxhello <caixiaohuichn@gmail.com> --------- Signed-off-by: cxhello <caixiaohuichn@gmail.com>
Refs #162
What is the purpose of the change
Add the runtime and naming specs, and complete the second follow-up from #162: the full register and deregister lifecycle.
The specs are aligned with Java client 3.3.0. This update addresses the review on this PR.
Brief changelog
SetupAck, ability negotiation, request rules, login, token refresh, AK/SK, and TLS.Changes since the first review
RpcClient#request. One initial attempt and up to three retries insidestart + requestTimeout; any failed attempt is retried, including a serverErrorResponse;301switches server and retries within the same budget. Foreground attempts are kept separate from background redo. The final error class is decided over the whole call, so the "request was not sent" guarantee of the error model stays true.deregisterInstancecancels the intent.NotifySubscriberResponseacknowledges protocol handling, not application completion. It is sent after the view is accepted or ignored and notification is scheduled, never waits for a listenerPromise, and survives a throwing listener. Ignored, duplicate, stale-epoch, and post-unsubscribe pushes are specified per case.registered=falsedoes not prove that the server holds no publication. The application-initiated deregistration always sends the real request, and the redo table is mapped toRedoData#getRedoType.The test design follows in #166.
Verifying this change
Docs only. Java defaults and behavior were checked against tag 3.3.0, specifically commit
e61ba821e025d713fc02d2020a338d4ce4251912(RpcClient,NamingGrpcClientProxy,NamingGrpcRedoService,RedoData,NacosNamingService,NamingPushRequestHandler,ServiceInfoHolder). Claims about 2.6.x were checked against thev2.6.3tag.Questions for maintainers
NamingListenerInvokerkeeps no completion state. Config retries failed listeners. Should naming stay as Java does?registerInstanceadds to a batch instead of replacing the first, because 2.6.x over HTTP keeps both. Java replaces. Is that acceptable?Follow this checklist to help us incorporate your contribution quickly and easily:
fix: reject ready when login is refused. Each commit in the pull request should have a meaningful subject line and body.specs/if the change affects behavior, public APIs, options, lifecycle, or error mapping.pnpm -r run buildand the affected unit and integration tests. SeeAGENTS.mdfor the commands.Assisted-by: Claude Code