From baca6ef22aca467962c97744d1ab08ddc6898dd6 Mon Sep 17 00:00:00 2001 From: Bryan White Date: Tue, 7 Nov 2023 08:50:35 +0100 Subject: [PATCH] docs: improve godoc comments & client README.md --- docs/pkg/client/README.md | 4 ++-- internal/testclient/testeventsquery/client.go | 16 +++++++-------- pkg/client/interface.go | 20 ++++++++++--------- 3 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/pkg/client/README.md b/docs/pkg/client/README.md index 67037836b..6f4032800 100644 --- a/docs/pkg/client/README.md +++ b/docs/pkg/client/README.md @@ -31,7 +31,7 @@ It includes lower-level interfaces for working with transactions and subscribing | **`TxClient`** | A high-level client used to build, sign, and broadcast transaction from cosmos-sdk messages. | | **`TxContext`** | Abstracts and encapsulates the transaction building, signing, encoding, and broadcasting concerns. | | **`BlockClient`** | Exposes methods for receiving notifications about newly committed blocks. | -| **`EventsQueryClient`** | Encapsulates blockchain event subscriptions in . | +| **`EventsQueryClient`** | Encapsulates blockchain event subscriptions. | | **`Connection`** | A transport agnostic communication channel for sending and receiving messages. | | **`Dialer`** | Abstracts the establishment of connections. | @@ -77,7 +77,7 @@ tx --"#EventsBytes()"--> evt bl --"#EventsBytes()"--> evt evt --> conn evt --"#DialContext()"--> dial -dial --(returns)--> conn +dial --"(returns)"--> conn ``` > **Figure 2**: An overview which articulates the dependency relationships between the various client interfaces and their subcompnents. diff --git a/internal/testclient/testeventsquery/client.go b/internal/testclient/testeventsquery/client.go index 3e5ea41c1..2c68606ce 100644 --- a/internal/testclient/testeventsquery/client.go +++ b/internal/testclient/testeventsquery/client.go @@ -27,12 +27,11 @@ func NewLocalnetClient(t *testing.T, opts ...client.EventsQueryClientOption) cli } // NewOneTimeEventsQuery creates a mock of the EventsQueryClient which expects -// a single call to the EventsBytes method. It returns a mock client whose event -// bytes method always constructs a new observable. query is the query string -// for which event bytes subscription is expected to be for. -// The caller can simulate blockchain events by sending on publishCh, the value -// of which is set to the publish channel of the events bytes observable publish -// channel. +// a single call to the EventsBytes method. query is the query string which is +// expected to be received by that call. +// It returns a mock client whose event bytes method constructs a new observable. +// The caller can simulate blockchain events by sending on the value publishCh +// points to, which is set by this helper function. func NewOneTimeEventsQuery( ctx context.Context, t *testing.T, @@ -57,9 +56,8 @@ func NewOneTimeEventsQuery( // NewOneTimeTxEventsQueryClient creates a mock of the Events that expects // a single call to the EventsBytes method where the query is for transaction // events for sender address matching that of the given key. -// The caller can simulate blockchain events by sending on publishCh, the value -// of which is set to the publish channel of the events bytes observable publish -// channel. +// The caller can simulate blockchain events by sending on the value publishCh +// points to, which is set by this helper function. func NewOneTimeTxEventsQueryClient( ctx context.Context, t *testing.T, diff --git a/pkg/client/interface.go b/pkg/client/interface.go index 17c2a1b86..32dab250c 100644 --- a/pkg/client/interface.go +++ b/pkg/client/interface.go @@ -70,6 +70,7 @@ type TxContext interface { // BlocksObservable is an observable which is notified with an either // value which contains either an error or the event message bytes. +// // TODO_HACK: The purpose of this type is to work around gomock's lack of // support for generic types. For the same reason, this type cannot be an // alias (i.e. EventsBytesObservable = observable.Observable[either.Either[[]byte]]). @@ -94,23 +95,24 @@ type Block interface { Hash() []byte } -// TODO_CONSIDERATION: the cosmos-sdk CLI code seems to use a cometbft RPC client -// which includes a `#Subscribe()` method for a similar purpose. Perhaps we could -// replace this custom websocket client with that. -// (see: https://github.com/cometbft/cometbft/blob/main/rpc/client/http/http.go#L110) -// (see: https://github.com/cosmos/cosmos-sdk/blob/main/client/rpc/tx.go#L114) -// -// NOTE: a branch which attempts this is available at: -// https://github.com/pokt-network/poktroll/pull/74 - // EventsBytesObservable is an observable which is notified with an either // value which contains either an error or the event message bytes. +// // TODO_HACK: The purpose of this type is to work around gomock's lack of // support for generic types. For the same reason, this type cannot be an // alias (i.e. EventsBytesObservable = observable.Observable[either.Bytes]). type EventsBytesObservable observable.Observable[either.Bytes] // EventsQueryClient is used to subscribe to chain event messages matching the given query, +// +// TODO_CONSIDERATION: the cosmos-sdk CLI code seems to use a cometbft RPC client +// which includes a `#Subscribe()` method for a similar purpose. Perhaps we could +// replace our custom implementation with one which wraps that. +// (see: https://github.com/cometbft/cometbft/blob/main/rpc/client/http/http.go#L110) +// (see: https://github.com/cosmos/cosmos-sdk/blob/main/client/rpc/tx.go#L114) +// +// NOTE: a branch which attempts this is available at: +// https://github.com/pokt-network/poktroll/pull/74 type EventsQueryClient interface { // EventsBytes returns an observable which is notified about chain event messages // matching the given query. It receives an either value which contains either an