From b05b69080473c82f828c0def433260015f29a69e Mon Sep 17 00:00:00 2001 From: Igor Artamonov Date: Fri, 29 Oct 2021 17:55:45 -0400 Subject: [PATCH] solution: docs for WebSocket support --- README.adoc | 26 ++++++++++++++++++++++---- docs/03-server-config.adoc | 8 +++++++- docs/reference-configuration.adoc | 23 +++++++++++++++-------- 3 files changed, 44 insertions(+), 13 deletions(-) diff --git a/README.adoc b/README.adoc index 8ac0390f..e1d2271d 100644 --- a/README.adoc +++ b/README.adoc @@ -24,7 +24,7 @@ It automatically verifies their availability and the current status of the netwo Provides: -- Standard Bitcoin and Ethereum JSON RPC API +- Standard Bitcoin and Ethereum JSON RPC API over HTTP and WebSocket - Enhanced gRPC-based API, with upstream selection, async execution, etc - **Secure** TLS with optional client authentication - Blockchain-aware edge **caching**, in memory and Redis @@ -107,12 +107,12 @@ Which sets the following: - gRPC access through 0.0.0.0:2449 ** TLS security is disabled (_please don't use in production!_) -- JSON RPC access through 0.0.0.0:8545 +- JSON RPC access through 0.0.0.0:8545 (both HTTP and WebsScket) ** proxy requests to Ethereum and Kovan upstreams ** request path for Ethereum Mainnet is `/eth`, `/kovan` for Kovan Testnet, and `/btc` for bitcoin ** i.e. call Ethereum Mainnet by `POST http://127.0.0.0:8545/eth` with JSON RPC payload - two upstreams, one for Ethereum Mainnet and another for Kovan Testnet (both upstreams are configured to use Infura endpoint) -- for Ethereum Mainnet it connects using JSON RPC and Websockets connections, +- for Ethereum Mainnet it connects using JSON RPC and WebSocket connections, - for Bitcoin Mainet only JSON RPC is used - `${INFURA_USER}` will be provided through environment variable @@ -146,7 +146,7 @@ Tools such as https://github.com/fullstorydev/grpcurl[gRPCurl] can automatically Alternatively you can connect to port 8545 with traditional JSON RPC requests -==== Access using JSON RPC +==== Access using JSON RPC over HTTP Dshackle implements standard JSON RPC interface, providing additional caching layer, upstream readiness/liveness checks, retry and other features for building Fault Tolerant services. @@ -165,6 +165,24 @@ curl --request POST \ {"jsonrpc":"2.0","id":1,"result":"0x72fa5e0181"} ---- +==== Access using JSON RPC over WebSocket + +Or the same Proxy URL can be accessed through WebSocket + +[source,bash] +---- +websocat ws://localhost:8545/eth +---- + +Then make RPC calls or subscriptions: + +---- +> | {"jsonrpc":"2.0", "id": 1, "method": "eth_subscribe", "params": ["newHeads"]} + +< | {"jsonrpc":"2.0","id":1,"result":"1f8"} +< | {"jsonrpc":"2.0","method":"eth_subscription","params":{"result":{....},"subscription":"1f8"}} +---- + ==== Access using gRPC NOTE: It's not necessary to use gRPC, as Dshackle can provide standard JSON RPC proxy, but Dshackle gRPC interface improves performance and provides additional features. diff --git a/docs/03-server-config.adoc b/docs/03-server-config.adoc index b1e45fc9..2fb2895c 100644 --- a/docs/03-server-config.adoc +++ b/docs/03-server-config.adoc @@ -62,6 +62,10 @@ a| `upstreams` === Enabling JSON RPC proxy +In addition to the gRPC protocol, Dshackle provides access compatible with Bitcoin and Ethereum JSON RPC. +The same server can be accessible as an HTTP JSON RPC and WebSocket JSON RPC. +For Ethereum, besides the standard RPC calls, it provides RPC subscriptions with `eth_subscribe` method. + .Example proxy: [source,yaml] ---- @@ -82,7 +86,9 @@ cluster: With that configuration Dshackle starts a JSON RPC proxy: - JSON RPC server is listening on `0.0.0.0:8080` -- `http://0.0.0.0:8080/eth` provides access to Ethereum API routed to an available upstream +- `http://0.0.0.0:8080/eth` (and `ws://0.0.0.0:8080/eth`) provides access to Ethereum API routed to an available upstream + +NOTE: Same URL should be used to access both HTTP RPC and WebSocket RPC .Full configuration: [source,yaml] diff --git a/docs/reference-configuration.adoc b/docs/reference-configuration.adoc index 16f06420..00f26f23 100644 --- a/docs/reference-configuration.adoc +++ b/docs/reference-configuration.adoc @@ -50,6 +50,7 @@ cache: proxy: host: 0.0.0.0 port: 8080 + websocket: true tls: enabled: true server: @@ -373,20 +374,26 @@ proxy: | `host` | `127.0.0.0` -| Host to bind gRPC server +| Host to bind HTTP server | `port` -| `2449` -| Port to bind gRPC server +| `8080` +| Port to bind HTT server +| `websocket` +| `true` +| Enable WebSocket Proxy | `tls` | -| Setup TLS configuration for the Proxy server. See <> section +| Setup TLS configuration for the Proxy server. +See <> section | `routes` | -a| Routing paths for Proxy.The proxy will handle requests as `https://${HOST}:${PORT}/${ROUTE_ID}` (or `http://` if TLS is not enabled) +a| Routing paths for Proxy. +The proxy will handle requests as `https://${HOST}:${PORT}/${ROUTE_ID}` (or `http://` if TLS is not enabled). +For WebSocket it's `wss` / `ws`, accordingly. |=== .Route config @@ -663,14 +670,14 @@ rpc: ---- | `ws.url` -| Websocket URL to connect to. +| WebSocket URL to connect to. Optional, but optimizes performance if it's available. | `ws.origin` -| HTTP `Origin` if required by Websocket remote server. +| HTTP `Origin` if required by WebSocket remote server. | `ws.basic-auth` + ... -| Websocket Basic Auth configuration, if required by the remote server +| WebSocket Basic Auth configuration, if required by the remote server | `ws.frameSize` | WebSocket frame size limit.