https://github.com/ohhi-vn/easy_rpc
Help dev can work easily with rpc in Elixir cluster
https://github.com/ohhi-vn/easy_rpc
cluster disport hex-package public rpc
Last synced: 3 months ago
JSON representation
Help dev can work easily with rpc in Elixir cluster
- Host: GitHub
- URL: https://github.com/ohhi-vn/easy_rpc
- Owner: ohhi-vn
- License: mit
- Created: 2025-03-02T06:55:06.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-08T05:17:05.000Z (3 months ago)
- Last Synced: 2026-03-08T10:26:01.074Z (3 months ago)
- Topics: cluster, disport, hex-package, public, rpc
- Language: Elixir
- Homepage:
- Size: 82 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
[](https://hexdocs.pm/easy_rpc)
[](https://hex.pm/packages/easy_rpc)
# EasyRpc
A library that makes it easy to wrap a remote procedure call (RPC) as a local function.
EasyRpc uses Erlang's `:erpc` module under the hood and adds retry, timeout, and error-handling support on top.
Each function can carry its own options, or inherit global options declared at the module level.
EasyRpc works seamlessly with [ClusterHelper](https://hex.pm/packages/cluster_helper) for dynamic Elixir clusters.
*Note: Collab between human & AI.*
## Installation
Add `easy_rpc` to your dependencies in `mix.exs`:
```elixir
def deps do
[
{:easy_rpc, "~> 0.7.0"}
]
end
```
---
## Two Usage Approaches
| | `DefRpc` | `RpcWrapper` |
|---|---|---|
| Functions declared | In module via `defrpc` macro | In config file |
| Node config loaded | At **runtime** per call | At **compile time** |
| Cluster topology changes | ✅ Picked up automatically | Requires recompile |
| Best for | Explicit control, dynamic clusters | All-in-config, stable topology |
---
## Usage — `DefRpc` (declarative macros)
### 1. Add node config
```elixir
# config/config.exs (or runtime.exs for runtime topology)
config :my_app, :remote_defrpc,
nodes: [:"remote@127.0.0.1"],
# or: nodes: {ClusterHelper, :get_nodes, [:remote_api]},
select_mode: :round_robin,
sticky_node: true
```
> `:round_robin` and `:sticky_node` are tracked **per process**.
### 2. Declare functions
```elixir
defmodule MyApp.Remote do
use EasyRpc.DefRpc,
otp_app: :my_app,
config_name: :remote_defrpc,
module: RemoteNode.Interface,
timeout: 1_000
defrpc :get_data
defrpc :put_data, args: 1
defrpc :clear, args: 2, as: :clear_data, private: true
defrpc :put_data, args: [:name], as: :put_with_retry, retry: 3, sleep_before_retry: 200, timeout: 1_000
end
```
**`defrpc` options:**
| Option | Description |
|-----------------------|-------------------------------------------------------|
| `:args` | Arity as integer, `[]` (zero), or list of named atoms |
| `:as` / `:new_name` | Override the generated function name |
| `:private` | Generate as `defp` (default: `false`) |
| `:retry` | Override global retry count |
| `:sleep_before_retry` | Milliseconds to wait before each retry (default: `0`) |
| `:timeout` | Override global timeout (ms or `:infinity`) |
| `:error_handling` | Override global error-handling flag |
---
## Usage — `RpcWrapper` (config-driven)
All function and node information is declared in config.
Functions are generated at compile time.
### 1. Add config
```elixir
# config/config.exs
config :my_app, :data_wrapper,
nodes: [:"node1@host", :"node2@host"],
# or: nodes: {ClusterHelper, :get_nodes, [:data]},
error_handling: true,
select_mode: :random,
module: TargetApp.Interface.Api,
timeout: 5_000,
retry: 3,
sleep_before_retry: 500, # wait 500 ms between retries
functions: [
# {function_name, arity}
# {function_name, arity, options}
{:get_data, 1},
{:put_data, 1, [error_handling: false]},
{:clear, 2, [new_name: :clear_data, retry: 3, sleep_before_retry: 100]},
{:clear_all, 0, [new_name: :reset, private: true]}
]
```
### 2. Use in your module
```elixir
defmodule MyApp.DataHelper do
use EasyRpc.RpcWrapper,
otp_app: :my_app,
config_name: :data_wrapper
def process_remote() do
case get_data("key") do
{:ok, data} -> data
{:error, reason} -> {:error, reason}
end
end
end
# Or call directly:
{:ok, result} = MyApp.DataHelper.get_data("my_key")
```
---
## Node Selection Strategies
Configure via `select_mode:` in your config:
| Strategy | Description |
|----------------|-----------------------------------------------------------------|
| `:random` | Randomly picks a node on each call (default) |
| `:round_robin` | Circular distribution, tracked per process |
| `:hash` | Consistent hashing on args — same args always hit the same node |
### Sticky Nodes
```elixir
config :my_app, :api,
nodes: [:node1@host, :node2@host],
select_mode: :random,
sticky_node: true # process pins to first selected node
```
### Dynamic Node Discovery
```elixir
config :my_app, :api,
nodes: {ClusterHelper, :get_nodes, [:backend]},
select_mode: :round_robin
```
---
## Error Handling
### Without error handling (default — raises on error)
```elixir
user = MyApi.get_user(123)
```
### With error handling (returns tagged tuples)
```elixir
case MyApi.get_user(123) do
{:ok, user} -> process(user)
{:error, %EasyRpc.Error{} = e} -> Logger.error(EasyRpc.Error.format(e))
end
```
Enable globally in config or per function:
```elixir
config :my_app, :api, error_handling: true
# or per defrpc:
defrpc :get_user, args: 1, error_handling: true
```
---
## Retry Logic
```elixir
# Global retry
config :my_app, :api, retry: 3
# Per-function
defrpc :critical_op, args: 1, retry: 5
```
> When `retry > 0`, `error_handling` is automatically enabled — retried calls
> always return `{:ok, result} | {:error, %EasyRpc.Error{}}`.
---
## Sleep Before Retry
By default EasyRpc retries immediately after a failure. Use `sleep_before_retry`
to add a fixed delay (in milliseconds) between attempts. This is useful for
giving a remote node time to recover, or for reducing thundering-herd pressure
on a flapping service.
```elixir
# Global — all retries in this config wait 500 ms
config :my_app, :api,
retry: 3,
sleep_before_retry: 500
# Per-function override
defrpc :critical_op, args: 1, retry: 5, sleep_before_retry: 200
```
The sleep happens **between** attempts — there is no delay before the first
call, and no delay after the final failure.
```
attempt 1 → fails → sleep 500 ms
attempt 2 → fails → sleep 500 ms
attempt 3 → fails → sleep 500 ms
attempt 4 → fails → return {:error, ...}
```
> `sleep_before_retry` requires a non-negative integer. The default is `0`
> (no sleep). Setting it without also setting `retry` has no effect.
---
## Timeout Configuration
```elixir
# Global
config :my_app, :api, timeout: 5_000
# Per-function
defrpc :long_op, args: 1, timeout: 30_000
defrpc :health_check, timeout: 500
defrpc :no_limit, timeout: :infinity
```
---
## Examples
See the [lib_examples repository](https://github.com/ohhi-vn/lib_examples/tree/main/easy_rpc) for complete, runnable examples.
---
## AI Agents & MCP Support
Sync usage rules from deps into your repo for AI agent support:
```bash
mix usage_rules.sync AGENTS.md --all \
--link-to-folder deps \
--inline usage_rules:all
```
Start the MCP server:
```bash
mix tidewave
```
Configure your agent to connect to `http://localhost:4113/tidewave/mcp` (change port in `mix.exs` if needed).
See [Tidewave docs](https://hexdocs.pm/tidewave/) for details.