display

Documentation

Overview

Package display implements the logic for displaying the status of resource operations. This includes formatting of diffs for previews, and events from updates or queries.

Index

• func ConvertEngineEvent(e engine.Event, showSecrets bool) (apitype.EngineEvent, error)
• func ConvertJSONEvent(apiEvent apitype.EngineEvent) (engine.Event, error)
• func MassageSecrets(m resource.PropertyMap, showSecrets bool) resource.PropertyMap
• func PrintObject(b *bytes.Buffer, props resource.PropertyMap, planning bool, indent int, ...)
• func PrintObjectDiff(b *bytes.Buffer, diff resource.ObjectDiff, include []resource.PropertyKey, ...)
• func PrintResourceReference(b *bytes.Buffer, resRef resource.ResourceReference, planning bool, indent int, ...)
• func PrintfWithWatchPrefix(t time.Time, resourceName string, format string, a ...interface{})
• func RenderDiffEvent(event engine.Event, seen map[resource.URN]engine.StepEventMetadata, ...) string
• func ShowDiffEvents(op string, events <-chan engine.Event, done chan<- bool, opts Options)
• func ShowEvents(op string, action apitype.UpdateKind, stack tokens.StackName, ...)
• func ShowJSONEvents(events <-chan engine.Event, done chan<- bool, opts Options)
• func ShowPreviewDigest(events <-chan engine.Event, done chan<- bool, opts Options)
• func ShowProgressEvents(op string, action apitype.UpdateKind, stack tokens.StackName, ...)
• func ShowProgressOutput(in <-chan Progress, out io.Writer, isInteractive bool)
• func ShowQueryEvents(op string, events <-chan engine.Event, done chan<- bool, opts Options)
• func ShowWatchEvents(op string, events <-chan engine.Event, done chan<- bool, opts Options)
• type DiagInfo
• type Options
  • func (opts Options) WithIsInteractive(isInteractive bool) Options
• type Progress
  • func (jm *Progress) Display(out io.Writer, termInfo terminal.Info)
• type ProgressDisplay
• type ResourceRow
• type Row
• type Type

Functions

func ConvertEngineEvent

func ConvertEngineEvent(e engine.Event, showSecrets bool) (apitype.EngineEvent, error)

ConvertEngineEvent converts a raw engine.Event into an apitype.EngineEvent used in the Pulumi REST API. Returns an error if the engine event is unknown or not in an expected format. EngineEvent.{ Sequence, Timestamp } are expected to be set by the caller.

IMPORTANT: Any resource secret data stored in the engine event will be encrypted using the blinding encrypter, and unrecoverable. So this operation is inherently lossy.

func ConvertJSONEvent

func ConvertJSONEvent(apiEvent apitype.EngineEvent) (engine.Event, error)

ConvertJSONEvent converts an apitype.EngineEvent from the Pulumi REST API into a raw engine.Event Returns an error if the engine event is unknown or not in an expected format.

IMPORTANT: Any resource secret data stored in the engine event will be encrypted using the blinding encrypter, and unrecoverable. So this operation is inherently lossy.

func MassageSecrets

func MassageSecrets(m resource.PropertyMap, showSecrets bool) resource.PropertyMap

MassageSecrets takes a property map and returns a new map by transforming each value with massagePropertyValue This allows us to serialize the resulting map using our existing serialization logic we use for deployments, to produce sane output for stackOutputs. If we did not do this, SecretValues would be serialized as objects with the signature key and value.

func PrintObject

func PrintObject(
	b *bytes.Buffer, props resource.PropertyMap, planning bool,
	indent int, op display.StepOp, prefix bool, truncateOutput bool, debug bool,
)

func PrintObjectDiff

func PrintObjectDiff(b *bytes.Buffer, diff resource.ObjectDiff, include []resource.PropertyKey,
	planning bool, indent int, summary bool, truncateOutput bool, debug bool,
)

func PrintResourceReference

func PrintResourceReference(
	b *bytes.Buffer, resRef resource.ResourceReference, planning bool,
	indent int, op display.StepOp, prefix bool, debug bool,
)

func PrintfWithWatchPrefix

func PrintfWithWatchPrefix(t time.Time, resourceName string, format string, a ...interface{})

PrintfWithWatchPrefix wraps fmt.Printf with a watch mode prefixer that adds a timestamp and resource metadata.

func RenderDiffEvent

func RenderDiffEvent(event engine.Event, seen map[resource.URN]engine.StepEventMetadata, opts Options) string

func ShowDiffEvents

func ShowDiffEvents(op string, events <-chan engine.Event, done chan<- bool, opts Options)

ShowDiffEvents displays the engine events with the diff view.

func ShowEvents

func ShowEvents(
	op string, action apitype.UpdateKind, stack tokens.StackName, proj tokens.PackageName,
	permalink string, events <-chan engine.Event, done chan<- bool, opts Options, isPreview bool,
)

ShowEvents reads events from the `events` channel until it is closed, displaying each event as it comes in. Once all events have been read from the channel and displayed, it closes the `done` channel so the caller can await all the events being written.

func ShowJSONEvents

func ShowJSONEvents(events <-chan engine.Event, done chan<- bool, opts Options)

ShowJSONEvents renders incremental engine events to stdout.

func ShowPreviewDigest

func ShowPreviewDigest(events <-chan engine.Event, done chan<- bool, opts Options)

ShowPreviewDigest renders engine events from a preview into a well-formed JSON document. Note that this does not emit events incrementally so that it can guarantee anything emitted to stdout is well-formed. This means that, if used interactively, the experience will lead to potentially very long pauses. If run in CI, it is up to the end user to ensure that output is periodically printed to prevent tools from thinking preview has hung.

func ShowProgressEvents

func ShowProgressEvents(op string, action apitype.UpdateKind, stack tokens.StackName, proj tokens.PackageName,
	permalink string, events <-chan engine.Event, done chan<- bool, opts Options, isPreview bool,
)

ShowProgressEvents displays the engine events with docker's progress view.

func ShowProgressOutput

func ShowProgressOutput(in <-chan Progress, out io.Writer, isInteractive bool)

ShowProgressOutput displays a progress stream from `in` to `out`, `isInteractive` describes if `out` is a terminal. If this is the case, it will print `\n` at the end of each line and move the cursor while displaying.

func ShowQueryEvents

func ShowQueryEvents(op string, events <-chan engine.Event,
	done chan<- bool, opts Options,
)

ShowQueryEvents displays query events on the CLI.

func ShowWatchEvents

func ShowWatchEvents(op string, events <-chan engine.Event, done chan<- bool, opts Options)

ShowWatchEvents renders incoming engine events for display in Watch Mode.

Types

type DiagInfo

type DiagInfo struct {
	ErrorCount, WarningCount, InfoCount, DebugCount int

	// The very last diagnostic event we got for this resource (regardless of severity). We'll print
	// this out in the non-interactive mode whenever we get new events. Importantly, we don't want
	// to print out the most significant diagnostic, as that means a flurry of event swill cause us
	// to keep printing out the most significant diagnostic over and over again.
	LastDiag *engine.DiagEventPayload

	// The last error we received.  If we have an error, and we're in tree-view, we'll prefer to
	// show this over the last non-error diag so that users know about something bad early on.
	LastError *engine.DiagEventPayload

	// All the diagnostic events we've heard about this resource.  We'll print the last diagnostic
	// in the status region while a resource is in progress.  At the end we'll print out all
	// diagnostics for a resource.
	//
	// Diagnostic events are bucketed by their associated stream ID (with 0 being the default
	// stream).
	StreamIDToDiagPayloads map[int32][]engine.DiagEventPayload
}

DiagInfo contains the bundle of diagnostic information for a single resource.

type Options

type Options struct {
	Color                  colors.Colorization // colorization to apply to events.
	ShowConfig             bool                // true if we should show configuration information.
	ShowPolicyRemediations bool                // true if we should show detailed policy remediations.
	ShowReplacementSteps   bool                // true to show the replacement steps in the plan.
	ShowSameResources      bool                // true to show the resources that aren't updated in addition to updates.
	ShowReads              bool                // true to show resources that are being read in
	TruncateOutput         bool                // true if we should truncate long outputs
	SuppressOutputs        bool                // true to suppress output summarization, e.g. if contains sensitive info.
	SuppressPermalink      bool                // true to suppress state permalink
	SummaryDiff            bool                // true if diff display should be summarized.
	IsInteractive          bool                // true if we should display things interactively.
	Type                   Type                // type of display (rich diff, progress, or query).
	JSONDisplay            bool                // true if we should emit the entire diff as JSON.
	EventLogPath           string              // the path to the file to use for logging events, if any.
	Debug                  bool                // true to enable debug output.
	Stdin                  io.Reader           // the reader to use for stdin. Defaults to os.Stdin if unset.
	Stdout                 io.Writer           // the writer to use for stdout. Defaults to os.Stdout if unset.
	Stderr                 io.Writer           // the writer to use for stderr. Defaults to os.Stderr if unset.
	SuppressTimings        bool                // true to suppress displaying timings of resource actions
	SuppressProgress       bool                // true to suppress displaying progress spinner.
	// contains filtered or unexported fields
}

Options controls how the output of events are rendered

func (Options) WithIsInteractive

func (opts Options) WithIsInteractive(isInteractive bool) Options

type Progress

type Progress struct {
	ID      string
	Message string
	Action  string
}

Progress describes a message we want to show in the display. There are two types of messages, simple 'Messages' which just get printed out as a single uninterpreted line, and 'Actions' which are placed and updated in the progress-grid based on their ID. Messages do not need an ID, while Actions must have an ID.

func (*Progress) Display

func (jm *Progress) Display(out io.Writer, termInfo terminal.Info)

Display displays the Progress to `out`. `termInfo` is non-nil if `out` is a terminal.

type ProgressDisplay

type ProgressDisplay struct {
	// contains filtered or unexported fields
}

ProgressDisplay organizes all the information needed for a dynamically updated "progress" view of an update.

type ResourceRow

type ResourceRow interface {
	Row

	Step() engine.StepEventMetadata
	SetStep(step engine.StepEventMetadata)
	AddOutputStep(step engine.StepEventMetadata)

	// The tick we were on when we created this row.  Purely used for generating an
	// ellipses to show progress for in-flight resources.
	Tick() int

	IsDone() bool

	SetFailed()

	DiagInfo() *DiagInfo
	PolicyPayloads() []engine.PolicyViolationEventPayload
	PolicyRemediationPayloads() []engine.PolicyRemediationEventPayload

	RecordDiagEvent(diagEvent engine.Event)
	RecordPolicyViolationEvent(diagEvent engine.Event)
	RecordPolicyRemediationEvent(diagEvent engine.Event)
}

type Row

type Row interface {
	DisplayOrderIndex() int
	SetDisplayOrderIndex(index int)

	ColorizedColumns() []string
	ColorizedSuffix() string

	HideRowIfUnnecessary() bool
	SetHideRowIfUnnecessary(value bool)
}

type Type

type Type int

Type of output to display.

const (
	// DisplayProgress displays an update as it progresses.
	DisplayProgress Type = iota
	// DisplayDiff displays a rich diff.
	DisplayDiff
	// DisplayQuery displays query output.
	DisplayQuery
	// DisplayWatch displays watch output.
	DisplayWatch
)