No description
- Rust 65.5%
- HTML 14.7%
- Shell 11.8%
- JavaScript 4.9%
- CSS 2.3%
- Other 0.8%
kristof5
e5544202cb
- Separate OpenRPC/JSON-RPC logic from admin dashboard into two routers: - build_rpc_router(): JSON-RPC 2.0 only, listens on rpc.sock - build_ui_router(): Admin dashboard, reverse proxy, MCP gateway, listens on ui.sock - Add ui_socket_path() config helper for dashboard socket - Add socket-only mode support (--port 0) for headless deployments - Update discovery manifests to distinguish between protocols (openrpc vs ui) - Add runsocket Makefile target for testing socket-only mode - Make router_openrpc_spec() public for handler visibility This aligns with hero_sockets convention where each service exposes both machine-callable (rpc.sock) and browser-callable (ui.sock) interfaces. Co-Authored-By: Claude Haiku 4.5 <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