invocation

package
v0.4.0 Latest Latest
Warning

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

 Go to latest Published: Sep 2, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package invocation defines metadata that must cross every external effect boundary.

Index

Constants

View Source 
const (
	HeaderVerb           = "X-Effectus-Verb"
	HeaderRequestID      = "X-Effectus-Request-ID"
	HeaderExecutionID    = "X-Effectus-Execution-ID"
	HeaderSagaID         = "X-Effectus-Saga-ID"
	HeaderEffectID       = "X-Effectus-Effect-ID"
	HeaderAttempt        = "X-Effectus-Attempt"
	HeaderDirection      = "X-Effectus-Direction"
	HeaderArgumentHash   = "X-Effectus-Argument-Hash"
	HeaderContractHash   = "X-Effectus-Contract-Hash"
	HeaderFencingGrants  = "X-Effectus-Fencing-Grants"
	HeaderDeadline       = "X-Effectus-Deadline"
	HeaderOutcome        = "X-Effectus-Outcome"
	HeaderIdempotencyKey = "Idempotency-Key"
)
View Source 
const HTTPResolverID = "effectus/http/v1"

Variables

This section is empty.

Functions

func ValidateOutcome 

func ValidateOutcome(outcome Outcome) error

ValidateOutcome rejects incomplete or contradictory classifications.

Types

type Context 

type Context struct {
	RequestID     string         `json:"request_id"`
	ExecutionID   string         `json:"execution_id"`
	Saga          Saga           `json:"saga"`
	FencingGrants []FencingGrant `json:"fencing_grants,omitempty"`
	Deadline      time.Time      `json:"deadline"`
}

Context contains transport-neutral invocation metadata.

type Descriptor added in v0.4.0 

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

Descriptor is canonical resolver input. Its fields are private so a value cannot be changed after NewDescriptor or ParseDescriptor returns.

func NewDescriptor added in v0.4.0 

func NewDescriptor(spec DescriptorSpec) (Descriptor, error)

NewDescriptor validates and freezes canonical executor resolver input.

func ParseDescriptor added in v0.4.0 

func ParseDescriptor(data []byte) (Descriptor, error)

ParseDescriptor strictly decodes a canonical executor descriptor.

func (Descriptor) CanonicalJSON added in v0.4.0 

func (descriptor Descriptor) CanonicalJSON() ([]byte, error)

CanonicalJSON returns the unique JSON encoding of descriptor.

func (Descriptor) Headers added in v0.4.0 

func (descriptor Descriptor) Headers() map[string]string

Headers returns a copy of static non-reserved transport headers.

func (Descriptor) MarshalJSON added in v0.4.0 

func (descriptor Descriptor) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler using the canonical representation.

func (Descriptor) Reference added in v0.4.0 

func (descriptor Descriptor) Reference() string

Reference returns the transport endpoint or digest-pinned artifact reference.

func (Descriptor) ResolverID added in v0.4.0 

func (descriptor Descriptor) ResolverID() string

ResolverID returns the stable resolver implementation identity. An empty ID denotes an embedded callback and is invalid in a production Generation.

func (Descriptor) Settings added in v0.4.0 

func (descriptor Descriptor) Settings() map[string]string

Settings returns a copy of transport-specific scalar settings.

func (Descriptor) Type added in v0.4.0 

func (descriptor Descriptor) Type() DescriptorType

Type returns the executor transport type.

func (*Descriptor) UnmarshalJSON added in v0.4.0 

func (descriptor *Descriptor) UnmarshalJSON(data []byte) error

UnmarshalJSON implements strict JSON decoding. Unknown and duplicate fields are rejected, and the receiver changes only after complete validation.

type DescriptorKV added in v0.4.0 

type DescriptorKV struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

DescriptorKV is one canonically ordered descriptor value.

type DescriptorSpec added in v0.4.0 

type DescriptorSpec struct {
	Type       DescriptorType
	ResolverID string
	Reference  string
	Headers    map[string]string
	Settings   map[string]string
}

DescriptorSpec is construction input for an immutable Descriptor. NewDescriptor copies all maps and rejects reserved invocation metadata.

type DescriptorType added in v0.4.0 

type DescriptorType string

DescriptorType identifies a supported executor transport. 

const (
	DescriptorHTTP     DescriptorType = "http"
	DescriptorGRPC     DescriptorType = "grpc"
	DescriptorStream   DescriptorType = "stream"
	DescriptorOCI      DescriptorType = "oci"
	DescriptorEmbedded DescriptorType = "embedded"
)

type Direction 

type Direction string

Direction distinguishes a forward mutation from its compensation. 

const (
	DirectionForward      Direction = "forward"
	DirectionCompensation Direction = "compensation"
)

type Executor 

type Executor interface {
	Invoke(context.Context, Request) Outcome
}

Executor accepts stable identity and fencing metadata as part of its API.

type FencingGrant 

type FencingGrant struct {
	Authority string `json:"authority"`
	Resource  string `json:"resource"`
	Token     uint64 `json:"token"`
}

FencingGrant is immutable system metadata. Adapters must not source these values from caller arguments or caller headers.

type FencingStatus 

type FencingStatus string

FencingStatus describes observation without claiming destination enforcement. 

const (
	FencingNotRequested  FencingStatus = "not_requested"
	FencingLocalLockOnly FencingStatus = "local_lock_only"
	FencingPropagated    FencingStatus = "propagated"
	FencingAcknowledged  FencingStatus = "acknowledged"
	FencingStaleRejected FencingStatus = "stale_rejected"
)

type HTTPExecutor 

type HTTPExecutor struct {
	URL              string
	Method           string
	Headers          map[string]string
	Client           *http.Client
	MaxResponseBytes int64
}

HTTPExecutor sends one invocation without an internal retry loop.

func NewHTTPExecutor 

func NewHTTPExecutor(executor HTTPExecutor) (*HTTPExecutor, error)

func (*HTTPExecutor) InvocationResolverDescriptor added in v0.4.0 

func (executor *HTTPExecutor) InvocationResolverDescriptor() (Descriptor, error)

InvocationResolverDescriptor returns the immutable transport configuration.

func (*HTTPExecutor) Invoke 

func (executor *HTTPExecutor) Invoke(ctx context.Context, request Request) Outcome

type HTTPResolver added in v0.4.0 

type HTTPResolver struct{}

HTTPResolver reconstructs the canonical HTTP executor from a Descriptor.

func (HTTPResolver) Resolve added in v0.4.0 

func (HTTPResolver) Resolve(_ context.Context, descriptor Descriptor) (Executor, io.Closer, error)

Resolve implements Resolver. Network policy is enforced for every dial and redirect, not only when the descriptor is admitted.

type Outcome 

type Outcome struct {
	Class  OutcomeClass
	Result any
	Err    error
}

Outcome is the executor's explicit result classification.

type OutcomeClass 

type OutcomeClass string

OutcomeClass states whether the destination can know that a mutation committed. 

const (
	OutcomeSuccess                    OutcomeClass = "success"
	OutcomeRetryableKnownNotCommitted OutcomeClass = "retryable_failure_known_not_committed"
	OutcomePermanentFailure           OutcomeClass = "permanent_failure"
	OutcomeUnknown                    OutcomeClass = "unknown_outcome"
	OutcomeStaleFence                 OutcomeClass = "stale_fence"
)

type Registry added in v0.4.0 

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

Registry is an immutable resolver registry keyed by stable resolver ID.

func NewRegistry added in v0.4.0 

func NewRegistry(registrations []ResolverRegistration) (*Registry, error)

NewRegistry constructs an immutable registry and rejects duplicate IDs.

func (*Registry) Resolve added in v0.4.0 

func (registry *Registry) Resolve(ctx context.Context, descriptor Descriptor) (Executor, io.Closer, error)

Resolve resolves a descriptor or fails closed when its resolver is absent.

type Request 

type Request struct {
	Metadata     Context        `json:"metadata"`
	Verb         string         `json:"verb"`
	Arguments    map[string]any `json:"arguments"`
	ArgumentHash string         `json:"argument_hash"`
	ContractHash string         `json:"contract_hash"`
}

Request is the immutable call delivered to an invocation-aware executor.

type Resolver added in v0.4.0 

type Resolver interface {
	Resolve(context.Context, Descriptor) (Executor, io.Closer, error)
}

Resolver constructs an executor and returns the resource owned by the generation. The closer can be nil when the executor owns no resources.

type ResolverDescriptorProvider 

type ResolverDescriptorProvider interface {
	InvocationResolverDescriptor() (Descriptor, error)
}

ResolverDescriptorProvider exposes the canonical descriptor for an executor.

type ResolverFunc added in v0.4.0 

type ResolverFunc func(context.Context, Descriptor) (Executor, io.Closer, error)

ResolverFunc adapts a function to Resolver.

func (ResolverFunc) Resolve added in v0.4.0 

func (function ResolverFunc) Resolve(ctx context.Context, descriptor Descriptor) (Executor, io.Closer, error)

type ResolverRegistration added in v0.4.0 

type ResolverRegistration struct {
	ID       string
	Resolver Resolver
}

ResolverRegistration binds one stable ID to one resolver.

type Saga 

type Saga struct {
	SagaID         string    `json:"saga_id"`
	EffectID       string    `json:"effect_id"`
	Attempt        uint64    `json:"attempt"`
	Direction      Direction `json:"direction"`
	IdempotencyKey string    `json:"idempotency_key"`
}

Saga identifies one durable effect occurrence and dispatch attempt.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.