No description
- Rust 64.4%
- HTML 15.9%
- Shell 11.7%
- JavaScript 4.9%
- CSS 2.3%
- Other 0.8%
4540a40740
Now that hero_rpc's OSIS handler accepts JSON "data" directly
(0dc2c90), the Python client no longer needs to convert dicts to
OTOML format. The generated .set() methods send {"data": dict}
which the server deserializes via serde_json.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
|
||
|---|---|---|
| .forgejo/workflows | ||
| crates | ||
| docs | ||
| scripts | ||
| .gitignore | ||
| buildenv.sh | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CLAUDE.md | ||
| Makefile | ||
| README.md | ||
Hero Router
The single TCP entry point for all Hero services. Scans Unix sockets, routes HTTP traffic by URL prefix, provides service discovery, documentation, and an MCP gateway.
Quick Start
# Build and start
make run
# Stop
make stop
# CLI: list discovered services
hero_router list
Open the admin dashboard at http://localhost:9997.
Architecture
Internet / Browser / hero_proxy
│
:9988 (TCP, localhost only)
│
hero_router
├── /{service}/rpc/* → {service}/rpc.sock
├── /{service}/admin/* → {service}/ui.sock
├── /{service}/{web}/* → {service}/web_{name}.sock
├── /rpc → management API
├── /mcp → MCP gateway
└── :9997 → admin dashboard
│
Unix sockets (auto-discovered)
~/hero/var/sockets/
hero_compute/rpc.sock
hero_compute/ui.sock
hero_proxy/rpc.sock
hero_proc/rpc.sock
...
Features
- Auto-discovery — scans
$HERO_SOCKET_DIR/for service sockets - URL prefix routing —
/{service}/{socket_type}/*stripped and forwarded - Header injection —
X-Hero-Context,X-Hero-Claims,X-Forwarded-Prefix - MCP gateway — exposes services as MCP-compatible tools for AI agents
- Admin dashboard — interactive web UI with service status
- CLI —
list,scan,spec,markdown,htmlsubcommands - Documentation generation — Markdown and HTML from OpenRPC specs
Crate
| Crate | Type | Description |
|---|---|---|
hero_router |
binary + library | Single binary with CLI, server, admin UI, and core library (herolib_router) |
All crates were consolidated into a single binary in v0.2.0.
Sockets
All sockets under $HERO_SOCKET_DIR/hero_router/ (default: ~/hero/var/sockets/hero_router/).
| Socket | Protocol | Description |
|---|---|---|
rpc.sock |
JSON-RPC 2.0 | Management API |
ui.sock |
HTTP | Admin dashboard |
Ports (TCP, localhost only)
| Port | Description |
|---|---|
| 9988 | Routing entry point — proxies /{service}/* to Unix sockets |
| 9997 | Admin dashboard |
Documentation
- Configuration — Environment variables and CLI flags
- API Reference — JSON-RPC management API
- Architecture — Routing, discovery, and request flow
- Setup — Installation and deployment
- Releasing — How to create a new release
Development
make check # cargo check
make test # cargo test
make lint # clippy
make fmt # rustfmt
make rundev # debug build
make test-all # full CI suite
Installation
make install # build release + install to ~/hero/bin/
Security
- TCP listeners bind to
127.0.0.1only (never0.0.0.0) - No authentication required (localhost-only access)
- Use hero_proxy for external/TLS access