dtmx

type Config struct {
	// Enabled controls whether distributed transactions are active. When false,
	// New returns a disabled no-op Manager that fails fast on SubmitSaga.
	Enabled bool `json:"enabled" yaml:"enabled"`

	// Driver selects the registered implementation. The production driver is
	// "dtm" from package github.com/aisphereio/kernel/dtmx/dtm.
	Driver string `json:"driver" yaml:"driver"`

	// Protocol selects how DTM calls branch endpoints. Currently "http" is
	// implemented; gRPC can be added without changing business code.
	Protocol string `json:"protocol" yaml:"protocol"`

	// Server is the DTM HTTP API endpoint, e.g.
	// http://127.0.0.1:36789/api/dtmsvr.
	Server string `json:"server" yaml:"server"`

	// ServiceBaseURL is the externally reachable base URL for this service.
	// Helpers use it to build branch callback URLs.
	ServiceBaseURL string `json:"service_base_url" yaml:"service_base_url"`

	// BranchPrefix is the prefix for internal branch endpoints, e.g.
	// /internal/dtm. It is optional and used only by BranchURL helper.
	BranchPrefix string `json:"branch_prefix" yaml:"branch_prefix"`

	// WaitResult asks DTM to wait for Saga execution result on Submit. Use true
	// in synchronous user-facing flows; false in fire-and-retry background flows.
	WaitResult bool `json:"wait_result" yaml:"wait_result"`

	// Timeout bounds the local SubmitSaga call. DTM itself still owns branch
	// retry/timeout behavior.
	Timeout time.Duration `json:"timeout_ns" yaml:"timeout_ns"`

	// BranchSecret is propagated to DTM as a branch header. DTM then forwards it
	// to branch action/compensate endpoints, where ValidateBranchRequest or
	// BranchAuthMiddleware can verify the callback. Keep it empty only when the
	// branch endpoints are protected by stronger network controls such as mTLS
	// and private networking.
	BranchSecret string `json:"branch_secret" yaml:"branch_secret"`

	// Logger is the component logger. If nil, dtmx uses logx.DefaultLogger().
	Logger logx.Logger `json:"-" yaml:"-"`

	// Metrics is the optional metrics manager.
	Metrics metricsx.Manager `json:"-" yaml:"-"`

	// MetricsEnabled controls whether dtmx records metrics.
	MetricsEnabled bool `json:"metrics_enabled" yaml:"metrics_enabled"`
}

type DriverOpener func(Config) (Manager, error)

type Manager interface {
	Enabled() bool
	DriverName() string
	NewGID(ctx context.Context) (string, error)
	SubmitSaga(ctx context.Context, saga Saga) (TransactionResult, error)
	BranchURL(path string) string
	Close() error
}

type Saga struct {
	GID   string
	Name  string
	Steps []SagaStep

	// Options override Config defaults for a single Saga.
	Options SagaOptions
}

type SagaOption func(*Saga)

type SagaOptions struct {
	WaitResult    *bool
	Timeout       time.Duration
	BranchHeaders map[string]string
}

type SagaStep struct {
	Name       string
	Action     string
	Compensate string
	Payload    any
}

type TransactionResult struct {
	GID       string
	Protocol  string
	Pattern   string
	Submitted bool
	StartedAt time.Time
	Elapsed   time.Duration
}