GitHub user CAICAIIs added a comment to the discussion: [DISCUSS] [GSoC 2026]
Proposal on Seata-Go multi-registry support and seata-ctl diagnostics
# GSoC 2026 Proposal: Enhance Seata-Go Multi-Registry Support and seata-ctl
Diagnostic Tool Capability
- Name: Yang Xuwei
- GitHub: CAICAIIs
- Time zone: Asia/Shanghai (UTC+8)
- Weekly availability during GSoC: around 35-40 hours per week
## Relevant Preparation
- `#1056` and `#1057`: Oracle XA investigation and follow-up implementation
attempt
- `#1061`: XA `commitOnXA()` and `LockQuery()` work
- `#1079`: TCC fence identity fix
- `#3175` and `#3180`: Apache Dubbo-Go contributions in compatibility-sensitive
paths
## Project Summary
After tracing the current Go SDK registry path through `pkg/client/client.go`,
`pkg/discovery/base.go`, `pkg/discovery/config.go`, `pkg/discovery/init.go`,
`pkg/discovery/file.go`, `pkg/discovery/etcd3.go`, and
`pkg/remoting/getty/session_manager.go`, my conclusion is that Seata-Go is not
yet in a state where "add four registries and a TUI" would be a credible
project description.
Right now, the registry abstraction is still very small: `RegistryService` only
exposes `Lookup` and `Close`; `InitRegistry` only wires `file` and `etcd`;
`nacos`, `zk`, `consul`, `redis`, `eureka`, and `sofa` are still placeholders;
and the current etcd watcher updates an internal cache without reconciling live
Getty sessions. On the tooling side, the current incubator-seata-ctl already
has a useful CLI/REPL and terminal-output foundation, but it is not yet a
mature TUI platform, and some of its admin flows assume server APIs that I do
not want to promise blindly.
Because of that, I want this proposal to stay aligned with the official topic
while sequencing the work around four concrete outcomes:
- a Java-aligned multi-registry foundation in seata-go
- production-credible Nacos and ZooKeeper support first, followed by Consul and
Redis on top of the same foundation
- a bounded but useful seata-ctl diagnostic baseline covering environment
self-checks plus transaction and lock inspection
- TUI polish, samples, and community-facing documentation only after the
required backend and CLI baseline is stable
The final goal is not just "more registry names in configuration." It is to
make Seata-Go easier to deploy in real service-governance environments and
easier to debug when distributed transactions behave unexpectedly.
## Background and Problem Definition
Apache Seata's Java implementation already has a mature registry SPI and a
broader operational story, but Seata-Go still lags behind at the infrastructure
boundary.
The gap matters for two reasons.
First, registry support is part of real deployment viability. If Go users can
only rely on `file` or a partial `etcd` path while the rest of their platform
already uses Nacos or ZooKeeper, Seata-Go looks like a special-case client
instead of a first-class member of the Seata ecosystem.
Second, troubleshooting matters almost as much as feature support. Distributed
transaction failures are often caused by partially correct setups: stale
registry entries, unhealthy server nodes, inconsistent group mappings, or
orphaned transaction/lock state. In those moments, a small but reliable query
tool is usually more valuable than a broad but fragile admin surface.
I also compared the Go code with Java 2.x. Java already has:
- `RegistryService`
- `RegistryFactory`
- `MultiRegistryFactory`
- real Nacos, ZooKeeper, Consul, and Redis implementations
- richer alive-address and multi-registry behavior than the Go SDK currently has
That gives this project a strong reference direction. I do not need to invent
the architecture from scratch, but I do need to translate it carefully into Go
and into the current Seata-Go codebase.
## Scope Clarification
The official Apache idea for this topic has a broad surface: multi-registry
support, NamingServer compatibility, seata-ctl diagnostics, structured output,
and TUI ambitions. I therefore keep the proposal aligned with that umbrella,
but stage the delivery so the shared registry foundation and the first
diagnostically useful CLI slice land first. I think the right way to make that
scope credible is to preserve the priority ordering of the idea instead of
flattening everything into one summer-sized promise.
My interpretation of the required scope is:
- `P0`: establish the shared registry foundation, land Nacos and ZooKeeper
first, and fix NamingServer/path-compatibility issues that block that baseline
- `P1`: bring Consul and Redis onto the same shared path and deliver a bounded
seata-ctl diagnostic baseline with structured output
- `P2`: add TUI polish, strengthen samples/docs, and complete community-facing
writeups
What I am explicitly not treating as required first-wave deliverables:
- full parity with every Java registry backend
- a broad TUI-centered seata-ctl rewrite before the command semantics are stable
- config mutation / reload workflows
- synthetic transaction simulation flows
- hidden server-side API additions that have not been confirmed with mentors
If a server-side contract turns out to be necessary for part of the CLI work, I
will treat that as a mentor-confirmation item during community bonding, not as
an implicit assumption inside the required scope.
## Current State and Gap Analysis
My current understanding is based on direct code reading across all three
relevant codebases.
### In local incubator-seata-go
- `pkg/discovery/base.go` still defines `RegistryService` as only `Lookup` and
`Close`.
- `pkg/discovery/init.go` really initializes only `file` and `etcd`.
- `pkg/discovery/nacos.go`, `pkg/discovery/zk.go`, `pkg/discovery/consul.go`,
and `pkg/discovery/redis.go` are still stub files with `panic("implement me")`.
- `pkg/discovery/etcd3.go` has real `Get` + `Watch` logic, but no
registration/lease path and no live session reconciliation.
- `pkg/remoting/getty/session_manager.go` still creates sessions from a
one-time registry lookup.
- `pkg/discovery/config.go` already exposes some registry config surface, but
the runtime and config model are not fully aligned.
This means the Go-side work is not "hook up a few SDKs." The shared foundation
still needs to become registry-aware in a more explicit way.
### In local incubator-seata Java 2.x
- `RegistryService` already models `register`, `unregister`, `subscribe`,
`unsubscribe`, `lookup`, and `close`.
- `RegistryFactory` and `MultiRegistryFactory` provide the factory and
multi-registry loading model that Seata-Go currently lacks.
- Nacos, ZooKeeper, Consul, and Redis are implemented with backend-specific
semantics:
- Nacos: listeners and address maps
- ZooKeeper: ephemeral nodes and watchers
- Consul: health checks, notifier loops, and heartbeat-aware behavior
- Redis: TTL refresh plus pub/sub
That is an important scoping signal. These adapters are not the same problem
with different import paths.
### In current incubator-seata-ctl
- The repo already has a real CLI codebase.
- `cmd/root.go`, `action/root.go`, and `action/common/args.go` show that the
interactive CLI/REPL flow is already part of the current design.
- `seata/txn.go`, `seata/status.go`, and `seata/config.go` show that query and
terminal-output paths already exist.
- The project is a better foundation for a small read-only query layer than for
promising a large TUI or mutation-heavy admin surface.
## Project Goals
### Core goals
1. Introduce a Java-aligned registry SPI and factory path in Seata-Go so
registry support no longer grows around an implicit `file` / `etcd`-only design.
2. Keep current `file` and `etcd` behavior safe while improving the
architecture around them.
3. Deliver Nacos support as the first required production-facing registry
adapter.
4. Deliver ZooKeeper support as the second required adapter, with explicit
watcher and session-update handling.
5. Deliver Consul and Redis on the same shared registry path after the
Nacos/ZooKeeper baseline is stable.
6. Deliver one bounded seata-ctl diagnostic baseline covering environment
self-checks, active transactions, and XID locks.
7. Ship tests, samples, documentation, and community-facing writeups as part of
the feature work instead of deferring them to the end.
### Non-goals for the guaranteed scope
- Full Java registry matrix parity in one summer
- A broad seata-ctl config-management platform
- Full TUI delivery as a must-ship milestone
- Implicit server API expansion
## Technical Plan
### 1. Shared multi-registry foundation in seata-go
The first step is not Nacos-specific or ZooKeeper-specific business logic. The
first step is to stop treating the current Go discovery layer as if `Lookup`
and `Close` are enough.
I plan to introduce a clearer registry layer around the operations that Java
Seata already models:
- `register`
- `unregister`
- `subscribe`
- `unsubscribe`
- `lookup`
- `close`
I also want the loading path to become more explicit, closer to a
provider/factory model than the current switch-only initialization path. This
is the architectural work that makes the later backend additions reviewable
instead of ad hoc.
### 2. Preserve current file and etcd behavior while fixing the boundary
I do not want the foundation work to regress current users.
That means:
- preserving file lookup behavior
- preserving the current etcd discovery path
- fixing obvious init/config issues
- making unsupported-type behavior fail in a clearer way
- creating a boundary where registry updates can reach remoting/session
handling instead of stopping at an internal cache
One of the most important local findings was that etcd watch updates currently
stop at the cache layer. I want to address that class of problem early, because
otherwise every new backend inherits the same weakness.
### 3. Nacos first
Nacos should be the first required backend for three reasons:
- it is explicitly prioritized by the idea
- the Go SDK already has some Nacos config surface
- the Java implementation gives a clear reference shape
I do not want to describe this as simple endpoint lookup work. The real work
includes naming conventions, group and cluster routing, listener behavior, and
making the Go-side semantics line up with what Java users already expect.
### 4. ZooKeeper second
ZooKeeper should be the second required backend because it is also explicitly
prioritized by the idea and because its operational model is meaningfully
different from Nacos.
The Java implementation uses ephemeral nodes and watchers, so the Go version
should be built with those realities in mind instead of pretending the same
adapter template fits every registry family.
### 5. Bounded seata-ctl diagnostic baseline
For the required CLI slice, I want to stay with one bounded, diagnostically
useful scope:
- server/network reachability checks against the configured Seata server
- config/required-field validation for the local client side
- active transaction queries
- XID lock queries
- table / JSON / YAML output
I do not want to promise config mutation, reload, or a broad admin surface as
required deliverables. The current tool already has a usable command flow and
terminal output path, so the most credible proposal is to extend those existing
diagnostics first, then treat the TUI as second-wave polish once the commands
themselves are solid.
Concretely, this is the part of the current codebase I expect to build on:
- `cmd/root.go`
- `action/root.go`
- `action/common/args.go`
- `seata/txn.go`
- the current table-rendering/output flow in `seata/*`
### 6. Consul and Redis on the same shared path
I do want the foundation to be strong enough for Consul and Redis, because the
official topic explicitly includes them and the Java side already shows how
those backends behave. I still want them sequenced after Nacos and ZooKeeper
rather than ahead of the common registry/session boundary, but I am treating
them as planned in-scope work, not as out-of-scope extras.
## Deliverables and Acceptance Criteria
| Deliverable | Priority | Acceptance criteria |
| --- | --- | --- |
| Shared registry SPI/factory layer in seata-go | P0 | Seata-Go no longer
relies on a `Lookup` / `Close`-only mental model, and registry/provider/factory
behavior is explicit and reviewable. |
| Safe file / etcd foundation plus NamingServer/path compatibility work | P0 |
Existing `file` and `etcd` behavior still works, init/config gaps are improved,
and NamingServer/path-compatibility blockers for the Go SDK are explicitly
addressed. |
| Nacos adapter | P0 | Nacos works through the new shared registry path with
validated naming/routing behavior, tests, and sample config. |
| ZooKeeper adapter | P0 | ZooKeeper works through the new shared registry path
with watcher-based behavior, tests, and sample config. |
| Consul and Redis adapters | P1 | Consul and Redis both run through the same
shared registry path with backend-appropriate discovery semantics,
compatibility notes, and test coverage proportional to the final scope. |
| seata-ctl diagnostic baseline | P1 | One usable diagnostic command family
exists for server/config self-checks plus active transaction and XID lock
inspection with table / JSON / YAML output. |
| TUI, samples, and community output | P2 | Interactive polish, sample
integration updates, contributor-facing docs, and community-facing writeups
land after the backend and CLI baseline is already stable. |
## Validation and Testing Plan
I want verification to shape the scope from the start, not only confirm it at
the end.
### Layer 1: fast unit and mock tests
These will cover:
- provider/factory routing
- config parsing and backend selection
- subscription and lookup dispatch
- cache/session-update boundary behavior
- structured CLI output formatting
- config/self-check command behavior
### Layer 2: backend integration tests
These will validate:
- Nacos lookup/subscription behavior
- ZooKeeper watcher and node-update behavior
- no-regression behavior for existing file and etcd paths
- active transaction / lock query command behavior where integration hooks exist
- NamingServer/path-compatibility cases where the backend contract depends on
them
### Layer 3: sample-oriented validation
I also want to provide sample configs and minimal runnable flows so the result
is understandable to users and future contributors, not only to maintainers
reading isolated tests. That includes sample-level validation for the new
registry paths and the CLI diagnostics that community users are expected to run.
### Regression rule
Any registry work that weakens the existing `file` or `etcd` path is a failed
tradeoff. Current behavior safety is part of the acceptance criteria.
## Upstream Merge Strategy
I want this project to land as a sequence of reviewable PRs, not one oversized
end-of-summer patch.
Planned order:
1. shared registry/factory foundation plus `file` / `etcd` safety work
2. NamingServer/path-compatibility fixes needed for the Go-side registry
baseline
3. Nacos support
4. ZooKeeper support plus session-behavior hardening
5. Consul and Redis through the same shared path
6. bounded seata-ctl diagnostic baseline
7. TUI polish, docs, samples, and community output only after the required
baseline is already stable
This is the same review philosophy that made the multi-database proposal
stronger: land the shared foundation first, then build the feature-specific
layers on top of it.
## Implementation Plan and Timeline
### Community bonding
- confirm acceptance matrix with mentors
- confirm how much NamingServer compatibility work is really expected
- confirm the exact CLI depth expected for `seata-ctl`, especially where
self-checks end and broader admin tooling begins
- prepare test environments for Nacos, ZooKeeper, Consul, and Redis as early as
practical
- confirm the expected NamingServer/path-compatibility fixes for the Go SDK
- publish a short design note describing the shared registry path and cut-order
### Weeks 1-2: shared foundation
- introduce registry/provider/factory structure
- preserve file and etcd
- fix init/config issues that block clean backend work
- define the session-reconciliation boundary
Expected artifact: PR 1 with no-regression coverage.
### Weeks 3-5: Nacos
- implement Nacos through the new shared path
- validate naming/group/cluster behavior
- add tests and sample config
Expected artifact: PR 2 with backend-specific tests and compatibility notes.
### Weeks 6-7: ZooKeeper plus hardening
- implement ZooKeeper through the same shared path
- validate watcher behavior and live-session update behavior
- fold in review-driven hardening from the first two PRs
Expected artifact: PR 3 and a midterm-ready baseline.
### Weeks 8-9: Consul and Redis
- implement Consul and Redis on top of the same shared factory/session boundary
- validate discovery semantics, heartbeat/refresh behavior where applicable,
and compatibility notes
- fold in any NamingServer/path-related fixes still needed for the complete
registry matrix
Expected artifact: PR 4 with the full multi-registry baseline in reviewable
shape.
### Weeks 10-11: bounded seata-ctl diagnostic baseline
- extend the current CLI/REPL diagnostic path
- add server/config self-check commands
- add active transaction and XID lock inspection
- support table / JSON / YAML output
Expected artifact: PR 5 with one demonstrable diagnostic command family.
### Week 12: TUI polish, docs, and samples
- add lightweight TUI polish only if the command baseline is already stable
- complete docs, contributor guidance, and sample configs
- complete community-facing writeups if time remains after the required
engineering baseline
Expected artifact: PR 6 with polish, docs, and community output.
### Cut order if time slips
1. deeper TUI work beyond lightweight interactive polish
2. broader seata-ctl extras beyond the bounded diagnostic slice
3. deeper hardening for Consul and Redis beyond the baseline needed for project
acceptance
If the shared registry/session foundation runs deeper than expected, I would
next shrink ZooKeeper to the smallest reviewable baseline rather than dilute
the common layer, Nacos quality, or the validation story.
### Minimum acceptable final state
The final state I consider acceptable, even under pressure, is:
- shared registry/factory work in seata-go
- safe file and etcd behavior after the refactor
- Nacos in a reviewable, test-backed state
- ZooKeeper at least at a clear, reviewable baseline
- Consul and Redis at least at a clear, reviewable baseline on the shared path
- one bounded seata-ctl diagnostic slice that mentors can run and evaluate
## Risk Analysis and Mitigation
| Risk | Impact | Mitigation |
| --- | --- | --- |
| Shared registry/session work is deeper than it first appears | High | Do the
foundation first, land it incrementally, and keep `file` / `etcd` as hard
regression gates. |
| Nacos and ZooKeeper expose different operational assumptions than expected |
Medium | Follow the Java reference implementations instead of forcing an
artificial one-shape-fits-all adapter design. |
| seata-ctl diagnostic work depends on server/API behavior that is not
guaranteed | High | Keep the guaranteed CLI milestone bounded and
read-oriented; treat any extra server dependency as a mentor-confirmation item.
|
| Consul and Redis baseline work takes longer than expected | Medium | Sequence
them behind the shared foundation and the first two adapters, and cut deeper
hardening before weakening the required baseline. |
| Review latency slows integration | Medium | Work in PR-sized checkpoints and
surface boundary questions early during bonding and implementation. |
## Collaboration Style
I want this project to be easy to mentor and easy to review.
My plan is to:
- share a short design note early
- work in small reviewable PRs
- keep tests and docs in the same patch series as the code
- report progress in terms of merged or reviewable checkpoints, not vague
status updates
- ask boundary questions early when Java compatibility or server-side
assumptions are involved
Registry behavior and debugging tools are both easy to over-promise. I would
rather stay explicit about tradeoffs and get early feedback than optimize for a
larger-looking scope.
## Why I Am a Good Fit
I study Environmental Engineering at Nanchang University, but my open-source
work has been concentrated in Go middleware and distributed-systems-adjacent
code. More importantly for this project, I already have recent contribution
history in Apache middleware repositories and I am comfortable doing
compatibility-sensitive work under review.
For this proposal, I did not stop at the idea title. I read:
- the current Go discovery/remoting path
- the current seata-ctl codebase
- the Java 2.x registry reference implementations
That preparation is the reason this proposal is narrower and more explicit than
a generic "support all registries and build a TUI" draft. I would rather
present a fundable, reviewable plan than a broader promise that becomes hard to
merge halfway through the summer.
## Availability and Communication
- Weekly availability: around 35-40 hours
- Time zone: Asia/Shanghai (UTC+8)
- Preferred channels: mailing list, issue/PR discussion, and community meetings
when useful
- Known conflicts: none at the moment
If my availability changes later, I will surface it early instead of letting it
become a hidden project risk.
## Questions for Mentors
1. For the official four-registry scope, which Consul and Redis behaviors are
considered the minimum acceptable compatibility baseline for GSoC?
2. For `seata-ctl`, is server/config self-check plus transaction/lock
inspection the right required diagnostic baseline, with TUI depth kept behind
that?
3. Which NamingServer and path-compatibility issues are already known and
should be included from day one?
4. If a useful CLI diagnostic flow needs a small server-side API addition, is
that acceptable, or should the project stay strictly on top of existing server
endpoints?
## After GSoC
If the project goes well, I want to continue with the remaining registry work,
more operational examples, and follow-up compatibility fixes. The outcome I
care about is not only more feature names in configuration files. I want
Seata-Go to be easier to extend, easier to deploy, and easier to debug in
environments that already depend on real registry infrastructure.
GitHub link:
https://github.com/apache/incubator-seata-go/discussions/1108#discussioncomment-16711089
----
This is an automatically sent email for [email protected].
To unsubscribe, please send an email to: [email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
