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

249 lines
9.1 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"
"git.luoli.live/root/virt/agent/operation"
)
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"`
// SupersededOperation is a non-secret immutable snapshot injected only by
// the parent Agent after it authorizes an exceptional successor. The child
// uses a separate Journal, so it cannot load the predecessor itself.
SupersededOperation *operation.Record `json:"superseded_operation,omitempty"`
SupersededExpectedState *operation.ExpectedState `json:"superseded_expected_state,omitempty"`
}
// RequestIdentity is the non-secret, immutable subset persisted beside an
// isolated worker Journal. It bridges the narrow crash window after the child
// commits a terminal operation but before it publishes completion.json.
type RequestIdentity struct {
Version int `json:"version"`
OperationID string `json:"operation_id"`
ActorUserID int64 `json:"actor_user_id"`
Method string `json:"method"`
RequestTarget string `json:"request_target"`
BodySHA256 string `json:"body_sha256"`
Fingerprint string `json:"fingerprint"`
IntegritySHA256 string `json:"integrity_sha256"`
}
func requestIdentityDigest(i RequestIdentity) string {
sum := sha256.Sum256([]byte(fmt.Sprintf(
"%d\n%s\n%d\n%s\n%s\n%s\n%s",
i.Version, i.OperationID, i.ActorUserID, i.Method, i.RequestTarget, i.BodySHA256, i.Fingerprint,
)))
return hex.EncodeToString(sum[:])
}
func validateRequestTarget(target string) error {
parsed, err := url.ParseRequestURI(target)
if err != nil || parsed.IsAbs() || parsed.Host != "" ||
!strings.HasPrefix(parsed.Path, "/v1/") || strings.ContainsAny(target, "\x00\r\n\\# ") {
return errors.New("invalid worker request target")
}
return nil
}
func (i RequestIdentity) Validate() error {
if i.Version != ProtocolVersion || !operationIDPattern.MatchString(i.OperationID) ||
i.ActorUserID < 0 || !fingerprintPattern.MatchString(i.BodySHA256) ||
!fingerprintPattern.MatchString(i.Fingerprint) ||
!fingerprintPattern.MatchString(i.IntegritySHA256) || i.IntegritySHA256 != requestIdentityDigest(i) {
return errors.New("invalid worker recovery identity")
}
switch i.Method {
case http.MethodPost, http.MethodPut, http.MethodPatch, http.MethodDelete:
default:
return errors.New("worker recovery identity must describe a mutation")
}
return validateRequestTarget(i.RequestTarget)
}
func requestIdentityFromRequest(request Request) (RequestIdentity, error) {
if err := request.Validate(); err != nil {
return RequestIdentity{}, err
}
identity := RequestIdentity{
Version: ProtocolVersion, OperationID: request.OperationID,
ActorUserID: request.Actor.UserID, Method: request.Method,
RequestTarget: request.RequestTarget, BodySHA256: auth.BodyDigest([]byte(request.Body)),
Fingerprint: request.Fingerprint,
}
identity.IntegritySHA256 = requestIdentityDigest(identity)
return identity, identity.Validate()
}
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")
}
if err := validateRequestTarget(r.RequestTarget); err != nil {
return err
}
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")
}
if r.SupersededOperation != nil {
prior := r.SupersededOperation
vpcRepair := strings.HasSuffix(r.RequestTarget, "/repair")
if prior.OperationID == "" || prior.OperationID == r.OperationID ||
!operation.ValidOperationIdentity(prior.Action, prior.ResourceID, prior.Fingerprint) ||
prior.State != operation.StateFailed || !prior.EffectMayHaveApplied ||
prior.SafeToResubmit || prior.Tombstone ||
!(strings.HasSuffix(r.RequestTarget, "/force-delete") ||
strings.HasSuffix(r.RequestTarget, "/peer-migration/cleanup-target") ||
vpcRepair) ||
(vpcRepair != (r.SupersededExpectedState != nil)) ||
(vpcRepair && !prior.ExecutionFenced) {
return errors.New("worker superseded operation is invalid")
}
} else if r.SupersededExpectedState != nil {
return errors.New("worker superseded expected state has no operation")
}
if Fingerprint(r.Method, r.RequestTarget, []byte(r.Body)) != r.Fingerprint {
return errors.New("worker request fingerprint does not match target and body")
}
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[:])
}