Skip to content

docs: add Node.js runtime and naming runtime specs - #165

Merged
KomachiSion merged 3 commits into
nacos-group:masterfrom
cxhello:docs/runtime-specs
Nov 17, 2026
Merged

KomachiSion merged 3 commits into
nacos-group:masterfrom
cxhello:docs/runtime-specs

Conversation

@cxhello

@cxhello cxhello commented Nov 9, 2026 •

Copy link
Copy Markdown
Member

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

  • Add the Node.js runtime spec: addressing, connection lifecycle, SetupAck, ability negotiation, request rules, login, token refresh, AK/SK, and TLS.
  • Add the naming runtime spec: service identity, routing for ephemeral and persistent instances, several instances per service, discovery, cache, subscription, and redo.
  • Define deregistration as asked in [Roadmap] nacos-sdk-nodejs 3.x #162: the same routing as registration, errors propagated, the intent kept until the server confirms, no fresh registration after a reconnect, and no replay of persistent instances.
  • Record each difference from the Java client with its reason.

Changes since the first review

  • Request retry: replaced "a sent request is never retried" with the bounded retry loop from RpcClient#request. 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. 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.
  • Failure intent: 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, and an explicit deregisterInstance cancels the intent.
  • Discovery and listeners: cache and subscription are separate facts. Removing the last listener unsubscribes but keeps the cache; a later discovery checks the subscription even when a cached view exists and subscribes again when needed. Resubscription failure returns a cached view, or rejects when there is no cache.
  • Push ACK: a NotifySubscriberResponse acknowledges protocol handling, not application completion. 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.
  • Result-unknown boundary: registered=false does not prove that the server holds no publication. The application-initiated deregistration always sends the real request, and the redo table is mapped to RedoData#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 the v2.6.3 tag.

Questions for maintainers

  • Error classification: when attempts are exhausted, the class is decided over the whole call. If an earlier attempt was sent and a later attempt could not be, the call is reported as result unknown, not connection unavailable. Java surfaces the last exception instead. Is the stronger guarantee acceptable?
  • Naming listener failure: a listener that throws is not retried. This matches Java, where NamingListenerInvoker keeps no completion state. Config retries failed listeners. Should naming stay as Java does?
  • Several instances per service: a second registerInstance adds to a batch instead of replacing the first, because 2.6.x over HTTP keeps both. Java replaces. Is that acceptable?
  • Not planned for 3.0: naming disk cache, naming failover, and push-empty protection. Do MSE users depend on any of them?

Follow this checklist to help us incorporate your contribution quickly and easily:

  • Make sure there is a Github issue filed for the change (usually before you start working on it). Trivial changes like typos do not require a Github issue. Your pull request should address just this issue, without pulling in other changes - one PR resolves one issue.
  • Format the pull request title with Conventional Commits, like fix: reject ready when login is refused. Each commit in the pull request should have a meaningful subject line and body.
  • Write a pull request description that is detailed enough to understand what your pull request does, how, and why.
  • Update the matching specs under specs/ if the change affects behavior, public APIs, options, lifecycle, or error mapping.
  • Write necessary unit tests to verify your logic. If a public client contract changes, update the test scenarios and coverage registry, and add integration tests that go through the public client.
  • Run pnpm -r run build and the affected unit and integration tests. See AGENTS.md for the commands.

Assisted-by: Claude Code

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>
@KomachiSion

Copy link
Copy Markdown
Contributor

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: 90f8ce1147e87f9cd8076bd47ee6574f1363b806.

1. Failure handling: preserve the latest intent, as Java does

Please 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, UN_REGISTER=301 is a connection failure signal: reconnecting while discarding the registration intent can leave nothing to restore.

Please use the Java behavior as the baseline:

  • Validate local arguments before changing intent or sending a request.
  • Preserve the latest registration/deregistration intent when the request fails. Surface the failure to the caller; retaining intent must not turn that failed call into success.
  • Keep bounded RPC retries/connection recovery separate from background Naming redo. Java handles 301 in the RPC layer and retains Naming intent. The blanket “never retry a sent request” rule needs to be reconciled with this flow; do not replace it with unlimited retries.
  • Keep persistent instances out of Naming redo. Bounded request retries and reconnect replay of persistent resources are different things.
  • Document that a failed ephemeral registration can become effective later through redo—for example, after connectivity or permissions recover. An explicit deregistration cancels that intent, subject to the boundary in section 4 below; closing the client releases its connection-scoped state.
  • Use the same intent rules for batch changes and subscriptions. Serialize application operations, redo, and state updates per service so that an older completion or rollback cannot overwrite a newer operation.

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 lifecycle

Naming §3 says a discovery-created subscription stays until close(), while §5 says removing the last listener unsubscribes. Please resolve this using the Java flow, rather than adding a separate permanent discovery-subscription ownership model:

  • Treat “a cached view exists” and “the service is subscribed” as separate facts.
  • Removing the last explicit listener sends unsubscribe, while retaining the cached view.
  • A subsequent discovery call with subscribe=true checks subscription state even when a cached view exists, and establishes the subscription again when needed.
  • If resubscription fails, an existing cached view may still be returned according to the Java path; with no cached view, propagate the failure. Keep the appropriate recovery intent.
  • Multiple cluster-filtered listeners share one service subscription. Removing one listener must not unsubscribe the others.
  • Remove the unconditional “stays active until close” statement and update the corresponding acceptance cases.

This is the combination of Java tryToSubscribe and doUnsubscribe, not just the unsubscribe half.

3. Make push ACK independent of application completion

A 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:

  1. Decode and validate the push against the connection/subscription lifecycle.
  2. Accept or ignore the view under the documented rules; update the cache and schedule notification when applicable.
  3. Send the matching NotifySubscriberResponse. Application notification runs independently; ACK must not wait for a listener's Promise to settle.
  4. A listener throwing or rejecting goes to the error path. It must not roll back an accepted cache update or turn that push into an SDK receive failure.

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 absence

Please correct the explanation for desired empty + registered=false -> REMOVE: registered=false alone does not prove that an old connection has closed and its publication has been removed. It can also mean that a registration response was never confirmed.

However, Java has this boundary too. Java's RedoData can select REMOVE when registration was unconfirmed and unregistering is set. Java first attempts the actual deregistration, and RPC recovery provides additional opportunities, but those steps do not establish a general guarantee for every result-unknown failure.

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

Area Scenario and assertions
Registration failure Fail after intent is recorded, then recover. The original call fails, intent remains, and redo can restore it. Cover 301 explicitly. Invalid local input must create no intent.
Deregistration failure Start from a confirmed registration, fail deregistration, then recover. The call fails, the unregistered intent remains, and redo must not re-register the removed instance.
Batch and ordering Single → multiple → one → empty; failure during a batch update; deregister followed by register; late responses from an old epoch. Verify remaining members and the latest intent, not only Promise results.
Discovery/listener lifecycle getAllInstances → subscribe(L) → unSubscribe(L) → getAllInstances: retain cache, unsubscribe when the last listener is removed, and re-establish subscription on the later discovery call. Also cover multiple cluster listeners.
Offline discovery Resubscription fails with and without cache: return the allowed cached view in the first case; surface failure in the second. Verify recovery when connectivity returns.
Push ACK Use a listener that returns a pending Promise, throws, or rejects. ACK must not depend on callback success/completion; cache and callback error handling remain independent. Verify the ACK itself, not just callback counts.
Push lifecycle Duplicate push, malformed view, stale epoch, unsubscribe/re-subscribe, and close during dispatch. Assert the documented protocol response and ensure no new callback starts for a removed listener.
Result-unknown boundary Registration may have applied without a confirmed response, followed by a failed deregistration. Verify the direct cancellation attempt and the documented Java-compatible state transitions; do not assert a stronger surviving-connection cleanup guarantee that the chosen design does not provide.
Persistent lifecycle Registration/deregistration use the persistent route or its documented fallback; failures remain visible, and reconnect does not add persistent-resource redo.

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>
cxhello added a commit to cxhello/nacos-sdk-nodejs that referenced this pull request Nov 12, 2026
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>
@cxhello

cxhello commented Nov 12, 2026

Copy link
Copy Markdown
Member Author

Thanks for the detailed review. All four points are addressed in 42059b3, and the matching scenarios are in #166.

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 deregisterInstance cancels the intent, and close() releases the connection-scoped state. Bounded RPC retries now live in Runtime 3.5 and are kept separate from background redo. 301 is handled in the retry loop, persistent instances stay out of redo, and batch changes and subscriptions use the same intent rules through the per-service queue.

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 close()" statement is gone. Removing the last listener sends unsubscribe while retaining the cache; a later discovery with subscribe=true checks the subscription even with a cached view and re-establishes it. Resubscription failure returns the cached view when there is one and propagates the failure when there is not; both keep recovery intent. Multiple cluster-filtered listeners share one cluster = NULL server subscription, and removing one does not unsubscribe the others.

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 NotifySubscriberResponse. Notification never gates the ACK, and a listener that throws or rejects goes to error without rolling back the accepted cache, turning the push into a receive failure, or introducing Config-style retry. Section 4.1 specifies malformed views, duplicate pushes, stale connection epochs, stale subscription generations, and pushes after unsubscribe or close. A decoded view that is ignored still gets a success ACK; only a decode failure gets an error response.

4. registered=false. Documented as a boundary, not a stronger guarantee. The application-initiated deregistration always attempts the real request; registered=false can also mean that no registration response was confirmed. The redo table is mapped to RedoData#getRedoType, including the registered=false, unregistering=true, expectedRegistered=true case. Nothing claims a stronger surviving-connection cleanup guarantee than Java.

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 KomachiSion left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread specs/en/naming/naming-runtime-spec.md Resolved
Comment thread specs/en/naming/naming-runtime-spec.md Resolved
Comment thread specs/en/client/nodejs-runtime-spec.md Resolved
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>
cxhello added a commit to cxhello/nacos-sdk-nodejs that referenced this pull request Nov 13, 2026
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>
@cxhello
cxhello requested a review from KomachiSion November 13, 2026 07:43
@KomachiSion
KomachiSion merged commit 2a9fe06 into nacos-group:master Nov 17, 2026
7 checks passed
cxhello added a commit to cxhello/nacos-sdk-nodejs that referenced this pull request Nov 17, 2026
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>
KomachiSion pushed a commit that referenced this pull request Nov 18, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants