[Miner] feat: add events query client

Makefile

@@ -114,13 +114,18 @@ test_e2e: ## Run all E2E tests
 
 .PHONY: go_test
 go_test: go_version_check ## Run all go tests
-	go test -v ./...
+	go test -v -race -tags test ./...
+
+.PHONY: go_test_integration
+go_test_integration: go_version_check ## Run all go tests, including integration
+	go test -v -race -tags test,integration ./...
 
 .PHONY: go_mockgen
 go_mockgen: ## Use `mockgen` to generate mocks used for testing purposes of all the modules.
 	go generate ./x/application/types/
 	go generate ./x/gateway/types/
 	go generate ./x/supplier/types/
+	go generate ./pkg/...
 
 .PHONY: go_develop
 go_develop: proto_regen go_mockgen ## Generate protos and mocks

docs/pkg/client/events_query.md

@@ -0,0 +1,104 @@
+# Package `pocket/pkg/client/events_query` <!-- omit in toc -->
+
+> An event query package for interfacing with [CometBFT](https://cometbft.com/) and the [Cosmos SDK](https://v1.cosmos.network/sdk), facilitating subscriptions to chain event messages.
+
+- [Overview](#overview)
+- [Architecture Diagrams](#architecture-diagrams)
+- [Installation](#installation)
+- [Features](#features)
+- [Usage](#usage)
+  - [Basic Example](#basic-example)
+  - [Advanced Usage](#advanced-usage)
+  - [Configuration](#configuration)
+- [API Reference](#api-reference)
+- [Best Practices](#best-practices)
+- [FAQ](#faq)
+    - [Why use `events_query` over directly using Gorilla WebSockets?](#why-use-events_query-over-directly-using-gorilla-websockets)
+    - [How can I use a different connection mechanism other than WebSockets?](#how-can-i-use-a-different-connection-mechanism-other-than-websockets)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
+- [License](#license)
+
+## Overview
+
+The `events_query` package provides a client interface to subscribe to chain event messages. It abstracts the underlying connection mechanisms and offers a clear and easy-to-use way to get events from the chain. Highlights:
+
+- Offers subscription to chain event messages matching a given query.
+- Uses the Gorilla WebSockets package for underlying connection operations.
+- Provides a modular structure with interfaces allowing for mock implementations and testing.
+- Offers considerations for potential improvements and replacements, such as integration with the cometbft RPC client.
+
+## Architecture Diagrams
+
+_TODO(@bryanchriswhite): Add architecture diagrams for the package._
+
+## Installation
+
+```bash
+go get github.com/pokt-network/poktroll/pkg/client/events_query
+```
+
+## Features
+
+- **Websocket Connection**: Uses the [Gorilla WebSockets](https://github.com/gorilla/websocket) for implementing the connection interface.
+- **Events Subscription**: Subscribe to chain event messages using a simple query mechanism.
+- **Dialer Interface**: Offers a `Dialer` interface for constructing connections, which can be easily mocked for tests.
+- **Observable Pattern**: Integrates the observable pattern, making it easier to react to chain events.
+
+## Usage
+
+### Basic Example
+
+```go
+// Creating a new EventsQueryClient with the default websocket dialer:
+cometWebsocketURL := "ws://example.com"
+evtClient := eventsquery.NewEventsQueryClient(cometWebsocketURL)
+
+// Subscribing to a specific event:
+observable, errCh := evtClient.EventsBytes(context.Background(), "your-query-string")
+```
+
+### Advanced Usage
+
+_TODO(@bryanchriswhite): Add examples of advanced usage_
+
+### Configuration
+
+- **WithDialer**: Configure the client to use a custom dialer for connections.
+
+## API Reference
+
+- `EventsQueryClient`: Main interface to query events. Methods include:
+  - `EventsBytes(ctx, query)`: Returns an observable for chain events.
+  - `Close()`: Close any existing connections and unsubscribe all observers.
+- `Connection`: Interface representing a bidirectional message-passing connection.
+- `Dialer`: Interface encapsulating the creation of connections.
+
+For the complete API details, see the [godoc](https://pkg.go.dev/github.com/pokt-network/poktroll/pkg/client/events_query).
+
+## Best Practices
+
+- **Connection Handling**: Ensure to close the `EventsQueryClient` when done to free up resources and avoid potential leaks.
+- **Error Handling**: Always check the error channel returned by `EventsBytes` for asynchronous errors during operation.
+
+## FAQ
+
+#### Why use `events_query` over directly using Gorilla WebSockets?
+
+`events_query` abstracts many of the underlying details and provides a streamlined interface for subscribing to chain events. It also integrates the observable pattern and provides mockable interfaces for better testing.
+
+#### How can I use a different connection mechanism other than WebSockets?
+
+You can implement the `Dialer` and `Connection` interfaces and use the `WithDialer` configuration to provide your custom dialer.
+
+## Contributing
+
+If you're interested in improving the `events_query` package or adding new features, please start by discussing your ideas in the project's issues section. Check our main contributing guide for more details.
+
+## Changelog
+
+For detailed release notes, see the [CHANGELOG](../CHANGELOG.md).
+
+## License
+
+This package is released under the XYZ License. For more information, see the [LICENSE](../LICENSE) file at the root level.

go.mod

@@ -8,22 +8,22 @@ require (
 	cosmossdk.io/math v1.0.1
 	github.com/cometbft/cometbft v0.37.2
 	github.com/cometbft/cometbft-db v0.8.0
-	github.com/cosmos/cosmos-proto v1.0.0-beta.2
 	github.com/cosmos/cosmos-sdk v0.47.3
 	github.com/cosmos/gogoproto v1.4.10
 	github.com/cosmos/ibc-go/v7 v7.1.0
 	github.com/golang/mock v1.6.0
 	github.com/golang/protobuf v1.5.3
 	github.com/gorilla/mux v1.8.0
+	github.com/gorilla/websocket v1.5.0
 	github.com/grpc-ecosystem/grpc-gateway v1.16.0
 	github.com/grpc-ecosystem/grpc-gateway/v2 v2.15.2
 	github.com/regen-network/gocuke v0.6.2
 	github.com/spf13/cast v1.5.1
 	github.com/spf13/cobra v1.7.0
 	github.com/spf13/pflag v1.0.5
 	github.com/stretchr/testify v1.8.4
+	go.uber.org/multierr v1.11.0
 	golang.org/x/sync v0.3.0
-	google.golang.org/genproto v0.0.0-20230410155749-daa745c078e1
 	google.golang.org/grpc v1.56.1
 	gopkg.in/yaml.v2 v2.4.0
 )
@@ -68,6 +68,7 @@ require (
 	github.com/containerd/cgroups v1.1.0 // indirect
 	github.com/coreos/go-systemd/v22 v22.5.0 // indirect
 	github.com/cosmos/btcutil v1.0.5 // indirect
+	github.com/cosmos/cosmos-proto v1.0.0-beta.2 // indirect
 	github.com/cosmos/go-bip39 v1.0.0 // indirect
 	github.com/cosmos/gogogateway v1.2.0 // indirect
 	github.com/cosmos/iavl v0.20.0 // indirect
@@ -122,7 +123,6 @@ require (
 	github.com/googleapis/gax-go/v2 v2.8.0 // indirect
 	github.com/gorilla/handlers v1.5.1 // indirect
 	github.com/gorilla/rpc v1.2.0 // indirect
-	github.com/gorilla/websocket v1.5.0 // indirect
 	github.com/grpc-ecosystem/go-grpc-middleware v1.3.0 // indirect
 	github.com/gsterjov/go-libsecret v0.0.0-20161001094733-a6f4afe4910c // indirect
 	github.com/gtank/merlin v0.1.1 // indirect
@@ -251,7 +251,6 @@ require (
 	go.uber.org/atomic v1.10.0 // indirect
 	go.uber.org/dig v1.16.1 // indirect
 	go.uber.org/fx v1.19.2 // indirect
-	go.uber.org/multierr v1.11.0 // indirect
 	go.uber.org/zap v1.24.0 // indirect
 	golang.org/x/crypto v0.12.0 // indirect
 	golang.org/x/exp v0.0.0-20230626212559-97b1e661b5df // indirect
@@ -266,6 +265,7 @@ require (
 	gonum.org/v1/gonum v0.11.0 // indirect
 	google.golang.org/api v0.122.0 // indirect
 	google.golang.org/appengine v1.6.7 // indirect
+	google.golang.org/genproto v0.0.0-20230410155749-daa745c078e1 // indirect
 	google.golang.org/protobuf v1.31.0 // indirect
 	gopkg.in/ini.v1 v1.67.0 // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect

internal/testclient/common.go

@@ -0,0 +1,3 @@
+package testclient
+
+const CometLocalWebsocketURL = "ws://localhost:36657/websocket"

internal/testclient/testeventsquery/client.go

@@ -0,0 +1,17 @@
+package testeventsquery
+
+import (
+	"testing"
+
+	"pocket/internal/testclient"
+	"pocket/pkg/client"
+	eventsquery "pocket/pkg/client/events_query"
+)
+
+// NewLocalnetClient returns a new events query client which is configured to
+// connect to the localnet sequencer.
+func NewLocalnetClient(t *testing.T, opts ...client.EventsQueryClientOption) client.EventsQueryClient {
+	t.Helper()
+
+	return eventsquery.NewEventsQueryClient(testclient.CometLocalWebsocketURL, opts...)
+}

internal/testclient/testeventsquery/connection.go

@@ -0,0 +1,49 @@
+package testeventsquery
+
+import (
+	"pocket/pkg/either"
+	"testing"
+
+	"github.com/golang/mock/gomock"
+
+	"pocket/internal/mocks/mockclient"
+)
+
+// NewOneTimeMockConnAndDialer returns a new mock connection and mock dialer that
+// will return the mock connection when DialContext is called. The mock dialer
+// will expect DialContext to be called exactly once. The connection mock will
+// expect Close to be called exactly once.
+// Callers must mock the Receive method with an EXPECT call before the connection
+// mock can be used.
+func NewOneTimeMockConnAndDialer(t *testing.T) (
+	*mockclient.MockConnection,
+	*mockclient.MockDialer,
+) {
+	ctrl := gomock.NewController(t)
+	connMock := mockclient.NewMockConnection(ctrl)
+	connMock.EXPECT().Close().
+		Return(nil).
+		Times(1)
+
+	dialerMock := NewOneTimeMockDialer(t, either.Success(connMock))
+
+	return connMock, dialerMock
+}
+
+// NewOneTimeMockDialer returns a mock dialer that will return either the given
+// connection mock or error when DialContext is called. The mock dialer will
+// expect DialContext to be called exactly once.
+func NewOneTimeMockDialer(
+	t *testing.T,
+	eitherConnMock either.Either[*mockclient.MockConnection],
+) *mockclient.MockDialer {
+	ctrl := gomock.NewController(t)
+	dialerMock := mockclient.NewMockDialer(ctrl)
+
+	connMock, err := eitherConnMock.ValueOrError()
+	dialerMock.EXPECT().DialContext(gomock.Any(), gomock.Any()).
+		Return(connMock, err).
+		Times(1)
+
+	return dialerMock
+}