mirror of
https://github.com/hashicorp/terraform.git
synced 2026-02-03 20:50:59 -05:00
49 lines
2.1 KiB
Go
49 lines
2.1 KiB
Go
// 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)
|
|
}
|