wire

package
v0.6.51 Latest Latest
Warning

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

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

Documentation

Overview

Package wire is the platform's wire contract as names (design §8, §9, §17): the NATS objects, headers and metadata of events, and the Temporal names of hooks, activities and schedules. The SDK (pkg/backplane/...) and the server (internal/...) both derive their names here, so the two sides of the contract cannot drift. It is not public API: services do not import it (a service reaching for native clients reads the names in the design), and it depends on nothing but the standard library.

Index

Constants

View Source
const (
	// BindingWorkflow runs one binding (a hook call) or one rule (an
	// event) on backplane's own task queue. The version is in the name: a
	// change that is not replay-compatible is a new name (.v2), registered
	// next to the old one until runs of the old one are gone.
	BindingWorkflow = "backplane.Binding.v1"

	// BindingRunPrefix starts the id of a hook call's run:
	// binding/<hook>/<Nexus request id>.
	BindingRunPrefix = "binding/"
	// TestRunPrefix starts the id of a console test run:
	// test/<hook>/<uuid>.
	TestRunPrefix = "test/"

	// Application error types of a failed run.
	//
	// StepFailedType: a step's activity (or child workflow) failed after
	// its retries; the message is "step <name>: <service>.<Activity>:
	// <handler's message>".
	StepFailedType = "backplane.StepFailed"
	// TransformFailedType: an expression failed on the run's values
	// ("transform failed at step render (input.to): ..."), or the program
	// or its input could not be read.
	TransformFailedType = "backplane.TransformFailed"

	// MemoBinding is the memo of a run: what ran, "<hook>@<version>"
	// ("@draft" for an unsaved definition) or "rule:<id>@<version>".
	MemoBinding = "backplane.binding"
)

Names of backplane's executor (design §7.2, §8.1, §17): the workflow that runs a binding or a rule, its ids and its failures.

View Source
const (
	// DirectRunPrefix starts the id of a direct run: direct/binding/<hook>/<id>,
	// direct/rule/<rule id>/<ce-id>, direct/test/<hook or rule>/<uuid>.
	DirectRunPrefix = "direct/"
	// DirectWorkflowType is what a direct run reports as its workflow type.
	DirectWorkflowType = "backplane.Direct.v1"
	// DirectQueue is what a direct run reports as its task queue.
	DirectQueue = "direct"
)

Names of the direct runtime (internal/direct): runs in backplane's own process, recorded in PostgreSQL.

View Source
const (
	HeaderSpecVersion = "ce-specversion"
	HeaderID          = "ce-id"
	HeaderSource      = "ce-source"
	HeaderType        = "ce-type"
	HeaderTime        = "ce-time"
	HeaderSubject     = "ce-subject"
	HeaderContentType = "ce-datacontenttype"
	HeaderInstance    = "ce-instance"
	HeaderVersion     = "ce-version"
	// HeaderMIME is the binding's content type header.
	HeaderMIME = "content-type"
	// CEPrefix starts every CloudEvents header.
	CEPrefix = "ce-"
	// SpecVersion is the CloudEvents version events carry.
	SpecVersion = "1.0"
	// ContentJSON is the content type of every payload.
	ContentJSON = "application/json"

	// HeaderError and HeaderConsumer are added to a dead letter: the last
	// handler error and the reactor that gave up.
	HeaderError    = "bp-error"
	HeaderConsumer = "bp-consumer"
	// HeaderDelivered: deliveries before the message was dead-lettered.
	HeaderDelivered = "bp-delivered"
	// HeaderRedriven marks a dead letter published back for its reactor:
	// the dead letter's sequence in the dead-letter stream.
	HeaderRedriven = "bp-redriven"
	// HeaderTest is the CloudEvents extension (ce-bptest) of an event the
	// console published by hand.
	HeaderTest = "ce-bptest"
)

CloudEvents over the NATS binding (binary mode): attributes and extensions are ce-* headers, the payload is the data.

View Source
const (
	MetaService  = "bp.service"
	MetaBy       = "bp.ensured-by"
	MetaKind     = "bp.kind"
	MetaConsumer = "bp.consumer"
	MetaEvent    = "bp.event"
	ByEmitter    = "emitter"
	BySubscriber = "subscriber"
	KindEvents   = "events"
	KindDead     = "dead-letters"
)

Metadata of streams and consumers.

View Source
const (
	// CallHookWorkflow runs one hook call raised outside workflow code, on
	// the hooks queue of the caller.
	CallHookWorkflow = "backplane.CallHook.v1"
	// HooksSuffix: the Nexus service of <service>'s hooks is
	// <service>.Hooks on endpoint <service>.
	HooksSuffix = ".Hooks"

	// Application error types.
	NoBindingType    = "backplane.NoBinding"
	HookFailedType   = "backplane.HookFailed"
	TimeoutType      = "backplane.Timeout"
	NonRetryableType = "backplane.NonRetryable"

	// MemoSource names who raised a hook call: <service>/<instance>, or
	// console:<session> for a run the console started.
	MemoSource = "source"
	// Search attributes of a hook call, when the namespace has them.
	AttrService = "BpService"
	AttrHook    = "BpHook"

	// MemoService is the owning service of a schedule the SDK manages;
	// MemoFingerprint, on its workflow action, the declaration's hash.
	MemoService     = "backplane.service"
	MemoFingerprint = "backplane.schedule"
	// MemoWiring marks a schedule a wiring file manages: on the schedule
	// (set at creation) and on its workflow action, the file's name.
	MemoWiring = "backplane.wiring"
)

Temporal names (design §7.2, §9, §17).

View Source
const AllEvents = "*"

AllEvents is the reactor pattern of every service's events; "<service>.*" is the pattern of one service's.

View Source
const (

	// RedriveToken is the subject token of redriven dead letters inside a
	// source stream: bp.<source>._redrive.<subscriber>.<consumer>. Token
	// never produces it (an escape is _ and two upper-case hex digits), so
	// it cannot collide with an event.
	RedriveToken = "_redrive"
)

Names of the NATS objects. Service, event and consumer names become NATS name and subject tokens through Token, so any name maps to valid, distinct NATS names; the platform's own names ([a-z0-9-] services, CamelCase events) pass through unchanged.

Variables

View Source
var ErrEventName = errors.New("event name must be <service>.<Event>")

ErrEventName: an event name is not "<service>.<Event>".

Functions

func BindingRunHook

func BindingRunHook(workflowID string) (string, bool, bool)

BindingRunHook is the hook of a run id made by BindingRunID or TestRunID, and whether it is a test run; ok is false for any other id.

func BindingRunID

func BindingRunID(hook, requestID string) string

BindingRunID is the run of a hook call: the Nexus request id makes a retried start of the same operation the same run.

func DLQStreamName

func DLQStreamName(subscriber string) string

DLQStreamName of the dead letters of subscriber's reactors: bp_dlq_<subscriber>.

func DLQStreamSubjects

func DLQStreamSubjects(subscriber string) string

DLQStreamSubjects of subscriber's dead-letter stream: bp.dlq.<subscriber>.>.

func DLQSubject

func DLQSubject(subscriber, consumer string) string

DLQSubject of the dead letters of one reactor: bp.dlq.<subscriber>.<consumer>.

func DirectRunID added in v0.3.0

func DirectRunID(hook, id string) string

DirectRunID is the id of a direct run of a hook call.

func DirectTestRunID added in v0.3.0

func DirectTestRunID(source, id string) string

DirectTestRunID is the id of a direct console test run of hook's binding or of a rule ("rule/<id>").

func Durable

func Durable(subscriber, consumer string) string

Durable name of subscriber's reactor consumer: <subscriber>__<consumer>, both escaped; unique because escaped tokens never contain "__". A name longer than maxName is cut and ends with a hash of the full name.

func EventOfSubject

func EventOfSubject(subject string) (string, bool)

EventOfSubject is the full event name "<service>.<Event>" of an event subject bp.<service>.<Event>; ok is false for any other subject (a redriven dead letter, a foreign subject).

func EventsSubject added in v0.6.47

func EventsSubject(service string) string

EventsSubject of every event of service: bp.<service>.*. Redrives (bp.<service>._redrive.…) have more tokens and do not match.

func HooksQueue

func HooksQueue(service string) string

HooksQueue is the queue of service's hook calls from outside workflow code.

func IsDirectRun added in v0.3.0

func IsDirectRun(workflowID string) bool

IsDirectRun reports whether workflowID names a direct run.

func IsPattern added in v0.6.47

func IsPattern(event string) bool

IsPattern reports whether a reactor's event is a pattern: AllEvents or "<service>.*".

func NexusService

func NexusService(service string) string

NexusService of service's hooks: <service>.Hooks on endpoint <service>.

func Queue

func Queue(service string) string

Queue is the task queue of service: its name.

func RedriveSubject

func RedriveSubject(source, subscriber, consumer string) string

RedriveSubject is where dead letters of subscriber's reactor consumer are published back for that reactor alone: in the source service's stream, bp.<source>._redrive.<subscriber>.<consumer>. The reactor's consumer filters on it next to its event's subject; no other consumer matches it.

func ScheduleID

func ScheduleID(service, name string) string

ScheduleID is the id of service's schedule name; every schedule of the service has the prefix "<service>/".

func ServiceOfStream added in v0.6.47

func ServiceOfStream(name string) (string, bool)

ServiceOfStream is the service of an event stream bp_<service>; ok is false for dead-letter and foreign streams.

func SplitEvent

func SplitEvent(full string) (string, string, error)

SplitEvent splits a full event name "<service>.<Event>" at its first dot.

func StreamName

func StreamName(service string) string

StreamName of service's events: bp_<service>.

func StreamSubjects

func StreamSubjects(service string) string

StreamSubjects of service's stream: bp.<service>.>.

func Subject

func Subject(service, name string) string

Subject of service's event name: bp.<service>.<Event>.

func TestRunID

func TestRunID(hook, id string) string

TestRunID is a console test run of hook's binding.

func Token

func Token(s string) string

Token escapes s into one NATS token: ASCII letters, digits and '-' stay, every other byte becomes _XX (upper-case hex). The mapping is injective, and an escaped token never contains "__".

func Untoken

func Untoken(s string) (string, bool)

Untoken reverses Token; ok is false when s is not an escaped token.

Types

This section is empty.

Jump to

Keyboard shortcuts

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