| // Copyright IBM Corp. 2014, 2026 | |
| // SPDX-License-Identifier: BUSL-1.1 | |
| package hooks | |
| import ( | |
| "context" | |
| ) | |
| // BeginFunc is the signature of a callback for a hook which begins a | |
| // series of related events. | |
| // | |
| // The given context is guaranteed to preserve the values from whichever | |
| // context was passed to the top-level [stackruntime.Plan] or | |
| // [stackruntime.Apply] call. | |
| // | |
| // The hook callback may return any value, and that value will be passed | |
| // verbatim to the corresponding [MoreFunc]. A typical use for that | |
| // extra arbitrary value would be to begin a tracing span in "Begin" and then | |
| // either adding events to or ending that span in "More". | |
| // | |
| // If a particular "begin" hook isn't implemented but one of its "more" hooks | |
| // is implemented then the extra tracking value will always be nil when | |
| // the first "more" hook runs. | |
| type BeginFunc[Msg any] func(context.Context, Msg) any | |
| // MoreFunc is the signature of a callback for a hook which reports | |
| // ongoing process or completion of a multi-step process previously reported | |
| // using a [HookFuncBegin] callback. | |
| // | |
| // The given context is guaranteed to preserve the values from whichever | |
| // context was passed to the top-level [stackruntime.Plan] or | |
| // [stackruntime.Apply] call. | |
| // | |
| // The hook callback recieves an additional argument which is guaranteed to be | |
| // the same value returned from the corresponding [BeginFunc]. See | |
| // [BeginFunc]'s documentation for more information. | |
| // | |
| // If the overall hooks also defines a [ContextAttachFunc] then a context | |
| // descended from its result will be passed into the [MoreFunc] for any events | |
| // related to the operation previously signalled by [BeginFunc]. | |
| // | |
| // The hook callback may optionally return a new arbitrary tracking value. If | |
| // the return value is non-nil then it replaces the original value for future | |
| // hooks belonging to the same context. If it's nil then the previous value | |
| // is retained. | |
| // | |
| // MoreFunc is also sometimes used in isolation for one-shot events, | |
| // in which case the extra value will always be nil unless stated otherwise | |
| // in a particular hook's documentation. | |
| type MoreFunc[Msg any] func(context.Context, any, Msg) any | |
| // ContextAttachFunc is the signature of an optional callback that knows | |
| // how to bind an arbitrary tracking value previously returned by a [BeginFunc] | |
| // to the values of a [context.Context] so that the tracking value can be | |
| // made available to downstream operations outside the direct scope of the | |
| // stack runtime, such as external HTTP requests. | |
| // | |
| // Use this if your [BeginFunc]s return something that should be visible to | |
| // all context-aware operations within the scope of the operation that was | |
| // begun. | |
| // | |
| // If you use this then your related [MoreFunc] callbacks for the same event | |
| // should always return nil, because there is no way to mutate the context | |
| // with a new tracking value after the fact. | |
| type ContextAttachFunc func(parent context.Context, tracking any) context.Context | |
| // SingleFunc is the signature of a callback for a hook which operates in | |
| // isolation, and has no related or enclosed events. | |
| // | |
| // The given context is guaranteed to preserve the values from whichever | |
| // context was passed to the top-level [stackruntime.Plan] or | |
| // [stackruntime.Apply] call. | |
| type SingleFunc[Msg any] func(context.Context, Msg) |