Documentation
¶
Overview ¶
Package operations provides HTTP contracts for asynchronous API operations.
It standardizes 202 Accepted responses, pollable operation resources, repository contracts, and lifecycle transition helpers while leaving queues, workers, persistence, and retry policy to application code or contrib adapters.
Index ¶
- Variables
- func CanTransition(from, to State) bool
- func IsTerminal(state State) bool
- func PollHandler[T any](config PollConfig[T]) http.Handler
- func ValidateState(state State) error
- func WriteAccepted(w http.ResponseWriter, config AcceptedConfig)
- func WriteOperation[T any](w http.ResponseWriter, status int, operation Operation[T])
- type Accepted
- type AcceptedConfig
- type Operation
- type PollConfig
- type Repository
- type State
- type Store
- type StoreFunc
- type TransitionConfig
- type Writer
- type WriterFuncs
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidState reports an unknown operation state. ErrInvalidState = errors.New("invalid operation state") // ErrInvalidTransition reports a disallowed operation lifecycle transition. ErrInvalidTransition = errors.New("invalid operation transition") )
Functions ¶
func CanTransition ¶
CanTransition reports whether an operation may move from one state to another.
func IsTerminal ¶
IsTerminal reports whether state is a completed operation state.
func PollHandler ¶
func PollHandler[T any](config PollConfig[T]) http.Handler
PollHandler returns an HTTP handler for polling operation state.
func ValidateState ¶
ValidateState reports whether state is a known operation lifecycle state.
func WriteAccepted ¶
func WriteAccepted(w http.ResponseWriter, config AcceptedConfig)
WriteAccepted writes a 202 Accepted response with Location and Retry-After headers when configured.
func WriteOperation ¶
func WriteOperation[T any](w http.ResponseWriter, status int, operation Operation[T])
WriteOperation writes an operation resource as JSON.
Types ¶
type Accepted ¶
type Accepted struct {
ID string `json:"id,omitempty"`
State State `json:"state"`
Location string `json:"location,omitempty"`
}
Accepted is the JSON body for a 202 Accepted operation response.
type AcceptedConfig ¶
AcceptedConfig configures WriteAccepted.
type Operation ¶
type Operation[T any] struct { ID string `json:"id"` State State `json:"state"` Result *T `json:"result,omitempty"` Problem *httpx.Problem `json:"problem,omitempty"` }
Operation is a pollable asynchronous operation resource.
func TransitionOperation ¶
func TransitionOperation[T any](operation Operation[T], config TransitionConfig[T]) (Operation[T], error)
TransitionOperation applies a validated lifecycle transition.
type PollConfig ¶
type PollConfig[T any] struct { Store Store[T] OperationID func(*http.Request) string ErrorWriter func(http.ResponseWriter, int, httpx.Problem) }
PollConfig configures PollHandler.
type Repository ¶
Repository loads and writes operation resources.
type State ¶
type State string
State describes the lifecycle state of an asynchronous operation.
const ( // StatePending means work has been accepted but not started. StatePending State = "pending" // StateRunning means work is in progress. StateRunning State = "running" // StateSucceeded means work completed successfully. StateSucceeded State = "succeeded" // StateFailed means work completed with a failure problem. StateFailed State = "failed" // StateCanceled means work was canceled before successful completion. StateCanceled State = "canceled" )
type Store ¶
type Store[T any] interface { GetOperation(ctx context.Context, id string) (Operation[T], bool, error) }
Store loads operation resources for polling handlers.
type TransitionConfig ¶
TransitionConfig configures a lifecycle state transition.
type Writer ¶
type Writer[T any] interface { CreateOperation(ctx context.Context, operation Operation[T]) error UpdateOperation(ctx context.Context, operation Operation[T]) error }
Writer creates and updates operation resources.
type WriterFuncs ¶
type WriterFuncs[T any] struct { Create func(context.Context, Operation[T]) error Update func(context.Context, Operation[T]) error }
WriterFuncs adapts functions to Writer.
func (WriterFuncs[T]) CreateOperation ¶
func (f WriterFuncs[T]) CreateOperation(ctx context.Context, operation Operation[T]) error
CreateOperation creates an operation resource.
func (WriterFuncs[T]) UpdateOperation ¶
func (f WriterFuncs[T]) UpdateOperation(ctx context.Context, operation Operation[T]) error
UpdateOperation updates an operation resource.
Source Files