emit

package
v0.2.0 Latest Latest
Warning

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

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

Documentation

Overview

Package emit implements emit@v1 as an extraction-ready, host-bound event publication step kind. Transport selection, destination authorization, and durable publication idempotency remain host responsibilities.

Index

Constants

View Source 
const (
	KindName    = "emit"
	KindVersion = "v1"

	CapabilityPublish = "event.publish"

	CodeInvalidInvocation = "emit_invalid_invocation"
	CodePolicyDenied      = "emit_policy_denied"
	CodePublishFailed     = "emit_publish_failed"
	CodeInvalidResult     = "emit_invalid_result"
)

Variables

View Source 
var (
	ErrInvalidOptions       = errors.New("invalid emit adapter options")
	ErrInvalidConfig        = errors.New("invalid emit configuration")
	ErrInvalidEnvelope      = errors.New("invalid emit envelope")
	ErrInvalidResult        = errors.New("invalid emit publication result")
	ErrPublicationConflict  = errors.New("emit publication idempotency conflict")
	ErrPublicationRejected  = errors.New("emit publication rejected")
	ErrPublicationTransient = errors.New("emit publication temporarily unavailable")
)

Functions

This section is empty.

Types

type AuthorizationRequest 

type AuthorizationRequest struct {
	Identity       stepkind.InvocationIdentity `json:"identity"`
	Destination    Destination                 `json:"destination"`
	EventType      string                      `json:"event_type"`
	Correlation    string                      `json:"correlation"`
	EnvelopeID     string                      `json:"envelope_id"`
	PayloadType    values.Type                 `json:"payload_type"`
	PayloadDigest  string                      `json:"payload_digest"`
	Redaction      values.RedactionClass       `json:"redaction"`
	Retention      values.RetentionClass       `json:"retention"`
	IdempotencyKey string                      `json:"idempotency_key"`
}

AuthorizationRequest contains only immutable identity and payload metadata; policy never receives inline payload or resolved secret material.

type ConfigDescription 

type ConfigDescription struct {
	Destination          Destination           `json:"destination"`
	EventType            string                `json:"event_type"`
	RequiredCapabilities []string              `json:"required_capabilities"`
	Effects              graph.EffectSet       `json:"effects"`
	Idempotency          graph.IdempotencyMode `json:"idempotency"`
	RetrySafety          stepkind.RetrySafety  `json:"retry_safety"`
}

ConfigDescription is a deterministic pre-execution policy projection.

type Destination 

type Destination struct {
	Kind       string            `json:"kind"`
	Reference  string            `json:"reference"`
	Attributes map[string]string `json:"attributes,omitempty"`
}

Destination is an application-neutral routing declaration. Kind identifies the host adapter/capability family and Reference is an opaque, non-secret route identity. Credentials and bearer URLs are forbidden in every field.

func (Destination) Validate 

func (d Destination) Validate() error

Validate checks the bounded transport-stable destination declaration.

type Envelope 

type Envelope struct {
	ID             string       `json:"id"`
	Destination    Destination  `json:"destination"`
	EventType      string       `json:"event_type"`
	Correlation    string       `json:"correlation"`
	Payload        values.Value `json:"payload"`
	IdempotencyKey string       `json:"idempotency_key"`
}

Envelope is the immutable typed publication handed to a host Publisher. Payload may be inline, an ArtifactRef, or a SecretRef and retains its exact classification and producer provenance. Publishers must never log it.

func (Envelope) Validate 

func (e Envelope) Validate() error

Validate checks the complete publication boundary without inspecting or rendering payload content.

type Kind 

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

Kind implements emit@v1. It is concurrency-safe when its injected policy and publisher are concurrency-safe.

func New 

func New(options Options) (*Kind, error)

New constructs a fail-closed emit executor.

func Register 

func Register(registry stepkind.Registry, options Options) (*Kind, error)

Register constructs and registers emit@v1.

func (*Kind) DescribeConfig 

func (*Kind) DescribeConfig(_ context.Context, input graph.Config) (ConfigDescription, error)

DescribeConfig exposes the immutable destination/effect policy projection.

func (*Kind) Execute 

func (k *Kind) Execute(ctx context.Context, prepared stepkind.PreparedInvocation) (stepkind.StepResult, error)

Execute authorizes and publishes one immutable typed envelope.

func (*Kind) Spec 

func (*Kind) Spec() stepkind.StepKindSpec

Spec returns the conservative static publication contract.

func (*Kind) ValidateConfig 

func (*Kind) ValidateConfig(ctx context.Context, input graph.Config) []diagnostic.Diagnostic

ValidateConfig reports deterministic source-addressable config failures.

type Observation 

type Observation struct {
	Phase             ObservationPhase      `json:"phase"`
	EnvelopeID        string                `json:"envelope_id"`
	EventType         string                `json:"event_type"`
	DestinationKind   string                `json:"destination_kind"`
	DestinationDigest string                `json:"destination_digest"`
	PayloadType       values.Type           `json:"payload_type"`
	PayloadDigest     string                `json:"payload_digest"`
	Redaction         values.RedactionClass `json:"redaction"`
	Outcome           PublicationOutcome    `json:"outcome,omitempty"`
	Code              string                `json:"code,omitempty"`
}

Observation contains only bounded routing and payload digests. It never carries the destination reference, correlation, attributes, payload, idempotency key, credentials, or raw causes.

type ObservationPhase 

type ObservationPhase string

ObservationPhase is a closed operational emit phase. Authorized never implies that a publication side effect occurred; the other phases are emitted only after authorization succeeds. 

const (
	ObservationAuthorized ObservationPhase = "authorized"
	ObservationPublished  ObservationPhase = "published"
	ObservationFailed     ObservationPhase = "failed"
)

type Observer 

type Observer interface {
	ObserveEmit(context.Context, Observation) error
}

Observer receives defensive, sanitized operational observations. Errors are deliberately ignored and cannot change workflow execution.

type ObserverFunc 

type ObserverFunc func(context.Context, Observation) error

ObserverFunc adapts a function to Observer.

func (ObserverFunc) ObserveEmit 

func (f ObserverFunc) ObserveEmit(ctx context.Context, observation Observation) error

ObserveEmit implements Observer.

type Options 

type Options struct {
	Policy    Policy
	Publisher Publisher
	Observer  Observer
}

Options supplies the application-owned execution boundaries. Observer is optional and fail-safe; Policy and Publisher are required.

type Policy 

type Policy interface {
	AuthorizeEmit(context.Context, AuthorizationRequest) error
}

Policy authorizes one exact destination and envelope before any publisher side effect. Implementations must be concurrency-safe and fail closed.

type PolicyFunc 

type PolicyFunc func(context.Context, AuthorizationRequest) error

PolicyFunc adapts a function to Policy.

func (PolicyFunc) AuthorizeEmit 

func (f PolicyFunc) AuthorizeEmit(ctx context.Context, request AuthorizationRequest) error

AuthorizeEmit implements Policy.

type PublicationError 

type PublicationError struct {
	Failure error
	Cause   error
}

PublicationError provides safe retry classification while retaining a raw process-local cause. Error never formats Cause.

func (*PublicationError) Error 

func (e *PublicationError) Error() string

func (*PublicationError) RetryClassification 

func (e *PublicationError) RetryClassification() stepkind.RetryClassification

func (*PublicationError) Unwrap 

func (e *PublicationError) Unwrap() []error

type PublicationOutcome 

type PublicationOutcome string

PublicationOutcome describes whether the host applied or exactly replayed the immutable publication. 

const (
	PublicationApplied  PublicationOutcome = "applied"
	PublicationReplayed PublicationOutcome = "replayed"
)

func (PublicationOutcome) Valid 

func (o PublicationOutcome) Valid() bool

Valid reports whether o belongs to the closed publication vocabulary.

type PublicationResult 

type PublicationResult struct {
	EnvelopeID    string             `json:"envelope_id"`
	PublicationID string             `json:"publication_id"`
	Outcome       PublicationOutcome `json:"outcome"`
	PublishedAt   time.Time          `json:"published_at"`
	Attributes    map[string]string  `json:"attributes,omitempty"`
}

PublicationResult contains bounded, non-secret receipt metadata only. Attributes must never contain payloads, credentials, raw transport errors, endpoint URLs, or secret destination identifiers.

func (PublicationResult) Validate 

func (r PublicationResult) Validate() error

Validate checks the safe durable receipt envelope.

type Publisher 

type Publisher interface {
	Publish(context.Context, Envelope) (PublicationResult, error)
}

Publisher performs the actual host-bound event/message publication. Implementations must be concurrency-safe and idempotent by IdempotencyKey: exact replay returns the same receipt with Outcome=replayed; a different envelope for an existing key returns ErrPublicationConflict.

type PublisherFunc 

type PublisherFunc func(context.Context, Envelope) (PublicationResult, error)

PublisherFunc adapts a function to Publisher.

func (PublisherFunc) Publish 

func (f PublisherFunc) Publish(ctx context.Context, envelope Envelope) (PublicationResult, error)

Publish implements Publisher.

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.