gyre

package module
v0.6.0 Latest Latest
Warning

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

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

README

Gyre

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

The latest tagged release is v0.6.0.

Packages

  • github.com/yaop-labs/gyre contains the stable contracts, runtime, config store, HTTP adapters, and wire-neutral health types.
  • github.com/yaop-labs/gyre/conformance contains the reusable product adapter contract suite.

Gyre has no third-party Go dependencies. Reef remains responsible for TLS, mTLS, bearer credentials, rotation, and network policy.

Runtime

Register every component before starting the runtime. Dependencies determine startup order; shutdown runs in reverse dependency order. Lifecycle operations are serialized, repeated Start and Close are idempotent, and registration after startup is rejected.

var runtime gyre.Runtime
_ = runtime.Add(database)
_ = runtime.AddWithDependencies(api, database.Name())

ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
defer stop()
if err := gyre.RunWithShutdownTimeout(ctx, &runtime, 20*time.Second); err != nil {
    return err
}

Products can mount gyre.RuntimeHTTPHandler(&runtime) for aggregate /healthz, /readyz, and /status endpoints, or gyre.HTTPHandler(component) for one component.

Configuration

ConfigStore.ApplyWith and RollbackWith serialize the generation check, product reload, and in-memory commit. A rejected reload never replaces the last-known-good envelope. The admin handler uses this transaction automatically when it is constructed with a runtime.

Admin config and watch responses recursively redact conventional secret fields. The admin handler does not authenticate requests; it must be mounted behind Reef or another trusted host boundary.

Conformance

Adopting products should run conformance.Check with a factory returning a fresh adapter. The suite verifies lifecycle identity and idempotence and can also exercise readiness failure/recovery, reload generations, rejected reloads, and bounded shutdown.

go test ./... -race -count=1
go vet ./...

Documentation

Index

Constants

View Source 
const DefaultShutdownTimeout = 30 * time.Second
View Source 
const Version = "0.6.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 RunWithShutdownTimeout added in v0.6.0 

func RunWithShutdownTimeout(ctx context.Context, runtime *Runtime, timeout time.Duration) error

RunWithShutdownTimeout is Run with an explicit shutdown bound. Shutdown gets a fresh context because ctx has already been canceled when cleanup begins.

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"`
	Error      string    `json:"error,omitempty"`
	Timestamp  time.Time `json:"timestamp"`
}

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 ConfigApplyFunc added in v0.6.0 

type ConfigApplyFunc func(context.Context, Envelope) 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) ApplyWith added in v0.6.0 

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

ApplyWith commits envelope only after apply succeeds. The generation check, product apply, and store commit are serialized as one transaction from the perspective of other ConfigStore operations.

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) RollbackWith added in v0.6.0 

func (s *ConfigStore) RollbackWith(ctx context.Context, generation uint64, apply ConfigApplyFunc) error

RollbackWith reapplies a historical config as a new monotonic generation and commits it only after apply succeeds.

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 RedactEnvelope added in v0.6.0 

func RedactEnvelope(envelope Envelope) Envelope

RedactEnvelope recursively removes conventionally secret values from a JSON config envelope. Invalid JSON is omitted rather than returned verbatim.

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

Directories

Path Synopsis
Package conformance provides the reusable Gyre adapter contract suite.
 Package conformance provides the reusable Gyre adapter contract suite.

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.