package fault

import "github.com/vmware/govmomi/fault"

Index

Examples

Functions

func As 

func As(err, target any) (localizedMessage string, okay bool)

As finds the first fault in the error's tree that matches target, and if one is found, sets the target to that fault value and returns the fault's localized message and true. Otherwise, false is returned.

The tree is inspected according to the object type. If the object implements Golang's error interface, the Unwrap() error or Unwrap() []error methods are repeatedly checked for additional errors. If the object implements GoVmomi's BaseMethodFault or HasLocalizedMethodFault interfaces, the object is checked for an underlying FaultCause. When err wraps multiple errors or faults, err is examined followed by a depth-first traversal of its children.

An error matches target if the error's concrete value is assignable to the value pointed to by target, or if the error has a method AsFault(BaseMethodFault) (string, bool) such that AsFault(BaseMethodFault) returns true. In the latter case, the AsFault method is responsible for setting target.

An error type might provide an AsFault method so it can be treated as if it were a different error type.

This function panics if err does not implement error, types.BaseMethodFault, types.HasLocalizedMethodFault, Fault() types.BaseMethodFault, or if target is not a pointer.

Example (FaultByAddress)

Code:play  

package main

import (
	"fmt"

	"github.com/vmware/govmomi/fault"
	"github.com/vmware/govmomi/task"
	"github.com/vmware/govmomi/vim25/types"
)

func main() {
	var (
		err    any
		target *types.InvalidPowerState
	)

	err = task.Error{
		LocalizedMethodFault: &types.LocalizedMethodFault{
			Fault: &types.InvalidPowerState{
				ExistingState:  types.VirtualMachinePowerStatePoweredOn,
				RequestedState: types.VirtualMachinePowerStatePoweredOff,
			},
			LocalizedMessage: "vm must be powered off to encrypt",
		},
	}

	localizedMessage, ok := fault.As(err, &target)

	fmt.Printf("result              = %v\n", ok)
	fmt.Printf("localizedMessage    = %v\n", localizedMessage)
	fmt.Printf("existingPowerState  = %v\n", target.ExistingState)
	fmt.Printf("requestedPowerState = %v\n", target.RequestedState)

}

Output:

result              = true
localizedMessage    = vm must be powered off to encrypt
existingPowerState  = poweredOn
requestedPowerState = poweredOff
Example (FaultByValue)

Code:play  

package main

import (
	"fmt"

	"github.com/vmware/govmomi/fault"
	"github.com/vmware/govmomi/vim25/types"
)

type valueFault uint8

func (f valueFault) GetMethodFault() *types.MethodFault {
	return nil
}

func main() {
	var (
		err    any
		target valueFault
	)

	err = &types.SystemError{
		RuntimeFault: types.RuntimeFault{
			MethodFault: types.MethodFault{
				FaultCause: &types.LocalizedMethodFault{
					Fault:            valueFault(1),
					LocalizedMessage: "fault by value",
				},
			},
		},
	}

	localizedMessage, ok := fault.As(err, &target)

	fmt.Printf("result              = %v\n", ok)
	fmt.Printf("localizedMessage    = %v\n", localizedMessage)
	fmt.Printf("value               = %d\n", target)

}

Output:

result              = true
localizedMessage    = fault by value
value               = 1

func In 

func In(err any, onFaultFn OnFaultFn)

In invokes onFaultFn for each fault in err's tree.

The tree is inspected according to the object type. If the object implements Golang's error interface, the Unwrap() error or Unwrap() []error methods are repeatedly checked for additional errors. If the object implements GoVmomi's BaseMethodFault or HasLocalizedMethodFault interfaces, the object is checked for an underlying FaultCause. When err wraps multiple errors or faults, err is examined followed by a depth-first traversal of its children.

This function panics if err does not implement error, types.BaseMethodFault, types.HasLocalizedMethodFault, Fault() types.BaseMethodFault, or if onFaultFn is nil.

Example (PrintAllTypeNamesAndMessages)

Code:play  

package main

import (
	"fmt"
	"reflect"

	"github.com/vmware/govmomi/fault"
	"github.com/vmware/govmomi/task"
	"github.com/vmware/govmomi/vim25/types"
)

func main() {
	var (
		err     any
		onFault fault.OnFaultFn
	)

	err = task.Error{
		LocalizedMethodFault: &types.LocalizedMethodFault{
			Fault: &types.RuntimeFault{
				MethodFault: types.MethodFault{
					FaultCause: &types.LocalizedMethodFault{
						Fault:            &types.SystemError{},
						LocalizedMessage: "inner message",
					},
				},
			},
			LocalizedMessage: "outer message",
		},
	}

	onFault = func(
		fault types.BaseMethodFault,
		localizedMessage string,
		localizableMessages []types.LocalizableMessage) bool {

		fmt.Printf("type             = %s\n", reflect.ValueOf(fault).Elem().Type().Name())
		fmt.Printf("localizedMessage = %s\n", localizedMessage)

		// Return false to continue discovering faults.
		return false
	}

	fault.In(err, onFault)

}

Output:

type             = RuntimeFault
localizedMessage = outer message
type             = SystemError
localizedMessage = inner message
Example (PrintFirstDiscoveredTypeNameAndMessage)

Code:play  

package main

import (
	"fmt"
	"reflect"

	"github.com/vmware/govmomi/fault"
	"github.com/vmware/govmomi/task"
	"github.com/vmware/govmomi/vim25/types"
)

func main() {
	var (
		err     any
		onFault fault.OnFaultFn
	)

	err = task.Error{
		LocalizedMethodFault: &types.LocalizedMethodFault{
			Fault: &types.RuntimeFault{
				MethodFault: types.MethodFault{
					FaultCause: &types.LocalizedMethodFault{
						Fault:            &types.SystemError{},
						LocalizedMessage: "inner message",
					},
				},
			},
			LocalizedMessage: "outer message",
		},
	}

	onFault = func(
		fault types.BaseMethodFault,
		localizedMessage string,
		localizableMessages []types.LocalizableMessage) bool {

		fmt.Printf("type             = %s\n", reflect.ValueOf(fault).Elem().Type().Name())
		fmt.Printf("localizedMessage = %s\n", localizedMessage)

		// Return true to force discovery to halt.
		return true
	}

	fault.In(err, onFault)

}

Output:

type             = RuntimeFault
localizedMessage = outer message

func Is 

func Is(err any, target types.BaseMethodFault) bool

Is reports whether any fault in err's tree matches target.

The tree is inspected according to the object type. If the object implements Golang's error interface, the Unwrap() error or Unwrap() []error methods are repeatedly checked for additional errors. If the object implements GoVmomi's BaseMethodFault or HasLocalizedMethodFault interfaces, the object is checked for an underlying FaultCause. When err wraps multiple errors or faults, err is examined followed by a depth-first traversal of its children.

An error is considered to match a target if it is equal to that target or if it implements a method IsFault(BaseMethodFault) bool such that IsFault(BaseMethodFault) returns true.

An error type might provide an IsFault method so it can be treated as equivalent to an existing fault. For example, if MyFault defines: 

func (m MyFault) IsFault(target BaseMethodFault) bool {
	return target == &types.NotSupported{}
}

then IsFault(MyError{}, &types.NotSupported{}) returns true. An IsFault method should only shallowly compare err and the target and not unwrap either.

Example (BaseMethodFault)

Code:play  

package main

import (
	"fmt"

	"github.com/vmware/govmomi/fault"
	"github.com/vmware/govmomi/vim25/types"
)

func main() {
	var (
		err    any
		target types.BaseMethodFault
	)

	err = &types.SystemError{}
	target = &types.SystemError{}

	fmt.Printf("result = %v\n", fault.Is(err, target))

}

Output:

result = true
Example (NestedFault)

Code:play  

package main

import (
	"fmt"

	"github.com/vmware/govmomi/fault"
	"github.com/vmware/govmomi/task"
	"github.com/vmware/govmomi/vim25/types"
)

func main() {
	var (
		err    any
		target types.BaseMethodFault
	)

	err = task.Error{
		LocalizedMethodFault: &types.LocalizedMethodFault{
			Fault: &types.RuntimeFault{
				MethodFault: types.MethodFault{
					FaultCause: &types.LocalizedMethodFault{
						Fault: &types.SystemError{},
					},
				},
			},
		},
	}
	target = &types.SystemError{}

	fmt.Printf("result = %v\n", fault.Is(err, target))

}

Output:

result = true
Example (SoapFault)

Code:play  

package main

import (
	"fmt"

	"github.com/vmware/govmomi/fault"
	"github.com/vmware/govmomi/vim25/soap"
	"github.com/vmware/govmomi/vim25/types"
)

func main() {
	var (
		err    any
		target types.BaseMethodFault
	)

	err = soap.WrapSoapFault(&soap.Fault{
		Detail: struct {
			Fault types.AnyType "xml:\",any,typeattr\""
		}{
			Fault: &types.RuntimeFault{
				MethodFault: types.MethodFault{
					FaultCause: &types.LocalizedMethodFault{
						Fault: &types.SystemError{},
					},
				},
			},
		},
	})
	target = &types.SystemError{}

	fmt.Printf("result = %v\n", fault.Is(err, target))

}

Output:

result = true
Example (VimFault)

Code:play  

package main

import (
	"fmt"

	"github.com/vmware/govmomi/fault"
	"github.com/vmware/govmomi/vim25/soap"
	"github.com/vmware/govmomi/vim25/types"
)

func main() {
	var (
		err    any
		target types.BaseMethodFault
	)

	err = soap.WrapVimFault(&types.RuntimeFault{
		MethodFault: types.MethodFault{
			FaultCause: &types.LocalizedMethodFault{
				Fault: &types.SystemError{},
			},
		},
	})
	target = &types.SystemError{}

	fmt.Printf("result = %v\n", fault.Is(err, target))

}

Output:

result = true

Types

type OnFaultFn 

type OnFaultFn func(
	fault types.BaseMethodFault,
	localizedMessage string,
	localizableMessages []types.LocalizableMessage) bool

OnFaultFn is called for every fault encountered when inspecting an error or fault for a fault tree. The In function returns when the entire tree is inspected or the OnFaultFn returns true.

Source Files

fault.go

Version
v0.48.1 (latest)
Published
Feb 11, 2025
Platform
linux/amd64
Imports
2 packages
Last checked
2 months ago –

Tools for package owners.