You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/agent/worker/protocol.go

165 lines
5.5 KiB
Go

package worker
import (
"context"
"crypto/sha256"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"net/http"
"net/url"
"regexp"
"strings"
"git.luoli.live/root/virt/agent/auth"
)
const (
ProtocolVersion = 1
MaxEnvelopeBytes = 2 << 20
MaxWorkerResponse = 2 << 20
ResultUnconfirmed = "result_unconfirmed"
workerFailureText = "operation result could not be confirmed before the worker deadline"
)
var (
operationIDPattern = regexp.MustCompile(`^[A-Za-z0-9_-]{8,80}$`)
fingerprintPattern = regexp.MustCompile(`^[0-9a-f]{64}$`)
)
// Request is sent over the helper's stdin. It is deliberately never written
// to the receipt directory because mutation bodies can contain guest secrets.
type Request struct {
Version int `json:"version"`
Method string `json:"method"`
RequestTarget string `json:"request_target"`
Body string `json:"body"`
Actor auth.Actor `json:"actor"`
OperationID string `json:"operation_id"`
Fingerprint string `json:"fingerprint"`
}
func (r Request) Validate() error {
if r.Version != ProtocolVersion || !operationIDPattern.MatchString(r.OperationID) ||
!fingerprintPattern.MatchString(r.Fingerprint) || len(r.Body) > MaxEnvelopeBytes {
return errors.New("invalid worker request identity")
}
switch r.Method {
case http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete:
default:
return errors.New("worker request must be a mutation")
}
parsed, err := url.ParseRequestURI(r.RequestTarget)
if err != nil || parsed.IsAbs() || parsed.Host != "" ||
!strings.HasPrefix(parsed.Path, "/v1/") || strings.ContainsAny(r.RequestTarget, "\x00\r\n\\# ") {
return errors.New("invalid worker request target")
}
if err := r.Actor.Validate(); err != nil {
return fmt.Errorf("invalid worker actor: %w", err)
}
if r.Actor.OperationID == "" || r.Actor.OperationID != r.OperationID {
return errors.New("worker actor operation ID does not match request")
}
return nil
}
// Response is the immutable helper receipt. Status is intentionally limited
// to public terminal states; a helper never emits a recoverable intermediate.
type Response struct {
Version int `json:"version"`
OperationID string `json:"operation_id"`
Fingerprint string `json:"fingerprint"`
Status string `json:"status"`
Result json.RawMessage `json:"result,omitempty"`
ErrorCode string `json:"error_code,omitempty"`
ErrorMessage string `json:"error_message,omitempty"`
EffectMayHaveApplied bool `json:"effect_may_have_applied"`
SafeToResubmit bool `json:"safe_to_resubmit"`
}
func (r Response) Validate() error {
if r.Version != ProtocolVersion || !operationIDPattern.MatchString(r.OperationID) ||
!fingerprintPattern.MatchString(r.Fingerprint) {
return errors.New("invalid worker response identity")
}
if r.Status != "succeeded" && r.Status != "failed" {
return errors.New("worker response is not terminal")
}
if len(r.Result) != 0 && !json.Valid(r.Result) {
return errors.New("worker response result is invalid JSON")
}
if r.Status == "succeeded" {
if r.ErrorCode != "" || r.ErrorMessage != "" || r.EffectMayHaveApplied || r.SafeToResubmit {
return errors.New("successful worker response contains failure semantics")
}
return nil
}
if r.ErrorCode == "" || len(r.ErrorCode) > 64 || len(r.ErrorMessage) > 1024 {
return errors.New("failed worker response is incomplete")
}
if r.SafeToResubmit && r.EffectMayHaveApplied {
return errors.New("ambiguous worker response cannot be resubmitted")
}
return nil
}
func UnconfirmedResponse(operationID, fingerprint string) Response {
return Response{
Version: ProtocolVersion, OperationID: operationID, Fingerprint: fingerprint,
Status: "failed", ErrorCode: ResultUnconfirmed, ErrorMessage: workerFailureText,
EffectMayHaveApplied: true, SafeToResubmit: false,
}
}
// Error preserves the helper's bounded public failure classification without
// exposing stderr, paths, credentials, or native libvirt diagnostics.
type Error struct {
Code string
Message string
EffectMayHaveApplied bool
ResubmitAllowed bool
ExecutionFenced bool
Result json.RawMessage
}
func (e *Error) Error() string {
if e.Message != "" {
return e.Message
}
return "isolated mutation failed"
}
func (e *Error) PublicCode() string { return e.Code }
func (e *Error) PublicMessage() string { return e.Message }
func (e *Error) FailureSemantics() (bool, bool) {
return e.EffectMayHaveApplied, e.ResubmitAllowed
}
func (e *Error) RequiresExecutionFence() bool { return e.ExecutionFenced }
type Executor interface {
Execute(context.Context, Request) (json.RawMessage, error)
}
func Result(response Response) (json.RawMessage, error) {
if err := response.Validate(); err != nil {
return nil, err
}
if response.Status == "succeeded" {
return append(json.RawMessage(nil), response.Result...), nil
}
return append(json.RawMessage(nil), response.Result...), &Error{
Code: response.ErrorCode, Message: response.ErrorMessage,
EffectMayHaveApplied: response.EffectMayHaveApplied,
ResubmitAllowed: response.SafeToResubmit,
Result: append(json.RawMessage(nil), response.Result...),
}
}
func Fingerprint(method, target string, body []byte) string {
sum := sha256.Sum256([]byte(strings.ToUpper(method) + "\n" + target + "\n" + string(body)))
return hex.EncodeToString(sum[:])
}