Failure Converter (#29)

💥 BREAKING CHANGE 💥 

- Add a `FailureConverter` to convert from a `Failure` to `error` and
back and remove `Failure` from the main SDK APIs.
- Changed `HandlerError` to take a `Cause error` instead of a `Failure`
object.
- `HandlerError` gets an `Unwrap()` method for use with helpers in the
`errors` package.
- Changed `UnsuccessfulOperationError` to take a `Cause error` instead
of a `Failure` object.
- `UnsuccessfulOperationError` gets an `Unwrap()` method for use with
helpers in the `errors` package.
- Added new shorthand constructors for `UnsuccessfulOperationError`:
`NewFailedOperationError` and `NewCanceledOperationError`.
- Added a new `NewOperationCompletionUnsuccessful` constructor that
takes an error object and options to support a failure converter.
- Rename `StartLinks` to `Links`.

Author: bergundy

README.md

@@ -60,11 +60,11 @@ result, err := nexus.StartOperation(ctx, client, operation, MyInput{Field: "valu
 if err != nil {
 	var unsuccessfulOperationError *nexus.UnsuccessfulOperationError
 	if errors.As(err, &unsuccessfulOperationError) { // operation failed or canceled
-		fmt.Printf("Operation unsuccessful with state: %s, failure message: %s\n", unsuccessfulOperationError.State, unsuccessfulOperationError.Failure.Message)
+		fmt.Printf("Operation unsuccessful with state: %s, failure message: %s\n", unsuccessfulOperationError.State, unsuccessfulOperationError.Cause.Error())
 	}
 	var handlerError *nexus.HandlerError
 	if errors.As(err, &handlerError) {
-		fmt.Printf("Handler returned an error, type: %s, failure message: %s\n", handlerError.Type, handlerError.Failure.Message)
+		fmt.Printf("Handler returned an error, type: %s, failure message: %s\n", handlerError.Type, handlerError.Cause.Error())
 	}
 	// most other errors should be returned as *nexus.UnexpectedResponseError
 }
@@ -209,16 +209,13 @@ _, err = io.ReadAll(response.Body)
 fmt.Println("delivered completion with status code", response.StatusCode)
 ```
 
-To deliver failed and canceled completions, pass a `OperationCompletionUnsuccessful` struct pointer with the failure and
-state attached.
+To deliver failed and canceled completions, pass a `OperationCompletionUnsuccessful` struct pointer constructed with
+`NewOperationCompletionUnsuccessful`.
 
 Custom HTTP headers may be provided via `OperationCompletionUnsuccessful.Header`.
 
 ```go
-completion := &OperationCompletionUnsuccessful{
-	State: nexus.OperationStateCanceled,
-	Failure: &nexus.Failure{Message: "canceled as requested"},
-}
+completion := nexus.NewOperationCompletionUnsuccessful(nexus.NewOperationFailedError(fmt.Errorf("some error")), nexus.OperationCompletionUnsuccessfulOptions{})
 request, _ := nexus.NewCompletionHTTPRequest(ctx, callbackURL, completion)
 // ...
 ```
@@ -290,10 +287,8 @@ _ = http.Serve(listener, httpHandler)
 
 ```go
 func (h *myArbitraryLengthOperation) Start(ctx context.Context, input MyInput, options nexus.StartOperationOptions) (nexus.HandlerStartOperationResult[MyOutput], error) {
-	return nil, &nexus.UnsuccessfulOperationError{
-		State: nexus.OperationStateFailed, // or OperationStateCanceled
-		Failure: &nexus.Failure{Message: "Do or do not, there is not try"},
-	}
+	// Alternatively use NewCanceledOperationError to resolve an operation as canceled.
+	return nil, nexus.NewFailedOperationError(errors.New("Do or do not, there is not try"))
 }
 ```
 
@@ -329,14 +324,14 @@ func (h *myArbitraryLengthOperation) GetResult(ctx context.Context, id string, o
 			}
 			// Optionally translate to operation failure (could also result in canceled state).
 			// Optionally expose the error details to the caller.
-			return nil, &nexus.UnsuccessfulOperationError{State: nexus.OperationStateFailed, Failure: nexus.Failure{Message: err.Error()}}
+			return nil, nexus.NewFailedOperationError(err)
 		}
 		return result, nil
 	} else {
 		result, err := h.peekOperation(ctx)
 		if err != nil {
 			// Optionally translate to operation failure (could also result in canceled state).
-			return nil, &nexus.UnsuccessfulOperationError{State: nexus.OperationStateFailed, Failure: nexus.Failure{Message: err.Error()}}
+			return nil, nexus.NewFailedOperationError(err)
 		}
 		return result, nil
 	}

nexus/api.go

@@ -53,7 +53,9 @@ const (
 	StatusUpstreamTimeout = 520
 )
 
-// A Failure represents failed handler invocations as well as `failed` or `canceled` operation results.
+// A Failure represents failed handler invocations as well as `failed` or `canceled` operation results. Failures
+// shouldn't typically be constructed directly. The SDK APIs take a [FailureConverter] instance that can translate
+// language errors to and from [Failure] instances.
 type Failure struct {
 	// A simple text message.
 	Message string `json:"message"`
@@ -63,18 +65,55 @@ type Failure struct {
 	Details json.RawMessage `json:"details,omitempty"`
 }
 
+// An error that directly represents a wire representation of [Failure].
+// The SDK will convert to this error by default unless the [FailureConverter] instance is customized.
+type FailureError struct {
+	// The underlying Failure object this error represents.
+	Failure Failure
+}
+
+// Error implements the error interface.
+func (e *FailureError) Error() string {
+	return e.Failure.Message
+}
+
 // UnsuccessfulOperationError represents "failed" and "canceled" operation results.
 type UnsuccessfulOperationError struct {
-	State   OperationState
-	Failure Failure
+	// State of the operation. Only [OperationStateFailed] and [OperationStateCanceled] are valid.
+	State OperationState
+	// The underlying cause for this error.
+	Cause error
+}
+
+// NewFailedOperationError is shorthand for constructing an [UnsuccessfulOperationError] with State set to
+// [OperationStateFailed] and the given err as the Cause.
+func NewFailedOperationError(err error) *UnsuccessfulOperationError {
+	return &UnsuccessfulOperationError{
+		State: OperationStateFailed,
+		Cause: err,
+	}
+}
+
+// NewFailedOperationError is shorthand for constructing an [UnsuccessfulOperationError] with State set to
+// [OperationStateCanceled] and the given err as the Cause.
+func NewCanceledOperationError(err error) *UnsuccessfulOperationError {
+	return &UnsuccessfulOperationError{
+		State: OperationStateCanceled,
+		Cause: err,
+	}
 }
 
 // Error implements the error interface.
 func (e *UnsuccessfulOperationError) Error() string {
-	if e.Failure.Message != "" {
-		return fmt.Sprintf("operation %s: %s", e.State, e.Failure.Message)
+	if e.Cause == nil {
+		return fmt.Sprintf("operation %s", e.State)
 	}
-	return fmt.Sprintf("operation %s", e.State)
+	return fmt.Sprintf("operation %s: %s", e.State, e.Cause.Error())
+}
+
+// Unwrap returns the cause for use with utilities in the errors package.
+func (e *UnsuccessfulOperationError) Unwrap() error {
+	return e.Cause
 }
 
 // ErrOperationStillRunning indicates that an operation is still running while trying to get its result.

nexus/client.go

@@ -27,8 +27,11 @@ type HTTPClientOptions struct {
 	// Defaults to [http.DefaultClient.Do].
 	HTTPCaller func(*http.Request) (*http.Response, error)
 	// A [Serializer] to customize client serialization behavior.
-	// By default the client handles, JSONables, byte slices, and nil.
+	// By default the client handles JSONables, byte slices, and nil.
 	Serializer Serializer
+	// A [FailureConverter] to convert a [Failure] instance to and from an [error]. Defaults to
+	// [DefaultFailureConverter].
+	FailureConverter FailureConverter
 }
 
 // User-Agent header set on HTTP requests.
@@ -114,6 +117,9 @@ func NewHTTPClient(options HTTPClientOptions) (*HTTPClient, error) {
 	if options.Serializer == nil {
 		options.Serializer = defaultSerializer
 	}
+	if options.FailureConverter == nil {
+		options.FailureConverter = defaultFailureConverter
+	}
 
 	return &HTTPClient{
 		options:        options,
@@ -267,17 +273,18 @@ func (c *HTTPClient) StartOperation(
 			return nil, err
 		}
 
-		failure, err := failureFromResponse(response, body)
+		failure, err := c.failureFromResponse(response, body)
 		if err != nil {
 			return nil, err
 		}
 
+		failureErr := c.options.FailureConverter.FailureToError(failure)
 		return nil, &UnsuccessfulOperationError{
-			State:   state,
-			Failure: failure,
+			State: state,
+			Cause: failureErr,
 		}
 	default:
-		return nil, bestEffortHandlerErrorFromResponse(response, body)
+		return nil, c.bestEffortHandlerErrorFromResponse(response, body)
 	}
 }
 
@@ -393,7 +400,7 @@ func operationInfoFromResponse(response *http.Response, body []byte) (*Operation
 	return &info, nil
 }
 
-func failureFromResponse(response *http.Response, body []byte) (Failure, error) {
+func (c *HTTPClient) failureFromResponse(response *http.Response, body []byte) (Failure, error) {
 	if !isMediaTypeJSON(response.Header.Get("Content-Type")) {
 		return Failure{}, newUnexpectedResponseError(fmt.Sprintf("invalid response content type: %q", response.Header.Get("Content-Type")), response, body)
 	}
@@ -402,43 +409,49 @@ func failureFromResponse(response *http.Response, body []byte) (Failure, error)
 	return failure, err
 }
 
-func failureFromResponseOrDefault(response *http.Response, body []byte, defaultMessage string) Failure {
-	failure, err := failureFromResponse(response, body)
+func (c *HTTPClient) failureFromResponseOrDefault(response *http.Response, body []byte, defaultMessage string) Failure {
+	failure, err := c.failureFromResponse(response, body)
 	if err != nil {
 		failure.Message = defaultMessage
 	}
 	return failure
 }
 
-func bestEffortHandlerErrorFromResponse(response *http.Response, body []byte) error {
+func (c *HTTPClient) failureErrorFromResponseOrDefault(response *http.Response, body []byte, defaultMessage string) error {
+	failure := c.failureFromResponseOrDefault(response, body, defaultMessage)
+	failureErr := c.options.FailureConverter.FailureToError(failure)
+	return failureErr
+}
+
+func (c *HTTPClient) bestEffortHandlerErrorFromResponse(response *http.Response, body []byte) error {
 	switch response.StatusCode {
 	case http.StatusBadRequest:
-		failure := failureFromResponseOrDefault(response, body, "bad request")
-		return &HandlerError{Type: HandlerErrorTypeBadRequest, Failure: &failure}
+		failureErr := c.failureErrorFromResponseOrDefault(response, body, "bad request")
+		return &HandlerError{Type: HandlerErrorTypeBadRequest, Cause: failureErr}
 	case http.StatusUnauthorized:
-		failure := failureFromResponseOrDefault(response, body, "unauthenticated")
-		return &HandlerError{Type: HandlerErrorTypeUnauthenticated, Failure: &failure}
+		failureErr := c.failureErrorFromResponseOrDefault(response, body, "unauthenticated")
+		return &HandlerError{Type: HandlerErrorTypeUnauthenticated, Cause: failureErr}
 	case http.StatusForbidden:
-		failure := failureFromResponseOrDefault(response, body, "unauthorized")
-		return &HandlerError{Type: HandlerErrorTypeUnauthorized, Failure: &failure}
+		failureErr := c.failureErrorFromResponseOrDefault(response, body, "unauthorized")
+		return &HandlerError{Type: HandlerErrorTypeUnauthorized, Cause: failureErr}
 	case http.StatusNotFound:
-		failure := failureFromResponseOrDefault(response, body, "not found")
-		return &HandlerError{Type: HandlerErrorTypeNotFound, Failure: &failure}
+		failureErr := c.failureErrorFromResponseOrDefault(response, body, "not found")
+		return &HandlerError{Type: HandlerErrorTypeNotFound, Cause: failureErr}
 	case http.StatusTooManyRequests:
-		failure := failureFromResponseOrDefault(response, body, "resource exhausted")
-		return &HandlerError{Type: HandlerErrorTypeResourceExhausted, Failure: &failure}
+		failureErr := c.failureErrorFromResponseOrDefault(response, body, "resource exhausted")
+		return &HandlerError{Type: HandlerErrorTypeResourceExhausted, Cause: failureErr}
 	case http.StatusInternalServerError:
-		failure := failureFromResponseOrDefault(response, body, "internal error")
-		return &HandlerError{Type: HandlerErrorTypeInternal, Failure: &failure}
+		failureErr := c.failureErrorFromResponseOrDefault(response, body, "internal error")
+		return &HandlerError{Type: HandlerErrorTypeInternal, Cause: failureErr}
 	case http.StatusNotImplemented:
-		failure := failureFromResponseOrDefault(response, body, "not implemented")
-		return &HandlerError{Type: HandlerErrorTypeNotImplemented, Failure: &failure}
+		failureErr := c.failureErrorFromResponseOrDefault(response, body, "not implemented")
+		return &HandlerError{Type: HandlerErrorTypeNotImplemented, Cause: failureErr}
 	case http.StatusServiceUnavailable:
-		failure := failureFromResponseOrDefault(response, body, "unavailable")
-		return &HandlerError{Type: HandlerErrorTypeUnavailable, Failure: &failure}
+		failureErr := c.failureErrorFromResponseOrDefault(response, body, "unavailable")
+		return &HandlerError{Type: HandlerErrorTypeUnavailable, Cause: failureErr}
 	case StatusUpstreamTimeout:
-		failure := failureFromResponseOrDefault(response, body, "upstream timeout")
-		return &HandlerError{Type: HandlerErrorTypeUpstreamTimeout, Failure: &failure}
+		failureErr := c.failureErrorFromResponseOrDefault(response, body, "upstream timeout")
+		return &HandlerError{Type: HandlerErrorTypeUpstreamTimeout, Cause: failureErr}
 	default:
 		return newUnexpectedResponseError(fmt.Sprintf("unexpected response status: %q", response.Status), response, body)
 	}

nexus/client_example_test.go

@@ -20,11 +20,11 @@ func ExampleHTTPClient_StartOperation() {
 	if err != nil {
 		var unsuccessfulOperationError *nexus.UnsuccessfulOperationError
 		if errors.As(err, &unsuccessfulOperationError) { // operation failed or canceled
-			fmt.Printf("Operation unsuccessful with state: %s, failure message: %s\n", unsuccessfulOperationError.State, unsuccessfulOperationError.Failure.Message)
+			fmt.Printf("Operation unsuccessful with state: %s, failure message: %s\n", unsuccessfulOperationError.State, unsuccessfulOperationError.Cause.Error())
 		}
 		var handlerError *nexus.HandlerError
 		if errors.As(err, &handlerError) {
-			fmt.Printf("Handler returned an error, type: %s, failure message: %s\n", handlerError.Type, handlerError.Failure.Message)
+			fmt.Printf("Handler returned an error, type: %s, failure message: %s\n", handlerError.Type, handlerError.Cause.Error())
 		}
 		// most other errors should be returned as *nexus.UnexpectedResponseError
 	}

nexus/completion.go

@@ -142,7 +142,36 @@ type OperationCompletionUnsuccessful struct {
 	// Links are used to link back to the operation when a completion callback is received before a started response.
 	Links []Link
 	// Failure object to send with the completion.
-	Failure *Failure
+	Failure Failure
+}
+
+// OperationCompletionUnsuccessfulOptions are options for [NewOperationCompletionUnsuccessful].
+type OperationCompletionUnsuccessfulOptions struct {
+	// A [FailureConverter] to convert a [Failure] instance to and from an [error]. Defaults to
+	// [DefaultFailureConverter].
+	FailureConverter FailureConverter
+	// OperationID is the unique ID for this operation. Used when a completion callback is received before a started response.
+	OperationID string
+	// StartTime is the time the operation started. Used when a completion callback is received before a started response.
+	StartTime time.Time
+	// Links are used to link back to the operation when a completion callback is received before a started response.
+	Links []Link
+}
+
+// NewOperationCompletionUnsuccessful constructs an [OperationCompletionUnsuccessful] from a given error.
+func NewOperationCompletionUnsuccessful(error *UnsuccessfulOperationError, options OperationCompletionUnsuccessfulOptions) (*OperationCompletionUnsuccessful, error) {
+	if options.FailureConverter == nil {
+		options.FailureConverter = defaultFailureConverter
+	}
+
+	return &OperationCompletionUnsuccessful{
+		Header:      make(Header),
+		State:       error.State,
+		Failure:     options.FailureConverter.ErrorToFailure(error.Cause),
+		OperationID: options.OperationID,
+		StartTime:   options.StartTime,
+		Links:       options.Links,
+	}, nil
 }
 
 func (c *OperationCompletionUnsuccessful) applyToHTTPRequest(request *http.Request) error {
@@ -185,10 +214,10 @@ type CompletionRequest struct {
 	OperationID string
 	// StartTime is the time the operation started. Used when a completion callback is received before a started response.
 	StartTime time.Time
-	// StartLinks are used to link back to the operation when a completion callback is received before a started response.
-	StartLinks []Link
+	// Links are used to link back to the operation when a completion callback is received before a started response.
+	Links []Link
 	// Parsed from request and set if State is failed or canceled.
-	Failure *Failure
+	Error error
 	// Extracted from request and set if State is succeeded.
 	Result *LazyValue
 }
@@ -209,6 +238,9 @@ type CompletionHandlerOptions struct {
 	// A [Serializer] to customize handler serialization behavior.
 	// By default the handler handles, JSONables, byte slices, and nil.
 	Serializer Serializer
+	// A [FailureConverter] to convert a [Failure] instance to and from an [error]. Defaults to
+	// [DefaultFailureConverter].
+	FailureConverter FailureConverter
 }
 
 type completionHTTPHandler struct {
@@ -231,7 +263,7 @@ func (h *completionHTTPHandler) ServeHTTP(writer http.ResponseWriter, request *h
 		}
 	}
 	var decodeErr error
-	if completion.StartLinks, decodeErr = getLinksFromHeader(request.Header); decodeErr != nil {
+	if completion.Links, decodeErr = getLinksFromHeader(request.Header); decodeErr != nil {
 		h.writeFailure(writer, HandlerErrorf(HandlerErrorTypeBadRequest, "failed to decode links from request headers"))
 		return
 	}
@@ -251,7 +283,7 @@ func (h *completionHTTPHandler) ServeHTTP(writer http.ResponseWriter, request *h
 			h.writeFailure(writer, HandlerErrorf(HandlerErrorTypeBadRequest, "failed to read Failure from request body"))
 			return
 		}
-		completion.Failure = &failure
+		completion.Error = h.failureConverter.FailureToError(failure)
 	case OperationStateSucceeded:
 		completion.Result = &LazyValue{
 			serializer: h.options.Serializer,
@@ -277,10 +309,14 @@ func NewCompletionHTTPHandler(options CompletionHandlerOptions) http.Handler {
 	if options.Serializer == nil {
 		options.Serializer = defaultSerializer
 	}
+	if options.FailureConverter == nil {
+		options.FailureConverter = defaultFailureConverter
+	}
 	return &completionHTTPHandler{
 		options: options,
 		baseHTTPHandler: baseHTTPHandler{
-			logger: options.Logger,
+			logger:           options.Logger,
+			failureConverter: options.FailureConverter,
 		},
 	}
 }