operation

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 31, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source
const (
	SchemaVersion = "pinax.operation.v1"

	MaxResultBytes  = 64 << 10
	MaxReceiptBytes = 16 << 10
)

Variables

This section is empty.

Functions

func CanTransition

func CanTransition(from, to Status, retryable, replaySafe bool) bool

func CanonicalDigest

func CanonicalDigest(value any) (string, error)

CanonicalDigest produces a stable digest for JSON-shaped request DTOs. It sorts every object level and preserves array order, so Go map iteration order cannot create a second logical idempotency binding.

func IdentityDigest

func IdentityDigest(parts ...string) string

IdentityDigest hashes principal and scope material with length prefixes, so raw identity values never need to enter the ledger.

func IsCode

func IsCode(err error, code ErrorCode) bool

func RetryableReplay

func RetryableReplay(row OperationRow) bool

RetryableReplay 报告 operation 是否处于可安全重放重试的 failed 终态。

func StatusKnown

func StatusKnown(status Status) bool

func StatusTerminal

func StatusTerminal(status Status) bool

func ValidateCreateRequest

func ValidateCreateRequest(request CreateRequest) error

ValidateCreateRequest lets mutation adapters reject incomplete identities before opening or creating the owner operation ledger.

Types

type CreateRequest

type CreateRequest struct {
	OperationID     string
	IdempotencyKey  string
	CapabilityID    string
	BindingID       string
	PrincipalDigest string
	ScopeDigest     string
	RequestDigest   string
	RevisionBefore  string
}

type CreateResult

type CreateResult struct {
	Operation OperationRow
	Replay    bool
	// RetryClaimed 表示本次调用把 failed+retryable+replay_safe 的既有
	// operation 事务内迁移到 applying 并获得执行权;调用方应继续执行
	// mutation 而不是短路返回。输掉竞态的并发调用拿到普通 Replay。
	RetryClaimed bool
}

type Error

type Error struct {
	Code    ErrorCode
	Message string
	Cause   error
}

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type ErrorCode

type ErrorCode string
const (
	CodeIdentityRequired    ErrorCode = "operation_identity_required"
	CodeIdempotencyConflict ErrorCode = "idempotency_conflict"
	CodeStoreUnavailable    ErrorCode = "operation_store_unavailable"
	CodeNotFound            ErrorCode = "operation_not_found"
	CodeIllegalTransition   ErrorCode = "operation_transition_invalid"
	CodePayloadInvalid      ErrorCode = "operation_payload_invalid"
	CodePayloadTooLarge     ErrorCode = "operation_payload_too_large"
	CodeReconcileRequired   ErrorCode = "reconcile_required"
	CodeEvidenceConflict    ErrorCode = "reconcile_evidence_conflict"
)

type IdempotencyRow

type IdempotencyRow struct {
	ID              uint   `gorm:"primaryKey"`
	PrincipalDigest string `gorm:"size:80;not null;uniqueIndex:idx_operation_idempotency_binding,priority:1"`
	ScopeDigest     string `gorm:"size:80;not null;uniqueIndex:idx_operation_idempotency_binding,priority:2"`
	IdempotencyKey  string `gorm:"size:128;not null;uniqueIndex:idx_operation_idempotency_binding,priority:3"`
	CapabilityID    string `gorm:"size:128;not null"`
	BindingID       string `gorm:"size:160;not null"`
	OperationID     string `gorm:"size:128;not null;uniqueIndex"`
	RequestDigest   string `gorm:"size:80;not null"`
	CreatedAt       time.Time
}

func (IdempotencyRow) TableName

func (IdempotencyRow) TableName() string

type OperationRow

type OperationRow struct {
	OperationID     string `gorm:"primaryKey;size:128"`
	CapabilityID    string `gorm:"size:128;not null;index"`
	BindingID       string `gorm:"size:160;not null;index"`
	PrincipalDigest string `gorm:"size:80;not null;index:idx_operation_scope,priority:1"`
	ScopeDigest     string `gorm:"size:80;not null;index:idx_operation_scope,priority:2"`
	RequestDigest   string `gorm:"size:80;not null"`
	Status          Status `gorm:"size:32;not null;index"`
	ReplaySafe      bool
	Retryable       bool
	ResultJSON      []byte `gorm:"type:blob"`
	ReceiptJSON     []byte `gorm:"type:blob"`
	ReceiptRef      string `gorm:"size:512"`
	ResourceRef     string `gorm:"size:512"`
	RevisionBefore  string `gorm:"size:160"`
	RevisionAfter   string `gorm:"size:160"`
	ErrorCode       string `gorm:"size:128"`
	ErrorMessage    string `gorm:"size:512"`
	ReconcileCount  uint
	CreatedAt       time.Time
	UpdatedAt       time.Time
	AcceptedAt      time.Time
	ApplyingAt      *time.Time
	CompletedAt     *time.Time
}

OperationRow is the durable owner-side record for one logical mutation. Result and receipt payloads are bounded, redacted JSON projections; request bodies, credentials, provider payloads and absolute vault paths do not belong in this table.

func (OperationRow) TableName

func (OperationRow) TableName() string

type Outcome

type Outcome struct {
	Result        json.RawMessage
	Receipt       json.RawMessage
	ReceiptRef    string
	ResourceRef   string
	RevisionAfter string
	ErrorCode     string
	ErrorMessage  string
	Retryable     bool
	ReplaySafe    bool
}

type ReconcileDecision

type ReconcileDecision struct {
	Status     Status
	Outcome    Outcome
	NextAction string
}

func DecideReconcile

func DecideReconcile(current OperationRow, evidence ReconcileEvidence) (ReconcileDecision, error)

DecideReconcile 只根据 receipt/revision/resource inspector 提供的证据决策。 crash window 中 operation 可能仍是 applying,但 domain mutation 已完成; 此处绝不能重新执行 mutation 猜测结果。证据不足时必须保持 reconcile_required,等待人工或后续 inspector 提供可验证证据。

type ReconcileEvidence

type ReconcileEvidence struct {
	Applied       bool
	NotApplied    bool
	ProofRef      string
	Result        json.RawMessage
	Receipt       json.RawMessage
	ReceiptRef    string
	ResourceRef   string
	RevisionAfter string
	ErrorCode     string
	ErrorMessage  string
	Retryable     bool
	ReplaySafe    bool
}

type Status

type Status string
const (
	StatusAccepted          Status = "accepted"
	StatusApplying          Status = "applying"
	StatusSucceeded         Status = "succeeded"
	StatusFailed            Status = "failed"
	StatusReconcileRequired Status = "reconcile_required"
)

type Store

type Store struct {
	// contains filtered or unexported fields
}

func Open

func Open(root string) (*Store, error)

func OpenDB

func OpenDB(db *gorm.DB) (*Store, error)

func OpenExisting

func OpenExisting(root string) (*Store, error)

OpenExisting opens an existing operation ledger without creating one for a read-only status lookup on an older vault.

func OpenReadSnapshot added in v0.3.1

func OpenReadSnapshot(root string) (*Store, func(), error)

OpenReadSnapshot opens a bounded private copy without migration or source sidecar writes. Missing ledgers remain missing; callers must not initialize.

func (*Store) ApplyReconcileDecision

func (s *Store) ApplyReconcileDecision(ctx context.Context, operationID string, decision ReconcileDecision) (OperationRow, error)

func (*Store) CheckpointApplying

func (s *Store) CheckpointApplying(ctx context.Context, id string, outcome Outcome) error

CheckpointApplying persists recovery references before a filesystem side effect. It never stores the request or note body and cannot change a terminal operation.

func (*Store) Close

func (s *Store) Close() error

func (*Store) CompleteFailed

func (s *Store) CompleteFailed(ctx context.Context, operationID string, outcome Outcome) (OperationRow, error)

func (*Store) CompleteSucceeded

func (s *Store) CompleteSucceeded(ctx context.Context, operationID string, outcome Outcome) (OperationRow, error)

func (*Store) CreateAccepted

func (s *Store) CreateAccepted(ctx context.Context, request CreateRequest) (CreateResult, error)

func (*Store) FindReplay

func (s *Store) FindReplay(ctx context.Context, request CreateRequest) (CreateResult, bool, error)

FindReplay performs a read-only lookup for an existing immutable operation binding. It lets mutation adapters return durable outcomes before evaluating preconditions that may no longer hold after a successful mutation.

func (*Store) Get

func (s *Store) Get(ctx context.Context, operationID string) (OperationRow, error)

func (*Store) GetAuthorized

func (s *Store) GetAuthorized(ctx context.Context, operationID, principalDigest, scopeDigest string) (OperationRow, error)

func (*Store) ListCapability added in v0.3.1

func (s *Store) ListCapability(ctx context.Context, capabilityID, afterID string, limit int) ([]OperationRow, error)

ListCapability returns an owner-local, bounded ledger page for recovery and invariant checks. It is not a transport-visible or principal-scoped listing.

func (*Store) Migrate

func (s *Store) Migrate(ctx context.Context) error

func (*Store) RequireReconcile

func (s *Store) RequireReconcile(ctx context.Context, operationID string, outcome Outcome) (OperationRow, error)

func (*Store) RetryApplying

func (s *Store) RetryApplying(ctx context.Context, operationID string) (OperationRow, error)

func (*Store) StartApplying

func (s *Store) StartApplying(ctx context.Context, operationID string) (OperationRow, error)

func (*Store) StartApplyingWithOutcome

func (s *Store) StartApplyingWithOutcome(ctx context.Context, operationID string, outcome Outcome) (OperationRow, error)

StartApplyingWithOutcome persists bounded preparation evidence before the domain mutation starts. This closes the crash window where reconciliation would otherwise know that an operation was applying but not which durable resource identity it intended to create.

type View

type View struct {
	SchemaVersion     string          `json:"schema_version"`
	OperationID       string          `json:"operation_id"`
	CapabilityID      string          `json:"capability_id"`
	BindingID         string          `json:"binding_id"`
	RequestDigest     string          `json:"request_digest,omitempty"`
	Status            Status          `json:"status"`
	Retryable         bool            `json:"retryable"`
	ReplaySafe        bool            `json:"replay_safe"`
	ReconcileRequired bool            `json:"reconcile_required"`
	RequiredAction    string          `json:"required_action,omitempty"`
	Result            json.RawMessage `json:"result,omitempty"`
	Receipt           json.RawMessage `json:"receipt,omitempty"`
	ReceiptRef        string          `json:"receipt_ref,omitempty"`
	ResourceRef       string          `json:"resource_ref,omitempty"`
	RevisionBefore    string          `json:"revision_before,omitempty"`
	RevisionAfter     string          `json:"revision_after,omitempty"`
	Error             *ViewError      `json:"error,omitempty"`
	CreatedAt         string          `json:"created_at"`
	UpdatedAt         string          `json:"updated_at"`
	AcceptedAt        string          `json:"accepted_at"`
	ApplyingAt        string          `json:"applying_at,omitempty"`
	CompletedAt       string          `json:"completed_at,omitempty"`
}

func ViewFromRow

func ViewFromRow(row OperationRow) View

type ViewError

type ViewError struct {
	Code    string `json:"code"`
	Message string `json:"message"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL