feat: receipts in the server can be logged (#67)

Ref: storacha/piri#174

When client code registers UCAN handlers in a go-ucanto server, there is
currently no way for that code to grasp the receipt the server generates
and sends back to the invoker. This PR adds a new `WithRequestLogger`
server option to register a callback the server will use to pass the
receipt back.

Additionally, a new `WithInvocation` method is added to the `Receipt`
type that allows producing a receipt with an attached invocation from
one that doesn't have it. Receipts issued by the retrieval server don't
include invocation blocks to save space in the headers, but it is useful
that logged receipts are full receipts in the sense that they also have
the invocation blocks in them.

Author: volmedo

core/receipt/receipt.go

@@ -44,6 +44,8 @@ type Receipt[O, X any] interface {
 	Signature() signature.SignatureView
 	Archive() io.Reader
 	Export() iter.Seq2[block.Block, error]
+	Clone() (Receipt[O, X], error)
+	AttachInvocation(invocation invocation.Invocation) error
 }
 
 func toResultModel[O, X any](res result.Result[O, X]) rdm.ResultModel[O, X] {
@@ -221,6 +223,54 @@ func (r *receipt[O, X]) Export() iter.Seq2[block.Block, error] {
 	return iterable.Concat2(iterators...)
 }
 
+// Clone returns a new Receipt by copying r's backing blockstore.
+func (r *receipt[O, X]) Clone() (Receipt[O, X], error) {
+	blks, err := blockstore.NewBlockStore(blockstore.WithBlocksIterator(r.blks.Iterator()))
+	if err != nil {
+		return nil, fmt.Errorf("creating block reader: %w", err)
+	}
+	return &receipt[O, X]{
+		rt:   r.rt,
+		blks: blks,
+		data: r.data,
+	}, nil
+}
+
+// AttachInvocation adds the invocation's blocks to the receipt's blockstore.
+// If r already has an invocation, it returns r unchanged.
+// If the invocation doesn't match r's ran, it returns an error.
+func (r *receipt[O, X]) AttachInvocation(invocation invocation.Invocation) error {
+	// confirm the invocation matches the receipt
+	ran := r.Ran()
+	if ran.Link().String() != invocation.Link().String() {
+		return fmt.Errorf("expected invocation with CID %s, got %s", ran.Link(), invocation.Link())
+	}
+
+	// don't add the invocation if it's already there
+	if _, ok := ran.Invocation(); ok {
+		return nil
+	}
+
+	// no need to copy receipt blocks if the backing BlockReader is actually a BlockStore
+	if bs, ok := r.blks.(blockstore.BlockStore); ok {
+		for b, err := range invocation.Export() {
+			if err != nil {
+				return fmt.Errorf("attaching invocation blocks: %w", err)
+			}
+			bs.Put(b)
+		}
+	} else {
+		blks, err := blockstore.NewBlockReader(blockstore.WithBlocksIterator(iterable.Concat2(r.blks.Iterator(), invocation.Export())))
+		if err != nil {
+			return fmt.Errorf("creating block reader: %w", err)
+		}
+
+		r.blks = blks
+	}
+
+	return nil
+}
+
 type ReceiptReader[O, X any] interface {
 	Read(rcpt ipld.Link, blks iter.Seq2[block.Block, error]) (Receipt[O, X], error)
 }

core/receipt/receipt_test.go

@@ -310,6 +310,91 @@ func TestExport(t *testing.T) {
 	require.Contains(t, blklnks, otherblk.Link().String())
 }
 
+func TestAttachInvocation(t *testing.T) {
+	inv, err := invocation.Invoke(
+		fixtures.Alice,
+		fixtures.Bob,
+		ucan.NewCapability("ran/invoke", fixtures.Alice.DID().String(), ucan.NoCaveats{}),
+	)
+	require.NoError(t, err)
+
+	out := result.Ok[someOkType, someErrorType](someOkType{SomeOkProperty: "some ok value"})
+
+	t.Run("adds invocation to receipt without one", func(t *testing.T) {
+		issuedRcpt, err := Issue(fixtures.Alice, out, ran.FromLink(inv.Link()))
+		require.NoError(t, err)
+
+		ranInv, ok := issuedRcpt.Ran().Invocation()
+		require.False(t, ok)
+		require.Nil(t, ranInv)
+
+		err = issuedRcpt.AttachInvocation(inv)
+		require.NoError(t, err)
+
+		ranInv, ok = issuedRcpt.Ran().Invocation()
+		require.True(t, ok)
+		require.Equal(t, inv.Link().String(), ranInv.Link().String())
+	})
+
+	t.Run("doesn't fail if receipt already has invocation and invocations match", func(t *testing.T) {
+		issuedRcpt, err := Issue(fixtures.Alice, out, ran.FromInvocation(inv))
+		require.NoError(t, err)
+
+		ranInv, ok := issuedRcpt.Ran().Invocation()
+		require.True(t, ok)
+		require.Equal(t, inv.Link().String(), ranInv.Link().String())
+
+		err = issuedRcpt.AttachInvocation(inv)
+		require.NoError(t, err)
+	})
+
+	t.Run("fails if receipt invocations don't match", func(t *testing.T) {
+		issuedRcpt, err := Issue(fixtures.Alice, out, ran.FromLink(inv.Link()))
+		require.NoError(t, err)
+
+		inv2, err := invocation.Invoke(
+			fixtures.Alice,
+			fixtures.Service, // previous invocation's audience is Bob
+			ucan.NewCapability("ran/invoke", fixtures.Alice.DID().String(), ucan.NoCaveats{}),
+		)
+		require.NoError(t, err)
+
+		err = issuedRcpt.AttachInvocation(inv2)
+		require.Error(t, err)
+	})
+}
+
+func TestClone(t *testing.T) {
+	inv, err := invocation.Invoke(
+		fixtures.Alice,
+		fixtures.Bob,
+		ucan.NewCapability("ran/invoke", fixtures.Alice.DID().String(), ucan.NoCaveats{}),
+	)
+	require.NoError(t, err)
+
+	out := result.Ok[someOkType, someErrorType](someOkType{SomeOkProperty: "some ok value"})
+
+	rcpt1, err := Issue(fixtures.Alice, out, ran.FromLink(inv.Link()))
+	require.NoError(t, err)
+
+	rcpt2, err := rcpt1.Clone()
+	require.NoError(t, err)
+
+	// attach an invocation to rcpt2 and confirm it doesn't affect rcpt1
+	err = rcpt2.AttachInvocation(inv)
+	require.NoError(t, err)
+
+	rcpt1NumBlocks := 0
+	for range rcpt1.Blocks() {
+		rcpt1NumBlocks++
+	}
+	rcpt2NumBlocks := 0
+	for range rcpt2.Blocks() {
+		rcpt2NumBlocks++
+	}
+	require.True(t, rcpt2NumBlocks > rcpt1NumBlocks)
+}
+
 func TestAnyReceiptReader(t *testing.T) {
 	ranInv, err := invocation.Invoke(
 		fixtures.Alice,

server/options.go

@@ -28,6 +28,7 @@ type srvConfig struct {
 	authorityProofs       []delegation.Delegation
 	altAudiences          []ucan.Principal
 	catch                 ErrorHandlerFunc
+	logReceipt            ReceiptLoggerFunc
 }
 
 func WithServiceMethod[O ipld.Builder, X failure.IPLDBuilderFailure](can string, handleFunc ServiceMethod[O, X]) Option {
@@ -75,6 +76,15 @@ func WithErrorHandler(fn ErrorHandlerFunc) Option {
 	}
 }
 
+// WithReceiptLogger configures a function to be called when a receipt is
+// issued.
+func WithReceiptLogger(fn ReceiptLoggerFunc) Option {
+	return func(cfg *srvConfig) error {
+		cfg.logReceipt = fn
+		return nil
+	}
+}
+
 // WithCanIssue configures a function that determines whether a given capability
 // can be issued by a given DID or whether it needs to be delegated to the
 // issuer.

server/retrieval/options.go

@@ -28,6 +28,7 @@ type srvConfig struct {
 	authorityProofs       []delegation.Delegation
 	altAudiences          []ucan.Principal
 	catch                 server.ErrorHandlerFunc
+	logReceipt            server.ReceiptLoggerFunc
 	delegationCache       delegation.Store
 }
 
@@ -67,6 +68,15 @@ func WithErrorHandler(fn server.ErrorHandlerFunc) Option {
 	}
 }
 
+// WithReceiptLogger configures a function to be called when a receipt is generated,
+// allowing access to the receipts produced by the server.
+func WithReceiptLogger(fn server.ReceiptLoggerFunc) Option {
+	return func(cfg *srvConfig) error {
+		cfg.logReceipt = fn
+		return nil
+	}
+}
+
 // WithCanIssue configures a function that determines whether a given capability
 // can be issued by a given DID or whether it needs to be delegated to the
 // issuer.

server/retrieval/server.go

@@ -121,6 +121,9 @@ func NewServer(id principal.Signer, options ...Option) (*Server, error) {
 	if cfg.catch != nil {
 		srvOpts = append(srvOpts, server.WithErrorHandler(cfg.catch))
 	}
+	if cfg.logReceipt != nil {
+		srvOpts = append(srvOpts, server.WithReceiptLogger(cfg.logReceipt))
+	}
 	if cfg.validateAuthorization != nil {
 		srvOpts = append(srvOpts, server.WithRevocationChecker(cfg.validateAuthorization))
 	}
@@ -188,6 +191,10 @@ func (srv *Server) Catch(err server.HandlerExecutionError[any]) {
 	srv.server.Catch(err)
 }
 
+func (srv *Server) LogReceipt(rcpt receipt.AnyReceipt, inv invocation.Invocation) {
+	srv.server.LogReceipt(rcpt, inv)
+}
+
 var _ CachingServer = (*Server)(nil)
 
 func Handle(ctx context.Context, srv CachingServer, request transport.HTTPRequest) (transport.HTTPResponse, error) {
@@ -462,5 +469,7 @@ func Run(ctx context.Context, srv server.Server[Service], invocation server.Serv
 		return nil, Response{}, err
 	}
 
+	srv.LogReceipt(rcpt, invocation)
+
 	return rcpt, resp, nil
 }

server/server.go

@@ -67,6 +67,7 @@ type Server[S any] interface {
 	// Service is the actual service providing capability handlers.
 	Service() S
 	Catch(err HandlerExecutionError[any])
+	LogReceipt(rcpt receipt.AnyReceipt, inv invocation.Invocation)
 }
 
 // Server is a materialized service that is configured to use a specific
@@ -83,6 +84,10 @@ type ServerView[S any] interface {
 // to be logged.
 type ErrorHandlerFunc func(err HandlerExecutionError[any])
 
+// ReceiptLoggerFunc allows receipts generated during handler execution to be logged.
+// The original invocation is also provided for reference.
+type ReceiptLoggerFunc func(receipt.AnyReceipt, invocation.Invocation)
+
 func NewServer(id principal.Signer, options ...Option) (ServerView[Service], error) {
 	cfg := srvConfig{service: Service{}}
 	for _, opt := range options {
@@ -131,7 +136,7 @@ func NewServer(id principal.Signer, options ...Option) (ServerView[Service], err
 	}
 
 	ctx := serverContext{id, canIssue, validateAuthorization, resolveProof, parsePrincipal, resolveDIDKey, cfg.authorityProofs, cfg.altAudiences}
-	svr := &server{id, cfg.service, ctx, codec, catch}
+	svr := &server{id, cfg.service, ctx, codec, catch, cfg.logReceipt}
 	return svr, nil
 }
 
@@ -184,11 +189,12 @@ func (sctx serverContext) AlternativeAudiences() []ucan.Principal {
 }
 
 type server struct {
-	id      principal.Signer
-	service Service
-	context InvocationContext
-	codec   transport.InboundCodec
-	catch   ErrorHandlerFunc
+	id         principal.Signer
+	service    Service
+	context    InvocationContext
+	codec      transport.InboundCodec
+	catch      ErrorHandlerFunc
+	logReceipt ReceiptLoggerFunc
 }
 
 func (srv *server) ID() principal.Signer {
@@ -219,6 +225,12 @@ func (srv *server) Catch(err HandlerExecutionError[any]) {
 	srv.catch(err)
 }
 
+func (srv *server) LogReceipt(rcpt receipt.AnyReceipt, inv invocation.Invocation) {
+	if srv.logReceipt != nil {
+		srv.logReceipt(rcpt, inv)
+	}
+}
+
 var _ transport.Channel = (*server)(nil)
 var _ ServerView[Service] = (*server)(nil)
 
@@ -322,5 +334,7 @@ func Run(ctx context.Context, server Server[Service], invocation ServiceInvocati
 		return receipt.Issue(server.ID(), result.NewFailure(herr), ran.FromInvocation(invocation))
 	}
 
+	server.LogReceipt(rcpt, invocation)
+
 	return rcpt, nil
 }