[DISCUSS] [GSoC 2026] Proposal on Seata-Go multi-registry support and seata-ctl diagnostics

[CAICAIIs]

Dear Seata community,

My name is Xuwei Yang (GitHub: CAICAIIs). I have submitted a GSoC 2026 proposal for Apache Seata on improving Seata-Go multi-registry support and enhancing seata-ctl diagnostic capability, and I would like to briefly introduce the idea here.

From my recent reading of the Seata-Go, Seata Java, and seata-ctl codebases, my understanding is that Seata-Go still has a clear gap with the Java side in registry support, while the current diagnostic tooling on the Go side is also still limited. In practice, this makes it harder to use Seata-Go in environments that already depend on registries such as Nacos or ZooKeeper, and it also increases the cost of troubleshooting distributed transaction issues.

My proposal is to approach this work incrementally. On the Seata-Go side, I plan to first improve the shared registry foundation, then prioritize Nacos and ZooKeeper support, followed by Consul and Redis. On the seata-ctl side, I plan to focus on a practical diagnostic baseline first, including environment checks, transaction inspection, and lock inspection, and then continue with further improvements if time allows.

I have recently been contributing in Seata-Go and related Go middleware projects, and I also did some local prototype and code reading work while preparing this proposal. Please find the attached proposal PDF for more details. I would greatly appreciate any feedback from the community on the scope and priorities of this topic.

CAICAIIsSeataGoMultiRegistryAndSeataCtl.pdf

Best regards,
Xuwei Yang
GitHub: CAICAIIs
Time zone: Asia/Shanghai (UTC+8)

[Code-Fight]

Please put a copy of the technical solution here in content form. Thanks.

[CAICAIIs]

Please put a copy of the technical solution here in content form. Thanks.

done, Thank you for your advice.

[CAICAIIs]

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.