env

package
v0.6.91 Latest Latest
Warning

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

Go to latest
Published: Nov 13, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package env is what every node of one service shares: the manifest being declared into and the wiring of events, hooks and activities to a transport. Declaration packages reach it through the node a Scope wraps, so nothing is process-global.

Index

Constants

View Source
const DefaultHookTimeout = 30 * time.Second

DefaultHookTimeout bounds a hook call nothing else bounds: no deadline on the context, none on the call or the declaration, no configured one.

Variables

View Source
var ErrNoBinding = errors.New("no binding")

ErrNoBinding: backplane has no binding for the hook.

View Source
var ErrUnavailable = errors.New("backplane: transport unavailable")

ErrUnavailable: no transport carries this call (yet).

Functions

func CallKeyOf

func CallKeyOf(ctx context.Context) string

CallKeyOf is the idempotency key WithCallKey set, or "".

func WithActivityInfo

func WithActivityInfo(ctx context.Context, info ActivityInfo) context.Context

WithActivityInfo attaches info to a handler's ctx.

func WithCallKey

func WithCallKey(ctx context.Context, key string) context.Context

WithCallKey marks the hook call made with ctx as idempotent under key: the transport runs one call per key. Empty key: an ordinary call.

func WithIncoming

func WithIncoming(ctx context.Context, in Incoming) context.Context

WithIncoming returns ctx carrying in.

Types

type ActivityInfo

type ActivityInfo struct {
	Attempt   int32     // 1 for the first
	Binding   string    // binding or rule that called, from the envelope
	Step      string    // its step
	Key       string    // "<workflow id>/<activity id>": the same for every attempt
	Deadline  time.Time // of this attempt; zero when unbounded
	Heartbeat func(details ...any)
}

ActivityInfo is what the transport knows about the activity execution a handler serves.

func ActivityInfoOf

func ActivityInfoOf(ctx context.Context) (ActivityInfo, bool)

ActivityInfoOf is the info attached by WithActivityInfo.

type Broker

type Broker interface {
	Publish(ctx context.Context, m Message) error
}

Broker carries events (NATS JetStream; a recorder in tests).

type Caller

type Caller interface {
	Call(ctx context.Context, hook string, in []byte) ([]byte, error)
}

Caller carries hook calls (Temporal Nexus; a stub in tests). Payloads are encoded JSON.

type Delivery

type Delivery struct {
	MaxDeliver  int            // deliveries before the dead letter
	Concurrency int            // handlers in flight at once
	Timeout     time.Duration  // of one handler call
	Redelivery  backoff.Policy // delay after a failed delivery
	StartAll    bool           // a new consumer starts at the stream's first message
	// Ordered: one message in flight across every instance (strict order).
	Ordered bool
	// InactiveThreshold: the server deletes the consumer after this long
	// without an instance pulling; zero never.
	InactiveThreshold time.Duration
}

Delivery is how a reactor's messages are delivered, as its author declared it; a zero field means the transport's default.

type Env

type Env struct {
	Service  string
	Manifest *manifest.Builder
	// contains filtered or unexported fields
}

Env of one service.

func New

func New(service string, m *manifest.Builder) *Env

New creates the env of service.

func Of

func Of(n *node.Node) *Env

Of returns the env of the tree n belongs to.

func (*Env) Activities

func (e *Env) Activities() map[string]Handler

Activities lists the declared activities by name.

func (*Env) Activity

func (e *Env) Activity(name string, h Handler)

Activity stores the handler of a declared activity. A name an own activity has panics: both are one Temporal activity name on the queue.

func (*Env) ActivityHandler

func (e *Env) ActivityHandler(name string) (Handler, bool)

ActivityHandler returns the handler of a declared activity.

func (*Env) Bound added in v0.6.8

func (e *Env) Bound(hook string) bool

Bound reports whether hook (its short name) may have a binding: false only when backplane's set is known and lacks it.

func (*Env) BoundChanges added in v0.6.8

func (e *Env) BoundChanges(ctx context.Context) <-chan struct{}

BoundChanges signals after every change of the bound set until ctx ends; one pending signal at most.

func (*Env) Broker

func (e *Env) Broker() Broker

Broker is the installed event transport or nil.

func (*Env) Caller

func (e *Env) Caller() Caller

Caller is the installed hook transport or nil.

func (*Env) FollowSection added in v0.6.37

func (e *Env) FollowSection(name string, fn func(raw []byte))

FollowSection has fn told of section name's published set (a backplanev1.SectionSet; nil when there is none) while the service runs.

func (*Env) Followed added in v0.6.37

func (e *Env) Followed() map[string][]func(raw []byte)

Followed is every followed section name with its functions.

func (*Env) HookTimeout

func (e *Env) HookTimeout() time.Duration

HookTimeout is the platform default deadline of a hook call: the configured one or DefaultHookTimeout. Never zero.

func (*Env) LiveSections added in v0.6.45

func (e *Env) LiveSections() map[string]*anypb.Any

LiveSections are the live section values set so far, by name.

func (*Env) OnSectionChange added in v0.6.45

func (e *Env) OnSectionChange(fn func())

OnSectionChange has fn called after every change of a live section.

func (*Env) OwnActivities added in v0.6.32

func (e *Env) OwnActivities() map[string]Handler

OwnActivities lists the activities of OwnActivity by name.

func (*Env) OwnActivity added in v0.6.32

func (e *Env) OwnActivity(name string, h Handler)

OwnActivity stores the handler of an activity only the service's own workflows run: registered on the worker as a declared one is, not in the manifest and not callable by the platform. A name taken panics.

func (*Env) PayloadCodec added in v0.6.51

func (e *Env) PayloadCodec() any

PayloadCodec is the installed codec; nil without the transport.

func (*Env) Reactor

func (e *Env) Reactor(r Reactor)

Reactor stores a declared reactor.

func (*Env) ReactorOf

func (e *Env) ReactorOf(consumer string) (Reactor, bool)

ReactorOf returns the declared reactor named consumer.

func (*Env) Reactors

func (e *Env) Reactors() []Reactor

Reactors lists the declared reactors in declaration order.

func (*Env) RegisterWorker

func (e *Env) RegisterWorker(fn func(registry any))

RegisterWorker adds fn, called with the service's Temporal worker (worker.Registry) whenever the worker is built.

func (*Env) SetBound added in v0.6.8

func (e *Env) SetBound(hooks []string)

SetBound installs the service's hooks with a binding in force (names without the service prefix) and signals BoundChanges when it differs; nil returns to unknown.

func (*Env) SetBroker

func (e *Env) SetBroker(b Broker)

SetBroker installs the event transport; nil removes it.

func (*Env) SetCaller

func (e *Env) SetCaller(c Caller)

SetCaller installs the hook transport; nil removes it.

func (*Env) SetHookTimeout

func (e *Env) SetHookTimeout(d time.Duration)

SetHookTimeout sets the platform default deadline of a hook call; 0 or less restores DefaultHookTimeout.

func (*Env) SetPayloadCodec added in v0.6.51

func (e *Env) SetPayloadCodec(codec any)

SetPayloadCodec installs the codec of workflow payloads (an infra/temporal Codec).

func (*Env) SetSection added in v0.6.45

func (e *Env) SetSection(name string, value *anypb.Any)

SetSection sets the live value of section name; an equal value tells no one.

func (*Env) SetWorkflowClient

func (e *Env) SetWorkflowClient(fn func() (any, error))

SetWorkflowClient installs how the Temporal client is reached.

func (*Env) WorkerRegistrations

func (e *Env) WorkerRegistrations() []func(registry any)

WorkerRegistrations are the functions given to RegisterWorker.

func (*Env) WorkflowClient

func (e *Env) WorkflowClient() (any, error)

WorkflowClient is the connected Temporal client (a client.Client).

type Handler

type Handler func(ctx context.Context, in []byte) ([]byte, error)

Handler serves an activity or a reactor; payloads are encoded JSON.

type Incoming

type Incoming struct {
	ID         string
	Source     string
	Type       string
	Subject    string
	Time       time.Time
	Attempt    int
	Consumer   string
	Extensions map[string]string
}

Incoming is the metadata of the event a reactor's handler is running for; the transport puts it on the handler's context.

func IncomingOf

func IncomingOf(ctx context.Context) (Incoming, bool)

IncomingOf returns the metadata WithIncoming put on ctx; the extensions are a copy.

type Message

type Message struct {
	Event   string // full name "<service>.<Event>"
	Key     string // CloudEvents subject, optional
	ID      string // ce-id and the dedup id; empty: a new UUID
	Time    time.Time
	Payload []byte // encoded JSON
	// Extensions are CloudEvents extension attributes by name, without the
	// ce- prefix; the event package validates the names.
	Extensions map[string]string
}

Message is one event to publish.

type NonRetryableError

type NonRetryableError struct{ Err error }

NonRetryableError marks a handler error the transport must not retry: the input is wrong, retrying cannot help.

func (NonRetryableError) Error

func (e NonRetryableError) Error() string

func (NonRetryableError) Unwrap

func (e NonRetryableError) Unwrap() error

type Reactor

type Reactor struct {
	Event    string // full name "<service>.<Event>"
	Consumer string // unique within the service
	Handler  Handler
	Delivery Delivery
}

Reactor is a declared durable consumer of another service's event.

type RetryAfterError added in v0.6.0

type RetryAfterError struct {
	Err   error
	Delay time.Duration
}

RetryAfterError marks a handler error retryable no sooner than Delay.

func (RetryAfterError) Error added in v0.6.0

func (e RetryAfterError) Error() string

func (RetryAfterError) Unwrap added in v0.6.0

func (e RetryAfterError) Unwrap() error

Jump to

Keyboard shortcuts

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