Documentation
¶
Overview ¶
Package catalog lets workflows label themselves, and lets applications find workflows by label.
A label is a string pair such as lifecycle=install, stored in the entry metadata under the reserved prefix "label:". The engine does not interpret labels; this package does.
Label rules:
- One value per label. Passing the same label option twice keeps the last value.
- Labels are set when the workflow is registered and cannot change afterwards, because metadata values never change.
- Label names use lowercase letters, digits, dots and dashes, and start and end with a letter or digit.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrMetadataUnsupported = errors.New("workflow entry does not support metadata")
ErrMetadataUnsupported is returned by Register when labels were requested but the entry does not support metadata. The workflow stays registered without labels.
Functions ¶
func FindByLifecycle ¶ added in v0.46.0
func FindByLifecycle(engine workflow.Engine, lifecycle Lifecycle) []workflow.Identifier
FindByLifecycle returns the IDs of the workflows of the engine that are labeled lifecycle=<lifecycle>, sorted by ID.
The result is a snapshot. Entries without metadata support are skipped. A workflow that is removed or replaced between listing and lookup is skipped or seen as its current entry; it never causes a panic. The engine is only used through its workflow.Engine methods, so wrapped engines work.
func Register ¶
func Register(engine workflow.Engine, id workflow.Identifier, config workflow.ConfigurationOptions, callback workflow.Callback, opts ...RegisterOption) (workflow.Entry, error)
Register registers a workflow with the engine and labels it with the given options.
Without options it behaves exactly like engine.Register. An error from engine.Register is returned unchanged, together with the entry that engine.Register returned, which is nil. If the entry does not support metadata, Register returns the entry together with ErrMetadataUnsupported; the workflow stays registered without labels.
Types ¶
type PanicError ¶ added in v0.47.0
type PanicError struct {
Value any
}
PanicError is the error of a lifecycle step that panicked. Value is the value the step panicked with.
Its text reports only the type of Value, because a panic value can carry secrets. Value itself is not redacted.
func (*PanicError) Error ¶ added in v0.47.0
func (e *PanicError) Error() string
type RegisterOption ¶
RegisterOption sets a label on a workflow when it is registered.
func WithLifecycle ¶
func WithLifecycle(lifecycle Lifecycle) RegisterOption
WithLifecycle labels the workflow with lifecycle=<lifecycle>.
type StepFailure ¶ added in v0.47.0
type StepFailure struct {
ID workflow.Identifier
Err error
}
StepFailure is a lifecycle step that did not succeed: its ID and its error.
Err is the original error of the step, so errors.Is and errors.As work on it. A step that panicked has a *PanicError. A step that did not run has an error that wraps the context error. The text of Err is not redacted: the error of a step can contain any value the step received, such as a token. Callers must redact the text of Err before they show it to a user, write it to a log or send it to analytics.
func RunLifecycle ¶ added in v0.47.0
func RunLifecycle(ic workflow.InvocationContext, lifecycle Lifecycle) []StepFailure
RunLifecycle runs every workflow labeled with the lifecycle as a step, in ID order, and returns the steps that failed.
Steps run with their defaults: no input is passed to them. A step that returns an error or panics is recorded, and the next step still runs. The output data of a step is dropped. The calling workflow is skipped, so it never runs as a step. When the context of the invocation is canceled, the loop stops, and every step that did not run is recorded with an error that wraps the context error. Progress is reported through the user interface of the invocation, which shows nothing without a terminal. RunLifecycle never writes the configuration of the engine.
A step can invoke the workflow that runs the lifecycle. The steps run in the context of the step, which marks the lifecycle as running. A nested RunLifecycle for a lifecycle that is already running in its invocation chain does not run the steps again, and returns nil. Independent runs do not affect each other.
It returns nil when there are no steps or when every step succeeded.
Source Files