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