| // Copyright IBM Corp. 2014, 2026 | |
| // SPDX-License-Identifier: BUSL-1.1 | |
| package stackruntime | |
| import ( | |
| "context" | |
| "github.com/hashicorp/terraform/internal/stacks/stackruntime/internal/stackeval" | |
| ) | |
| // This file exposes a small part of the API surface of "stackeval" to external | |
| // callers. We need to orient it this way because package stackeval cannot | |
| // itself depend on stackruntime. | |
| // Hooks is an optional mechanism for callers to get streaming notifications | |
| // of various kinds of events that can occur during plan and apply operations. | |
| // | |
| // To use this, construct a Hooks object and then wrap it in a [context.Context] | |
| // using the [ContextWithHooks] function, and then use that context (or another | |
| // context derived from it that inherits the values) when calling into | |
| // [Plan] or [Apply]. | |
| // | |
| // All of the callback fields in Hooks are optional and may be left as nil | |
| // if the caller has no interest in a particular event. | |
| // | |
| // The events exposed by Hooks are intended for ancillary use-cases like | |
| // realtime UI updates, and so a caller that is only concerned with the primary | |
| // results of an operation can safely ignore this and just consume the direct | |
| // results from the [Plan] and [Apply] functions as described in their | |
| // own documentation. | |
| // | |
| // Hook functions should typically run to completion quickly to avoid noticable | |
| // delays to the progress of the operation being monitored. In particular, | |
| // if a hook implementation is sending data to a network service then the | |
| // actual transmission of the events should be decoupled from the notifications, | |
| // such as by using a buffered channel as a FIFO queue and ideally transmitting | |
| // the events in batches where possible. | |
| type Hooks = stackeval.Hooks | |
| // ContextWithHooks returns a context that carries the given [Hooks] as | |
| // one of its values. | |
| // | |
| // Pass the resulting context -- or a descendant that preserves the values -- | |
| // to [Plan] or [Apply] to be notified when the different hookable events | |
| // occur during that plan or apply process. | |
| func ContextWithHooks(parent context.Context, hooks *Hooks) context.Context { | |
| return stackeval.ContextWithHooks(parent, hooks) | |
| } |