Documentation
¶
Overview ¶
Package workorder is the epic-#405 fleet work order model: a unit of work addressed to a specific agent identity, authorised by an engagement, signed by the control plane, and driven through an explicit state machine. It is pure domain: it imports only shared and the stdlib.
The signing itself lives outside the domain (a platform signer holds the key); the domain only defines the canonical, deterministic payload that is signed, so the authorising fields cannot drift between issue and verify.
Index ¶
- Constants
- func CanTransition(from, to State) bool
- func SameRequest(left, right *WorkOrder) bool
- type State
- type WorkOrder
- func (w *WorkOrder) AttachResponseCommand(command fleetagent.ResponseCommand) error
- func (w *WorkOrder) AttachResponseHaltCommand(command fleetagent.ResponseHaltCommand) error
- func (w *WorkOrder) AttachResponseObservation(request fleetagent.ResponseObservationRequest) error
- func (w *WorkOrder) CompleteResponse(result fleetagent.ResponseExecutionResult, reason string, now time.Time) (bool, error)
- func (w *WorkOrder) SigningPayload() string
- func (w *WorkOrder) ValidateResponseBinding() error
Constants ¶
const ( CapabilityResponseProcess = "response.process" CapabilityResponseHalt = "response.halt" CapabilityResponseObserve = "response.observe" ResponsePriority = 100 ResponseHaltPriority = 200 ResponseObservePriority = 150 )
Variables ¶
This section is empty.
Functions ¶
func CanTransition ¶
CanTransition reports whether from -> to is a legal transition.
func SameRequest ¶ added in v0.2.0
SameRequest reports whether two orders represent the same idempotent issue request. Generated IDs, signatures, state and audit timestamps are intentionally excluded.
Types ¶
type State ¶
type State string
State is the lifecycle of a work order. Terminal states never transition again.
type WorkOrder ¶
type WorkOrder struct {
ID shared.ID
TenantID shared.ID
AssetID shared.ID
AgentID shared.ID // the addressed recipient; only this agent may claim it
Capability string // e.g. scan.source, scan.host, detect.rules
AuthorizationID shared.ID // the engagement/assessment that authorises the work
IdempotencyKey string
NotAfter time.Time // expiry; the order cannot be claimed after this
LeaseID string
LeaseUntil time.Time
TimeBucket int64 // unix bucket for the in-flight uniqueness guard
State State
RefuseReason string // non-empty only when State == StateRefused
Signature string // control-plane signature over SigningPayload()
Priority int
ResponseCommand *fleetagent.ResponseCommand
ResponseHalt *fleetagent.ResponseHaltCommand
ResponseObserve *fleetagent.ResponseObservationRequest
ResponseResult *fleetagent.ResponseExecutionResult
Audit shared.Audit
}
WorkOrder is one addressed, signed, authorised unit of work.
func New ¶
func New(id, tenantID, assetID, agentID shared.ID, capability string, authorizationID shared.ID, idempotencyKey string, notAfter time.Time, timeBucket int64, now time.Time) (*WorkOrder, error)
New validates and constructs a work order in the issued state. Signature is set separately by the issuing service after signing SigningPayload().
func (*WorkOrder) AttachResponseCommand ¶ added in v0.2.0
func (w *WorkOrder) AttachResponseCommand(command fleetagent.ResponseCommand) error
AttachResponseCommand binds the dedicated signed response payload to this addressed work order. Ordinary work orders retain their original wire/signature shape.
func (*WorkOrder) AttachResponseHaltCommand ¶ added in v0.2.0
func (w *WorkOrder) AttachResponseHaltCommand(command fleetagent.ResponseHaltCommand) error
AttachResponseHaltCommand binds a signed monotonic endpoint fence to a high-priority work order.
func (*WorkOrder) AttachResponseObservation ¶ added in v0.2.0
func (w *WorkOrder) AttachResponseObservation(request fleetagent.ResponseObservationRequest) error
AttachResponseObservation binds a verdict-free observer request to an addressed work order.
func (*WorkOrder) CompleteResponse ¶ added in v0.2.0
func (w *WorkOrder) CompleteResponse(result fleetagent.ResponseExecutionResult, reason string, now time.Time) (bool, error)
CompleteResponse atomically models the only valid succeeded/failed transition for response work. An exact terminal retry is a no-op; a changed retry conflicts rather than rewriting history.
func (*WorkOrder) SigningPayload ¶
SigningPayload is the canonical, deterministic representation of the authorising fields that the control plane signs and the agent verifies. Order and separators are fixed so the signature is stable. It deliberately covers the identity, the capability, the authorising engagement and the expiry, so a tampered target, capability, authorization or expiry invalidates the signature.
func (*WorkOrder) ValidateResponseBinding ¶ added in v0.2.0
ValidateResponseBinding revalidates the persisted response-command envelope after a storage round trip.
Source Files