pulumi/sdk/go/common/util/result/result.go

205 lines
6.8 KiB
Go
Raw Normal View History

Support bailing from RunFunc (#13804) **Background** The result.Result type is used by our CLI implementation to communicate how we want to exit the program. Most `result.Result` values (built from errors with `result.FromError`) cause the program to print the message to stderr and exit the program with exit code -1. The exception is `result.Bail()`, which indicates that we've already printed the error message, and we simply need to `exit(-1)` now. Our CLI command implementation use `cmdutil.RunResultFunc` which takes a `func(...) result.Result` to implement this logic. `cmdutil` additionally includes a `cmdutil.RunFunc` which takes a `func(...) error` and wraps it in `RunResultFunc`, relying on `result.FromError` for the conversion: func RunFunc(run func(...) error) func(...) { return RunResultFunc(func(...) result.Result { if err := run(...); err != nil { return result.FromError(err) } return nil }) } **Problem** In CLI contexts where we're using an `error`, and we want to print an error message to the user and exit, it's desirable to use diag.Sink to print the message to the user with the appropriate level (error, warning, etc.) and exit without printing anything else. However, the only way to do that currently is by converting that function to return `result.Result`, turn all error returns to `result.FromError`, and then return `result.Bail()`. **Solution** This change introduces a `result.BailError` error that gets converted into a `result.Bail()` when it passes through `result.FromError`. It allows commands implementations that use `error` to continue returning errors and still provide an ideal CLI experience. It relies on `errors.As` for matching, so even if an intermediate layer wraps the error with `fmt.Errorf("..: %w", ErrBail)`, we'll recognize the request to bail. BailError keep track of the internal error that triggered it, which (when everything is moved off of result and onto error) means we'll still be able to see the internal errors that triggered a bail during debugging. Currently debugging engine tests is pretty horrible because you often just get back a `result.Result{err:nil}` with no information where in the engine stack that came from. **Testing** Besides unit tests, this includes an end-to-end test for using RunResultFunc with a bail error. The test operates by putting the mock behavior in a fake test, and re-running the test binary to execute *just that test*. **Demonstration** This change also ports the following commands to use BailError: cancel, convert, env, policy rm, stack rm. These command implementations are simple and were able to switch easily, without bubbling into a change to a bunch of other code.
2023-08-29 07:43:40 +00:00
// Copyright 2016-2023, Pulumi Corporation.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package result
import (
"errors"
"fmt"
Support bailing from RunFunc (#13804) **Background** The result.Result type is used by our CLI implementation to communicate how we want to exit the program. Most `result.Result` values (built from errors with `result.FromError`) cause the program to print the message to stderr and exit the program with exit code -1. The exception is `result.Bail()`, which indicates that we've already printed the error message, and we simply need to `exit(-1)` now. Our CLI command implementation use `cmdutil.RunResultFunc` which takes a `func(...) result.Result` to implement this logic. `cmdutil` additionally includes a `cmdutil.RunFunc` which takes a `func(...) error` and wraps it in `RunResultFunc`, relying on `result.FromError` for the conversion: func RunFunc(run func(...) error) func(...) { return RunResultFunc(func(...) result.Result { if err := run(...); err != nil { return result.FromError(err) } return nil }) } **Problem** In CLI contexts where we're using an `error`, and we want to print an error message to the user and exit, it's desirable to use diag.Sink to print the message to the user with the appropriate level (error, warning, etc.) and exit without printing anything else. However, the only way to do that currently is by converting that function to return `result.Result`, turn all error returns to `result.FromError`, and then return `result.Bail()`. **Solution** This change introduces a `result.BailError` error that gets converted into a `result.Bail()` when it passes through `result.FromError`. It allows commands implementations that use `error` to continue returning errors and still provide an ideal CLI experience. It relies on `errors.As` for matching, so even if an intermediate layer wraps the error with `fmt.Errorf("..: %w", ErrBail)`, we'll recognize the request to bail. BailError keep track of the internal error that triggered it, which (when everything is moved off of result and onto error) means we'll still be able to see the internal errors that triggered a bail during debugging. Currently debugging engine tests is pretty horrible because you often just get back a `result.Result{err:nil}` with no information where in the engine stack that came from. **Testing** Besides unit tests, this includes an end-to-end test for using RunResultFunc with a bail error. The test operates by putting the mock behavior in a fake test, and re-running the test binary to execute *just that test*. **Demonstration** This change also ports the following commands to use BailError: cancel, convert, env, policy rm, stack rm. These command implementations are simple and were able to switch easily, without bubbling into a change to a bunch of other code.
2023-08-29 07:43:40 +00:00
"io"
"github.com/hashicorp/go-multierror"
Support bailing from RunFunc (#13804) **Background** The result.Result type is used by our CLI implementation to communicate how we want to exit the program. Most `result.Result` values (built from errors with `result.FromError`) cause the program to print the message to stderr and exit the program with exit code -1. The exception is `result.Bail()`, which indicates that we've already printed the error message, and we simply need to `exit(-1)` now. Our CLI command implementation use `cmdutil.RunResultFunc` which takes a `func(...) result.Result` to implement this logic. `cmdutil` additionally includes a `cmdutil.RunFunc` which takes a `func(...) error` and wraps it in `RunResultFunc`, relying on `result.FromError` for the conversion: func RunFunc(run func(...) error) func(...) { return RunResultFunc(func(...) result.Result { if err := run(...); err != nil { return result.FromError(err) } return nil }) } **Problem** In CLI contexts where we're using an `error`, and we want to print an error message to the user and exit, it's desirable to use diag.Sink to print the message to the user with the appropriate level (error, warning, etc.) and exit without printing anything else. However, the only way to do that currently is by converting that function to return `result.Result`, turn all error returns to `result.FromError`, and then return `result.Bail()`. **Solution** This change introduces a `result.BailError` error that gets converted into a `result.Bail()` when it passes through `result.FromError`. It allows commands implementations that use `error` to continue returning errors and still provide an ideal CLI experience. It relies on `errors.As` for matching, so even if an intermediate layer wraps the error with `fmt.Errorf("..: %w", ErrBail)`, we'll recognize the request to bail. BailError keep track of the internal error that triggered it, which (when everything is moved off of result and onto error) means we'll still be able to see the internal errors that triggered a bail during debugging. Currently debugging engine tests is pretty horrible because you often just get back a `result.Result{err:nil}` with no information where in the engine stack that came from. **Testing** Besides unit tests, this includes an end-to-end test for using RunResultFunc with a bail error. The test operates by putting the mock behavior in a fake test, and re-running the test binary to execute *just that test*. **Demonstration** This change also ports the following commands to use BailError: cancel, convert, env, policy rm, stack rm. These command implementations are simple and were able to switch easily, without bubbling into a change to a bunch of other code.
2023-08-29 07:43:40 +00:00
"github.com/pulumi/pulumi/sdk/v3/go/common/util/contract"
)
Support bailing from RunFunc (#13804) **Background** The result.Result type is used by our CLI implementation to communicate how we want to exit the program. Most `result.Result` values (built from errors with `result.FromError`) cause the program to print the message to stderr and exit the program with exit code -1. The exception is `result.Bail()`, which indicates that we've already printed the error message, and we simply need to `exit(-1)` now. Our CLI command implementation use `cmdutil.RunResultFunc` which takes a `func(...) result.Result` to implement this logic. `cmdutil` additionally includes a `cmdutil.RunFunc` which takes a `func(...) error` and wraps it in `RunResultFunc`, relying on `result.FromError` for the conversion: func RunFunc(run func(...) error) func(...) { return RunResultFunc(func(...) result.Result { if err := run(...); err != nil { return result.FromError(err) } return nil }) } **Problem** In CLI contexts where we're using an `error`, and we want to print an error message to the user and exit, it's desirable to use diag.Sink to print the message to the user with the appropriate level (error, warning, etc.) and exit without printing anything else. However, the only way to do that currently is by converting that function to return `result.Result`, turn all error returns to `result.FromError`, and then return `result.Bail()`. **Solution** This change introduces a `result.BailError` error that gets converted into a `result.Bail()` when it passes through `result.FromError`. It allows commands implementations that use `error` to continue returning errors and still provide an ideal CLI experience. It relies on `errors.As` for matching, so even if an intermediate layer wraps the error with `fmt.Errorf("..: %w", ErrBail)`, we'll recognize the request to bail. BailError keep track of the internal error that triggered it, which (when everything is moved off of result and onto error) means we'll still be able to see the internal errors that triggered a bail during debugging. Currently debugging engine tests is pretty horrible because you often just get back a `result.Result{err:nil}` with no information where in the engine stack that came from. **Testing** Besides unit tests, this includes an end-to-end test for using RunResultFunc with a bail error. The test operates by putting the mock behavior in a fake test, and re-running the test binary to execute *just that test*. **Demonstration** This change also ports the following commands to use BailError: cancel, convert, env, policy rm, stack rm. These command implementations are simple and were able to switch easily, without bubbling into a change to a bunch of other code.
2023-08-29 07:43:40 +00:00
type bailError struct {
err error
}
// BailError is the replacement for Result now that Go supports wrapping errors. It is used to indicate that
// a computation failed, but that it failed gracefully, i.e. it is not a bug in Pulumi. BailError implements
// the error interface but will prefix it's error string with BAIL, which if ever seen in user facing messages
// indicates that a check for bailing was missed. It also blocks `Unwrap` calls, instead to get access to the
// inner error use the `IsBail` function.
func BailError(err error) error {
contract.Requiref(err != nil, "err", "must not be nil")
return &bailError{err: err}
}
func (b *bailError) Error() string {
return fmt.Sprintf("BAIL: %v", b.err)
}
// BailErrorf is a helper for BailError(fmt.Errorf(...)).
func BailErrorf(format string, args ...interface{}) error {
return BailError(fmt.Errorf(format, args...))
}
// FprintBailf writes a formatted string to the given writer and returns a BailError with the same message.
func FprintBailf(w io.Writer, msg string, args ...any) error {
msg = fmt.Sprintf(msg, args...)
fmt.Fprintln(w, msg)
return BailError(errors.New(msg))
}
// IsBail reports whether any error in err's tree is a `BailError`.
func IsBail(err error) bool {
if err == nil {
return false
}
var bail *bailError
ok := errors.As(err, &bail)
return ok
}
// Result represents the result of a computation that can fail. The Result type revolves around two
// notions of failure:
//
// 1. Computations can fail, but they can fail gracefully. Computations that fail gracefully do so
// by logging a diagnostic and returning a non-nil "bail" result.
//
// 2. Computations can fail due to bugs in Pulumi. Computations that fail in this manner do so by
// constructing a Result using the `Error`, `Errorf`, or `FromError` constructor functions.
//
// Result is an interface so that it can be nullable. A function returning a pointer Result has the
// following semantics:
//
2022-09-14 02:12:02 +00:00
// - If the result is `nil`, the caller should proceed. The callee believes
// that the overarching plan can still continue, even if it logged
// diagnostics.
//
2022-09-14 02:12:02 +00:00
// - If the result is non-nil, the caller should not proceed. Most often, the
// caller should return this Result to its caller.
//
// At the highest level, when a function wishes to return only an `error`, the `Error` member
// function can be used to turn a nullable `Result` into an `error`.
type Result interface {
Error() error
IsBail() bool
}
type simpleResult struct {
err error
}
func (r *simpleResult) Error() error { return r.err }
func (r *simpleResult) IsBail() bool { return r.err == nil }
func (r *simpleResult) String() string {
if r.err == nil {
return "Bail"
}
return fmt.Sprintf("Error: %s", r.err)
}
all: Reformat with gofumpt Per team discussion, switching to gofumpt. [gofumpt][1] is an alternative, stricter alternative to gofmt. It addresses other stylistic concerns that gofmt doesn't yet cover. [1]: https://github.com/mvdan/gofumpt See the full list of [Added rules][2], but it includes: - Dropping empty lines around function bodies - Dropping unnecessary variable grouping when there's only one variable - Ensuring an empty line between multi-line functions - simplification (`-s` in gofmt) is always enabled - Ensuring multi-line function signatures end with `) {` on a separate line. [2]: https://github.com/mvdan/gofumpt#Added-rules gofumpt is stricter, but there's no lock-in. All gofumpt output is valid gofmt output, so if we decide we don't like it, it's easy to switch back without any code changes. gofumpt support is built into the tooling we use for development so this won't change development workflows. - golangci-lint includes a gofumpt check (enabled in this PR) - gopls, the LSP for Go, includes a gofumpt option (see [installation instrutions][3]) [3]: https://github.com/mvdan/gofumpt#installation This change was generated by running: ```bash gofumpt -w $(rg --files -g '*.go' | rg -v testdata | rg -v compilation_error) ``` The following files were manually tweaked afterwards: - pkg/cmd/pulumi/stack_change_secrets_provider.go: one of the lines overflowed and had comments in an inconvenient place - pkg/cmd/pulumi/destroy.go: `var x T = y` where `T` wasn't necessary - pkg/cmd/pulumi/policy_new.go: long line because of error message - pkg/backend/snapshot_test.go: long line trying to assign three variables in the same assignment I have included mention of gofumpt in the CONTRIBUTING.md.
2023-03-03 16:36:39 +00:00
func (r *simpleResult) GoString() string {
if r.err == nil {
return "&simpleResult{}"
}
return fmt.Sprintf("&simpleResult{err: %#v}", r.err)
}
// Bail produces a Result that represents a computation that failed to complete
// successfully but is not a bug in Pulumi.
func Bail() Result {
return &simpleResult{err: nil}
}
// Errorf produces a Result that represents an internal Pulumi error,
// constructed from the given format string and arguments.
func Errorf(msg string, args ...interface{}) Result {
err := fmt.Errorf(msg, args...)
return FromError(err)
}
// Error produces a Result that represents an internal Pulumi error,
// constructed from the given message.
func Error(msg string) Result {
err := errors.New(msg)
return FromError(err)
}
Support bailing from RunFunc (#13804) **Background** The result.Result type is used by our CLI implementation to communicate how we want to exit the program. Most `result.Result` values (built from errors with `result.FromError`) cause the program to print the message to stderr and exit the program with exit code -1. The exception is `result.Bail()`, which indicates that we've already printed the error message, and we simply need to `exit(-1)` now. Our CLI command implementation use `cmdutil.RunResultFunc` which takes a `func(...) result.Result` to implement this logic. `cmdutil` additionally includes a `cmdutil.RunFunc` which takes a `func(...) error` and wraps it in `RunResultFunc`, relying on `result.FromError` for the conversion: func RunFunc(run func(...) error) func(...) { return RunResultFunc(func(...) result.Result { if err := run(...); err != nil { return result.FromError(err) } return nil }) } **Problem** In CLI contexts where we're using an `error`, and we want to print an error message to the user and exit, it's desirable to use diag.Sink to print the message to the user with the appropriate level (error, warning, etc.) and exit without printing anything else. However, the only way to do that currently is by converting that function to return `result.Result`, turn all error returns to `result.FromError`, and then return `result.Bail()`. **Solution** This change introduces a `result.BailError` error that gets converted into a `result.Bail()` when it passes through `result.FromError`. It allows commands implementations that use `error` to continue returning errors and still provide an ideal CLI experience. It relies on `errors.As` for matching, so even if an intermediate layer wraps the error with `fmt.Errorf("..: %w", ErrBail)`, we'll recognize the request to bail. BailError keep track of the internal error that triggered it, which (when everything is moved off of result and onto error) means we'll still be able to see the internal errors that triggered a bail during debugging. Currently debugging engine tests is pretty horrible because you often just get back a `result.Result{err:nil}` with no information where in the engine stack that came from. **Testing** Besides unit tests, this includes an end-to-end test for using RunResultFunc with a bail error. The test operates by putting the mock behavior in a fake test, and re-running the test binary to execute *just that test*. **Demonstration** This change also ports the following commands to use BailError: cancel, convert, env, policy rm, stack rm. These command implementations are simple and were able to switch easily, without bubbling into a change to a bunch of other code.
2023-08-29 07:43:40 +00:00
// FromError produces a Result that wraps an internal Pulumi error. Do not call this with a 'nil' error. A
// 'nil' error means that there was no problem, and in that case a 'nil' result should be used instead. If
// this is called with an error from `BailError` it will discard the inner error of that and return a bail
// result.
func FromError(err error) Result {
if err == nil {
panic("FromError should not be called with a nil-error. " +
"If there is no error, then a nil result should be returned. " +
"Caller should check for this first.")
}
Support bailing from RunFunc (#13804) **Background** The result.Result type is used by our CLI implementation to communicate how we want to exit the program. Most `result.Result` values (built from errors with `result.FromError`) cause the program to print the message to stderr and exit the program with exit code -1. The exception is `result.Bail()`, which indicates that we've already printed the error message, and we simply need to `exit(-1)` now. Our CLI command implementation use `cmdutil.RunResultFunc` which takes a `func(...) result.Result` to implement this logic. `cmdutil` additionally includes a `cmdutil.RunFunc` which takes a `func(...) error` and wraps it in `RunResultFunc`, relying on `result.FromError` for the conversion: func RunFunc(run func(...) error) func(...) { return RunResultFunc(func(...) result.Result { if err := run(...); err != nil { return result.FromError(err) } return nil }) } **Problem** In CLI contexts where we're using an `error`, and we want to print an error message to the user and exit, it's desirable to use diag.Sink to print the message to the user with the appropriate level (error, warning, etc.) and exit without printing anything else. However, the only way to do that currently is by converting that function to return `result.Result`, turn all error returns to `result.FromError`, and then return `result.Bail()`. **Solution** This change introduces a `result.BailError` error that gets converted into a `result.Bail()` when it passes through `result.FromError`. It allows commands implementations that use `error` to continue returning errors and still provide an ideal CLI experience. It relies on `errors.As` for matching, so even if an intermediate layer wraps the error with `fmt.Errorf("..: %w", ErrBail)`, we'll recognize the request to bail. BailError keep track of the internal error that triggered it, which (when everything is moved off of result and onto error) means we'll still be able to see the internal errors that triggered a bail during debugging. Currently debugging engine tests is pretty horrible because you often just get back a `result.Result{err:nil}` with no information where in the engine stack that came from. **Testing** Besides unit tests, this includes an end-to-end test for using RunResultFunc with a bail error. The test operates by putting the mock behavior in a fake test, and re-running the test binary to execute *just that test*. **Demonstration** This change also ports the following commands to use BailError: cancel, convert, env, policy rm, stack rm. These command implementations are simple and were able to switch easily, without bubbling into a change to a bunch of other code.
2023-08-29 07:43:40 +00:00
if IsBail(err) {
return &simpleResult{err: nil}
}
return &simpleResult{err: err}
}
// WrapIfNonNil returns a non-nil Result if [err] is non-nil. Otherwise it returns nil.
func WrapIfNonNil(err error) Result {
if err == nil {
return nil
}
return FromError(err)
}
// TODO returns an error that can be used in places that have not yet been
// adapted to use Results. Their use is intended to be temporary until Results
// are plumbed throughout the Pulumi codebase.
func TODO() error {
return errors.New("bailing due to error")
}
// Merge combines two results into one final result. It properly respects all three forms of Result
// (i.e. nil/bail/error) for both results, and combines all sensibly into a final form that represents
// the information of both.
func Merge(res1 Result, res2 Result) Result {
2019-03-14 00:52:50 +00:00
switch {
// If both are nil, then there's no problem. Return 'nil' to properly convey that outwards.
2019-03-14 00:52:50 +00:00
case res1 == nil && res2 == nil:
return nil
// Otherwise, if one is nil, and the other is not, then the non-nil takes precedence.
// i.e. an actual error (or bail) takes precedence
2019-03-14 00:52:50 +00:00
case res1 == nil:
return res2
2019-03-14 00:52:50 +00:00
case res2 == nil:
return res1
// If both results have asked to bail, then just bail. That properly respects both requests.
2019-03-14 00:52:50 +00:00
case res1.IsBail() && res2.IsBail():
return Bail()
// We have two non-nil results and one, or both, of the results indicate an error.
// If we have a request to Bail and a request to error then the request to error takes
// precedence. The concept of bailing is that we've printed an error already and should just
// quickly finish the entire pulumi execution. However, for an error, we are indicating a bug
// happened, and that we haven't printed it, and that it should print at the end. So we need
// to respect the error form here and pass it all the way back.
2019-03-14 00:52:50 +00:00
case res1.IsBail():
return res2
2019-03-14 00:52:50 +00:00
case res2.IsBail():
return res1
// Both results are errors. Combine them into one joint error and return that.
2019-03-14 00:52:50 +00:00
default:
return FromError(multierror.Append(res1.Error(), res2.Error()))
2019-03-14 00:52:50 +00:00
}
}