hook

package
v0.6.31 Latest Latest
Warning

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

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

Documentation

Overview

Package hook declares operations a service calls without implementing them ("нужно"). Who answers is a binding in backplane; the call is a Temporal Nexus operation <Name> of service <service>.Hooks on endpoint <service>. Call works from any Go code; workflows.CallHook is the same call from workflow code. Without Temporal Call returns ErrUnavailable.

Inputs and outputs evolve additively: a reader ignores fields it does not know (protojson with DiscardUnknown), a missing field reads as its zero value, and renaming a field means adding a new one and keeping the old until every reader uses the new.

price := hook.Declare[Quote, Price](root, "Price", hook.DefaultTimeout(5*time.Second),
    hook.Describe("price of a quote"))
out, err := price.Call(ctx, q, hook.Key(q.ID), hook.Timeout(2*time.Second))

Index

Constants

This section is empty.

Variables

View Source
var (
	// ErrUnavailable is returned while no transport carries hook calls.
	ErrUnavailable = env.ErrUnavailable
	// ErrNoBinding: backplane has no binding for the hook.
	ErrNoBinding = env.ErrNoBinding
)

Functions

This section is empty.

Types

type CallOption

type CallOption interface {
	// contains filtered or unexported methods
}

CallOption tunes one call.

func Key

func Key(k string) CallOption

Key makes the call idempotent under k: calls with the same key run the binding once. A call while the first runs waits for it; a call after it succeeded gets its result (the input of the later call is not looked at); a call after it failed runs again. The workflow id is hook/<service>/<Name>/<k>; Temporal remembers it for the namespace's retention. workflows.CallHook ignores the key: a workflow is durable already.

func Timeout

func Timeout(d time.Duration) CallOption

Timeout is the call's deadline, over the declared DefaultTimeout; the context's own deadline still applies when earlier. d <= 0 is ignored.

type Option

type Option interface {
	// contains filtered or unexported methods
}

Option configures Declare.

func DefaultTimeout

func DefaultTimeout(d time.Duration) Option

DefaultTimeout is the deadline of a call that sets none with Timeout; without it the platform default applies (backplane.temporal.hook_timeout, 30s). The manifest carries it for the console. d <= 0 is ignored.

func Describe

func Describe(s string) Option

Describe is the hook's description for the console.

func Required

func Required() Option

Required marks the hook as one the service cannot work without.

type Ref

type Ref[Req, Res any] struct {
	// contains filtered or unexported fields
}

Ref is a declared hook. The zero Ref is undeclared: Call fails.

func Declare

func Declare[Req, Res any](scope deps.Scope, name string, opts ...Option) Ref[Req, Res]

Declare registers a hook in the manifest. name is CamelCase ([A-Z][A-Za-z0-9]*), anything else panics. Schemas are reflected from Req and Res when possible; without them the payload is plain JSON (protojson for proto messages).

func (Ref[Req, Res]) BindingChanges added in v0.6.8

func (r Ref[Req, Res]) BindingChanges(ctx context.Context) <-chan struct{}

BindingChanges signals after every change of the service's bound hooks until ctx ends, one pending signal at most: re-read Bound of the hooks that matter.

func (Ref[Req, Res]) Bound added in v0.6.8

func (r Ref[Req, Res]) Bound() bool

Bound reports whether the hook may have a binding in force: false only when backplane's published set of this service's bound hooks is known and lacks it, so Call would end in ErrNoBinding. A service skips work it would do only for a bound hook (configuring a webhook, building a payload); the set follows saves in Wiring within seconds. Unknown — no Consul, not watched yet — counts as bound.

func (Ref[Req, Res]) Call

func (r Ref[Req, Res]) Call(ctx context.Context, in Req, opts ...CallOption) (Res, error)

Call raises the hook and waits for the bound implementation. The deadline is the earliest of ctx's and the call's own: Timeout, else the declared DefaultTimeout, else — when ctx has none — the platform default. Outside workflow code only: in a workflow use workflows.CallHook.

func (Ref[Req, Res]) CallTimeout

func (r Ref[Req, Res]) CallTimeout(opts ...CallOption) time.Duration

CallTimeout resolves the declared, per-call and transport default timeout. Native workflow adapters use it without importing a backend into hook.

func (Ref[Req, Res]) Name

func (r Ref[Req, Res]) Name() string

Name is the full hook name <service>.<Name>.

Jump to

Keyboard shortcuts

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