Documentation
¶
Overview ¶
Package operations tracks the asynchronous administrative operations of the HTTP server. A caller starts one operation, reads its status later, and may cancel it. Every status field comes from a closed set or from the caller's own bounded detail, so a status is safe to log and to serialize.
Index ¶
- Constants
- type Kind
- type Option
- type Registry
- func (r *Registry) Cancel(id string) (Status, bool)
- func (r *Registry) Close(ctx context.Context) error
- func (r *Registry) Done(id string) <-chan struct{}
- func (r *Registry) Metrics() []Sample
- func (r *Registry) Start(kind Kind, run Run) (Status, error)
- func (r *Registry) Status(id string) (Status, bool)
- type Run
- type Sample
- type State
- type Status
Constants ¶
const DefaultRetained = 64
DefaultRetained is the operation history that one registry keeps. A status read finds a recent operation, and the memory stays bounded.
const DefaultTimeout = 30 * time.Minute
DefaultTimeout bounds one operation run. The registry cancels a run that passes the bound, and the status then reports the timeout reason.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Kind ¶
type Kind string
Kind names one administrative operation class. The closed set bounds every metric label that carries a kind.
const KindCatalogUpdate Kind = "catalog_update"
KindCatalogUpdate is one catalog acquisition run.
type Option ¶
type Option func(*Registry)
Option configures a registry.
func WithClock ¶
WithClock injects the registry clock. A test then reads exact timestamps without a real wait.
func WithRetained ¶
WithRetained sets the operation history that the registry keeps.
func WithTimeout ¶
WithTimeout sets the bound on one operation run.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry starts, tracks, and cancels asynchronous operations. Every method is safe for concurrent use.
func NewRegistry ¶
NewRegistry returns a registry that runs operations in the background.
func (*Registry) Cancel ¶
Cancel asks one operation to stop. It returns the snapshot at the request, and the second result reports whether the registry holds the operation.
func (*Registry) Close ¶
Close cancels every live operation and waits for the background runs. It returns a timeout error when a run does not join before the context ends.
func (*Registry) Done ¶
Done returns a channel that closes when the operation reaches a terminal state. It returns nil for an operation that the registry does not hold.
func (*Registry) Metrics ¶
Metrics returns one monotonic total for each kind, state, and reason. Every label comes from a closed set, so the metric cardinality stays bounded.
type Run ¶
Run runs one operation. It returns a bounded detail summary that the registry serializes into the status.
type Sample ¶
type Sample struct {
// Kind names the operation class.
Kind Kind
// State names the lifecycle position that the total counts.
State State
// Reason holds the bounded failure cause of a failed row.
Reason sources.ProviderReason
// Total is the monotonic count of entries into the state.
Total int
}
Sample is one bounded metric row. The kind, the state, and the reason all come from closed sets, so the metric cardinality stays bounded.
type State ¶
type State string
State names where one operation sits in its lifecycle. The closed set bounds every metric label that carries a state.
const ( // StateAccepted means the server holds the operation and has not run it. StateAccepted State = "accepted" // StateRunning means the operation runs now. StateRunning State = "running" // StateSucceeded means the operation finished without an error. StateSucceeded State = "succeeded" // StateFailed means the operation stopped on an error. StateFailed State = "failed" // StateCanceled means a caller canceled the operation. StateCanceled State = "canceled" )
type Status ¶
type Status struct {
// ID is the opaque operation identity that a caller reads back.
ID string `json:"id"`
// Kind names the operation class.
Kind Kind `json:"kind"`
// State names the current lifecycle position.
State State `json:"state"`
// Reason holds the bounded failure cause. A successful operation and a
// canceled operation both leave it empty.
Reason sources.ProviderReason `json:"reason,omitempty"`
// AcceptedAt records when the server accepted the operation.
AcceptedAt time.Time `json:"accepted_at"`
// StartedAt records when the operation began to run.
StartedAt time.Time `json:"started_at,omitzero"`
// CompletedAt records when the operation reached a terminal state.
CompletedAt time.Time `json:"completed_at,omitzero"`
// Detail holds the bounded result summary that the operation produced.
Detail map[string]any `json:"detail,omitempty"`
}
Status is one operation snapshot. It carries a bounded reason code instead of provider message text, so a caller may log it and serialize it.
Source Files