Documentation
¶
Index ¶
- Constants
- func CanTransition(from, to Status, retryable, replaySafe bool) bool
- func CanonicalDigest(value any) (string, error)
- func IdentityDigest(parts ...string) string
- func IsCode(err error, code ErrorCode) bool
- func RetryableReplay(row OperationRow) bool
- func StatusKnown(status Status) bool
- func StatusTerminal(status Status) bool
- func ValidateCreateRequest(request CreateRequest) error
- type CreateRequest
- type CreateResult
- type Error
- type ErrorCode
- type IdempotencyRow
- type OperationRow
- type Outcome
- type ReconcileDecision
- type ReconcileEvidence
- type Status
- type Store
- func (s *Store) ApplyReconcileDecision(ctx context.Context, operationID string, decision ReconcileDecision) (OperationRow, error)
- func (s *Store) CheckpointApplying(ctx context.Context, id string, outcome Outcome) error
- func (s *Store) Close() error
- func (s *Store) CompleteFailed(ctx context.Context, operationID string, outcome Outcome) (OperationRow, error)
- func (s *Store) CompleteSucceeded(ctx context.Context, operationID string, outcome Outcome) (OperationRow, error)
- func (s *Store) CreateAccepted(ctx context.Context, request CreateRequest) (CreateResult, error)
- func (s *Store) FindReplay(ctx context.Context, request CreateRequest) (CreateResult, bool, error)
- func (s *Store) Get(ctx context.Context, operationID string) (OperationRow, error)
- func (s *Store) GetAuthorized(ctx context.Context, operationID, principalDigest, scopeDigest string) (OperationRow, error)
- func (s *Store) ListCapability(ctx context.Context, capabilityID, afterID string, limit int) ([]OperationRow, error)
- func (s *Store) Migrate(ctx context.Context) error
- func (s *Store) RequireReconcile(ctx context.Context, operationID string, outcome Outcome) (OperationRow, error)
- func (s *Store) RetryApplying(ctx context.Context, operationID string) (OperationRow, error)
- func (s *Store) StartApplying(ctx context.Context, operationID string) (OperationRow, error)
- func (s *Store) StartApplyingWithOutcome(ctx context.Context, operationID string, outcome Outcome) (OperationRow, error)
- type View
- type ViewError
Constants ¶
const ( SchemaVersion = "pinax.operation.v1" MaxResultBytes = 64 << 10 MaxReceiptBytes = 16 << 10 )
Variables ¶
This section is empty.
Functions ¶
func CanTransition ¶
func CanonicalDigest ¶
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 ¶
IdentityDigest hashes principal and scope material with length prefixes, so raw identity values never need to enter the ledger.
func RetryableReplay ¶
func RetryableReplay(row OperationRow) bool
RetryableReplay 报告 operation 是否处于可安全重放重试的 failed 终态。
func StatusKnown ¶
func StatusTerminal ¶
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 CreateResult ¶
type CreateResult struct {
Operation OperationRow
Replay bool
// RetryClaimed 表示本次调用把 failed+retryable+replay_safe 的既有
// operation 事务内迁移到 applying 并获得执行权;调用方应继续执行
// mutation 而不是短路返回。输掉竞态的并发调用拿到普通 Replay。
RetryClaimed bool
}
type ErrorCode ¶
type ErrorCode string
const ( CodeIdentityRequired ErrorCode = "operation_identity_required" CodeIdempotencyConflict ErrorCode = "idempotency_conflict" 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 ReconcileDecision ¶
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 Store ¶
type Store struct {
// contains filtered or unexported fields
}
func OpenExisting ¶
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
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 ¶
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) CompleteFailed ¶
func (*Store) CompleteSucceeded ¶
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) GetAuthorized ¶
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) RequireReconcile ¶
func (*Store) RetryApplying ¶
func (*Store) StartApplying ¶
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