Documentation
¶
Overview ¶
Package inject implements the HTTP endpoint that receives edge-trigger payloads (from k8s-event-watcher and any other source speaking the envelope.InjectPayload shape) and dispatches them into the mast runtime.
For the v0.1 spike this endpoint is single-session and single-bearer. Multi-session substrate and the X-Asserted-Caller proxy-identity mechanism from core-agent's recipe are deferred.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrBadPayload = errors.New("invalid inject payload")
ErrBadPayload, returned (or wrapped) by a Handler, marks a request the daemon refuses on its content (e.g. a payload UID deriving a reserved session ID). Mapped to 400 instead of the generic 500 so emitters don't retry a request that can never succeed.
ErrUnavailable, returned (or wrapped) by a Handler or ResumeHandler, tells the server the daemon is refusing new work — a shutdown drain is underway. The server maps it to 503 + Retry-After instead of the generic 500, so emitters retry against the replacement pod rather than treating a rolling restart as a crash.
Functions ¶
This section is empty.
Types ¶
type AbortHandler ¶
type AbortHandler func(ctx context.Context, req AbortRequest) error
AbortHandler applies an abort request. Optional; when nil the /abort route responds 404.
type AbortRequest ¶
type AbortRequest struct {
// SessionID identifies the session to mark aborted.
SessionID string `json:"session_id"`
// Reason is the operator-supplied reason, recorded in the abort
// marker and surfaced by `mast sessions list/show`.
Reason string `json:"reason,omitempty"`
}
AbortRequest asks the daemon to mark a session aborted.
Semantics are those of pkg/transcript's Store.Abort — a durable operator-abort marker appended to the session's event log, not preemption of in-flight work. See that method's doc for the full contract (docs/durable-execution-design.md, "Operator-facing surface"; engine-level terminal abort is v0.2).
type Config ¶
type Config struct {
// Listen is the bind address, e.g. ":7777".
Listen string
// BearerToken is the shared secret required in the Authorization
// header. Empty disables auth (intended only for local development;
// production deploys must set it).
BearerToken string
// Handler is called for each valid inject. Required.
Handler Handler
// ResumeHandler is called for each valid resume POST. Optional.
ResumeHandler ResumeHandler
// AbortHandler is called for each valid abort POST. Optional.
AbortHandler AbortHandler
// Logger is the structured logger. Defaults to slog.Default().
Logger *slog.Logger
// Metrics, when non-nil, is served at GET /metrics (Prometheus
// scrape). Unauthenticated by design — scrape configs don't carry
// the inject bearer token, and the payload is aggregate counters
// only. Nil leaves the route unregistered.
Metrics http.Handler
// BaseContext, when non-nil, is the context every request context
// derives from. The daemon passes its turn-lifetime context so
// that when the shutdown drain window elapses, in-flight handler
// turns are cancelled and unwind instead of dying at process exit.
BaseContext context.Context
}
Config configures the inject server.
type Handler ¶
type Handler func(ctx context.Context, payload envelope.InjectPayload) error
Handler receives a validated inject payload and drives the mast runtime. It returns an error if dispatch fails; the server maps that to a 5xx response (503 + Retry-After for ErrUnavailable).
type ResumeHandler ¶
type ResumeHandler func(ctx context.Context, req ResumeRequest) error
ResumeHandler feeds a resume payload into the runtime. Optional; when nil the /resume route responds 404.
type ResumeRequest ¶
type ResumeRequest struct {
// SessionID identifies the paused session (e.g. "incident-<uid>").
SessionID string `json:"session_id"`
// InterruptID matches the pending RequestInput's InterruptID.
InterruptID string `json:"interrupt_id"`
// Response is the reply payload; validated against the interrupt's
// ResponseSchema by the workflow engine on resume.
Response any `json:"response"`
}
ResumeRequest is the operator's answer to a pending HITL interrupt.
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server is the HTTP inject endpoint.
func (*Server) ListenAndServe ¶
ListenAndServe blocks serving requests. Returns http.ErrServerClosed on graceful shutdown.
Source Files