grpc

Documentation

Index

• Variables
• type ErrorMatcher
• type StatusCodeConverter
• type StatusCodeMatcher
  • func NewStatusCodeMatcher(code codes.Code, errorMatcher ErrorMatcher) StatusCodeMatcher
• type StatusConverter
  • func NewDefaultStatusConverter(opts ...StatusConverterOption) StatusConverter
  • func NewStatusConverter(opts ...StatusConverterOption) StatusConverter
• type StatusConverterOption
  • func SetStatusMatchers(matchers ...StatusMatcher) StatusConverterOption
  • func WithStatusCodeConverter(converter StatusCodeConverter) StatusConverterOption
  • func WithStatusConverter(converter StatusConverter) StatusConverterOption
  • func WithStatusMatchers(matchers ...StatusMatcher) StatusConverterOption
• type StatusMatcher
  • func NewValidationStatusMatcher() StatusMatcher

Examples

• NewStatusConverter

Variables

var DefaultStatusMatchers = []StatusMatcher{
	NewStatusCodeMatcher(codes.NotFound, errors.IsNotFoundError),
	NewValidationStatusMatcher(),
	NewStatusCodeMatcher(codes.FailedPrecondition, errors.IsConflictError),
}

DefaultStatusMatchers is a list of default StatusMatchers. nolint: gochecknoglobals

Types

type ErrorMatcher

type ErrorMatcher func(err error) bool

ErrorMatcher checks if an error matches a certain condition.

type StatusCodeConverter

type StatusCodeConverter interface {
	// NewStatusWithCode creates a new gRPC status with a code from an error.
	NewStatusWithCode(ctx context.Context, code codes.Code, err error) *status.Status
}

StatusCodeConverter converts an error to a gRPC status.

type StatusCodeMatcher

type StatusCodeMatcher interface {
	StatusMatcher

	// Code returns the gRPC status code.
	Code() codes.Code
}

StatusCodeMatcher matches an error and returns the appropriate status code for it.

func NewStatusCodeMatcher

func NewStatusCodeMatcher(code codes.Code, errorMatcher ErrorMatcher) StatusCodeMatcher

NewStatusCodeMatcher returns a new StatusCodeMatcher.

type StatusConverter

type StatusConverter interface {
	// NewStatus creates a new gRPC Status from an error.
	NewStatus(ctx context.Context, err error) *status.Status
}

StatusConverter converts an error to gRPC Status.

func NewDefaultStatusConverter

func NewDefaultStatusConverter(opts ...StatusConverterOption) StatusConverter

NewStatusConverter returns a new StatusConverter implementation populated with default status matchers.

func NewStatusConverter

func NewStatusConverter(opts ...StatusConverterOption) StatusConverter

NewStatusConverter returns a new StatusConverter implementation.

Example

statusConverter := NewStatusConverter(
	WithStatusMatchers(
		NewStatusCodeMatcher(codes.NotFound, func(err error) bool { return err.Error() == "not found" }),
	),
)

err := errors.New("not found")

s := statusConverter.NewStatus(context.Background(), err)

fmt.Println(s.Code(), s.Message())

Output:

NotFound not found

type StatusConverterOption

type StatusConverterOption interface {
	// contains filtered or unexported methods
}

StatusConverterOption configures a StatusConverter using the functional options paradigm popularized by Rob Pike and Dave Cheney. If you're unfamiliar with this style, see: - https://commandcenter.blogspot.com/2014/01/self-referential-functions-and-design.html - https://dave.cheney.net/2014/10/17/functional-options-for-friendly-apis.

func SetStatusMatchers

func SetStatusMatchers(matchers ...StatusMatcher) StatusConverterOption

SetStatusMatchers configures a StatusConverter to match errors. Matchers override the existing list of matchers. If no matchers match the error (or no matchers are configured) a status with Internal code is returned.

If a matcher also implements StatusConverter it is used instead of the builtin StatusConverter for creating the status.

If a matchers also implements StatusCodeMatcher the builtin StatusCodeConverter is used for creating the status.

func WithStatusCodeConverter

func WithStatusCodeConverter(converter StatusCodeConverter) StatusConverterOption

WithStatusCodeConverter configures a StatusCodeConverter.

func WithStatusConverter

func WithStatusConverter(converter StatusConverter) StatusConverterOption

WithStatusConverter configures a StatusConverter.

func WithStatusMatchers

func WithStatusMatchers(matchers ...StatusMatcher) StatusConverterOption

WithStatusMatchers configures a StatusConverter to match errors. Matchers are appended to the existing list of matchers. If no matchers match the error (or no matchers are configured) a status with Internal code is returned.

If a matcher also implements StatusConverter it is used instead of the builtin StatusConverter for creating the status.

If a matchers also implements StatusCodeMatcher the builtin StatusCodeConverter is used for creating the status.

type StatusMatcher

type StatusMatcher interface {
	// MatchError evaluates the predefined set of conditions for err.
	MatchError(err error) bool
}

StatusMatcher matches an error. A StatusMatcher usually also implements one of the following interfaces:

• StatusCodeMatcher to indicate a gRPC status code for an error
• StatusConverter if a matched error requires special conversion logic

func NewValidationStatusMatcher

func NewValidationStatusMatcher() StatusMatcher

NewValidationStatusMatcher returns a status matcher for validation errors. If the returned error matches the following interface, violation info gets attached to the returned status:

type violationError interface {
	Violations() map[string][]string
}