v.io: v.io/v23/verror Index | Files

package verror

import "v.io/v23/verror"

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.

nolint:golint

Index

Package Files

compat.go init.go pkgpath.go verror.go verror.vdl.go

Variables

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 = Register("v.io/v23/verror.Unknown", NoRetry, "{1:}{2:} Error{:_}")
    // ErrInternal means an internal error has occurred.  A more specific error
    // should always be used, if possible.
    ErrInternal = Register("v.io/v23/verror.Internal", NoRetry, "{1:}{2:} Internal error{:_}")
    // ErrNotImplemented means that the request type is valid but that the method to
    // handle the request has not been implemented.
    ErrNotImplemented = Register("v.io/v23/verror.NotImplemented", NoRetry, "{1:}{2:} Not implemented{:_}")
    // ErrEndOfFile means the end-of-file has been reached; more generally, no more
    // input data is available.
    ErrEndOfFile = Register("v.io/v23/verror.EndOfFile", NoRetry, "{1:}{2:} End of file{:_}")
    // ErrBadArg means the arguments to an operation are invalid or incorrectly
    // formatted.
    ErrBadArg = Register("v.io/v23/verror.BadArg", NoRetry, "{1:}{2:} Bad argument{:_}")
    // ErrBadState means an operation was attempted on an object while the object was
    // in an incompatible state.
    ErrBadState = Register("v.io/v23/verror.BadState", NoRetry, "{1:}{2:} Invalid state{:_}")
    // 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 = Register("v.io/v23/verror.BadVersion", NoRetry, "{1:}{2:} Version is out of date")
    // ErrExist means that the requested item already exists; typically returned when
    // an attempt to create an item fails because it already exists.
    ErrExist = Register("v.io/v23/verror.Exist", NoRetry, "{1:}{2:} Already exists{:_}")
    // 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       = Register("v.io/v23/verror.NoExist", NoRetry, "{1:}{2:} Does not exist{:_}")
    ErrUnknownMethod = Register("v.io/v23/verror.UnknownMethod", NoRetry, "{1:}{2:} Method does not exist{:_}")
    ErrUnknownSuffix = Register("v.io/v23/verror.UnknownSuffix", NoRetry, "{1:}{2:} Suffix does not exist{:_}")
    // 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 = Register("v.io/v23/verror.NoExistOrNoAccess", NoRetry, "{1:}{2:} Does not exist or access denied{:_}")
    // ErrNoServers means a name was resolved to unusable or inaccessible servers.
    ErrNoServers = Register("v.io/v23/verror.NoServers", RetryRefetch, "{1:}{2:} No usable servers found{:_}")
    // ErrNoAccess means the server does not authorize the client for access.
    ErrNoAccess = Register("v.io/v23/verror.NoAccess", RetryRefetch, "{1:}{2:} Access denied{:_}")
    // ErrNotTrusted means the client does not trust the server.
    ErrNotTrusted = Register("v.io/v23/verror.NotTrusted", RetryRefetch, "{1:}{2:} Client does not trust server{:_}")
    // 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 = Register("v.io/v23/verror.Aborted", NoRetry, "{1:}{2:} Aborted{:_}")
    // ErrBadProtocol means that an operation was not completed because of a protocol
    // or codec error.
    ErrBadProtocol = Register("v.io/v23/verror.BadProtocol", NoRetry, "{1:}{2:} Bad protocol or type{:_}")
    // ErrCanceled means that an operation was not completed because it was
    // explicitly cancelled by the caller.
    ErrCanceled = Register("v.io/v23/verror.Canceled", NoRetry, "{1:}{2:} Canceled{:_}")
    // ErrTimeout means that an operation was not completed before the time deadline
    // for the operation.
    ErrTimeout = Register("v.io/v23/verror.Timeout", NoRetry, "{1:}{2:} Timeout{:_}")
)

func AddSubErrs Uses

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 Uses

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 Uses

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 Uses

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

ErrorFromNative converts from the native to wire representation of errors.

func ErrorToNative Uses

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

ErrorToNative converts from the wire to native representation of errors.

func Errorf Uses

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

Errorf is like ErrUnknown.Errorf.

func ExplicitAddSubErrs Uses

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 Uses

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 Uses

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 Uses

func FromWire(wire *vdl.WireError) error

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

func IsAny Uses

func IsAny(err error) bool

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

func Message Uses

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

Message is like ErrUnknown.Message.

func New Uses

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 Uses

func NewErrAborted(ctx *context.T) error

NewErrAborted returns an error with the ErrAborted ID.

func NewErrBadArg Uses

func NewErrBadArg(ctx *context.T) error

NewErrBadArg returns an error with the ErrBadArg ID.

func NewErrBadProtocol Uses

func NewErrBadProtocol(ctx *context.T) error

NewErrBadProtocol returns an error with the ErrBadProtocol ID.

func NewErrBadState Uses

func NewErrBadState(ctx *context.T) error

NewErrBadState returns an error with the ErrBadState ID.

func NewErrBadVersion Uses

func NewErrBadVersion(ctx *context.T) error

NewErrBadVersion returns an error with the ErrBadVersion ID.

func NewErrCanceled Uses

func NewErrCanceled(ctx *context.T) error

NewErrCanceled returns an error with the ErrCanceled ID.

func NewErrEndOfFile Uses

func NewErrEndOfFile(ctx *context.T) error

NewErrEndOfFile returns an error with the ErrEndOfFile ID.

func NewErrExist Uses

func NewErrExist(ctx *context.T) error

NewErrExist returns an error with the ErrExist ID.

func NewErrInternal Uses

func NewErrInternal(ctx *context.T) error

NewErrInternal returns an error with the ErrInternal ID.

func NewErrNoAccess Uses

func NewErrNoAccess(ctx *context.T) error

NewErrNoAccess returns an error with the ErrNoAccess ID.

func NewErrNoExist Uses

func NewErrNoExist(ctx *context.T) error

NewErrNoExist returns an error with the ErrNoExist ID.

func NewErrNoExistOrNoAccess Uses

func NewErrNoExistOrNoAccess(ctx *context.T) error

NewErrNoExistOrNoAccess returns an error with the ErrNoExistOrNoAccess ID.

func NewErrNoServers Uses

func NewErrNoServers(ctx *context.T) error

NewErrNoServers returns an error with the ErrNoServers ID.

func NewErrNotImplemented Uses

func NewErrNotImplemented(ctx *context.T) error

NewErrNotImplemented returns an error with the ErrNotImplemented ID.

func NewErrNotTrusted Uses

func NewErrNotTrusted(ctx *context.T) error

NewErrNotTrusted returns an error with the ErrNotTrusted ID.

func NewErrTimeout Uses

func NewErrTimeout(ctx *context.T) error

NewErrTimeout returns an error with the ErrTimeout ID.

func NewErrUnknown Uses

func NewErrUnknown(ctx *context.T) error

NewErrUnknown returns an error with the ErrUnknown ID.

func NewErrUnknownMethod Uses

func NewErrUnknownMethod(ctx *context.T) error

NewErrUnknownMethod returns an error with the ErrUnknownMethod ID.

func NewErrUnknownSuffix Uses

func NewErrUnknownSuffix(ctx *context.T) error

NewErrUnknownSuffix returns an error with the ErrUnknownSuffix ID.

func SetDefaultContext Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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().

type ActionCode Uses

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 Uses

func Action(err error) ActionCode

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

func (ActionCode) RetryAction Uses

func (ac ActionCode) RetryAction() ActionCode

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

type E Uses

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 Uses

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 Uses

func (e E) Is(err error) bool

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

func (E) Unwrap Uses

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 Uses

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

func (*E) VDLRead Uses

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

func (E) VDLReflect Uses

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

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

func (E) VDLWrite Uses

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

type ID Uses

type ID string

ID is a unique identifier for errors.

func ErrorID Uses

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 "".

type IDAction Uses

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 Uses

func NewID(id ID) IDAction

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

func NewIDAction Uses

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. NewIDAction will internally prepend the caller's package path to id if it's not already present.

func Register Uses

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. Register will internally prepend the caller's package path to id if it's not already present.

func (IDAction) Error Uses

func (id IDAction) Error() string

Error implements error.

func (IDAction) Errorf Uses

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 Uses

func (id IDAction) Is(err error) bool

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

func (IDAction) Message Uses

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 Uses

type PCs []uintptr

PCs represents a list of PC locations

func Stack Uses

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 Uses

func (st PCs) String() string

type SubErr Uses

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 Uses

func (subErr SubErr) Error() string

Error implements error.

func (SubErr) String Uses

func (subErr SubErr) String() string

type SubErrOpts Uses

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

type SubErrs Uses

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 Uses

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

String is the default printing function for SubErrs.

Package verror imports 16 packages (graph) and is imported by 352 packages. Updated 2020-09-24. Refresh now. Tools for package owners.