|
2 | 2 |
|
3 | 3 | An extensible and modular RPC request router and proxy service built in Rust. |
4 | 4 |
|
5 | | -## Features |
| 5 | +## Demo |
6 | 6 |
|
7 | | -- Load balancing across multiple RPC backends with EMA-based health tracking |
8 | | -- Tiered caching with in-memory LRU and Redis support |
9 | | -- Sliding window rate limiting |
10 | | -- HTTP and WebSocket support |
11 | | -- Method routing and request validation |
12 | | -- Prometheus metrics |
| 7 | +<https://github.com/user-attachments/assets/3c3fa289-5a12-41ff-b556-e52e4cd1f04d> |
13 | 8 |
|
14 | | -## Repository Structure |
| 9 | +## Overview |
15 | 10 |
|
16 | | -``` |
17 | | -bin/ |
18 | | - roxy/ Entry point for the Roxy binary |
19 | | -crates/ |
20 | | - backend/ HTTP backends with health tracking and load balancing |
21 | | - cache/ Memory, Redis, and fallback cache implementations |
22 | | - cli/ CLI definition and application builder |
23 | | - config/ TOML configuration parsing and validation |
24 | | - rpc/ JSON-RPC codec, routing, validation, and rate limiting |
25 | | - runtime/ Tokio and deterministic runtime implementations |
26 | | - server/ HTTP and WebSocket server with metrics |
27 | | - test-utils/ Mock backends, fixtures, and async test helpers |
28 | | - traits/ Core trait definitions for all components |
29 | | - types/ Error types and alloy re-exports |
30 | | -``` |
| 11 | +Roxy is a JSON-RPC proxy that sits between clients and upstream RPC backends. It distributes requests across multiple backends using exponential moving average (EMA) based health tracking to route traffic toward healthier endpoints. Responses can be cached in a tiered system with an in-memory LRU cache and optional Redis backing. Rate limiting uses a sliding window algorithm to control request throughput. The server accepts both HTTP and WebSocket connections and exposes Prometheus metrics for observability. |
31 | 12 |
|
32 | | -## Prerequisites |
| 13 | +## Installation |
33 | 14 |
|
34 | | -- Rust 1.88+ |
| 15 | +```bash |
| 16 | +cargo install roxy-proxy |
| 17 | +``` |
35 | 18 |
|
36 | | -## Getting Started |
| 19 | +## Usage |
37 | 20 |
|
38 | | -Clone the repository: |
| 21 | +Run the proxy with a configuration file: |
39 | 22 |
|
40 | 23 | ```bash |
41 | | -git clone https://github.com/refcell/roxy |
42 | | -cd roxy |
| 24 | +roxy-proxy --config roxy.toml |
43 | 25 | ``` |
44 | 26 |
|
45 | | -Build: |
| 27 | +Validate configuration without starting the server: |
46 | 28 |
|
47 | 29 | ```bash |
48 | | -cargo build --release |
| 30 | +roxy-proxy --config roxy.toml --check |
49 | 31 | ``` |
50 | 32 |
|
51 | | -## Running Roxy |
| 33 | +## Configuration |
52 | 34 |
|
53 | | -Create a configuration file: |
| 35 | +Create a TOML configuration file: |
54 | 36 |
|
55 | 37 | ```toml |
56 | 38 | [[backends]] |
@@ -78,20 +60,6 @@ host = "0.0.0.0" |
78 | 60 | port = 8545 |
79 | 61 | ``` |
80 | 62 |
|
81 | | -Run the proxy: |
82 | | - |
83 | | -```bash |
84 | | -./target/release/roxy --config roxy.toml |
85 | | -``` |
86 | | - |
87 | | -Validate configuration without starting: |
88 | | - |
89 | | -```bash |
90 | | -./target/release/roxy --config roxy.toml --check |
91 | | -``` |
92 | | - |
93 | | -## Configuration |
94 | | - |
95 | 63 | | Section | Description | |
96 | 64 | |--------------|------------------------------------------------| |
97 | 65 | | server | Bind address, port, connection limits | |
|
0 commit comments