// Copyright (c) HashiCorp, Inc.
// 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)