errors

README

Error codes in Dapr

Introduction

This guide is intended for developers working on the Dapr code base, specifically for those updating the error handling to align with the gRPC richer error model. The goal is to standardize error responses across Dapr's services.

Prerequisites

• Familiarity with gRPC and its error model. Refer to the gRPC Richer Error Model Guide.

Step 1: Understanding the Current Error Handling

Currently, error handling in Dapr is a mix of predefined errors and dynamically constructed errors within the code.

• Predefined Errors: There are some legacy predefined errors located at /pkg/messages/predefined.go, but the new errors are located in /pkg/api/errors. These errors are standard and reused across various parts of the Dapr codebase. They provide a consistent error handling mechanism for common scenarios.
• Dynamically Constructed Errors: These errors are created on the fly within the code, typically to handle specific situations or errors that are not covered by the predefined set.

As we move predefined errors to the rich error model and a new location (pkg/api/errors), the first step in updating to the new error model is to familiarize yourself with the existing error handling patterns, both predefined and dynamically constructed. This understanding will be crucial when replacing them with the richer error model aligned with gRPC standards.

Step 2: Adding New Errors

1. Check for existing errors: Before creating a new error, check if a relevant error file exists in /pkg/api/errors/.
2. Create a new error file: If no relevant file exists, create a new file following the pattern <building-block>.go.

Step 3: Designing Rich Error Messages

1. Understand Rich Error Construction: Familiarize yourself with the construction of rich error messages. The definition can be found in github.com/dapr/kit/errors.
2. Helper Methods: Utilize the error builder and the helper methods like WithErrorInfo, WithResourceInfo to enrich error information.
3. Reference implementation: You can check out pkg/api/errors/state.go for a reference implementation. The following code snippet shows how to create a new error using the helper methods:

func StateStoreInvalidKeyName(storeName string, key string, msg string) error {
	return kiterrors.NewBuilder(
		codes.InvalidArgument,
		http.StatusBadRequest,
		msg,
		"ERR_MALFORMED_REQUEST",
	).
		WithErrorInfo(kiterrors.CodePrefixStateStore+kiterrors.CodeIllegalKey, nil).
		WithResourceInfo("state", storeName, "", "").
		WithFieldViolation(key, msg).
		Build()
}

1. Mandatory and Optional Information:
   • ErrorInfo: This is a required field.
   • ResourceInfo and other Details fields: These are optional but should be used following best practices as outlined in the Google Cloud Error Model.

Step 4: Implementing the New Error Model

1. Consistent Use: Ensure that the new error model is used consistently throughout the codebase.
2. Refactoring: Replace existing errors in the code with the newly defined rich errors.

Step 5: Testing and Integration

1. Integration Tests: Add integration tests for the new error handling mechanism.
2. Follow Existing Patterns: Use the existing integration tests for the state API as a reference for structure and best practices. For example, these are the integration tests for the errors in state api: /tests/integration/suite/daprd/state/grpc/errors.go and /tests/integration/suite/daprd/state/http/errors.go

Documentation

Index

• Constants
• func NotConfigured(name string, componentType string, metadata map[string]string, ...) error
• func NotFound(name string, componentType string, metadata map[string]string, ...) error
• func PubSubCloudEventCreation(name string, pubsubType string, metadata map[string]string) error
• func PubSubMarshalEnvelope(name string, topic string, pubsubType string, metadata map[string]string) error
• func PubSubMarshalEvents(name string, pubsubType string, topic string, metadata map[string]string) error
• func PubSubMetadataDeserialize(name string, pubsubType string, metadata map[string]string, err error) error
• func PubSubNameEmpty(name string, pubsubType string, metadata map[string]string) error
• func PubSubOubox(appID string, err error) error
• func PubSubPublishForbidden(name string, pubsubType string, topic string, appID string, err error) error
• func PubSubPublishMessage(name string, pubsubType string, topic string, err error) error
• func PubSubTestNotFound(name string, pubsubType string, topic string, err error) error
• func PubSubTopicEmpty(name string, pubsubType string, metadata map[string]string) error
• func PubSubUnMarshalEvents(name string, pubsubType string, topic string, metadata map[string]string, ...) error
• func StateStoreInvalidKeyName(storeName string, key string, msg string) error
• func StateStoreQueryFailed(storeName string, detail string) error
• func StateStoreQueryUnsupported(storeName string) error
• func StateStoreTooManyTransactionalOps(storeName string, count int, max int) error
• func StateStoreTransactionsNotSupported(storeName string) error

Constants

const (
	InFixTopic                     = "TOPIC"
	PostFixNameEmpty               = "NAME_EMPTY"
	PostFixMetadataDeserialization = "METADATA_DESERIALIZATION"
	PostFixPublishMessage          = "PUBLISH_MESSAGE"
	PostFixCloudEventCreation      = "CLOUD_EVENT_CREATION"
	PostFixMarshalEnvelope         = "MARSHAL_ENVELOPE"
	PostFixMarshalEvents           = "MARSHAL_EVENTS"
	PostFixUnMarshalEvents         = "UNMARSHAL_EVENTS"
	PostFixForbidden               = "FORBIDDEN"
	PostFixOutbox                  = "OUTBOX"
)

Functions

func NotConfigured

func NotConfigured(name string, componentType string, metadata map[string]string, grpcCode codes.Code, httpCode int, legacyTag string, reason string) error

func NotFound

func NotFound(name string, componentType string, metadata map[string]string, grpcCode codes.Code, httpCode int, legacyTag string, reason string) error

func PubSubCloudEventCreation

func PubSubCloudEventCreation(name string, pubsubType string, metadata map[string]string) error

func PubSubMarshalEnvelope

func PubSubMarshalEnvelope(name string, topic string, pubsubType string, metadata map[string]string) error

func PubSubMarshalEvents

func PubSubMarshalEvents(name string, pubsubType string, topic string, metadata map[string]string) error

func PubSubMetadataDeserialize

func PubSubMetadataDeserialize(name string, pubsubType string, metadata map[string]string, err error) error

func PubSubNameEmpty

func PubSubNameEmpty(name string, pubsubType string, metadata map[string]string) error

func PubSubOubox

func PubSubOubox(appID string, err error) error

func PubSubPublishForbidden

func PubSubPublishForbidden(name string, pubsubType string, topic string, appID string, err error) error

func PubSubPublishMessage

func PubSubPublishMessage(name string, pubsubType string, topic string, err error) error

func PubSubTestNotFound

func PubSubTestNotFound(name string, pubsubType string, topic string, err error) error

This is specifically for the error we are expecting for the api_tests. The not found expected error codes are different than the existing ones for PubSubNotFound, hence why this one is needed

func PubSubTopicEmpty

func PubSubTopicEmpty(name string, pubsubType string, metadata map[string]string) error

func PubSubUnMarshalEvents

func PubSubUnMarshalEvents(name string, pubsubType string, topic string, metadata map[string]string, err error) error

PubSubUnMarshalEvents only occurs in http/api.go

func StateStoreInvalidKeyName

func StateStoreInvalidKeyName(storeName string, key string, msg string) error

func StateStoreQueryFailed

func StateStoreQueryFailed(storeName string, detail string) error

func StateStoreQueryUnsupported

func StateStoreQueryUnsupported(storeName string) error

func StateStoreTooManyTransactionalOps

func StateStoreTooManyTransactionalOps(storeName string, count int, max int) error

func StateStoreTransactionsNotSupported

func StateStoreTransactionsNotSupported(storeName string) error