gyre

package module
v0.5.0 Latest Latest
Warning

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

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

README

Gyre

Gyre is the shared operational contract for YAOP components. It standardizes lifecycle, readiness, status, reload generations, typed errors, and resource identity while leaving product business logic in each product.

v0.1

The first release is intentionally a small Go module:

  • core Component, Reloadable, Snapshot, Condition, and Envelope types;
  • typed operational errors with retryability;
  • deterministic resource merging with explicit identity conflict rejection;
  • HTTP adapter exposing /healthz, /readyz, and /status;
  • named readiness checks and contract tests.

The HTTP adapter is composable: products mount gyre.HTTPHandler(component) in their own mux and may add product-specific endpoints. /healthz is deliberately cheap and does not execute dependency checks; /readyz executes bounded readiness checks supplied by the component.

See docs/ for the research, decisions, API draft, and migration matrix.

Documentation

Index

Constants

View Source 
const Version = "0.5.0"

Variables

This section is empty.

Functions

func AdminHandler 

func AdminHandler(store *ConfigStore, runtime *Runtime) http.Handler

AdminHandler exposes local, authenticated-by-the-host admin operations. It does not implement network authentication; products must mount it behind Reef or an equivalent trusted boundary.

func ConformanceCheck 

func ConformanceCheck(ctx context.Context, component Component) error

ConformanceCheck performs cheap, deterministic checks an adapter can run in its own test suite. It does not start network listeners or inspect product internals.

func HTTPHandler 

func HTTPHandler(component Component) http.Handler

HTTPHandler exposes the stable operational endpoints for a component. Products can mount it into an existing mux.

func RedactConfig 

func RedactConfig(values map[string]string) map[string]string

RedactConfig removes values for fields conventionally carrying secrets. It is intended for status/admin output, never for applying configuration.

func Run 

func Run(ctx context.Context, runtime *Runtime) error

Run starts runtime and blocks until ctx is canceled, then performs a context-bounded close. Signal delivery belongs to the executable and should be converted to context cancellation with os/signal.NotifyContext.

func RuntimeHTTPHandler 

func RuntimeHTTPHandler(runtime *Runtime) http.Handler

RuntimeHTTPHandler exposes aggregate operational endpoints.

Types

type AuditEvent 

type AuditEvent struct {
	Action     string `json:"action"`
	Generation uint64 `json:"generation"`
	Success    bool   `json:"success"`
}

type Check 

type Check struct {
	Name  string
	Scope CheckScope
	Check func(context.Context) error
}

type CheckScope 

type CheckScope string
const (
	ScopeLiveness  CheckScope = "liveness"
	ScopeReadiness CheckScope = "readiness"
)

type Checker 

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

func (*Checker) Add 

func (c *Checker) Add(check Check) error

func (*Checker) Ready 

func (c *Checker) Ready(ctx context.Context) error

type Code 

type Code string
const (
	CodeConfigInvalid Code = "config_invalid"
	CodeUnavailable   Code = "unavailable"
	CodeOverloaded    Code = "overloaded"
	CodeUnauthorized  Code = "unauthorized"
	CodeDependency    Code = "dependency"
	CodeCorruption    Code = "corruption"
	CodeShuttingDown  Code = "shutting_down"
	CodeInternal      Code = "internal"
)

type Component 

type Component interface {
	Name() string
	Version() string
	Start(context.Context) error
	Ready(context.Context) error
	Status() Snapshot
	Close(context.Context) error
}

type Condition 

type Condition struct {
	Type           string    `json:"type"`
	Status         bool      `json:"status"`
	Reason         string    `json:"reason,omitempty"`
	Message        string    `json:"message,omitempty"`
	LastTransition time.Time `json:"last_transition"`
}

type ConfigApplier 

type ConfigApplier interface {
	Apply(context.Context, Envelope) (ReloadResult, error)
}

type ConfigStore 

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

func (*ConfigStore) Apply 

func (s *ConfigStore) Apply(ctx context.Context, envelope Envelope, expected uint64) error

func (*ConfigStore) Audit 

func (s *ConfigStore) Audit() []AuditEvent

func (*ConfigStore) Current 

func (s *ConfigStore) Current() (Envelope, bool)

func (*ConfigStore) Rollback 

func (s *ConfigStore) Rollback(ctx context.Context, generation uint64) error

func (*ConfigStore) Validate 

func (s *ConfigStore) Validate(envelope Envelope, expected uint64) error

func (*ConfigStore) Watch 

func (s *ConfigStore) Watch(ctx context.Context) <-chan Envelope

type ConfigValidator 

type ConfigValidator interface {
	Validate(context.Context, Envelope) error
}

type CredentialEvent 

type CredentialEvent struct {
	Status  CredentialStatus `json:"status"`
	Success bool             `json:"success"`
	Changed bool             `json:"changed"`
}

type CredentialObserver 

type CredentialObserver interface{ ObserveCredential(CredentialEvent) }

type CredentialObserverFunc 

type CredentialObserverFunc func(CredentialEvent)

func (CredentialObserverFunc) ObserveCredential 

func (f CredentialObserverFunc) ObserveCredential(e CredentialEvent)

type CredentialSource 

type CredentialSource interface {
	CredentialStatus() []CredentialStatus
	Close() error
}

CredentialSource is the narrow bridge for Reef or another provider. Gyre observes lifecycle only; loading, rotation, and policy stay provider-owned.

type CredentialStatus 

type CredentialStatus struct {
	Name        string    `json:"name"`
	Kind        string    `json:"kind"`
	Generation  uint64    `json:"generation"`
	LastSuccess time.Time `json:"last_success,omitempty"`
	LastFailure time.Time `json:"last_failure,omitempty"`
	LastError   string    `json:"last_error,omitempty"`
	NotBefore   time.Time `json:"not_before,omitempty"`
	NotAfter    time.Time `json:"not_after,omitempty"`
}

CredentialStatus is deliberately secret-free and can be backed by Reef's credential.Status without importing Reef into Gyre core.

type CredentialStatusProvider 

type CredentialStatusProvider interface {
	CredentialSource
	SetObserver(CredentialObserver)
}

type Envelope 

type Envelope struct {
	APIVersion string          `json:"api_version" yaml:"api_version"`
	Kind       string          `json:"kind" yaml:"kind"`
	Generation uint64          `json:"generation" yaml:"generation"`
	Spec       json.RawMessage `json:"spec" yaml:"spec"`
}

func (Envelope) Validate 

func (e Envelope) Validate() error

type Error 

type Error struct {
	Code      Code
	Component string
	Operation string
	Retryable bool
	Cause     error
}

func E 

func E(code Code, component, operation string, retryable bool, cause error) *Error

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Unwrap 

func (e *Error) Unwrap() error

type FuncComponent 

type FuncComponent struct {
	ComponentName    string
	ComponentVersion string
	StartFunc        func(context.Context) error
	ReadyFunc        func(context.Context) error
	CloseFunc        func(context.Context) error
	StatusFunc       func() Snapshot
}

FuncComponent adapts an existing product lifecycle to Gyre. It is useful during migration and keeps compatibility code at the boundary.

func (*FuncComponent) Close 

func (f *FuncComponent) Close(ctx context.Context) error

func (*FuncComponent) Name 

func (f *FuncComponent) Name() string

func (*FuncComponent) Ready 

func (f *FuncComponent) Ready(ctx context.Context) error

func (*FuncComponent) Start 

func (f *FuncComponent) Start(ctx context.Context) error

func (*FuncComponent) Status 

func (f *FuncComponent) Status() Snapshot

func (*FuncComponent) Version 

func (f *FuncComponent) Version() string

type GRPCHealthAdapter 

type GRPCHealthAdapter struct{ Runtime *Runtime }

GRPCHealthAdapter provides the semantics required by grpc health services without forcing gyre to depend on a particular gRPC implementation. A transport bridge can translate HealthStatus to its native enum.

func (GRPCHealthAdapter) Check 

func (a GRPCHealthAdapter) Check(ctx context.Context, service string) HealthStatus

type HealthStatus 

type HealthStatus int

HealthStatus is intentionally wire-neutral and maps directly to the grpc.health.v1 ServingStatus values in adapters. 

const (
	HealthUnknown HealthStatus = iota
	HealthServing
	HealthNotServing
)

type MetricsSink 

type MetricsSink interface {
	Observe(name, operation string, duration time.Duration, err error)
}

MetricsSink is a minimal integration point for products' metrics systems. Implementations should keep recording non-blocking and allocation-light.

type Registry 

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

Registry coordinates a set of components with deterministic startup and reverse-order shutdown. It intentionally does not infer dependencies.

func (*Registry) Add 

func (r *Registry) Add(component Component) error

func (*Registry) Close 

func (r *Registry) Close(ctx context.Context) error

func (*Registry) Ready 

func (r *Registry) Ready(ctx context.Context) error

func (*Registry) Start 

func (r *Registry) Start(ctx context.Context) error

func (*Registry) Status 

func (r *Registry) Status() []Snapshot

type ReloadResult 

type ReloadResult struct {
	Generation      uint64
	Changed         []string
	RestartRequired []string
}

func ReloadTransaction 

func ReloadTransaction(ctx context.Context, envelope Envelope, validator ConfigValidator, applier ConfigApplier) (ReloadResult, error)

ReloadTransaction validates and applies a generation atomically from the caller's perspective: Apply is invoked only after validation succeeds.

type Reloadable 

type Reloadable interface {
	Reload(context.Context, Envelope) (ReloadResult, error)
}

type Resource 

type Resource map[string]string

func MergeResource 

func MergeResource(layers ...Resource) (Resource, error)

Merge applies layers from weakest to strongest. Explicit conflicting service.name values are rejected instead of silently changing identity.

func (Resource) Clone 

func (r Resource) Clone() Resource

type Runtime 

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

Runtime owns the lifecycle of registered components and coordinates reloads. Product code still owns dependency meaning and configuration decoding.

func (*Runtime) Add 

func (r *Runtime) Add(component Component) error

func (*Runtime) AddWithDependencies 

func (r *Runtime) AddWithDependencies(component Component, dependencies ...string) error

func (*Runtime) Close 

func (r *Runtime) Close(ctx context.Context) error

func (*Runtime) Ready 

func (r *Runtime) Ready(ctx context.Context) error

func (*Runtime) Reload 

func (r *Runtime) Reload(ctx context.Context, name string, envelope Envelope) (ReloadResult, error)

func (*Runtime) Start 

func (r *Runtime) Start(ctx context.Context) error

func (*Runtime) Status 

func (r *Runtime) Status() []Snapshot

type RuntimeMetrics 

type RuntimeMetrics struct{ Sink MetricsSink }

RuntimeMetrics wraps a sink and can be used by lifecycle adapters.

func (RuntimeMetrics) Observe 

func (m RuntimeMetrics) Observe(name, operation string, started time.Time, err error)

type Snapshot 

type Snapshot struct {
	Name       string      `json:"name"`
	Version    string      `json:"version"`
	State      State       `json:"state"`
	Generation uint64      `json:"generation"`
	Since      time.Time   `json:"since"`
	Conditions []Condition `json:"conditions,omitempty"`
}

type State 

type State string
const (
	StateStarting State = "starting"
	StateReady    State = "ready"
	StateDegraded State = "degraded"
	StateStopping State = "stopping"
	StateStopped  State = "stopped"
	StateFailed   State = "failed"
)

Source Files

View all Source files

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.