89 lines
3.4 KiB
Go
89 lines
3.4 KiB
Go
package servicediscovery
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
)
|
|
|
|
// ErrNotInstalled reports that a service has never been installed. It is
|
|
// distinct from a service that is installed but currently has no healthy
|
|
// endpoint: that case is an empty, non-error result, not ErrNotInstalled.
|
|
// Implementations of [ServiceRegistry.Resolve] and [ServiceRegistry.Watch]
|
|
// return it (wrapped, matched with errors.Is) when a service's "installed"
|
|
// marker is absent. Callers match it and treat the capability as disabled.
|
|
var ErrNotInstalled = errors.New("servicediscovery: service not installed")
|
|
|
|
// Endpoint is one resolved instance of a service.
|
|
type Endpoint struct {
|
|
// Service is the logical name the endpoint was registered under. It is
|
|
// redundant within the scope of a single Resolve/Watch call, but it makes
|
|
// the value self-describing and directly usable by a consumer that reads
|
|
// raw registry records (e.g. a custom gRPC resolver) rather than going
|
|
// through ServiceRegistry.
|
|
Service string `json:"service,omitempty"`
|
|
|
|
// ID distinguishes multiple instances of the same service. It is the
|
|
// per-instance identifier; two endpoints with the same Service and ID are
|
|
// the same instance. An ID must not contain the registry's key separator
|
|
// (see the NATS implementation's key scheme).
|
|
ID string `json:"id"`
|
|
|
|
// Address is the dialable host:port for the instance.
|
|
Address string `json:"address"`
|
|
}
|
|
|
|
// EventKind is the kind of membership change an [Event] describes.
|
|
type EventKind int
|
|
|
|
const (
|
|
// Join reports that an endpoint became live.
|
|
Join EventKind = iota
|
|
|
|
// Leave reports that an endpoint left: it was unregistered, its heartbeat
|
|
// expired, or its process stopped.
|
|
Leave
|
|
)
|
|
|
|
// String returns a human-readable kind, for logging and tests.
|
|
func (k EventKind) String() string {
|
|
switch k {
|
|
case Join:
|
|
return "join"
|
|
case Leave:
|
|
return "leave"
|
|
default:
|
|
return "unknown"
|
|
}
|
|
}
|
|
|
|
// Event is a single membership change for one endpoint.
|
|
type Event struct {
|
|
// Endpoint is the instance that joined or left. On a [Leave] the Address
|
|
// may be empty: the registry observing an entry disappear can recover the
|
|
// instance's ID from the key but not the address it carried. The ID
|
|
// uniquely identifies the instance.
|
|
Endpoint Endpoint
|
|
|
|
// Kind is [Join] or [Leave].
|
|
Kind EventKind
|
|
}
|
|
|
|
// ServiceRegistry resolves and watches the live endpoints of a named service.
|
|
// It models network endpoints only. In-process services do not register here;
|
|
// application composition selects local adapters independently of discovery.
|
|
type ServiceRegistry interface {
|
|
// Resolve returns the current healthy endpoints for service. It returns
|
|
// [ErrNotInstalled] if service has never been installed. If service is
|
|
// installed but currently has no healthy endpoint, it returns a
|
|
// possibly-empty slice with a nil error -- callers distinguish that from
|
|
// NotInstalled to avoid treating an optional, disabled service as broken.
|
|
Resolve(ctx context.Context, service string) ([]Endpoint, error)
|
|
|
|
// Watch returns a channel that emits [Join] and [Leave] events as service's
|
|
// membership changes, until ctx is cancelled. It returns [ErrNotInstalled]
|
|
// if service has never been installed at the time of the call. A service
|
|
// that is installed but currently has no healthy endpoint returns a live
|
|
// channel that simply does not emit until an endpoint joins.
|
|
Watch(ctx context.Context, service string) (<-chan Event, error)
|
|
}
|