feat: custom failures (#55)

This PR changes the server handler return types.

Previously a handler signature was:

```go
func[O any](Context, Capability[C], Invocation, InvocationContext) (O, fx.Effects, error)
```

It is now:

```go
func[O any, X failure.IPLDBuilderFailure](Context, Capability[C], Invocation, InvocationContext) (result.Result[O, X], fx.Effects, error)
```

i.e. Instead of returning a success value (`O`), it now returns a
`result.Result[O, X]`.

This allows the handler to return a custom error in a `result.Result`.
This is in the case where the error is _known_. Previously all errors
would have a `name` of `HandlerExecutionError` and the actual error
would be communicated in the `cause` property. This is awkward to unpack
on the client, is redundant (every error is currently a
`HandlerExecutionError`) and incompatible with the JS implementation.

The intention of `HandlerExecutionError` is a catch all for _unexpected
errors_, however it is currently being used to communicate _all_
failures. This is my fault for rushing the implementation.

The failure type `X` is constrained to `failure.IPLDBuilderFailure`,
which ensures known errors a) have a `name` property, b) are an `error`
(and have a message) and c) have a `ToIPLD()` method.

To summarise, handlers should communicate _known_ errors as an error
result, and unexpected errors in the `error` return value.

Note: there is an alternative to this
#56

Author: alanshaw

server/handler.go

@@ -14,13 +14,21 @@ import (
 	"github.com/storacha/go-ucanto/validator"
 )
 
-type HandlerFunc[C any, O ipld.Builder] func(ctx context.Context, capability ucan.Capability[C], invocation invocation.Invocation, context InvocationContext) (out O, fx fx.Effects, err error)
+type HandlerFunc[C any, O ipld.Builder, X failure.IPLDBuilderFailure] func(
+	ctx context.Context,
+	capability ucan.Capability[C],
+	invocation invocation.Invocation,
+	context InvocationContext,
+) (result result.Result[O, X], fx fx.Effects, err error)
 
 // Provide is used to define given capability provider. It decorates the passed
 // handler and takes care of UCAN validation. It only calls the handler
 // when validation succeeds.
-func Provide[C any, O ipld.Builder](capability validator.CapabilityParser[C], handler HandlerFunc[C, O]) ServiceMethod[O] {
-	return func(ctx context.Context, invocation invocation.Invocation, ictx InvocationContext) (transaction.Transaction[O, ipld.Builder], error) {
+func Provide[C any, O ipld.Builder, X failure.IPLDBuilderFailure](
+	capability validator.CapabilityParser[C],
+	handler HandlerFunc[C, O, X],
+) ServiceMethod[O, failure.IPLDBuilderFailure] {
+	return func(ctx context.Context, invocation invocation.Invocation, ictx InvocationContext) (transaction.Transaction[O, failure.IPLDBuilderFailure], error) {
 		vctx := validator.NewValidationContext(
 			ictx.ID().Verifier(),
 			capability,
@@ -46,19 +54,26 @@ func Provide[C any, O ipld.Builder](capability validator.CapabilityParser[C], ha
 		if _, err := acceptedAudiences.Read(invocation.Audience().DID().String()); err != nil {
 			expectedAudiences := append([]ucan.Principal{ictx.ID()}, ictx.AlternativeAudiences()...)
 			audErr := NewInvalidAudienceError(invocation.Audience(), expectedAudiences...)
-			return transaction.NewTransaction(result.Error[O, ipld.Builder](audErr)), nil
+			return transaction.NewTransaction(result.Error[O, failure.IPLDBuilderFailure](audErr)), nil
 		}
 
 		auth, aerr := validator.Access(ctx, invocation, vctx)
 		if aerr != nil {
-			return transaction.NewTransaction(result.Error[O, ipld.Builder](failure.FromError(aerr))), nil
+			return transaction.NewTransaction(result.Error[O](failure.FromError(aerr))), nil
 		}
 
-		o, fx, herr := handler(ctx, auth.Capability(), invocation, ictx)
+		res, fx, herr := handler(ctx, auth.Capability(), invocation, ictx)
 		if herr != nil {
 			return nil, herr
 		}
 
-		return transaction.NewTransaction(result.Ok[O, ipld.Builder](o), transaction.WithEffects(fx)), nil
+		return transaction.NewTransaction(
+			result.MapResultR0(
+				res,
+				func(o O) O { return o },
+				func(x X) failure.IPLDBuilderFailure { return x },
+			),
+			transaction.WithEffects(fx),
+		), nil
 	}
 }

server/options.go

@@ -7,6 +7,7 @@ import (
 	"github.com/storacha/go-ucanto/core/invocation"
 	"github.com/storacha/go-ucanto/core/ipld"
 	"github.com/storacha/go-ucanto/core/result"
+	"github.com/storacha/go-ucanto/core/result/failure"
 	"github.com/storacha/go-ucanto/server/transaction"
 	"github.com/storacha/go-ucanto/transport"
 	"github.com/storacha/go-ucanto/ucan"
@@ -29,14 +30,18 @@ type srvConfig struct {
 	catch                 ErrorHandlerFunc
 }
 
-func WithServiceMethod[O ipld.Builder](can string, handleFunc ServiceMethod[O]) Option {
+func WithServiceMethod[O ipld.Builder, X failure.IPLDBuilderFailure](can string, handleFunc ServiceMethod[O, X]) Option {
 	return func(cfg *srvConfig) error {
-		cfg.service[can] = func(ctx context.Context, input invocation.Invocation, invCtx InvocationContext) (transaction.Transaction[ipld.Builder, ipld.Builder], error) {
+		cfg.service[can] = func(ctx context.Context, input invocation.Invocation, invCtx InvocationContext) (transaction.Transaction[ipld.Builder, failure.IPLDBuilderFailure], error) {
 			tx, err := handleFunc(ctx, input, invCtx)
 			if err != nil {
 				return nil, err
 			}
-			out := result.MapOk(tx.Out(), func(o O) ipld.Builder { return o })
+			out := result.MapResultR0(
+				tx.Out(),
+				func(o O) ipld.Builder { return o },
+				func(x X) failure.IPLDBuilderFailure { return x },
+			)
 			return transaction.NewTransaction(out, transaction.WithEffects(tx.Fx())), nil
 		}
 		return nil

server/server.go

@@ -17,6 +17,7 @@ import (
 	"github.com/storacha/go-ucanto/core/message"
 	"github.com/storacha/go-ucanto/core/receipt"
 	"github.com/storacha/go-ucanto/core/result"
+	"github.com/storacha/go-ucanto/core/result/failure"
 	"github.com/storacha/go-ucanto/did"
 	"github.com/storacha/go-ucanto/principal"
 	"github.com/storacha/go-ucanto/principal/ed25519/verifier"
@@ -44,11 +45,15 @@ type InvocationContext interface {
 }
 
 // ServiceMethod is an invocation handler.
-type ServiceMethod[O ipld.Builder] func(context.Context, invocation.Invocation, InvocationContext) (transaction.Transaction[O, ipld.Builder], error)
+type ServiceMethod[O ipld.Builder, X failure.IPLDBuilderFailure] func(
+	context.Context,
+	invocation.Invocation,
+	InvocationContext,
+) (transaction.Transaction[O, X], error)
 
 // Service is a mapping of service names to handlers, used to define a
 // service implementation.
-type Service = map[ucan.Ability]ServiceMethod[ipld.Builder]
+type Service = map[ucan.Ability]ServiceMethod[ipld.Builder, failure.IPLDBuilderFailure]
 
 type ServiceInvocation = invocation.IssuedInvocation
 

server/server_test.go

@@ -74,6 +74,31 @@ func (ok uploadAddSuccess) ToIPLD() (ipld.Node, error) {
 	return nb.Build(), nil
 }
 
+type uploadAddFailure struct {
+	name    string
+	message string
+}
+
+func (x uploadAddFailure) Name() string {
+	return x.name
+}
+
+func (x uploadAddFailure) Error() string {
+	return x.message
+}
+
+func (x uploadAddFailure) ToIPLD() (ipld.Node, error) {
+	np := basicnode.Prototype.Any
+	nb := np.NewBuilder()
+	ma, _ := nb.BeginMap(2)
+	ma.AssembleKey().AssignString("name")
+	ma.AssembleValue().AssignString(x.name)
+	ma.AssembleKey().AssignString("message")
+	ma.AssembleValue().AssignString(x.message)
+	ma.Finish()
+	return nb.Build(), nil
+}
+
 var rcptsch = []byte(`
 	type Result union {
 		| UploadAddSuccess "ok"
@@ -129,8 +154,8 @@ func TestExecute(t *testing.T) {
 			fixtures.Service,
 			WithServiceMethod(
 				uploadadd.Can(),
-				Provide(uploadadd, func(ctx context.Context, cap ucan.Capability[uploadAddCaveats], inv invocation.Invocation, ictx InvocationContext) (uploadAddSuccess, fx.Effects, error) {
-					return uploadAddSuccess{Root: cap.Nb().Root, Status: "done"}, nil, nil
+				Provide(uploadadd, func(ctx context.Context, cap ucan.Capability[uploadAddCaveats], inv invocation.Invocation, ictx InvocationContext) (result.Result[uploadAddSuccess, uploadAddFailure], fx.Effects, error) {
+					return result.Ok[uploadAddSuccess, uploadAddFailure](uploadAddSuccess{Root: cap.Nb().Root, Status: "done"}), nil, nil
 				}),
 			),
 		))
@@ -152,13 +177,13 @@ func TestExecute(t *testing.T) {
 		rcpt := helpers.Must(reader.Read(rcptlnk, resp.Blocks()))
 
 		result.MatchResultR0(rcpt.Out(), func(ok uploadAddSuccess) {
-			fmt.Printf("%+v\n", ok)
+			t.Logf("%+v\n", ok)
 			require.Equal(t, ok.Root, rt)
 			require.Equal(t, ok.Status, "done")
 		}, func(x ipld.Node) {
 			f := asFailure(t, x)
-			fmt.Println(f.Message)
-			fmt.Println(*f.Stack)
+			t.Log(f.Message)
+			t.Log(*f.Stack)
 			require.Nil(t, f)
 		})
 	})
@@ -175,8 +200,8 @@ func TestExecute(t *testing.T) {
 			fixtures.Service,
 			WithServiceMethod(
 				uploadadd.Can(),
-				Provide(uploadadd, func(ctx context.Context, cap ucan.Capability[uploadAddCaveats], inv invocation.Invocation, ictx InvocationContext) (uploadAddSuccess, fx.Effects, error) {
-					return uploadAddSuccess{Root: cap.Nb().Root, Status: "done"}, nil, nil
+				Provide(uploadadd, func(ctx context.Context, cap ucan.Capability[uploadAddCaveats], inv invocation.Invocation, ictx InvocationContext) (result.Result[uploadAddSuccess, uploadAddFailure], fx.Effects, error) {
+					return result.Ok[uploadAddSuccess, uploadAddFailure](uploadAddSuccess{Root: cap.Nb().Root, Status: "done"}), nil, nil
 				}),
 			),
 		))
@@ -208,13 +233,13 @@ func TestExecute(t *testing.T) {
 		rcpt := helpers.Must(reader.Read(rcptlnk, resp.Blocks()))
 
 		result.MatchResultR0(rcpt.Out(), func(ok uploadAddSuccess) {
-			fmt.Printf("%+v\n", ok)
+			t.Logf("%+v\n", ok)
 			require.Equal(t, ok.Root, rt)
 			require.Equal(t, ok.Status, "done")
 		}, func(x ipld.Node) {
 			f := asFailure(t, x)
-			fmt.Println(f.Message)
-			fmt.Println(*f.Stack)
+			t.Log(f.Message)
+			t.Log(*f.Stack)
 			require.Nil(t, f)
 		})
 	})
@@ -242,7 +267,7 @@ func TestExecute(t *testing.T) {
 			t.Fatalf("expected error: %s", invs[0].Link())
 		}, func(x ipld.Node) {
 			f := asFailure(t, x)
-			fmt.Printf("%s %+v\n", *f.Name, f)
+			t.Logf("%s %+v\n", *f.Name, f)
 			require.Equal(t, *f.Name, "HandlerNotFoundError")
 		})
 	})
@@ -259,8 +284,8 @@ func TestExecute(t *testing.T) {
 			fixtures.Service,
 			WithServiceMethod(
 				uploadadd.Can(),
-				Provide(uploadadd, func(ctx context.Context, cap ucan.Capability[uploadAddCaveats], inv invocation.Invocation, ictx InvocationContext) (uploadAddSuccess, fx.Effects, error) {
-					return uploadAddSuccess{}, nil, fmt.Errorf("test error")
+				Provide(uploadadd, func(ctx context.Context, cap ucan.Capability[uploadAddCaveats], inv invocation.Invocation, ictx InvocationContext) (result.Result[uploadAddSuccess, uploadAddFailure], fx.Effects, error) {
+					return nil, nil, fmt.Errorf("test error")
 				}),
 			),
 		))
@@ -280,11 +305,49 @@ func TestExecute(t *testing.T) {
 			t.Fatalf("expected error: %s", invs[0].Link())
 		}, func(x ipld.Node) {
 			f := asFailure(t, x)
-			fmt.Printf("%s %+v\n", *f.Name, f)
+			t.Logf("%s %+v\n", *f.Name, f)
 			require.Equal(t, *f.Name, "HandlerExecutionError")
 		})
 	})
 
+	t.Run("failure", func(t *testing.T) {
+		uploadadd := validator.NewCapability(
+			"upload/add",
+			schema.DIDString(),
+			schema.Struct[uploadAddCaveats](uploadAddCaveatsType(), nil),
+			nil,
+		)
+
+		server := helpers.Must(NewServer(
+			fixtures.Service,
+			WithServiceMethod(
+				uploadadd.Can(),
+				Provide(uploadadd, func(ctx context.Context, cap ucan.Capability[uploadAddCaveats], inv invocation.Invocation, ictx InvocationContext) (result.Result[uploadAddSuccess, uploadAddFailure], fx.Effects, error) {
+					return result.Error[uploadAddSuccess](uploadAddFailure{name: "UploadAddError", message: "boom"}), nil, nil
+				}),
+			),
+		))
+
+		conn := helpers.Must(client.NewConnection(fixtures.Service, server))
+		rt := cidlink.Link{Cid: cid.MustParse("bafkreiem4twkqzsq2aj4shbycd4yvoj2cx72vezicletlhi7dijjciqpui")}
+		cap := uploadadd.New(fixtures.Alice.DID().String(), uploadAddCaveats{Root: rt})
+		invs := []invocation.Invocation{helpers.Must(invocation.Invoke(fixtures.Alice, fixtures.Service, cap))}
+		resp := helpers.Must(client.Execute(t.Context(), invs, conn))
+		rcptlnk, ok := resp.Get(invs[0].Link())
+		require.True(t, ok, "missing receipt for invocation: %s", invs[0].Link())
+
+		reader := helpers.Must(receipt.NewReceiptReader[uploadAddSuccess, ipld.Node](rcptsch))
+		rcpt := helpers.Must(reader.Read(rcptlnk, resp.Blocks()))
+
+		result.MatchResultR0(rcpt.Out(), func(uploadAddSuccess) {
+			t.Fatalf("expected error: %s", invs[0].Link())
+		}, func(x ipld.Node) {
+			f := asFailure(t, x)
+			t.Logf("%s %+v\n", *f.Name, f)
+			require.Equal(t, *f.Name, "UploadAddError")
+		})
+	})
+
 	t.Run("invalid audience", func(t *testing.T) {
 		uploadadd := validator.NewCapability(
 			"upload/add",
@@ -297,8 +360,8 @@ func TestExecute(t *testing.T) {
 			fixtures.Service,
 			WithServiceMethod(
 				uploadadd.Can(),
-				Provide(uploadadd, func(ctx context.Context, cap ucan.Capability[uploadAddCaveats], inv invocation.Invocation, ictx InvocationContext) (uploadAddSuccess, fx.Effects, error) {
-					return uploadAddSuccess{Root: cap.Nb().Root, Status: "done"}, nil, nil
+				Provide(uploadadd, func(ctx context.Context, cap ucan.Capability[uploadAddCaveats], inv invocation.Invocation, ictx InvocationContext) (result.Result[uploadAddSuccess, uploadAddFailure], fx.Effects, error) {
+					return result.Ok[uploadAddSuccess, uploadAddFailure](uploadAddSuccess{Root: cap.Nb().Root, Status: "done"}), nil, nil
 				}),
 			),
 		))
@@ -339,8 +402,8 @@ func TestExecute(t *testing.T) {
 			fixtures.Service,
 			WithServiceMethod(
 				uploadadd.Can(),
-				Provide(uploadadd, func(ctx context.Context, cap ucan.Capability[uploadAddCaveats], inv invocation.Invocation, ictx InvocationContext) (uploadAddSuccess, fx.Effects, error) {
-					return uploadAddSuccess{Root: cap.Nb().Root, Status: "done"}, nil, nil
+				Provide(uploadadd, func(ctx context.Context, cap ucan.Capability[uploadAddCaveats], inv invocation.Invocation, ictx InvocationContext) (result.Result[uploadAddSuccess, uploadAddFailure], fx.Effects, error) {
+					return result.Ok[uploadAddSuccess, uploadAddFailure](uploadAddSuccess{Root: cap.Nb().Root, Status: "done"}), nil, nil
 				}),
 			),
 			WithAlternativeAudiences(fixtures.Bob),