seata

README

Seata Plugin for Lynx

lynx-seata is a thin Lynx integration for seata-go. Its runtime scope is intentionally small:

• decide whether the Seata client should start
• pass an external Seata config file path into client.InitPath(...)
• expose WithGlobalTx(...) so service code can mark transaction boundaries explicitly

It does not introduce a Lynx-owned YAML surface for registry, coordinator, auth, Saga, TCC, XA, or transport tuning. Those settings stay in the external Seata config file referenced by config_file_path.

Runtime facts

• Go module: github.com/go-lynx/lynx-seata
• Config prefix: lynx.seata
• Runtime plugin name: seata.server
• Public APIs: GetPlugin(), GetConfig(), GetConfigFilePath(), IsEnabled(), WithGlobalTx(...), GetMetrics()

Configuration

The shipped example in conf/example_config.yml is the authoritative runtime shape:

lynx:
  seata:
    enabled: true
    config_file_path: "./conf/seata.yml"

Field behavior:

• enabled: gates Seata startup and resource registration
• config_file_path: filesystem path passed to client.InitPath(...)

Usage

import (
	"context"
	"time"

	seata "github.com/go-lynx/lynx-seata"
)

func createOrder(ctx context.Context) error {
	plugin := seata.GetPlugin()
	if plugin == nil || !plugin.IsEnabled() {
		return nil
	}

	return plugin.WithGlobalTx(ctx, "CreateOrderTx", 30*time.Second, func(ctx context.Context) error {
		return doBusiness(ctx)
	})
}

Operational notes

• Keep all real Seata topology and client settings in the external file pointed to by config_file_path.
• WithGlobalTx(...) is the intended API for business-level transaction boundaries.
• client.InitPath(...) is now guarded as a process-wide one-time initialization. Repeated startup with the same config path is allowed; switching to a different config path in the same process returns an explicit error.
• CheckHealth() only validates that the plugin is enabled and the path is non-empty. It is not a full connectivity probe for the Seata control plane.

Documentation

Overview

Package seata provides a Seata distributed-transaction plugin for the go-lynx framework. It wraps seata-go and exposes global transaction management via TxSeataClient, supporting AT/TCC/SAGA/XA modes as configured in the Seata configuration file. The plugin integrates with the lynx runtime contract, Prometheus metrics, and context-aware lifecycle hooks.

Index

• type SeataMetrics
  • func GetMetrics() *SeataMetrics
  • func (m *SeataMetrics) RecordHealthCheck(status string)
  • func (m *SeataMetrics) RecordTransaction(status string)
  • func (m *SeataMetrics) RecordTransactionDuration(status string, duration float64)
  • func (m *SeataMetrics) SetActiveTransactions(count float64)
  • func (m *SeataMetrics) SetBranchTransactions(count float64)
• type TxSeataClient
  • func GetPlugin() *TxSeataClient
  • func NewTxSeataClient() *TxSeataClient
  • func (t *TxSeataClient) CheckHealth() error
  • func (t *TxSeataClient) CleanupTasks() error
  • func (t *TxSeataClient) Configure(cfg any) error
  • func (t *TxSeataClient) GetConfig() *conf.Seata
  • func (t *TxSeataClient) GetConfigFilePath() string
  • func (t *TxSeataClient) InitializeContext(ctx context.Context, plugin plugins.Plugin, rt plugins.Runtime) error
  • func (t *TxSeataClient) InitializeResources(rt plugins.Runtime) error
  • func (t *TxSeataClient) IsContextAware() bool
  • func (t *TxSeataClient) IsEnabled() bool
  • func (t *TxSeataClient) PluginProtocol() plugins.PluginProtocol
  • func (t *TxSeataClient) StartContext(ctx context.Context, _ plugins.Plugin) error
  • func (t *TxSeataClient) StartupTasks() error
  • func (t *TxSeataClient) StopContext(ctx context.Context, _ plugins.Plugin) error
  • func (t *TxSeataClient) WithGlobalTx(ctx context.Context, name string, timeout time.Duration, ...) error

Types

type SeataMetrics

type SeataMetrics struct {
	// contains filtered or unexported fields
}

SeataMetrics defines Seata-related monitoring metrics.

func GetMetrics

func GetMetrics() *SeataMetrics

GetMetrics returns the Seata metrics instance for external use.

func (*SeataMetrics) RecordHealthCheck

func (m *SeataMetrics) RecordHealthCheck(status string)

RecordHealthCheck records a health check.

func (*SeataMetrics) RecordTransaction

func (m *SeataMetrics) RecordTransaction(status string)

RecordTransaction records a transaction completion.

func (*SeataMetrics) RecordTransactionDuration

func (m *SeataMetrics) RecordTransactionDuration(status string, duration float64)

RecordTransactionDuration records transaction duration.

func (*SeataMetrics) SetActiveTransactions

func (m *SeataMetrics) SetActiveTransactions(count float64)

SetActiveTransactions sets the number of active transactions.

func (*SeataMetrics) SetBranchTransactions

func (m *SeataMetrics) SetBranchTransactions(count float64)

SetBranchTransactions sets the number of branch transactions.

type TxSeataClient

type TxSeataClient struct {
	*plugins.BasePlugin
	// contains filtered or unexported fields
}

TxSeataClient is the Lynx plugin that manages the Seata distributed transaction client.

func GetPlugin

func GetPlugin() *TxSeataClient

GetPlugin obtains the TxSeataClient plugin instance from the application's plugin manager.

func NewTxSeataClient

func NewTxSeataClient() *TxSeataClient

NewTxSeataClient creates a new Seata plugin instance.

func (*TxSeataClient) CheckHealth

func (t *TxSeataClient) CheckHealth() error

CheckHealth performs a health check of the Seata client. When disabled, returns nil. When enabled, verifies the plugin is in a valid state.

func (*TxSeataClient) CleanupTasks

func (t *TxSeataClient) CleanupTasks() error

CleanupTasks performs cleanup during plugin shutdown. Seata-go does not expose a public shutdown API; connections will be released when the process exits.

func (*TxSeataClient) Configure

func (t *TxSeataClient) Configure(cfg any) error

Configure updates the plugin configuration. Overrides base to apply *conf.Seata.

func (*TxSeataClient) GetConfig

func (t *TxSeataClient) GetConfig() *conf.Seata

GetConfig returns the Seata configuration.

func (*TxSeataClient) GetConfigFilePath

func (t *TxSeataClient) GetConfigFilePath() string

GetConfigFilePath returns the Seata configuration file path.

func (*TxSeataClient) InitializeContext

func (t *TxSeataClient) InitializeContext(ctx context.Context, plugin plugins.Plugin, rt plugins.Runtime) error

func (*TxSeataClient) InitializeResources

func (t *TxSeataClient) InitializeResources(rt plugins.Runtime) error

InitializeResources loads and initializes the Seata plugin configuration.

func (*TxSeataClient) IsContextAware

func (t *TxSeataClient) IsContextAware() bool

func (*TxSeataClient) IsEnabled

func (t *TxSeataClient) IsEnabled() bool

IsEnabled returns whether the Seata plugin is enabled.

func (*TxSeataClient) PluginProtocol

func (t *TxSeataClient) PluginProtocol() plugins.PluginProtocol

func (*TxSeataClient) StartContext

func (t *TxSeataClient) StartContext(ctx context.Context, _ plugins.Plugin) error

func (*TxSeataClient) StartupTasks

func (t *TxSeataClient) StartupTasks() error

StartupTasks initializes the Seata client when enabled.

func (*TxSeataClient) StopContext

func (t *TxSeataClient) StopContext(ctx context.Context, _ plugins.Plugin) error

func (*TxSeataClient) WithGlobalTx

func (t *TxSeataClient) WithGlobalTx(ctx context.Context, name string, timeout time.Duration, business func(context.Context) error) error

WithGlobalTx executes the given business function within a global transaction. It wraps seata-go's tm.WithGlobalTx with sensible defaults.