verror

package
v0.1.13 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 21, 2020 License: BSD-3-Clause Imports: 15 Imported by: 344

Documentation

Overview

Package verror implements an error reporting mechanism that works across programming environments, and a set of common errors. It captures the location and parameters of the error call site to aid debugging. Rudimentary i18n support is provided, but now that more comprehensive i18n packages are available its use is deprecated and it will be removed in the near future; consequently Register and New are deprecated in favour of NewIDAction/NewID, IDAction.Errorf and IDAction.Message. Errorf is not intended or localization, whereas Message accepts a preformatted message to allow for localization via an alternative package/framework. The Convert function is also deprecated in favour of capturing non-verror error instances via Errorf, that is, IDAction.Errorf(ctx, "%v", err) should be used to create verror.E's from errors from other packages.

NOTE that the deprecated i18n support will be removed in the near future.

Each error has an identifier string, which is used for equality checks. E.g. a Javascript client can check if a Go server returned a NoExist error by checking the string identifier. Error identifier strings start with the VDL package path to ensure uniqueness, e.g. "v.io/v23/verror.NoExist". The NewID and NewIDAction functions automatically prepend the package path of the caller to the specified ID if it is not already included.

Each error contains an action, which is the suggested action for a typical client to perform upon receiving the error. E.g. some action codes represent whether to retry the operation after receiving the error.

Each error also contains a list of typed parameters, and an error message. The error message may be created in three ways:

  1. Via the Errorf method using fmt.Sprintf formatting.
  2. Via the Message method where the error message is preformatted and the parameter list is recorded.
  3. The error message is created by looking up a format string keyed on the error identifier, and applying the parameters to the format string. This enables error messages to be generated in different languages. Note that this method is now deprecated.

Contemporary Example:

To define a new error identifier, for example "someNewError", the code that originates the error is expected to declare a variable like this: 

var someNewError = verror.Register("someNewError", NoRetry)
...
return someNewError.Errorf(ctx, "my error message: %v", err)

Alternatively, to use golang.org/x/text/messsage for localization: 

p := message.NewPrinter(language.BritishEnglish)
msg := p.Sprintf("invalid name: %v: %v", name, err)
return someNewError.Message(ctx, msg, name, err)

The verror implementation supports errors.Is and errors.Unwrap. Note that errors.Unwrap provides access to 'sub-errors' as well as to chained instances of error. verror.WithSubErrors can be used to add additional 'sub-errors' to an existing error and these may be of type SubErr or any other error.

Deprecated Usage Example:

To define a new error identifier, for example "someNewError", client code is expected to declare a variable like this: 

var someNewError = verror.Register("someNewError", NoRetry,
                                   "{1} {2} English text for new error")

Text for other languages can be added to the default i18n Catalogue. Note that verror.Register will determine the name of the calling package and prepend it to 'someNewError'.

If the error should cause a client to retry, consider replacing "NoRetry" with one of the other Action codes below.

Errors are given parameters when used. Conventionally, the first parameter is the name of the component (typically server or binary name), and the second is the name of the operation (such as an RPC or subcommand) that encountered the error. Other parameters typically identify the object(s) on which the error occurred. This convention is normally applied by New(), which fetches the language, component name and operation name from the context.T: 

err = verror.New(someNewError, ctx, "object_on_which_error_occurred")

The ExplicitNew() call can be used to specify these things explicitly: 

err = verror.ExplicitNew(someNewError, i18n.GetLangID(ctx),
        "my_component", "op_name", "procedure_name", "object_name")

If the language, component and/or operation name are unknown, use i18n.NoLangID or the empty string, respectively.

Because of the convention for the first two parameters, messages in the catalogue typically look like this (at least for left-to-right languages): 

{1} {2} The new error {_}

The tokens {1}, {2}, etc. refer to the first and second positional parameters respectively, while {_} is replaced by the positional parameters not explicitly referred to elsewhere in the message. Thus, given the parameters above, this would lead to the output: 

my_component op_name The new error object_name

If a substring is of the form {:<number>}, {<number>:}, {:<number>:}, {:_}, {_:}, or {:_:}, and the corresponding parameters are not the empty string, the parameter is preceded by ": " or followed by ":" or both, respectively. For example, if the format: 

{3:} foo {2} bar{:_} ({3})

is used with the cat.Format example above, it yields: 

3rd: foo 2nd bar: 1st 4th (3rd)

The Convert() and ExplicitConvert() calls are like New() and ExplicitNew(), but convert existing errors (with their parameters, if applicable) to verror errors with given language, component name, and operation name, if non-empty values for these are provided. They also add a PC to a list of PC values to assist developers hunting for the error.

If the context.T specified with New() or Convert() is nil, a default context is used, set by SetDefaultContext(). This can be used in standalone programmes, or in anciliary threads not associated with an RPC. The user might do the following to get the language from the environment, and the programme name from Args[0]: 

ctx := runtime.NewContext()
ctx = i18n.WithLangID(ctx, i18n.LangIDFromEnv())
ctx = verror.WithComponentName(ctx, os.Args[0])
verror.SetDefaultContext(ctx)

A standalone tool might set the operation name to be a subcommand name, if any. If the default context has not been set, the error generated has no language, component and operation values; they will be filled in by the first Convert() call that does have these values.

Index

Constants

This section is empty.

Variables

View Source 
var (

	// ErrUnknown means the error has no known Id.  A more specific error should
	// always be used, if possible.  Unknown is typically only used when
	// automatically converting errors that do not contain an Id.
	ErrUnknown = NewIDAction("v.io/v23/verror.Unknown", NoRetry)
	// ErrInternal means an internal error has occurred.  A more specific error
	// should always be used, if possible.
	ErrInternal = NewIDAction("v.io/v23/verror.Internal", NoRetry)
	// ErrNotImplemented means that the request type is valid but that the method to
	// handle the request has not been implemented.
	ErrNotImplemented = NewIDAction("v.io/v23/verror.NotImplemented", NoRetry)
	// ErrEndOfFile means the end-of-file has been reached; more generally, no more
	// input data is available.
	ErrEndOfFile = NewIDAction("v.io/v23/verror.EndOfFile", NoRetry)
	// ErrBadArg means the arguments to an operation are invalid or incorrectly
	// formatted.
	ErrBadArg = NewIDAction("v.io/v23/verror.BadArg", NoRetry)
	// ErrBadState means an operation was attempted on an object while the object was
	// in an incompatible state.
	ErrBadState = NewIDAction("v.io/v23/verror.BadState", NoRetry)
	// ErrBadVersion means the version presented by the client (e.g. to a service
	// that supports content-hash-based caching or atomic read-modify-write) was
	// out of date or otherwise invalid, likely because some other request caused
	// the version at the server to change. The client should get a fresh version
	// and try again.
	ErrBadVersion = NewIDAction("v.io/v23/verror.BadVersion", NoRetry)
	// ErrExist means that the requested item already exists; typically returned when
	// an attempt to create an item fails because it already exists.
	ErrExist = NewIDAction("v.io/v23/verror.Exist", NoRetry)
	// ErrNoExist means that the requested item does not exist; typically returned
	// when an attempt to lookup an item fails because it does not exist.
	ErrNoExist       = NewIDAction("v.io/v23/verror.NoExist", NoRetry)
	ErrUnknownMethod = NewIDAction("v.io/v23/verror.UnknownMethod", NoRetry)
	ErrUnknownSuffix = NewIDAction("v.io/v23/verror.UnknownSuffix", NoRetry)
	// ErrNoExistOrNoAccess means that either the requested item does not exist, or
	// is inaccessible.  Typically returned when the distinction between existence
	// and inaccessiblity should be hidden to preserve privacy.
	ErrNoExistOrNoAccess = NewIDAction("v.io/v23/verror.NoExistOrNoAccess", NoRetry)
	// ErrNoServers means a name was resolved to unusable or inaccessible servers.
	ErrNoServers = NewIDAction("v.io/v23/verror.NoServers", RetryRefetch)
	// ErrNoAccess means the server does not authorize the client for access.
	ErrNoAccess = NewIDAction("v.io/v23/verror.NoAccess", RetryRefetch)
	// ErrNotTrusted means the client does not trust the server.
	ErrNotTrusted = NewIDAction("v.io/v23/verror.NotTrusted", RetryRefetch)
	// ErrAborted means that an operation was not completed because it was aborted by
	// the receiver.  A more specific error should be used if it would help the
	// caller decide how to proceed.
	ErrAborted = NewIDAction("v.io/v23/verror.Aborted", NoRetry)
	// ErrBadProtocol means that an operation was not completed because of a protocol
	// or codec error.
	ErrBadProtocol = NewIDAction("v.io/v23/verror.BadProtocol", NoRetry)
	// ErrCanceled means that an operation was not completed because it was
	// explicitly cancelled by the caller.
	ErrCanceled = NewIDAction("v.io/v23/verror.Canceled", NoRetry)
	// ErrTimeout means that an operation was not completed before the time deadline
	// for the operation.
	ErrTimeout = NewIDAction("v.io/v23/verror.Timeout", NoRetry)
)

Functions

func AddSubErrs 

func AddSubErrs(err error, ctx *context.T, errors ...SubErr) error

AddSubErrs is like ExplicitAddSubErrs, but uses the provided context to obtain the langID, componentName, and opName values.

func Convert 

func Convert(idAction IDAction, ctx *context.T, err error) error

Convert is like ExplicitConvert(), but obtains the language, component and operation names from the specified context.T. ctx may be nil.

func DebugString 

func DebugString(err error) string

DebugString returns a more verbose string representation of an error, perhaps more thorough than one might present to an end user, but useful for debugging by a developer.

func ErrorFromNative 

func ErrorFromNative(wire **vdl.WireError, native error) error

ErrorFromNative converts from the native to wire representation of errors.

func ErrorToNative 

func ErrorToNative(wire *vdl.WireError, native *error) error

ErrorToNative converts from the wire to native representation of errors.

func Errorf added in v0.1.10 

func Errorf(ctx *context.T, format string, params ...interface{}) error

Errorf is like ErrUnknown.Errorf.

func ErrorfAborted added in v0.1.10 

func ErrorfAborted(ctx *context.T, format string) error

ErrorfAborted calls ErrAborted.Errorf with the supplied arguments.

func ErrorfBadArg added in v0.1.10 

func ErrorfBadArg(ctx *context.T, format string) error

ErrorfBadArg calls ErrBadArg.Errorf with the supplied arguments.

func ErrorfBadProtocol added in v0.1.10 

func ErrorfBadProtocol(ctx *context.T, format string) error

ErrorfBadProtocol calls ErrBadProtocol.Errorf with the supplied arguments.

func ErrorfBadState added in v0.1.10 

func ErrorfBadState(ctx *context.T, format string) error

ErrorfBadState calls ErrBadState.Errorf with the supplied arguments.

func ErrorfBadVersion added in v0.1.10 

func ErrorfBadVersion(ctx *context.T, format string) error

ErrorfBadVersion calls ErrBadVersion.Errorf with the supplied arguments.

func ErrorfCanceled added in v0.1.10 

func ErrorfCanceled(ctx *context.T, format string) error

ErrorfCanceled calls ErrCanceled.Errorf with the supplied arguments.

func ErrorfEndOfFile added in v0.1.10 

func ErrorfEndOfFile(ctx *context.T, format string) error

ErrorfEndOfFile calls ErrEndOfFile.Errorf with the supplied arguments.

func ErrorfExist added in v0.1.10 

func ErrorfExist(ctx *context.T, format string) error

ErrorfExist calls ErrExist.Errorf with the supplied arguments.

func ErrorfInternal added in v0.1.10 

func ErrorfInternal(ctx *context.T, format string) error

ErrorfInternal calls ErrInternal.Errorf with the supplied arguments.

func ErrorfNoAccess added in v0.1.10 

func ErrorfNoAccess(ctx *context.T, format string) error

ErrorfNoAccess calls ErrNoAccess.Errorf with the supplied arguments.

func ErrorfNoExist added in v0.1.10 

func ErrorfNoExist(ctx *context.T, format string) error

ErrorfNoExist calls ErrNoExist.Errorf with the supplied arguments.

func ErrorfNoExistOrNoAccess added in v0.1.10 

func ErrorfNoExistOrNoAccess(ctx *context.T, format string) error

ErrorfNoExistOrNoAccess calls ErrNoExistOrNoAccess.Errorf with the supplied arguments.

func ErrorfNoServers added in v0.1.10 

func ErrorfNoServers(ctx *context.T, format string) error

ErrorfNoServers calls ErrNoServers.Errorf with the supplied arguments.

func ErrorfNotImplemented added in v0.1.10 

func ErrorfNotImplemented(ctx *context.T, format string) error

ErrorfNotImplemented calls ErrNotImplemented.Errorf with the supplied arguments.

func ErrorfNotTrusted added in v0.1.10 

func ErrorfNotTrusted(ctx *context.T, format string) error

ErrorfNotTrusted calls ErrNotTrusted.Errorf with the supplied arguments.

func ErrorfTimeout added in v0.1.10 

func ErrorfTimeout(ctx *context.T, format string) error

ErrorfTimeout calls ErrTimeout.Errorf with the supplied arguments.

func ErrorfUnknown added in v0.1.10 

func ErrorfUnknown(ctx *context.T, format string) error

ErrorfUnknown calls ErrUnknown.Errorf with the supplied arguments.

func ErrorfUnknownMethod added in v0.1.10 

func ErrorfUnknownMethod(ctx *context.T, format string) error

ErrorfUnknownMethod calls ErrUnknownMethod.Errorf with the supplied arguments.

func ErrorfUnknownSuffix added in v0.1.10 

func ErrorfUnknownSuffix(ctx *context.T, format string) error

ErrorfUnknownSuffix calls ErrUnknownSuffix.Errorf with the supplied arguments.

func ExplicitAddSubErrs 

func ExplicitAddSubErrs(err error, langID i18n.LangID, componentName string, opName string, errors ...SubErr) error

ExplicitAddSubErrs returns a copy of err with supplied errors appended as subordinate errors. Requires that errors[i].Err!=nil for 0<=i<len(errors).

func ExplicitConvert 

func ExplicitConvert(idAction IDAction, langID i18n.LangID, componentName string, opName string, err error) error

ExplicitConvert converts a regular err into an E error, setting its IDAction to idAction. If err is already an E, it returns err or an equivalent value without changing its type, but potentially changing the language, component or operation if langID!=i18n.NoLangID, componentName!="" or opName!="" respectively. The caller's PC is added to the error's stack.

func ExplicitNew 

func ExplicitNew(idAction IDAction, langID i18n.LangID, componentName string, opName string, v ...interface{}) error

ExplicitNew returns an error with the given ID, with an error string in the chosen language. The component and operation name are included the first and second parameters of the error. Other parameters are taken from v[]. The parameters are formatted into the message according to i18n.Cat().Format. The caller's PC is added to the error's stack. If the parameter list contains an instance of verror.E, then the stack of the first, and only the first, occurrence of such an instance, will be chained to the stack of this newly created error.

func FromWire 

func FromWire(wire *vdl.WireError) error

FromWire is a convenience for generated code to convert wire errors into native errors.

func IsAny added in v0.1.10 

func IsAny(err error) bool

IsAny returns true if err is any instance of a verror.E regardless of its ID.

func Message added in v0.1.10 

func Message(ctx *context.T, msg string, params ...interface{}) error

Message is like ErrUnknown.Message.

func MessageAborted added in v0.1.10 

func MessageAborted(ctx *context.T, message string) error

MessageAborted calls ErrAborted.Message with the supplied arguments.

func MessageBadArg added in v0.1.10 

func MessageBadArg(ctx *context.T, message string) error

MessageBadArg calls ErrBadArg.Message with the supplied arguments.

func MessageBadProtocol added in v0.1.10 

func MessageBadProtocol(ctx *context.T, message string) error

MessageBadProtocol calls ErrBadProtocol.Message with the supplied arguments.

func MessageBadState added in v0.1.10 

func MessageBadState(ctx *context.T, message string) error

MessageBadState calls ErrBadState.Message with the supplied arguments.

func MessageBadVersion added in v0.1.10 

func MessageBadVersion(ctx *context.T, message string) error

MessageBadVersion calls ErrBadVersion.Message with the supplied arguments.

func MessageCanceled added in v0.1.10 

func MessageCanceled(ctx *context.T, message string) error

MessageCanceled calls ErrCanceled.Message with the supplied arguments.

func MessageEndOfFile added in v0.1.10 

func MessageEndOfFile(ctx *context.T, message string) error

MessageEndOfFile calls ErrEndOfFile.Message with the supplied arguments.

func MessageExist added in v0.1.10 

func MessageExist(ctx *context.T, message string) error

MessageExist calls ErrExist.Message with the supplied arguments.

func MessageInternal added in v0.1.10 

func MessageInternal(ctx *context.T, message string) error

MessageInternal calls ErrInternal.Message with the supplied arguments.

func MessageNoAccess added in v0.1.10 

func MessageNoAccess(ctx *context.T, message string) error

MessageNoAccess calls ErrNoAccess.Message with the supplied arguments.

func MessageNoExist added in v0.1.10 

func MessageNoExist(ctx *context.T, message string) error

MessageNoExist calls ErrNoExist.Message with the supplied arguments.

func MessageNoExistOrNoAccess added in v0.1.10 

func MessageNoExistOrNoAccess(ctx *context.T, message string) error

MessageNoExistOrNoAccess calls ErrNoExistOrNoAccess.Message with the supplied arguments.

func MessageNoServers added in v0.1.10 

func MessageNoServers(ctx *context.T, message string) error

MessageNoServers calls ErrNoServers.Message with the supplied arguments.

func MessageNotImplemented added in v0.1.10 

func MessageNotImplemented(ctx *context.T, message string) error

MessageNotImplemented calls ErrNotImplemented.Message with the supplied arguments.

func MessageNotTrusted added in v0.1.10 

func MessageNotTrusted(ctx *context.T, message string) error

MessageNotTrusted calls ErrNotTrusted.Message with the supplied arguments.

func MessageTimeout added in v0.1.10 

func MessageTimeout(ctx *context.T, message string) error

MessageTimeout calls ErrTimeout.Message with the supplied arguments.

func MessageUnknown added in v0.1.10 

func MessageUnknown(ctx *context.T, message string) error

MessageUnknown calls ErrUnknown.Message with the supplied arguments.

func MessageUnknownMethod added in v0.1.10 

func MessageUnknownMethod(ctx *context.T, message string) error

MessageUnknownMethod calls ErrUnknownMethod.Message with the supplied arguments.

func MessageUnknownSuffix added in v0.1.10 

func MessageUnknownSuffix(ctx *context.T, message string) error

MessageUnknownSuffix calls ErrUnknownSuffix.Message with the supplied arguments.

func New 

func New(idAction IDAction, ctx *context.T, v ...interface{}) error

New is like ExplicitNew(), but obtains the language, component name, and operation name from the specified context.T. ctx may be nil.

func NewErrAborted 

func NewErrAborted(ctx *context.T) error

NewErrAborted returns an error with the ErrAborted ID. Deprecated: this function will be removed in the future, use ErrorfAborted or MessageAborted instead.

func NewErrBadArg 

func NewErrBadArg(ctx *context.T) error

NewErrBadArg returns an error with the ErrBadArg ID. Deprecated: this function will be removed in the future, use ErrorfBadArg or MessageBadArg instead.

func NewErrBadProtocol 

func NewErrBadProtocol(ctx *context.T) error

NewErrBadProtocol returns an error with the ErrBadProtocol ID. Deprecated: this function will be removed in the future, use ErrorfBadProtocol or MessageBadProtocol instead.

func NewErrBadState 

func NewErrBadState(ctx *context.T) error

NewErrBadState returns an error with the ErrBadState ID. Deprecated: this function will be removed in the future, use ErrorfBadState or MessageBadState instead.

func NewErrBadVersion 

func NewErrBadVersion(ctx *context.T) error

NewErrBadVersion returns an error with the ErrBadVersion ID. Deprecated: this function will be removed in the future, use ErrorfBadVersion or MessageBadVersion instead.

func NewErrCanceled 

func NewErrCanceled(ctx *context.T) error

NewErrCanceled returns an error with the ErrCanceled ID. Deprecated: this function will be removed in the future, use ErrorfCanceled or MessageCanceled instead.

func NewErrEndOfFile 

func NewErrEndOfFile(ctx *context.T) error

NewErrEndOfFile returns an error with the ErrEndOfFile ID. Deprecated: this function will be removed in the future, use ErrorfEndOfFile or MessageEndOfFile instead.

func NewErrExist 

func NewErrExist(ctx *context.T) error

NewErrExist returns an error with the ErrExist ID. Deprecated: this function will be removed in the future, use ErrorfExist or MessageExist instead.

func NewErrInternal 

func NewErrInternal(ctx *context.T) error

NewErrInternal returns an error with the ErrInternal ID. Deprecated: this function will be removed in the future, use ErrorfInternal or MessageInternal instead.

func NewErrNoAccess 

func NewErrNoAccess(ctx *context.T) error

NewErrNoAccess returns an error with the ErrNoAccess ID. Deprecated: this function will be removed in the future, use ErrorfNoAccess or MessageNoAccess instead.

func NewErrNoExist 

func NewErrNoExist(ctx *context.T) error

NewErrNoExist returns an error with the ErrNoExist ID. Deprecated: this function will be removed in the future, use ErrorfNoExist or MessageNoExist instead.

func NewErrNoExistOrNoAccess 

func NewErrNoExistOrNoAccess(ctx *context.T) error

NewErrNoExistOrNoAccess returns an error with the ErrNoExistOrNoAccess ID. Deprecated: this function will be removed in the future, use ErrorfNoExistOrNoAccess or MessageNoExistOrNoAccess instead.

func NewErrNoServers 

func NewErrNoServers(ctx *context.T) error

NewErrNoServers returns an error with the ErrNoServers ID. Deprecated: this function will be removed in the future, use ErrorfNoServers or MessageNoServers instead.

func NewErrNotImplemented 

func NewErrNotImplemented(ctx *context.T) error

NewErrNotImplemented returns an error with the ErrNotImplemented ID. Deprecated: this function will be removed in the future, use ErrorfNotImplemented or MessageNotImplemented instead.

func NewErrNotTrusted 

func NewErrNotTrusted(ctx *context.T) error

NewErrNotTrusted returns an error with the ErrNotTrusted ID. Deprecated: this function will be removed in the future, use ErrorfNotTrusted or MessageNotTrusted instead.

func NewErrTimeout 

func NewErrTimeout(ctx *context.T) error

NewErrTimeout returns an error with the ErrTimeout ID. Deprecated: this function will be removed in the future, use ErrorfTimeout or MessageTimeout instead.

func NewErrUnknown 

func NewErrUnknown(ctx *context.T) error

NewErrUnknown returns an error with the ErrUnknown ID. Deprecated: this function will be removed in the future, use ErrorfUnknown or MessageUnknown instead.

func NewErrUnknownMethod 

func NewErrUnknownMethod(ctx *context.T) error

NewErrUnknownMethod returns an error with the ErrUnknownMethod ID. Deprecated: this function will be removed in the future, use ErrorfUnknownMethod or MessageUnknownMethod instead.

func NewErrUnknownSuffix 

func NewErrUnknownSuffix(ctx *context.T) error

NewErrUnknownSuffix returns an error with the ErrUnknownSuffix ID. Deprecated: this function will be removed in the future, use ErrorfUnknownSuffix or MessageUnknownSuffix instead.

func Params added in v0.1.10 

func Params(err error) []interface{}

Params returns the ParameterList stored in err if it's an instance of verror.E, nil otherwise.

func ParamsErrAborted added in v0.1.10 

func ParamsErrAborted(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrAborted extracts the expected parameters from the error's ParameterList.

func ParamsErrBadArg added in v0.1.10 

func ParamsErrBadArg(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrBadArg extracts the expected parameters from the error's ParameterList.

func ParamsErrBadProtocol added in v0.1.10 

func ParamsErrBadProtocol(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrBadProtocol extracts the expected parameters from the error's ParameterList.

func ParamsErrBadState added in v0.1.10 

func ParamsErrBadState(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrBadState extracts the expected parameters from the error's ParameterList.

func ParamsErrBadVersion added in v0.1.10 

func ParamsErrBadVersion(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrBadVersion extracts the expected parameters from the error's ParameterList.

func ParamsErrCanceled added in v0.1.10 

func ParamsErrCanceled(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrCanceled extracts the expected parameters from the error's ParameterList.

func ParamsErrEndOfFile added in v0.1.10 

func ParamsErrEndOfFile(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrEndOfFile extracts the expected parameters from the error's ParameterList.

func ParamsErrExist added in v0.1.10 

func ParamsErrExist(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrExist extracts the expected parameters from the error's ParameterList.

func ParamsErrInternal added in v0.1.10 

func ParamsErrInternal(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrInternal extracts the expected parameters from the error's ParameterList.

func ParamsErrNoAccess added in v0.1.10 

func ParamsErrNoAccess(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrNoAccess extracts the expected parameters from the error's ParameterList.

func ParamsErrNoExist added in v0.1.10 

func ParamsErrNoExist(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrNoExist extracts the expected parameters from the error's ParameterList.

func ParamsErrNoExistOrNoAccess added in v0.1.10 

func ParamsErrNoExistOrNoAccess(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrNoExistOrNoAccess extracts the expected parameters from the error's ParameterList.

func ParamsErrNoServers added in v0.1.10 

func ParamsErrNoServers(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrNoServers extracts the expected parameters from the error's ParameterList.

func ParamsErrNotImplemented added in v0.1.10 

func ParamsErrNotImplemented(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrNotImplemented extracts the expected parameters from the error's ParameterList.

func ParamsErrNotTrusted added in v0.1.10 

func ParamsErrNotTrusted(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrNotTrusted extracts the expected parameters from the error's ParameterList.

func ParamsErrTimeout added in v0.1.10 

func ParamsErrTimeout(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrTimeout extracts the expected parameters from the error's ParameterList.

func ParamsErrUnknown added in v0.1.10 

func ParamsErrUnknown(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrUnknown extracts the expected parameters from the error's ParameterList.

func ParamsErrUnknownMethod added in v0.1.10 

func ParamsErrUnknownMethod(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrUnknownMethod extracts the expected parameters from the error's ParameterList.

func ParamsErrUnknownSuffix added in v0.1.10 

func ParamsErrUnknownSuffix(argumentError error) (verrorComponent string, verrorOperation string, returnErr error)

ParamsErrUnknownSuffix extracts the expected parameters from the error's ParameterList.

func SetDefaultContext 

func SetDefaultContext(ctx *context.T)

SetDefaultContext sets the default context used when a nil context.T is passed to New() or Convert(). It is typically used in standalone programmes that have no RPC context, or in servers for the context of ancillary threads not associated with any particular RPC.

func StackToText 

func StackToText(w io.Writer, stack []uintptr) error

StackToText emits on w a text representation of stack, which is typically obtained from Stack() and represents the source location(s) where an error was generated or passed through in the local address space.

func VDLRead 

func VDLRead(dec vdl.Decoder, x *error) error

VDLRead implements the logic to read x from dec.

Unlike regular VDLRead implementations, this handles the case where the decoder contains a nil value, to make code generation simpler.

func VDLWrite 

func VDLWrite(enc vdl.Encoder, x error) error

VDLWrite implements the logic to write x to enc.

Unlike regular VDLWrite implementations, this handles the case where x contains a nil value, to make code generation simpler.

func WireFromNative 

func WireFromNative(wire *vdl.WireError, native error) error

WireFromNative converts from the standard go error interface to verror.E, and then to vdl.WireError.

TODO(toddw): Remove this function after the switch to the new vdl Encoder/Decoder is complete.

func WireToNative 

func WireToNative(wire vdl.WireError, native *E) error

WireToNative converts from vdl.WireError to verror.E, which implements the standard go error interface.

TODO(toddw): Remove this function after the switch to the new vdl Encoder/Decoder is complete.

func WithComponentName 

func WithComponentName(ctx *context.T, componentName string) *context.T

WithComponentName returns a context based on ctx that has the componentName that New() and Convert() can use.

func WithSubErrors added in v0.1.10 

func WithSubErrors(err error, errors ...error) error

WithSubErrors returns a new E with the supplied suberrors appended to its parameter list. The results of their Error method are appended to that of err.Error().

Types

type ActionCode 

type ActionCode uint32

An ActionCode represents the action expected to be performed by a typical client receiving an error that perhaps it does not understand. 

const (
	// Retry actions are encoded in the bottom few bits.
	RetryActionMask ActionCode = 3

	NoRetry         ActionCode = 0 // Do not retry.
	RetryConnection ActionCode = 1 // Renew high-level connection/context.
	RetryRefetch    ActionCode = 2 // Refetch and retry (e.g., out of date HTTP ETag)
	RetryBackoff    ActionCode = 3 // Backoff and retry a finite number of times.
)

Codes for ActionCode.

func Action 

func Action(err error) ActionCode

Action returns the action of the given err, or NoRetry if the err has no Action.

func (ActionCode) RetryAction 

func (ac ActionCode) RetryAction() ActionCode

RetryAction returns the part of the ActionCode that indicates retry behaviour.

type E 

type E struct {
	ID        ID            // The identity of the error.
	Action    ActionCode    // Default action to take on error.
	Msg       string        // Error message; empty if no language known.
	ParamList []interface{} // The variadic parameters given to ExplicitNew().
	// contains filtered or unexported fields
}

E is the in-memory representation of a verror error.

The wire representation is defined as vdl.WireError; values of E type are automatically converted to/from vdl.WireError by VDL and VOM.

func (E) Error 

func (e E) Error() string

Error returns the error message; if it has not been formatted for a specific language, a default message containing the error ID and parameters is generated. This method is required to fulfil the error interface.

func (E) Is added in v0.1.10 

func (e E) Is(err error) bool

Is implements the Is method as expected by errors.Is.

func (E) Unwrap added in v0.1.10 

func (e E) Unwrap() error

Unwrap implements the Unwrap method as expected by errors.Unwrap. It returns verror.SubErrors followed by any error recorded with %w for Errorf or the last argument to Message, New or ExplicitNew.

func (E) VDLEqual 

func (e E) VDLEqual(yiface interface{}) bool

func (*E) VDLRead 

func (e *E) VDLRead(dec vdl.Decoder) error

func (E) VDLReflect 

func (E) VDLReflect(struct {
	Name string `vdl:"v.io/v23/vdl.WireError"`
})

TypeOf(verror.E{}) should give vdl.WireError.

func (E) VDLWrite 

func (e E) VDLWrite(enc vdl.Encoder) error

type ID 

type ID string

ID is a unique identifier for errors.

func ErrorID 

func ErrorID(err error) ID

ErrorID returns the ID of the given err, or Unknown if the err has no ID. If err is nil then ErrorID returns "".

func IDPath added in v0.1.13 

func IDPath(val interface{}, id string) ID

IDPath returns a string of the form <package-path>.<name> where <package-path> is derived from the type of the supplied value. Typical usage would be except that dummy can be replaced by an existing type defined in the package. 

type dummy int
verror.ID(verror.IDPath(dummy(0), "MyError"))

type IDAction 

type IDAction struct {
	ID     ID
	Action ActionCode
}

An IDAction combines a unique identifier ID for errors with an ActionCode. The ID allows stable error checking across different error messages and different address spaces. By convention the format for the identifier is "PKGPATH.NAME" - e.g. ErrIDFoo defined in the "v23/verror" package has id "v23/verror.ErrIDFoo". It is unwise ever to create two IDActions that associate different ActionCodes with the same ID. IDAction implements error so that it may be used with errors.Is.

func NewID added in v0.1.10 

func NewID(id ID) IDAction

NewID creates a new instance of IDAction with the given ID and a NoRetry Action.

func NewIDAction added in v0.1.10 

func NewIDAction(id ID, action ActionCode) IDAction

NewIDAction creates a new instance of IDAction with the given ID and Action field. It should be used when localization support is not required instead of Register. IDPath can be used to

func Register 

func Register(id ID, action ActionCode, englishText string) IDAction

Register returns a IDAction with the given ID and Action fields, and inserts a message into the default i18n Catalogue in US English. Other languages can be added by adding to the Catalogue. IDPath can be used to generate an appropriate ID.

func (IDAction) Error added in v0.1.10 

func (id IDAction) Error() string

Error implements error.

func (IDAction) Errorf added in v0.1.10 

func (id IDAction) Errorf(ctx *context.T, format string, params ...interface{}) error

Errorf creates a new verror.E that uses fmt.Errorf style formatting and is not intended for localization. Errorf prepends the component and operation name if they can be extracted from the context. It supports %w for errors.Unwrap which takes precedence over using the last parameter if it's an error as the error to be returned by Unwrap.

func (IDAction) Is added in v0.1.10 

func (id IDAction) Is(err error) bool

Is implements the Is method as expected by errors.Is.

func (IDAction) Message added in v0.1.10 

func (id IDAction) Message(ctx *context.T, msg string, params ...interface{}) error

Message is intended for pre-internationalizated messages. The msg is assumed to be have been preformated and the params are recorded in E.ParamList. If the last parameter is an error it will returned by Unwrap.

type PCs 

type PCs []uintptr

PCs represents a list of PC locations

func Stack 

func Stack(err error) PCs

Stack returns the list of PC locations on the stack when this error was first generated within this address space, or an empty list if err is not an E.

func (PCs) String 

func (st PCs) String() string

type SubErr 

type SubErr struct {
	Name    string
	Err     error
	Options SubErrOpts
}

A SubErr represents a (string, error, int32) triple, It is the element type for SubErrs.

func (SubErr) Error added in v0.1.10 

func (subErr SubErr) Error() string

Error implements error.

func (SubErr) String added in v0.1.10 

func (subErr SubErr) String() string

type SubErrOpts 

type SubErrOpts uint32
const (
	// Print, when set in SubErr.Options, tells Error() to print this SubErr.
	Print SubErrOpts = 0x1
)

type SubErrs 

type SubErrs []SubErr

A SubErrs is a special type that allows clients to include a list of subordinate errors to an error's parameter list. Clients can add a SubErrs to the parameter list directly, via New() or include one in an existing error using AddSubErrs(). Each element of the slice has a name, an error, and an integer that encodes options such as verror.Print as bits set within it. By convention, clients are expected to use name of the form "X=Y" to distinguish their subordinate errors from those of other abstraction layers. For example, a layer reporting on errors in individual blessings in an RPC might use strings like "blessing=<blessing_name>".

func (SubErrs) String 

func (subErrs SubErrs) String() (result string)

String is the default printing function for SubErrs.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.