Similarityoung opened a new issue, #998:
URL: https://github.com/apache/dubbo-go-pixiu/issues/998
## Problem Statement
Pixiu's Dubbo generic invocation path still has two competing target models.
On one side, Pixiu already has clusters and endpoints as the gateway's provider
view. On the other side, Dubbo generic invocation still carries provider target
information through API/backend config and can fall back to dubbo-go registry
resolution. This makes Nacos application/service discovery hard to land
cleanly, because provider address, service identity, protocol, serialization,
retry behavior, and dynamic API projection can diverge across API config, Dubbo
client config, and cluster endpoint state.
The desired behavior is simpler: for Nacos-backed Dubbo generic invocation,
Nacos discovery should populate Pixiu clusters, request execution should select
a Pixiu endpoint, and the Dubbo client should invoke that selected endpoint
directly. The API should describe the HTTP-to-Dubbo call intent, not own
provider target truth.
## Solution
Implement the first Nacos cluster-backed Dubbo generic invocation slice.
Nacos service/application discovery will resolve provider metadata using
dubbo-go metadata semantics, project discovered providers into service-level
Pixiu clusters, generate dynamic POST APIs and routers from provider methods,
and keep API/router/endpoint projection cleanup correct across add, update,
delete, unhealthy, and metadata-failure events.
At request time, the remote filter will select one endpoint from the matched
route's cluster. The selected endpoint's address and metadata become the single
runtime source for Dubbo service identity, protocol, serialization, group, and
version. The Dubbo client will only perform direct generic invoke against the
resolved outbound target. It will no longer perform runtime registry discovery
or configure implicit reference-level retries for this path.
## User Stories
1. As a Pixiu operator, I want Nacos provider discovery to populate Pixiu
clusters, so that Dubbo generic invocation uses the same provider view as the
rest of the gateway.
2. As a Pixiu operator, I want `registry-type` to match dubbo-go's
`service`, `interface`, and `all` vocabulary, so that configuration is not
Pixiu-specific or surprising.
3. As a Pixiu operator, I want omitted Nacos `registry-type` to mean
`service`, so that Pixiu follows dubbo-go's current default Nacos behavior.
4. As a Pixiu operator, I want `registry-type: all` to run through the
service path without double listening, so that Pixiu does not duplicate
provider events or maintain two provider views.
5. As a Pixiu operator, I want `registry-type: interface` to fail fast in
the first implementation, so that unsupported mode is explicit.
6. As a Pixiu operator, I want ZooKeeper to stay out of this slice, so that
the first implementation stays focused on Nacos.
7. As a Pixiu operator, I want Nacos application service names containing
`:` to be skipped in service discovery, so that interface registry entries are
not mixed into application-level discovery.
8. As a Pixiu operator, I want Pixiu to resolve provider metadata through
dubbo-go's metadata API, so that remote metadata report, local metadata RPC,
fallback, registry-scoped lookup, and cache semantics stay aligned with
dubbo-go.
9. As a Pixiu operator, I want provider metadata failures to prevent
API/endpoint generation, so that Pixiu does not expose incomplete Dubbo routes.
10. As a Pixiu operator, I want old projections removed when metadata can no
longer be resolved, so that stale APIs and endpoints do not remain available.
11. As a Pixiu operator, I want services with no valid method list to be
skipped, so that Pixiu does not expose wildcard Dubbo APIs in this slice.
12. As a Pixiu operator, I want dynamic APIs generated from provider method
metadata, so that HTTP users can call discovered Dubbo methods without manually
writing each route.
13. As a Pixiu operator, I want generated dynamic APIs to use POST, so that
generic invocation body mapping is stable.
14. As a Pixiu operator, I want generated dynamic API paths to remain
`/{application}/{interface}/{method}`, so that existing route shape is
preserved as an HTTP projection.
15. As a Pixiu operator, I want path application/interface segments to be
treated only as route projection, so that runtime Dubbo identity always comes
from the selected endpoint.
16. As a Pixiu operator, I want version/group path conflicts to be skipped
and logged, so that conflicting dynamic projections do not overwrite each other
silently.
17. As a Pixiu operator, I want each Dubbo service identity to map to a
service-level cluster, so that all methods of a service share provider
availability.
18. As a Pixiu operator, I want the same Nacos application instance to
project multiple service endpoints when it exports multiple services, so that
application-level discovery supports real Dubbo apps.
19. As a Pixiu operator, I want endpoint address to come from dubbo-go's
service URL conversion, so that `dubbo.endpoints` protocol-specific ports are
honored.
20. As a Pixiu operator, I want endpoint metadata to carry interface,
protocol, serialization, application, version, and group, so that request-time
invocation has one provider truth source.
21. As a Pixiu operator, I want dynamic endpoint IDs to include service
identity, address, protocol, and serialization, so that endpoint updates
replace the correct provider target.
22. As a Pixiu operator, I want unhealthy or disabled Nacos instances to
remove old projections, so that Pixiu does not invoke unavailable providers.
23. As a Pixiu operator, I want deleted Nacos application services to clean
up generated endpoints, APIs, and routers, so that stale HTTP exposure
disappears.
24. As a Pixiu operator, I want router and API projection cleanup to happen
together, so that removing an API does not leave a live route behind.
25. As a Pixiu API author, I want Dubbo API config to keep only method and
optional parameterTypes, so that provider target configuration is not
duplicated in APIs.
26. As a Pixiu API author, I want static routes to choose provider targets
through cluster endpoints, so that static and dynamic Dubbo invocation use the
same runtime model.
27. As a Pixiu API caller, I want dynamic generic invocation to accept
`values` and `types` in the request body, so that overload resolution remains
caller-controlled when parameter types are not inferred.
28. As a Pixiu API caller, I want static APIs with declared parameterTypes
to allow values-only requests, so that stable static contracts remain ergonomic.
29. As a Pixiu maintainer, I want mapping params to provide only argument
values and types, so that request mapping cannot rewrite service identity or
method.
30. As a Pixiu maintainer, I want the remote filter to select the endpoint
before building the Dubbo outbound request, so that Dubbo client code does not
depend on the global cluster manager.
31. As a Pixiu maintainer, I want the Dubbo client to consume a resolved
outbound request, so that the client remains a direct execution layer.
32. As a Pixiu maintainer, I want the Dubbo client to remove runtime
registry mode, so that provider resolution stays in Pixiu discovery and cluster
layers.
33. As a Pixiu maintainer, I want generic service cache keys to be
endpoint-scoped, so that cached references cannot be reused across different
direct provider targets.
34. As a Pixiu maintainer, I want registry IDs and retries removed from the
generic service cache key, so that deleted semantics do not keep influencing
runtime behavior.
35. As a Pixiu maintainer, I want `dubboProxyConfig` to be optional, so that
target configuration is not required in the Dubbo client config.
36. As a Pixiu maintainer, I want `dubboProxyConfig` to keep only timeout
and load-balance defaults for this path, so that client defaults do not
reintroduce provider discovery.
37. As a Pixiu maintainer, I want direct generic invoke failures to return
immediately without selecting another endpoint, so that this slice does not
change cluster retry semantics.
38. As a Pixiu maintainer, I want no compatibility layer for removed API
target fields, so that the implementation does not accumulate stale
configuration paths.
39. As a Pixiu maintainer, I want clear validation errors for missing
endpoint interface, protocol, or serialization, so that bad static cluster
config is diagnosable.
40. As a future contributor, I want this feature described in ADRs and a
PRD, so that follow-up implementation work has stable boundaries.
## Implementation Decisions
- Nacos is the only registry implementation in this PRD. ZooKeeper remains
out of scope.
- Nacos registry mode uses dubbo-go naming: `service`, `interface`, and
`all`; default is `service`.
- `all` is accepted but handled through the `service` path. Pixiu does not
start both service and interface listeners.
- `interface` is unsupported in the first implementation and should fail
fast.
- Provider metadata is resolved through dubbo-go's metadata entry point.
Pixiu does not read Nacos Config directly for metadata.
- Metadata must be resolved before Pixiu creates dynamic APIs or endpoints.
Metadata failure removes any previous projection for that instance.
- Services without a valid methods list are skipped. No wildcard API is
generated.
- Dynamic APIs use POST and the body mapping `requestBody.values ->
opt.values` and `requestBody.types -> opt.types`.
- Dynamic APIs do not infer Java parameter types from metadata. Dynamic
callers provide `types` unless a static API declares parameterTypes.
- Dynamic API paths use `/{application}/{interface}/{method}` only as HTTP
route projection.
- Runtime Dubbo service identity comes from selected endpoint metadata, not
from the HTTP path or API target fields.
- Service-level clusters are keyed by application, interface, version, and
group. Method is not part of the cluster identity.
- Endpoint identity includes service identity, provider address, protocol,
and serialization.
- Dynamic endpoint address comes from the service URL produced by dubbo-go
metadata conversion, preserving protocol-specific endpoint ports.
- Endpoint metadata mirrors Dubbo URL parameter names: application,
interface, version, group, protocol, and serialization.
- Interface, protocol, and serialization are required endpoint metadata for
invocation. Application, version, and group may be empty.
- The remote filter selects a cluster endpoint before constructing the Dubbo
outbound request.
- The Dubbo handler builds outbound target values from selected endpoint
address and metadata, plus API method and argument mapping.
- The Dubbo client consumes only resolved outbound values and performs
direct generic invocation.
- Runtime dubbo-go registry discovery is removed from this path.
- Dubbo reference-level implicit retries are removed from this path.
- Same-request cross-endpoint retry is not implemented in this slice.
- `DubboBackendConfig` keeps method and parameterTypes only for generic
invocation runtime contract.
- `DubboProxyConfig` is optional and only contributes timeout/load-balance
defaults when present.
- Registry configuration belongs to the Dubbo registry adapter, not to the
Dubbo client.
- Dynamic projection cleanup must remove generated routers and APIs
together. Endpoint cleanup remains cluster-level.
- Providers under the same service identity are assumed to expose compatible
method sets. Pixiu does not maintain method-to-endpoint availability state.
## Testing Decisions
- Tests should assert external behavior at the highest useful seam rather
than internal helper details.
- The primary seam for discovery behavior is the Nacos registry adapter
projection: given Nacos service/instance/metadata events, Pixiu should produce
or remove service-level endpoints, APIs, and routers.
- The primary seam for request behavior is the remote filter to Dubbo client
boundary: given a matched route cluster and selected endpoint metadata, Pixiu
should build a direct outbound request with the expected service identity,
address, protocol, serialization, method, arguments, and parameter types.
- Dubbo client tests should verify direct-only reference behavior and cache
key shape without depending on dubbo-go internals beyond observable
options/errors.
- Registry type tests should verify omitted/service/all/interface behavior
through adapter construction or the highest available registry config seam.
- Endpoint metadata validation tests should verify missing interface,
protocol, or serialization produces explicit request-time errors.
- Metadata failure tests should verify no new projection is created and old
projection is deleted.
- Empty methods tests should verify no wildcard API is produced.
- Dynamic cleanup tests should verify stale router and API entries are both
removed.
- Existing similar prior art includes cluster manager endpoint selection
tests, remote filter Dubbo outbound mapping tests, Dubbo client cache/reference
tests, router API insertion/removal tests, and current Nacos registry listener
tests.
## Out of Scope
- ZooKeeper support.
- Nacos `registry-type: interface` support.
- Double-listening behavior for `registry-type: all`.
- Method-level clusters.
- Method-to-endpoint availability state.
- Metadata-to-Java-signature inference.
- Wildcard APIs for missing method metadata.
- New generic invocation request body schema.
- Request body method selection.
- Mapping-based rewrite of service identity or method.
- Same-request cross-endpoint retry.
- Dubbo-go runtime registry discovery inside the Dubbo client.
- Compatibility aliases for removed API target fields.
- Strict YAML unknown-field validation for removed keys.
## Further Notes
This PRD follows the current ADR direction: endpoint metadata is the runtime
provider truth, APIs express only call intent, and Pixiu cluster selection owns
endpoint choice. The implementation should prefer the shortest correct path and
avoid compatibility layers or duplicate provider state.
The main implementation risk is accidental reintroduction of a second
provider target source through API URL, API Dubbo target fields, or Dubbo
client registries. Tests should make those paths visibly inert or removed.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
