fault

ExampleBus_AddAlert showcases when to use AddAlert.

package main

import (
	"context"
	"fmt"

	"github.com/alcionai/corso/src/pkg/fault"
)

var ctx = context.Background()

func main() {
	errs := fault.New(false)

	// Some events should be communicated to the end user without recording an
	// error to the operation.  Logs aren't sufficient because we don't promote
	// log messages to the terminal.  But errors and skips are too heavy and hacky
	// to use.  In these cases, we can create informational Alerts.
	//
	// Only the message gets shown to the user.  But since we're persisting this
	// data along with the backup details and other fault info, we have the option
	// of packing any other contextual data that we want.
	errs.AddAlert(ctx, fault.NewAlert(
		"something important happened!",
		"deduplication-namespace",
		"file-id",
		"file-name",
		map[string]any{"foo": "bar"}))

	// later on, after processing, end users can scrutinize the alerts.
	fmt.Println(errs.Alerts()[0].String())

	// Alert: something important happened!
}

Output:

ExampleBus_AddRecoverable describes the assumptions and best practices for aggregating iterable or recoverable errors.

package main

import (
	"context"

	"github.com/alcionai/clues"

	"github.com/alcionai/corso/src/pkg/fault"
)

var (
	items = []string{}

	ctx = context.Background()
)

func getIthItem(i int) error { return nil }

func main() {
	errs := fault.New(false)

	// AddRecoverable() is used to record any recoverable error.
	//
	// What counts as a recoverable error?  That's up to the given
	// implementation.  Normally, it's an inability to process one
	// of many items within an iteration (ex: couldn't download 1 of
	// 1000 emails).  But just because an error occurred during a loop
	// doesn't mean it's recoverable, ex: a failure to retrieve the next
	// page when accumulating a batch of resources isn't usually
	// recoverable.  The choice is always up to the function at hand.
	//
	// AddRecoverable() should only get called as the top-most location
	// of error handling within the recoverable process.  Child functions
	// should stick to normal golang error handling and expect the upstream
	// controller to call AddRecoverable() for you.
	for i := range items {
		clientBasedGetter := func(i int) error {
			if err := getIthItem(i); err != nil {
				// lower level calls don't AddRecoverable to the fault.Bus.
				// they stick to normal golang error handling.
				return clues.Wrap(err, "dependency")
			}

			return nil
		}

		if err := clientBasedGetter(i); err != nil {
			// Here at the top of the loop is the correct place
			// to aggregate the error using fault.
			// Side note: technically, you should use a local bus
			// here (see below) instead of errs.
			errs.AddRecoverable(ctx, err)
		}
	}

	// Iteration should exit anytime the fault failure is non-nil.
	// fault.Bus does not expose the failFast flag directly.  Instead,
	// when failFast is true, errors from AddRecoverable() automatically
	// promote to the Failure() spot.  Recoverable handling only needs to
	// check the errs.Failure().  If it is non-nil, then the loop should break.
	for i := range items {
		if errs.Failure() != nil {
			// if failFast == true errs.AddRecoverable() was called,
			// we'll catch the error here.
			break
		}

		if err := getIthItem(i); err != nil {
			errs.AddRecoverable(ctx, err)
		}
	}
}

Output:

ExampleBus_AddSkip showcases when to use AddSkip instead of an error.

package main

import (
	"context"
	"fmt"

	"github.com/alcionai/corso/src/pkg/fault"
)

var ctx = context.Background()

func main() {
	errs := fault.New(false)

	// Some conditions cause well-known problems that we want Corso to skip
	// over, instead of error out.  An initial case is when Graph API identifies
	// a file as containing malware.  We can't download the file: it'll always
	// error.  Our only option is to skip it.
	errs.AddSkip(ctx, fault.FileSkip(
		fault.SkipMalware,
		"deduplication-namespace",
		"file-id",
		"file-name",
		map[string]any{"foo": "bar"}))

	// later on, after processing, end users can scrutinize the skipped items.
	fmt.Println(errs.Skipped()[0].String())

}

Output:

skipped processing file: malware_detected

ExampleBus_Fail describes the assumptions and best practices for setting the Failure error.

package main

import (
	"fmt"

	"github.com/alcionai/clues"

	"github.com/alcionai/corso/src/pkg/fault"
)

func connectClient() error  { return nil }
func dependencyCall() error { return nil }

func main() {
	errs := fault.New(false)

	// Fail() is used to record non-recoverable errors.
	//
	// Fail() should only get called in the last step before returning
	// a fault.Bus from a controller.  In all other cases, you
	// can stick to standard golang error handling and expect some upstream
	// controller to call Fail() for you (if necessary).
	topLevelHandler := func(errs *fault.Bus) *fault.Bus {
		if err := connectClient(); err != nil {
			return errs.Fail(err)
		}

		return errs
	}
	if errs := topLevelHandler(errs); errs.Failure() != nil {
		fmt.Println(errs.Failure())
	}

	// Only the top-most func in the stack should set the failure.
	// IE: Fail() is not Wrap().  In lower levels, errors should get
	// wrapped and returned like normal, and only handled by fault
	// at the end.
	lowLevelCall := func() error {
		if err := dependencyCall(); err != nil {
			// wrap here, deeper into the stack
			return clues.Wrap(err, "dependency")
		}

		return nil
	}
	if err := lowLevelCall(); err != nil {
		// fail here, at the top of the stack
		errs.Fail(err)
	}
}

Output:

ExampleBus_Failure describes retrieving the non-recoverable error.

package main

import (
	"context"
	"fmt"

	"github.com/alcionai/clues"

	"github.com/alcionai/corso/src/pkg/fault"
)

var ctx = context.Background()

func main() {
	errs := fault.New(false)
	errs.Fail(clues.New("catastrophe"))

	// Failure() returns the primary failure.
	err := errs.Failure()
	fmt.Println(err)

	// if multiple Failures occur, each one after the first gets
	// added to the Recoverable slice as an overflow measure.
	errs.Fail(clues.New("another catastrophe"))
	errSl := errs.Recovered()

	for _, e := range errSl {
		fmt.Println(e)
	}

	// If Failure() is nil, then you can assume the operation completed.
	// A complete operation is not necessarily an error-free operation.
	// Recoverable errors may still have been added using AddRecoverable(ctx, err).
	// Make sure you check both.

	// If failFast is set to true, then the first recoerable error Added gets
	// promoted to the Err() position.
	errs = fault.New(true)
	errs.AddRecoverable(ctx, clues.New("not catastrophic, but still becomes the Failure()"))
	err = errs.Failure()
	fmt.Println(err)

}

Output:

catastrophe
another catastrophe
not catastrophic, but still becomes the Failure()

package main

import (
	"context"
	"fmt"

	"github.com/alcionai/corso/src/pkg/fault"
)

var (
	items = []string{}

	ctx = context.Background()
)

func getIthItem(i int) error { return nil }

func main() {
	// It is common for Corso to run operations in parallel,
	// and for iterations to be nested within iterations.  To
	// avoid mistakenly returning an error that was sourced
	// from some other async iteration, recoverable instances
	// are aggrgated into a Local.
	errs := fault.New(false)
	el := errs.Local()

	err := func() error {
		for i := range items {
			if el.Failure() != nil {
				break
			}

			if err := getIthItem(i); err != nil {
				// instead of calling errs.AddRecoverable(ctx, err), we call the
				// local bus's Add method.  The error will still get
				// added to the errs.Recovered() set.  But if this err
				// causes the run to fail, only this local bus treats
				// it as the causal failure.
				el.AddRecoverable(ctx, err)
			}
		}

		return el.Failure()
	}()
	if err != nil {
		// handle the Failure() that appeared in the local bus.
		fmt.Println("failure occurred", errs.Failure())
	}
}

Output: