registry

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 17, 2026 License: Apache-2.0 Imports: 9 Imported by: 0

Documentation

Overview

Package registry defines the provider-neutral Agent Instance Registry v1 directory contract. It reports ephemeral topology for an exact, already authorized ReleaseTarget. It does not own Agent Cards, Releases, bindings, permissions, or persistent Catalog facts.

Index

Constants

View Source 
const (
	LifecycleStateReady       LifecycleState = "ready"
	LifecycleStateUnavailable LifecycleState = "unavailable"
	LifecycleStateDraining    LifecycleState = "draining"

	// Aliases keep state names readable in provider code.
	InstanceStateReady       = LifecycleStateReady
	InstanceStateUnavailable = LifecycleStateUnavailable
	InstanceStateDraining    = LifecycleStateDraining
)
View Source 
const (
	SnapshotStateMissing   SnapshotState = "missing"
	SnapshotStateEmpty     SnapshotState = "empty"
	SnapshotStatePopulated SnapshotState = "populated"

	// Short aliases are retained for ergonomic state comparisons.
	SnapshotMissing   = SnapshotStateMissing
	SnapshotEmpty     = SnapshotStateEmpty
	SnapshotPopulated = SnapshotStatePopulated
)
View Source 
const (
	InstanceChangeInstancesChanged InstanceChangeKind = "instances_changed"
	// InstanceChangeStateChanged records a transition whose instance set is
	// unchanged but whose explicit snapshot state changed (for example, a
	// bound Service appearing after a missing snapshot).
	InstanceChangeStateChanged  InstanceChangeKind = "state_changed"
	InstanceChangeTargetDeleted InstanceChangeKind = "target_deleted"

	ChangeInstancesChanged = InstanceChangeInstancesChanged
	ChangeStateChanged     = InstanceChangeStateChanged
	ChangeTargetDeleted    = InstanceChangeTargetDeleted
)

Variables

View Source 
var (
	ErrMissing          = &OutcomeError{outcome: OutcomeMissing}
	ErrInvalid          = &OutcomeError{outcome: OutcomeInvalid}
	ErrUnauthorized     = &OutcomeError{outcome: OutcomeUnauthorized}
	ErrUnavailable      = &OutcomeError{outcome: OutcomeUnavailable}
	ErrStale            = &OutcomeError{outcome: OutcomeStale}
	ErrWatchInterrupted = &OutcomeError{outcome: OutcomeWatchInterrupted}
	ErrCanceled         = &OutcomeError{outcome: OutcomeCanceled}
	ErrClosed           = &OutcomeError{outcome: OutcomeClosed}
)

Functions

func IsCanceled 

func IsCanceled(err error) bool

func IsClosed 

func IsClosed(err error) bool

func IsInvalid 

func IsInvalid(err error) bool

func IsMissing 

func IsMissing(err error) bool

func IsOutcome 

func IsOutcome(err error, outcome Outcome) bool

IsOutcome reports whether err has the given typed v1 outcome.

func IsStale 

func IsStale(err error) bool

func IsUnauthorized 

func IsUnauthorized(err error) bool

func IsUnavailable 

func IsUnavailable(err error) bool

func IsWatchInterrupted 

func IsWatchInterrupted(err error) bool

func NewInstanceWatch 

func NewInstanceWatch(queueCapacity int) (InstanceWatch, InstanceWatchPublisher, error)

NewInstanceWatch creates a bounded pull watch and its provider-side publisher. queueCapacity must be explicit and positive; no queue default is inferred. A full queue latches watch_interrupted(delivery_overflow).

func NewWatch 

func NewWatch(queueCapacity int) (InstanceWatch, InstanceWatchPublisher, error)

NewWatch is a short alias for NewInstanceWatch.

Types

type AddressType 

type AddressType string

AddressType identifies the address family represented by a NetworkEndpoint. Providers may define additional valid values only in a later contract. 

const (
	AddressTypeIPv4 AddressType = "IPv4"
	AddressTypeIPv6 AddressType = "IPv6"
	// AddressTypeDNS is used by explicitly configured directories whose
	// deployment owner supplies a stable DNS instance address.
	AddressTypeDNS AddressType = "DNS"
)

type Capabilities 

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

Capabilities is an immutable set of directory capabilities.

func NewCapabilities 

func NewCapabilities(values ...Capability) (Capabilities, error)

NewCapabilities validates and copies an immutable capability set.

func (Capabilities) Equal 

func (c Capabilities) Equal(other Capabilities) bool

Equal reports whether both capability sets contain exactly the same values.

func (Capabilities) Supports 

func (c Capabilities) Supports(value Capability) bool

Supports reports whether this capability was explicitly advertised.

func (Capabilities) Values 

func (c Capabilities) Values() []Capability

Values returns a sorted copy of the advertised capability set.

type Capability 

type Capability string

Capability identifies an optional Instance Registry behavior. 

const (
	CapabilitySnapshot       Capability = "snapshot"
	CapabilityObserve        Capability = "observe"
	CapabilityRegistration   Capability = "registration"
	CapabilityDeregistration Capability = "deregistration"
	CapabilityLease          Capability = "lease"
	CapabilityHeartbeat      Capability = "heartbeat"
)

type Instance 

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

Instance is an immutable provider-reported runtime identity. It never selects an endpoint or makes a routing decision.

func NewInstance 

func NewInstance(input InstanceInput) (Instance, error)

NewInstance validates and copies one instance.

func (Instance) Endpoints 

func (i Instance) Endpoints() []NetworkEndpoint

Endpoints returns a sorted immutable-copy view of the network endpoint set.

func (Instance) Equal 

func (i Instance) Equal(other Instance) bool

Equal reports complete instance equality, including optional fields and safe metadata, but not pointer identity.

func (Instance) ID 

func (i Instance) ID() string

func (Instance) Lifecycle 

func (i Instance) Lifecycle() LifecycleState

func (Instance) Metadata 

func (i Instance) Metadata() map[string]string

Metadata returns a copy of the allowlisted safe metadata selected by the provider.

func (Instance) Ready 

func (i Instance) Ready() bool

func (Instance) SafeMetadata 

func (i Instance) SafeMetadata() map[string]string

SafeMetadata is an explicit synonym for Metadata.

func (Instance) Serving 

func (i Instance) Serving() bool

func (Instance) State 

func (i Instance) State() LifecycleState

func (Instance) Terminating 

func (i Instance) Terminating() bool

func (Instance) Validate 

func (i Instance) Validate() error

Validate verifies the complete, immutable instance shape.

func (Instance) Weight 

func (i Instance) Weight() (int, bool)

Weight returns the optional provider-reported weight. A present zero stays present; the directory never infers a weight.

func (Instance) Zone 

func (i Instance) Zone() (string, bool)

Zone returns the optional provider-reported zone without exposing an input pointer that could be mutated by a caller.

type InstanceChange 

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

InstanceChange is an immutable aggregate topology transition.

func NewInstanceChange 

func NewInstanceChange(input InstanceChangeInput) (InstanceChange, error)

NewInstanceChange validates and copies one complete topology transition.

func (InstanceChange) DeletedInstanceIDs 

func (c InstanceChange) DeletedInstanceIDs() []string

DeletedInstanceIDs returns a sorted copy of deleted instance IDs.

func (InstanceChange) Equal 

func (c InstanceChange) Equal(other InstanceChange) bool

Equal reports complete change equality.

func (InstanceChange) Kind 

func (c InstanceChange) Kind() InstanceChangeKind

func (InstanceChange) PreviousState 

func (c InstanceChange) PreviousState() SnapshotState

PreviousState returns the prior explicit snapshot state for a state-only transition. It is empty for instances_changed and target_deleted changes.

func (InstanceChange) Revision 

func (c InstanceChange) Revision() Revision

func (InstanceChange) Snapshot 

func (c InstanceChange) Snapshot() InstanceSnapshot

func (InstanceChange) Upserts 

func (c InstanceChange) Upserts() []Instance

Upserts returns a sorted copy of upserted instances.

func (InstanceChange) Validate 

func (c InstanceChange) Validate() error

Validate verifies all transition invariants.

type InstanceChangeInput 

type InstanceChangeInput struct {
	Kind               InstanceChangeKind
	Revision           Revision
	Upserts            []Instance
	DeletedInstanceIDs []string
	// PreviousState is required only for InstanceChangeStateChanged. It is
	// deliberately a state value rather than a second snapshot so callers
	// cannot smuggle an unrelated topology or revision into the transition.
	PreviousState SnapshotState
	Snapshot      InstanceSnapshot
}

InstanceChangeInput is the input form of one logical topology change.

type InstanceChangeKind 

type InstanceChangeKind string

InstanceChangeKind identifies a complete snapshot transition.

type InstanceDirectory 

type InstanceDirectory interface {
	Snapshot(context.Context, ReleaseTarget) (InstanceSnapshot, error)
	Observe(context.Context, ReleaseTarget) (InstanceObservation, error)
	Capabilities() Capabilities
	Close() error
}

InstanceDirectory reads and observes ephemeral topology for an exact, already-authorized ReleaseTarget. It does not resolve or authorize targets.

type InstanceInput 

type InstanceInput struct {
	ID          string
	Endpoints   []NetworkEndpoint
	Ready       bool
	Serving     bool
	Terminating bool
	State       LifecycleState
	Zone        *string
	Weight      *int
	Metadata    map[string]string
}

InstanceInput is the input form of one provider-reported instance. State is optional and, when supplied, must equal the derived state from the three explicit source condition booleans.

type InstanceLease 

type InstanceLease interface {
	Done() <-chan struct{}
	Err() error
	Close(context.Context) error
}

InstanceLease represents one continuously maintained ephemeral registration.

type InstanceObservation 

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

InstanceObservation atomically joins an immutable initial snapshot with an already-established pull watch.

func NewInstanceObservation 

func NewInstanceObservation(initial InstanceSnapshot, watch InstanceWatch) (InstanceObservation, error)

NewInstanceObservation constructs an observation from a valid initial snapshot and a non-nil established watch.

func (InstanceObservation) Initial 

func (o InstanceObservation) Initial() InstanceSnapshot

Initial returns the observation's immutable initial snapshot.

func (InstanceObservation) Watch 

func (o InstanceObservation) Watch() InstanceWatch

Watch returns the observation's pull watch.

type InstanceRegistrar 

type InstanceRegistrar interface {
	Register(context.Context, Registration) (InstanceLease, error)
	Capabilities() Capabilities
	Close() error
}

InstanceRegistrar publishes one exact runtime and owns its lease lifecycle.

type InstanceSnapshot 

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

InstanceSnapshot is an immutable complete topology view for one target.

func NewInstanceSnapshot 

func NewInstanceSnapshot(input InstanceSnapshotInput) (InstanceSnapshot, error)

NewInstanceSnapshot validates and copies one complete topology snapshot.

func NewSnapshot 

func NewSnapshot(input SnapshotInput) (InstanceSnapshot, error)

NewSnapshot is a short alias for NewInstanceSnapshot.

func (InstanceSnapshot) Equal 

func (s InstanceSnapshot) Equal(other InstanceSnapshot) bool

Equal reports complete snapshot equality.

func (InstanceSnapshot) Instances 

func (s InstanceSnapshot) Instances() []Instance

Instances returns a sorted copy of the immutable instance set.

func (InstanceSnapshot) Revision 

func (s InstanceSnapshot) Revision() Revision

func (InstanceSnapshot) State 

func (s InstanceSnapshot) State() SnapshotState

func (InstanceSnapshot) Target 

func (s InstanceSnapshot) Target() ReleaseTarget

func (InstanceSnapshot) Validate 

func (s InstanceSnapshot) Validate() error

Validate verifies the complete snapshot and its state/instance relation.

type InstanceSnapshotInput 

type InstanceSnapshotInput struct {
	Target    ReleaseTarget
	Revision  Revision
	State     SnapshotState
	Instances []Instance
}

InstanceSnapshotInput is the input form of one complete topology snapshot.

type InstanceWatch 

type InstanceWatch interface {
	Next(context.Context) (InstanceChange, error)
	Close() error
}

InstanceWatch is a pull-only, single-consumer topology change stream.

type InstanceWatchPublisher 

type InstanceWatchPublisher interface {
	Publish(InstanceChange) error
	Terminate(error)
}

InstanceWatchPublisher is the provider-side half of a locally created InstanceWatch. Consumers receive only InstanceWatch and can only pull.

type Lease 

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

func NewLease 

func NewLease(closeFunc func(context.Context) error) (*Lease, error)

NewLease creates the provider side of an InstanceLease.

func (*Lease) Close 

func (l *Lease) Close(ctx context.Context) error

func (*Lease) Done 

func (l *Lease) Done() <-chan struct{}

func (*Lease) Err 

func (l *Lease) Err() error

func (*Lease) Terminate 

func (l *Lease) Terminate(err error)

Terminate latches one provider-safe terminal outcome and wakes observers.

type LifecycleState 

type LifecycleState string

LifecycleState is the derived state of one provider-reported instance.

func DeriveLifecycleState 

func DeriveLifecycleState(ready, serving, terminating bool) LifecycleState

DeriveLifecycleState applies the v1 lifecycle truth table.

type NetworkEndpoint 

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

NetworkEndpoint is an immutable address, port, and transport tuple.

func NewNetworkEndpoint 

func NewNetworkEndpoint(input NetworkEndpointInput) (NetworkEndpoint, error)

NewNetworkEndpoint validates and copies one endpoint tuple.

func (NetworkEndpoint) Address 

func (e NetworkEndpoint) Address() string

func (NetworkEndpoint) AddressType 

func (e NetworkEndpoint) AddressType() AddressType

func (NetworkEndpoint) Equal 

func (e NetworkEndpoint) Equal(other NetworkEndpoint) bool

Equal reports tuple equality.

func (NetworkEndpoint) Port 

func (e NetworkEndpoint) Port() int

func (NetworkEndpoint) PortName 

func (e NetworkEndpoint) PortName() string

func (NetworkEndpoint) Protocol 

func (e NetworkEndpoint) Protocol() TransportProtocol

func (NetworkEndpoint) Validate 

func (e NetworkEndpoint) Validate() error

Validate verifies that this endpoint is complete. Address canonicalization is provider-specific; this provider-neutral layer preserves the supplied exact canonical address after requiring a non-empty safe value.

type NetworkEndpointInput 

type NetworkEndpointInput struct {
	AddressType AddressType
	Address     string
	PortName    string
	Port        int
	Protocol    TransportProtocol
}

NetworkEndpointInput is the input form of one network endpoint tuple.

type Outcome 

type Outcome string

Outcome identifies one terminal or operation outcome exposed by the Instance Registry v1 contract. 

const (
	OutcomeMissing          Outcome = "missing"
	OutcomeInvalid          Outcome = "invalid"
	OutcomeUnauthorized     Outcome = "unauthorized"
	OutcomeUnavailable      Outcome = "unavailable"
	OutcomeStale            Outcome = "stale"
	OutcomeWatchInterrupted Outcome = "watch_interrupted"
	OutcomeCanceled         Outcome = "canceled"
	OutcomeClosed           Outcome = "closed"
)

func OutcomeOf 

func OutcomeOf(err error) (Outcome, bool)

OutcomeOf reports the typed v1 outcome carried by err, including through ordinary wrapping.

type OutcomeCause 

type OutcomeCause string

OutcomeCause is an allowlisted, provider-safe classification that may accompany an outcome. It must never contain provider payloads, request data, credentials, or arbitrary transport text. 

const (
	CauseNone                    OutcomeCause = ""
	CauseInvalidInput            OutcomeCause = "invalid_input"
	CauseUnknownOutcome          OutcomeCause = "unknown_outcome"
	CauseUnknownCause            OutcomeCause = "unknown_cause"
	CauseTerminalOutcomeRequired OutcomeCause = "terminal_outcome_required"
	CauseResourceVersionExpired  OutcomeCause = "resource_version_expired"
	CauseDeliveryOverflow        OutcomeCause = "delivery_overflow"
	CauseWatchEventTooLarge      OutcomeCause = "watch_event_too_large"
	CauseWatchEventInvalid       OutcomeCause = "watch_event_invalid"
	CauseWatchStatusError        OutcomeCause = "watch_status_error"
	CauseStreamEOF               OutcomeCause = "stream_eof"
	CauseHTTPUnauthorized        OutcomeCause = "http_unauthorized"
	CauseHTTPForbidden           OutcomeCause = "http_forbidden"
	CauseProviderUnavailable     OutcomeCause = "provider_unavailable"
	CauseRateLimited             OutcomeCause = "rate_limited"
)

type OutcomeError 

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

OutcomeError is an immutable, typed Instance Registry outcome error. Cause is limited to provider-safe classification text; it must not include provider payloads, credentials, or request data.

func NewOutcomeError 

func NewOutcomeError(outcome Outcome, cause OutcomeCause) *OutcomeError

NewOutcomeError creates a typed outcome error with an allowlisted safe cause. Unknown outcome or cause values are represented as invalid input; the supplied text is intentionally not retained or reflected in the result.

func (*OutcomeError) Cause 

func (e *OutcomeError) Cause() OutcomeCause

Cause returns the provider-safe classification associated with this error.

func (*OutcomeError) Code 

func (e *OutcomeError) Code() Outcome

Code is an explicit synonym for Outcome.

func (*OutcomeError) Error 

func (e *OutcomeError) Error() string

func (*OutcomeError) Is 

func (e *OutcomeError) Is(target error) bool

Is makes outcome sentinels usable with errors.Is.

func (*OutcomeError) Outcome 

func (e *OutcomeError) Outcome() Outcome

Outcome returns this error's v1 outcome code.

func (*OutcomeError) Unwrap 

func (e *OutcomeError) Unwrap() error

Unwrap exposes only a local cancellation/deadline cause. Providers must use the safe Cause text rather than exposing arbitrary transport errors.

type Registration 

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

Registration is an immutable exact-Release runtime registration request.

func NewRegistration 

func NewRegistration(input RegistrationInput) (Registration, error)

func (Registration) Instance 

func (r Registration) Instance() Instance

func (Registration) Target 

func (r Registration) Target() ReleaseTarget

func (Registration) Validate 

func (r Registration) Validate() error

type RegistrationInput 

type RegistrationInput struct {
	Target   ReleaseTarget
	Instance Instance
}

RegistrationInput identifies one exact runtime instance to publish.

type ReleaseTarget 

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

ReleaseTarget is an exact, immutable Catalog-authorized release identity.

func NewReleaseTarget 

func NewReleaseTarget(input ReleaseTargetInput) (ReleaseTarget, error)

NewReleaseTarget validates and copies an exact ReleaseTarget v1 value.

func (ReleaseTarget) AgentCardVersion 

func (t ReleaseTarget) AgentCardVersion() string

func (ReleaseTarget) AgentID 

func (t ReleaseTarget) AgentID() string

func (ReleaseTarget) Audience 

func (t ReleaseTarget) Audience() string

func (ReleaseTarget) CanonicalEndpoint 

func (t ReleaseTarget) CanonicalEndpoint() string

func (ReleaseTarget) CardDigest 

func (t ReleaseTarget) CardDigest() string

func (ReleaseTarget) Equal 

func (t ReleaseTarget) Equal(other ReleaseTarget) bool

Equal reports byte-exact equality across all six target fields.

func (ReleaseTarget) ReleaseID 

func (t ReleaseTarget) ReleaseID() string

func (ReleaseTarget) Validate 

func (t ReleaseTarget) Validate() error

Validate verifies that this value is a complete exact ReleaseTarget v1. It is useful to directory implementations because a zero value can be constructed without NewReleaseTarget.

type ReleaseTargetInput 

type ReleaseTargetInput struct {
	AgentID           string
	AgentCardVersion  string
	ReleaseID         string
	CardDigest        string
	CanonicalEndpoint string
	Audience          string
}

ReleaseTargetInput contains the six byte-exact ReleaseTarget v1 fields. Construction validates but never trims, normalizes, or resolves them.

type Revision 

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

Revision is an immutable opaque provider revision scoped to one observation.

func NewRevision 

func NewRevision(input RevisionInput) (Revision, error)

NewRevision validates and copies an opaque revision.

func (Revision) Equal 

func (r Revision) Equal(other Revision) bool

Equal reports equal local order and byte-exact source token sequence.

func (Revision) LocalOrder 

func (r Revision) LocalOrder() uint64

LocalOrder returns the observation-local logical ordering number.

func (Revision) SourceTokens 

func (r Revision) SourceTokens() []string

SourceTokens returns a copy of the opaque source token sequence.

func (Revision) Validate 

func (r Revision) Validate() error

Validate verifies a complete opaque revision. The source token values are preserved and never parsed or ordered.

type RevisionInput 

type RevisionInput struct {
	SourceTokens []string
	LocalOrder   uint64
}

RevisionInput is an opaque provider revision plus observation-local order. Source tokens are never compared by this package.

type SnapshotInput 

type SnapshotInput = InstanceSnapshotInput

SnapshotInput is a compatibility-friendly short name for InstanceSnapshotInput.

type SnapshotState 

type SnapshotState string

SnapshotState identifies the complete topology state of a bound target.

type TransportProtocol 

type TransportProtocol string

TransportProtocol identifies the transport protocol of a NetworkEndpoint. 

const (
	TransportProtocolTCP TransportProtocol = "TCP"
)

Source Files

View all Source files

Directories

Path Synopsis
Package kubernetes provides the read/watch-only Kubernetes EndpointSlice Instance Directory provider.
 Package kubernetes provides the read/watch-only Kubernetes EndpointSlice Instance Directory provider.
Package nacos implements Nacos instance discovery.
 Package nacos implements Nacos instance discovery.
Package testkit provides deterministic backend-neutral Instance Registry fixtures.
 Package testkit provides deterministic backend-neutral Instance Registry fixtures.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.