management

package
v0.1.0-preview.4 Latest Latest
Warning

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

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

Documentation

Overview

Package management provides deterministic, opt-in production management probes and HTTP endpoints without a global registry.

Index

Constants

View Source 
const MaxHTTPMetricRoutes = 4096

MaxHTTPMetricRoutes is the hard cardinality bound for one collector.

Variables

This section is empty.

Functions

This section is empty.

Types

type Access 

type Access string

Access controls the network-origin policy for management requests. 

const (
	// AccessPublic accepts management requests from any network origin.
	AccessPublic Access = "public"
	// AccessLoopback accepts only direct IPv4 or IPv6 loopback peers. Proxy
	// forwarding headers are intentionally ignored.
	AccessLoopback Access = "loopback"
)

type ApplicationModule 

type ApplicationModule struct {
	ID                   string           `json:"id"`
	RootPackage          string           `json:"root_package"`
	Packages             []string         `json:"packages"`
	DefaultAPI           string           `json:"default_api"`
	NamedInterfaces      []NamedInterface `json:"named_interfaces"`
	AllowedDependencies  []string         `json:"allowed_dependencies"`
	ObservedDependencies []string         `json:"observed_dependencies"`
}

ApplicationModule is one deterministic client-facing module canvas.

type Check 

type Check struct {
	Name   string
	Module string
	Groups []Group
	Probe  Probe
}

Check declares one named probe in one or more management groups. Module is optional ownership metadata and is safe to expose.

func LifecycleChecks 

func LifecycleChecks(
	name string,
	module string,
	state func() lifecycle.State,
) ([]Check, error)

LifecycleChecks adapts one generated application's observable state into health, liveness, and readiness checks.

type Component 

type Component struct {
	Name   string `json:"name"`
	Module string `json:"module,omitempty"`
	Status Status `json:"status"`
}

Component is one safe client-facing check result. Probe errors are intentionally excluded.

type ConfigurationProperty 

type ConfigurationProperty struct {
	Key      string      `json:"key"`
	Kind     config.Kind `json:"kind"`
	Module   string      `json:"module,omitempty"`
	Value    string      `json:"value,omitempty"`
	Source   string      `json:"source,omitempty"`
	Resolved bool        `json:"resolved"`
	Default  bool        `json:"default,omitempty"`
	Secret   bool        `json:"secret,omitempty"`
}

ConfigurationProperty is one safe resolved configuration entry. Secret values are always redacted.

type ConfigurationReport 

type ConfigurationReport struct {
	Properties []ConfigurationProperty `json:"properties"`
}

ConfigurationReport is a deterministic generated configuration view.

func NewConfigurationReport 

func NewConfigurationReport(
	schema config.Schema,
	snapshot config.Snapshot,
) (ConfigurationReport, error)

NewConfigurationReport combines one generated schema and its resolved snapshot without exposing raw secret values.

type Endpoint 

type Endpoint string

Endpoint identifies one explicitly exposed management HTTP endpoint. 

const (
	// EndpointHealth exposes the aggregate health report.
	EndpointHealth Endpoint = "health"
	// EndpointLiveness exposes the process liveness report.
	EndpointLiveness Endpoint = "liveness"
	// EndpointReadiness exposes the traffic readiness report.
	EndpointReadiness Endpoint = "readiness"
	// EndpointInfo exposes caller-owned static application metadata.
	EndpointInfo Endpoint = "info"
	// EndpointMetrics exposes generated-route HTTP metrics.
	EndpointMetrics Endpoint = "metrics"
	// EndpointConfigProps exposes redacted generated configuration metadata.
	EndpointConfigProps Endpoint = "configprops"
	// EndpointModules exposes the generated application-module canvas.
	EndpointModules Endpoint = "modules"
	// EndpointLoggers exposes instance-owned logging levels and loopback-only
	// runtime updates.
	EndpointLoggers Endpoint = "loggers"
)

type Group 

type Group string

Group identifies one independently queryable health concern. 

const (
	// GroupHealth contains broad application health checks.
	GroupHealth Group = "health"
	// GroupLiveness contains checks that decide whether a process is alive.
	GroupLiveness Group = "liveness"
	// GroupReadiness contains checks that decide whether traffic is safe.
	GroupReadiness Group = "readiness"
)

type HTTPMetrics 

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

HTTPMetrics is an instance-owned, concurrency-safe generated-route metrics collector. Its labels come only from compiler-generated route metadata.

func NewHTTPMetrics 

func NewHTTPMetrics() *HTTPMetrics

NewHTTPMetrics creates an empty generated-route metrics collector.

func (*HTTPMetrics) BeginHTTP 

func (metrics *HTTPMetrics) BeginHTTP(
	ctx context.Context,
	route web.RouteMetadata,
) (context.Context, func(web.HTTPResult))

BeginHTTP implements web.HTTPObserver.

func (*HTTPMetrics) Snapshot 

func (metrics *HTTPMetrics) Snapshot() HTTPMetricsSnapshot

Snapshot returns route and response status metrics in stable order.

type HTTPMetricsSnapshot 

type HTTPMetricsSnapshot struct {
	Routes              []HTTPRouteMetric `json:"routes"`
	DroppedObservations uint64            `json:"dropped_observations"`
}

HTTPMetricsSnapshot is a deterministic immutable metrics view.

type HTTPRouteMetric 

type HTTPRouteMetric struct {
	Route              web.RouteMetadata `json:"route"`
	Requests           uint64            `json:"requests"`
	InFlight           int64             `json:"in_flight"`
	Responses          []StatusCount     `json:"responses"`
	Bytes              uint64            `json:"bytes"`
	TotalDurationNanos int64             `json:"total_duration_nanos"`
	MaxDurationNanos   int64             `json:"max_duration_nanos"`
	Panics             uint64            `json:"panics"`
}

HTTPRouteMetric is one immutable route metrics snapshot.

type Handler 

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

Handler serves one isolated set of management endpoints.

func NewHandler 

func NewHandler(options HandlerOptions) (*Handler, error)

NewHandler constructs exactly the explicitly exposed management endpoints.

func (*Handler) Pattern 

func (handler *Handler) Pattern() string

Pattern returns the GET-only ServeMux subtree pattern used to mount this handler. Restricting the method prevents a management subtree from conflicting with an application's ordinary GET root route.

func (*Handler) Patterns 

func (handler *Handler) Patterns() []string

Patterns returns every method-specific pattern required by this handler. Pattern remains the compatibility GET subtree; the exact POST pattern is present only when runtime logger control is explicitly exposed.

func (*Handler) ServeHTTP 

func (handler *Handler) ServeHTTP(writer http.ResponseWriter, request *http.Request)

ServeHTTP dispatches management requests without exposing other routes.

type HandlerOptions 

type HandlerOptions struct {
	BasePath      string
	Manager       *Manager
	Info          map[string]string
	Metrics       *HTTPMetrics
	Configuration *ConfigurationReport
	Modules       *ModuleReport
	Logging       *spicelogging.Controller
	Expose        []Endpoint
	Access        Access
}

HandlerOptions configures one isolated management HTTP handler.

type Manager 

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

Manager is an immutable collection of validated health checks.

func New 

func New(checks ...Check) (*Manager, error)

New validates, copies, and deterministically orders health checks.

func (*Manager) Report 

func (manager *Manager) Report(ctx context.Context, group Group) (Report, error)

Report runs one group in deterministic check order. Probe failures are represented as DOWN and are never exposed as response details.

type ModuleDefinition 

type ModuleDefinition struct {
	ID                  string
	RootPackage         string
	Packages            []string
	NamedInterfaces     []NamedInterface
	AllowedDependencies []string
}

ModuleDefinition is generated input for one validated application module.

type ModuleEdge 

type ModuleEdge struct {
	FromModule  string `json:"from_module"`
	ToModule    string `json:"to_module"`
	API         string `json:"api"`
	FromPackage string `json:"from_package"`
	ToPackage   string `json:"to_package"`
}

ModuleEdge is one observed cross-module Go import.

type ModuleReport 

type ModuleReport struct {
	Schema             string              `json:"schema"`
	Modules            []ApplicationModule `json:"modules"`
	Edges              []ModuleEdge        `json:"edges"`
	UnassignedPackages []string            `json:"unassigned_packages"`
}

ModuleReport is the portable runtime application-module canvas.

func NewModuleReport 

func NewModuleReport(
	definitions []ModuleDefinition,
	edges []ModuleEdge,
	unassignedPackages []string,
) (ModuleReport, error)

NewModuleReport validates and copies generated module metadata. The returned report uses the same schema and ordering as the Spice module JSON canvas.

type NamedInterface 

type NamedInterface struct {
	Name        string `json:"name"`
	PackagePath string `json:"package"`
}

NamedInterface identifies one explicitly exported descendant package.

type Probe 

type Probe func(context.Context) error

Probe is one caller-owned, context-aware health check.

type Report 

type Report struct {
	Group      Group       `json:"group"`
	Status     Status      `json:"status"`
	Components []Component `json:"components"`
}

Report is a deterministic group result.

type Status 

type Status string

Status is the stable client-facing result of a probe or report. 

const (
	// StatusUp means every selected check passed.
	StatusUp Status = "UP"
	// StatusDown means at least one selected check failed.
	StatusDown Status = "DOWN"
)

type StatusCount 

type StatusCount struct {
	Status int    `json:"status"`
	Count  uint64 `json:"count"`
}

StatusCount is one deterministic HTTP response-status count.

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.