Should we "Contextualize" our Client API?

[geoknee]

(This discussion spurred by a meeting with our PolyCrypt colleagues)

Our Client API currently works as follows:

1. The Client constructor will make a completed objectives chan (which has a hardcoded buffer of 100) :
   

   go-nitro/client/client.go

   Lines 26 to 31 in 33f46a7

   	// New is the constructor for a Client. It accepts a messaging service, a chain service, and a store as injected dependencies.
   	func New(messageService messageservice.MessageService, chainservice chainservice.ChainService, store store.Store, logDestination io.Writer) Client {
   	c := Client{}
   	c.Address = store.GetAddress()
   	c.engine = engine.New(messageService, chainservice, store, logDestination)
   	c.completedObjectives = make(chan protocols.ObjectiveId, 100)

   
   and which is exposed to the consumer via a public method
   

   go-nitro/client/client.go

   Lines 59 to 62 in 33f46a7

   	// CompletedObjectives returns a chan that receives a objective id whenever that objective is completed
   	func (c *Client) CompletedObjectives() <-chan protocols.ObjectiveId {
   	return c.completedObjectives
   	}

2. The consumer makes an API call and is returned (simply) an objective id:
   

   go-nitro/client/directfund_integration_test.go

   Line 61 in 070e3cf

   id := clientA.CreateDirectChannel(b, types.Address{}, types.Bytes{}, outcome, big.NewInt(0))

3. The consumer typically calls said public getter function and "listens" for successful events sent on the chan:
   

   go-nitro/client/directfund_integration_test.go

   Line 62 in 070e3cf

   got := <-clientA.CompletedObjectives()

Question 1: Would it be better for the consumer to have ownership of the chan where signals are sent? They could construct it and pass it to the go-nitro client constructor. They could then choose the buffer, for example.

• On the other hand, does our implementation rely on there being a buffer of a certain size?

Question 2: Should consumers pass in a context.Context object?

that makes it easy to pass request-scoped values, cancellation signals, and deadlines across API boundaries to all the goroutines involved in handling a request.

See :
https://pkg.go.dev/context
https://go.dev/blog/context

The cancellation signal, for example, might be a nice way for consumers (e.g. integration test scripts) to ask their Client to gracefully stop work when they are done.

• On the other hand, it doesn't seem likely that the go-nitro client itself would need to be stopped in a production environment. It could be useful for test environments, though, where we want to try out "crashes" and so on. And if the context was rather attached to an individual API call such as CreateDirectChannel (instead of the entire execution of the go-nitro client), it might make more sense...

A deadline might be a nice way for a consumer to express that they will only wait (say) 10 minutes for a virtual channel to be funded. The go-nitro client can choose to simply reject the request if it is smart enough to know the deadline is unobtainable, or it could cancel the request mid-way through if the deadline is hit.

• On the other hand, this seems more complicated in state channels than a simple server request. If I cancel part way through a protocol, I may have enabled certain actions on chain, and I may need to start a cleanup operation to recover my funds.

A further benefit might be: a nice way to provide support for errors and error handling, since that seems to be built in to a context.Context.

Question 3: Should we be returning errors from our API?
I think most likely yes. Perhaps these errors are only those related to local work (i.e. not the result of counterparty (in)activity or blockchain problems? I say that because, at lest in the current model, the API call returns after local work is done but before non-local work has finished.

• On the other hand, does this conflict with the error handling that a Context might provide?

Question 4: Where should we use these patterns? In the constructor for the go-nitro client, on each API method call, or both?

• Relevant for this question is that objectives can be spawned in clients via a route other than an API call. So we may not want to attach "too much" (return values, chans, contexts) to API calls, because we probably need another way to communicate between consumer and go-nitro client, and having more ways than strictly necessary seems like an anti-pattern to me. (Our Typescript implementation did just that, however: it was an event emitter but it was also returning promises for each API call). We can emulate a promise pretty easily by having API calls return a chan, and have actually experimented with that recently.