datasource

type ConnectionInfo struct {
	// Version is the server version string reported by the database — for
	// example "PostgreSQL 16.2 on x86_64-..." or an SQLite library version such
	// as "3.45.1". It is surfaced back to operators as confirmation of a
	// successful test.
	Version string
}

type Provider interface {
	// Name identifies the provider in error messages and logs. It does not need
	// to be globally unique but should be descriptive (for example "tenant-table"
	// or "vault-secrets").
	Name() string
	// Load returns the data sources this provider knows about. It runs once
	// during the FX startup phase and any error aborts boot.
	Load(ctx context.Context) ([]Spec, error)
}

type ReconcileOption func(*ReconcileOptions)

type ReconcileOptions struct {
	// DryRun makes Reconcile compute the diff and return it in the report without
	// performing Register/Update/Unregister. Useful for previewing what a
	// refresher job would do.
	DryRun bool
}

type ReconcileReport struct {
	Added   []string
	Updated []string
	Removed []string
	Errors  map[string]error
}

type RegisterOption func(*RegisterOptions)

type RegisterOptions struct {
	// CloseGrace controls how long the registry waits before closing a replaced
	// or unregistered connection. Zero (the default) closes immediately on a
	// background goroutine.
	CloseGrace time.Duration
}

type Registry interface {
	// Primary returns the orm.DB bound to the primary TOML configuration. It
	// is equivalent to Get(PrimaryName) but never returns an error.
	Primary() orm.DB

	// Get returns the orm.DB registered under name. It returns ErrNotFound when
	// no source is currently registered under name (including after it was
	// Unregister'd).
	Get(name string) (orm.DB, error)

	// Has reports whether name is currently registered and not closed.
	Has(name string) bool

	// Names returns every currently registered name (including primary) in
	// stable lexical order. Closed entries are excluded.
	Names() []string

	// Kind returns the dialect for the named data source. It returns ErrNotFound
	// for the same conditions as Get. Useful for sqlmigration / schema reflection
	// callers that need to branch on dialect without pulling out the full DB.
	Kind(name string) (config.DBKind, error)

	// Register opens a new data source and inserts it under name. It returns
	// ErrExists if the name is already registered, ErrPrimaryReserved if name
	// equals PrimaryName, ErrNameInvalid if name is empty or contains
	// whitespace/control characters, and ErrClosed once the registry has begun
	// shutting down. The newly opened connection is closed and not retained on
	// conflict. Register never closes an existing connection, so it takes no
	// RegisterOption.
	Register(ctx context.Context, name string, cfg config.DataSourceConfig) (orm.DB, error)

	// Update atomically replaces the connection for an existing data source with
	// one opened from cfg. The new connection must Open and Ping successfully
	// before the swap; on failure the existing entry is left untouched. The old
	// underlying *sql.DB is closed asynchronously so callers that already hold a
	// DB reference observe no downtime.
	//
	// Update returns ErrNotFound when name is not registered,
	// ErrPrimaryReserved when name is PrimaryName, and ErrClosed once the
	// registry has begun shutting down.
	Update(ctx context.Context, name string, cfg config.DataSourceConfig, opts ...RegisterOption) (orm.DB, error)

	// Unregister removes the named data source from the registry. Subsequent Get
	// calls return ErrNotFound. The underlying *sql.DB is closed asynchronously
	// (honoring WithCloseGrace), so callers already holding a DB reference can
	// finish in-flight queries before the connection pool tears down. Unregister
	// returns ErrPrimaryReserved for the primary source, ErrNotFound when name
	// is not registered, and ErrClosed once the registry has begun shutting down.
	Unregister(ctx context.Context, name string, opts ...RegisterOption) error

	// Reconcile drives the registry toward the supplied desired set of
	// non-primary sources. The implementation computes three buckets:
	//
	//   - specs has name but registry does not   → Register
	//   - both have name but cfg differs         → Update
	//   - registry has name but specs does not   → Unregister
	//
	// Reconciles are serialized (not concurrent) so two ticks of a refresher job
	// never race. Per-name failures populate ReconcileReport.Errors and do not
	// interrupt processing of the remaining names. specs entries referencing the
	// primary name are ignored.
	Reconcile(ctx context.Context, specs []Spec, opts ...ReconcileOption) (ReconcileReport, error)

	// TestConnection opens a throwaway connection from cfg, verifies it by
	// querying the server version, then closes it immediately. It never registers
	// anything and never mutates the registry — it is the connectivity probe
	// behind a UI "test connection" button, run before Register/Update. On success
	// it returns the reached server's ConnectionInfo; any error means the source
	// is unreachable or unusable.
	TestConnection(ctx context.Context, cfg config.DataSourceConfig) (ConnectionInfo, error)

	// HealthCheck pings every registered source in parallel and returns a
	// name -> error map. A nil error indicates the source is reachable.
	HealthCheck(ctx context.Context) map[string]error
}

type Spec struct {
	// Name is the registry key. Must be non-empty and not equal to PrimaryName.
	Name string
	// Config is the connection configuration applied when opening the source.
	Config config.DataSourceConfig
}