registry

type Backend interface {
	// Name is the backend identifier, used as the registry type and as the
	// nested flag prefix (e.g. "etcd" -> --registry.etcd.endpoints).
	Name() string
	// AddFlags binds the backend's configuration to flags under prefix. The
	// backend owns a typed Options struct and binds directly to it.
	AddFlags(fs *pflag.FlagSet, prefix string)
	// Decode overlays configuration-file values onto the backend's Options.
	// Keys are flag names with the prefix removed, e.g. "addr" for
	// --registry.polaris.addr. It is what makes a backend configurable from a
	// YAML file at all: the options layer cannot reach a backend's typed
	// Options by itself, because that is exactly the dependency this registry
	// exists to avoid. Implementations are one call to DecodeOptions.
	Decode(raw map[string]any) error
	// NewRegistrar builds a server-side Registrar from the parsed options.
	// host/port/protocol identify the local instance endpoint; backends that
	// embed them in Options (consul/nacos/eureka/polaris) set them, while
	// others (etcd/kubernetes) ignore them because registration carries the
	// endpoints in the ServiceInstance.
	NewRegistrar(host string, port int, protocol string) (Registrar, error)
	// NewDiscovery builds a client-side Discovery from the parsed options.
	NewDiscovery() (Discovery, error)
}

type BackendFactory func() Backend

type Discovery interface {
	// GetService returns the current instances for a service name.
	GetService(ctx context.Context, serviceName string) ([]*ServiceInstance, error)
	// Watch returns a Watcher that streams changes for the service.
	Watch(ctx context.Context, serviceName string) (Watcher, error)
	// Close releases the discovery's underlying resources (SDK clients and their
	// connections). It should be called only after any watchers obtained from
	// this discovery are stopped.
	Close() error
}

type DiscoveryFactory func(opts any) (Discovery, error)

type Registrar interface {
	// Register registers the instance with the registry and starts any
	// keepalive/heartbeat needed to keep it alive.
	Register(ctx context.Context, instance *ServiceInstance) error
	// Deregister removes the instance and stops any keepalive.
	Deregister(ctx context.Context, instance *ServiceInstance) error
}

type RegistrarFactory func(opts any) (Registrar, error)

type ServiceInstance struct {
	// ID uniquely identifies the instance (e.g. hostname, or the backend's
	// assigned instance id). May be empty for backends that derive it.
	ID string
	// Name is the logical service name, e.g. "edu.course.student-api".
	Name string
	// Version is the service version.
	Version string
	// Metadata carries arbitrary key/value tags.
	Metadata map[string]string
	// Endpoints lists the reachable addresses with scheme prefixes, e.g.
	// ["grpc://127.0.0.1:39090", "http://127.0.0.1:8080"].
	Endpoints []string
}

type Watcher interface {
	// Next returns the next snapshot of instances, blocking until one arrives
	// or the watcher is stopped.
	Next() ([]*ServiceInstance, error)
	// Stop terminates the watcher and releases its resources.
	Stop() error
}