env

package
v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Oct 15, 2026 License: MIT Imports: 9 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.

func (*Env) ActivityHandler

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

ActivityHandler returns the handler of a declared activity.

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) 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) 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) 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) 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