lhumina_code/hero_compute
20
0
Fork 0
Code Issues 14 Pull requests 4 Projects Releases 7 Packages Wiki Activity Actions

feat: Multi-node connectivity via hero_proxy over Mycelium #83

New issue
Open
opened 2026-04-08 10:59:40 +00:00 by mahmoud · 2 comments
mahmoud commented 2026-04-08 10:59:40 +00:00
Owner
Copy link

Overview

Enable hero_compute master/worker multi-node communication over Mycelium IPv6 using hero_proxy as the network layer. hero_router stays localhost-only (socket discovery + local routing). hero_proxy handles external traffic with Mycelium IPv6 binding.

Architecture

Each node:
  hero_proc         → manages all services
  hero_router       → localhost:9988, socket discovery, local TCP↔UDS
  hero_proxy        → Mycelium IPv6 listener, forwards to local Unix sockets
  hero_compute      → server + UI + explorer (master only)
  mycelium          → IPv6 overlay network

Worker → Master (heartbeat):
  Worker heartbeat_sender
    → HTTP POST to http://[master-mycelium-ipv6]:9997/hero_compute/rpc/...
    → Master's hero_proxy accepts on Mycelium IPv6
    → Forwards to ~/hero/var/sockets/hero_compute/explorer_rpc.sock

Master → Worker (RPC proxy):
  Master explorer
    → HTTP POST to http://[worker-mycelium-ipv6]:9997/hero_compute/rpc/...
    → Worker's hero_proxy accepts on Mycelium IPv6
    → Forwards to ~/hero/var/sockets/hero_compute/rpc.sock

Changes Required

1. Fix port alignment (hero_compute)

hero_router port is 9988 per the hero_sockets skill spec. hero_compute SDK currently has HERO_ROUTER_PORT = 9998 which is wrong.

  • Rename HERO_ROUTER_PORT → HERO_PROXY_PORT = 9997
  • Rename ROUTER_SERVER_RPC_PREFIX → PROXY_SERVER_RPC_PREFIX
  • Rename ROUTER_EXPLORER_RPC_PREFIX → PROXY_EXPLORER_RPC_PREFIX
  • Rename router_server_rpc_url() → proxy_server_rpc_url()
  • Rename router_explorer_rpc_url() → proxy_explorer_rpc_url()
  • All URL builders use port 9997 (hero_proxy HTTP)
  • Update heartbeat sender, explorer proxy, CLI write_env() accordingly

2. hero_proxy: Add socket-type URL routing (hero_proxy repo)

hero_proxy currently routes /{service}/* and picks the first socket it finds (prefers ui.sock over rpc.sock). For multi-node, we need to reach specific sockets.

Add hero_router-style routing: /{service}/{socket_type}/*

  • /{service}/rpc/* → {service}/rpc.sock
  • /{service}/ui/* → {service}/ui.sock
  • /{service}/explorer_rpc/* → {service}/explorer_rpc.sock
  • Fall back to current /{service}/* behavior for backward compatibility

This keeps URL formats consistent between hero_router (local) and hero_proxy (network).

Separate issue in hero_proxy repo.

3. hero_compute --start: Configure hero_proxy Mycelium listener

When starting in master or worker mode, hero_compute --start should:

  1. Verify hero_proxy is running (check socket exists)
  2. Call mycelium.info RPC to get the local Mycelium IPv6
  3. Call listener.add RPC to create a listener on [mycelium-ipv6]:9997 with auto_start=true
  4. Store the Mycelium IPv6 in the env file as MYCELIUM_IP

This way the user doesn't need to manually configure hero_proxy.

4. Install script + central config

Add to central config (hero_compute_config/development.toml):

[releases.hero_router]
repo = "lhumina_code/hero_router"
version = "v0.2.0"
binaries = ["hero_router"]
asset_suffix = "linux-amd64-musl"

[releases.hero_proxy]
repo = "lhumina_code/hero_proxy"
version = "v0.1.0"
binaries = ["hero_proxy", "hero_proxy_server", "hero_proxy_ui"]
asset_suffix = "linux-amd64-musl"

Update scripts/install.sh:

  • Download and install hero_router and hero_proxy binaries
  • Start hero_router via hero_proc (or hero_router start)
  • Start hero_proxy via hero_proc (or hero_proxy --start)

Update scripts/uninstall.sh to clean up hero_router and hero_proxy.

5. hero_router port fix (hero_router repo)

Update hero_router default port from 9998 to 9988 to match the hero_sockets skill spec.

Separate issue in hero_router repo.

6. Documentation

  • Update docs/setup.md — multi-node requires hero_proxy on each node
  • Update docs/architecture.md — show hero_proxy in the flow diagram
  • Update docs/configuration.md — new env vars, remove hero_router port references
  • Update .env.example — update URL format examples

Dependencies

  • hero_proxy needs socket-type routing (/{service}/{socket_type}/*) — separate issue
  • hero_router needs port change to 9988 — separate issue
  • hero_proxy v0.1.0 release must complete (CI pending)

Acceptance Criteria

  • hero_compute SDK uses hero_proxy port (9997) not hero_router port
  • hero_compute --start --mode master configures hero_proxy Mycelium listener
  • hero_compute --start --mode worker --master-ip <mycelium-ipv6> sends heartbeats through hero_proxy
  • Master explorer can proxy RPC calls to worker through hero_proxy
  • Install script downloads and starts hero_router + hero_proxy
  • Single node (local) mode works unchanged
  • Multi-node tested: two nodes on different networks connected via Mycelium

Related Issues

  • #65 — Phase 1: Socket convention (completed)
  • #69 — Phase 2: Hero Router replacement (completed, but needs revision for hero_proxy)
  • #80 — CamelCase method fix
  • hero_proxy: socket-type routing (to be created)
  • hero_router: port 9998→9988 (to be created)
## Overview Enable hero_compute master/worker multi-node communication over Mycelium IPv6 using hero_proxy as the network layer. hero_router stays localhost-only (socket discovery + local routing). hero_proxy handles external traffic with Mycelium IPv6 binding. ## Architecture ``` Each node: hero_proc → manages all services hero_router → localhost:9988, socket discovery, local TCP↔UDS hero_proxy → Mycelium IPv6 listener, forwards to local Unix sockets hero_compute → server + UI + explorer (master only) mycelium → IPv6 overlay network Worker → Master (heartbeat): Worker heartbeat_sender → HTTP POST to http://[master-mycelium-ipv6]:9997/hero_compute/rpc/... → Master's hero_proxy accepts on Mycelium IPv6 → Forwards to ~/hero/var/sockets/hero_compute/explorer_rpc.sock Master → Worker (RPC proxy): Master explorer → HTTP POST to http://[worker-mycelium-ipv6]:9997/hero_compute/rpc/... → Worker's hero_proxy accepts on Mycelium IPv6 → Forwards to ~/hero/var/sockets/hero_compute/rpc.sock ``` ## Changes Required ### 1. Fix port alignment (hero_compute) hero_router port is 9988 per the hero_sockets skill spec. hero_compute SDK currently has `HERO_ROUTER_PORT = 9998` which is wrong. - Rename `HERO_ROUTER_PORT` → `HERO_PROXY_PORT = 9997` - Rename `ROUTER_SERVER_RPC_PREFIX` → `PROXY_SERVER_RPC_PREFIX` - Rename `ROUTER_EXPLORER_RPC_PREFIX` → `PROXY_EXPLORER_RPC_PREFIX` - Rename `router_server_rpc_url()` → `proxy_server_rpc_url()` - Rename `router_explorer_rpc_url()` → `proxy_explorer_rpc_url()` - All URL builders use port 9997 (hero_proxy HTTP) - Update heartbeat sender, explorer proxy, CLI write_env() accordingly ### 2. hero_proxy: Add socket-type URL routing (hero_proxy repo) hero_proxy currently routes `/{service}/*` and picks the first socket it finds (prefers ui.sock over rpc.sock). For multi-node, we need to reach specific sockets. Add hero_router-style routing: `/{service}/{socket_type}/*` - `/{service}/rpc/*` → `{service}/rpc.sock` - `/{service}/ui/*` → `{service}/ui.sock` - `/{service}/explorer_rpc/*` → `{service}/explorer_rpc.sock` - Fall back to current `/{service}/*` behavior for backward compatibility This keeps URL formats consistent between hero_router (local) and hero_proxy (network). **Separate issue in hero_proxy repo.** ### 3. hero_compute --start: Configure hero_proxy Mycelium listener When starting in master or worker mode, `hero_compute --start` should: 1. Verify hero_proxy is running (check socket exists) 2. Call `mycelium.info` RPC to get the local Mycelium IPv6 3. Call `listener.add` RPC to create a listener on `[mycelium-ipv6]:9997` with `auto_start=true` 4. Store the Mycelium IPv6 in the env file as `MYCELIUM_IP` This way the user doesn't need to manually configure hero_proxy. ### 4. Install script + central config Add to central config (`hero_compute_config/development.toml`): ```toml [releases.hero_router] repo = "lhumina_code/hero_router" version = "v0.2.0" binaries = ["hero_router"] asset_suffix = "linux-amd64-musl" [releases.hero_proxy] repo = "lhumina_code/hero_proxy" version = "v0.1.0" binaries = ["hero_proxy", "hero_proxy_server", "hero_proxy_ui"] asset_suffix = "linux-amd64-musl" ``` Update `scripts/install.sh`: - Download and install hero_router and hero_proxy binaries - Start hero_router via hero_proc (or `hero_router start`) - Start hero_proxy via hero_proc (or `hero_proxy --start`) Update `scripts/uninstall.sh` to clean up hero_router and hero_proxy. ### 5. hero_router port fix (hero_router repo) Update hero_router default port from 9998 to 9988 to match the hero_sockets skill spec. **Separate issue in hero_router repo.** ### 6. Documentation - Update `docs/setup.md` — multi-node requires hero_proxy on each node - Update `docs/architecture.md` — show hero_proxy in the flow diagram - Update `docs/configuration.md` — new env vars, remove hero_router port references - Update `.env.example` — update URL format examples ## Dependencies - hero_proxy needs socket-type routing (`/{service}/{socket_type}/*`) — separate issue - hero_router needs port change to 9988 — separate issue - hero_proxy v0.1.0 release must complete (CI pending) ## Acceptance Criteria - [ ] hero_compute SDK uses hero_proxy port (9997) not hero_router port - [ ] `hero_compute --start --mode master` configures hero_proxy Mycelium listener - [ ] `hero_compute --start --mode worker --master-ip <mycelium-ipv6>` sends heartbeats through hero_proxy - [ ] Master explorer can proxy RPC calls to worker through hero_proxy - [ ] Install script downloads and starts hero_router + hero_proxy - [ ] Single node (local) mode works unchanged - [ ] Multi-node tested: two nodes on different networks connected via Mycelium ## Related Issues - #65 — Phase 1: Socket convention (completed) - #69 — Phase 2: Hero Router replacement (completed, but needs revision for hero_proxy) - #80 — CamelCase method fix - hero_proxy: socket-type routing (to be created) - hero_router: port 9998→9988 (to be created)
mahmoud commented 2026-04-08 12:33:29 +00:00
Author
Owner
Copy link

Implementation Spec for Issue #83

Objective

Enable hero_compute multi-node communication via hero_proxy over Mycelium IPv6, replacing the hero_router dependency for cross-node traffic.

Pre-completed

  • hero_proxy socket-type routing (hero_proxy#16, PR#17 — merged)
  • Central config updated with hero_router v0.1.1 and hero_proxy v0.1.1

Files to Modify

File Description
crates/hero_compute_sdk/src/lib.rs Rename HERO_ROUTER_PORT/router_* to HERO_PROXY_PORT/proxy_*, port 9998 to 9997
crates/hero_compute_server/src/heartbeat_sender.rs Update to use proxy_* functions
crates/hero_compute_explorer/src/explorer/proxy.rs Update to use proxy_* functions
crates/hero_compute/src/main.rs Update write_env(), add hero_proxy Mycelium listener setup
scripts/install.sh Add hero_router and hero_proxy download/install/start
scripts/uninstall.sh Add hero_router and hero_proxy cleanup
.env.example Update URL format examples
docs/setup.md Update multi-node docs
docs/architecture.md Update flow diagrams
docs/configuration.md Update env vars

Implementation Plan

Step 1: SDK — Rename router to proxy (Foundation)

Files: crates/hero_compute_sdk/src/lib.rs

  • Rename HERO_ROUTER_PORT to HERO_PROXY_PORT = 9997
  • Rename ROUTER_SERVER_RPC_PREFIX to PROXY_SERVER_RPC_PREFIX
  • Rename ROUTER_EXPLORER_RPC_PREFIX to PROXY_EXPLORER_RPC_PREFIX
  • Rename router_server_rpc_url() to proxy_server_rpc_url()
  • Rename router_explorer_rpc_url() to proxy_explorer_rpc_url()
  • Keep http_rpc_tcp() and http_rpc_unix() unchanged
    Dependencies: none

Step 2: Update heartbeat sender + explorer proxy

Files: heartbeat_sender.rs, proxy.rs

  • Update all references from router_* to proxy_*
  • Update HERO_ROUTER_PORT to HERO_PROXY_PORT
    Dependencies: Step 1

Step 3: CLI — hero_proxy Mycelium listener setup + write_env update

Files: crates/hero_compute/src/main.rs

  • In write_env(): update router_* calls to proxy_*
  • In self_start(): after starting services, if mode is master or worker:
    1. Check hero_proxy socket exists
    2. Call mycelium.info RPC via http_rpc_unix to get Mycelium IPv6
    3. Call listener.add RPC to create listener on [mycelium-ipv6]:9997
    4. Store MYCELIUM_IP in env file
  • Update detect_outbound_ip() to use HERO_PROXY_PORT
    Dependencies: Step 1

Step 4: Install script — Add hero_router + hero_proxy

Files: scripts/install.sh, scripts/uninstall.sh

  • Add hero_router and hero_proxy download steps (read from central config)
  • Start hero_router via hero_router start
  • Start hero_proxy via hero_proxy --start
  • Add cleanup in uninstall.sh
    Dependencies: none (parallel with Steps 1-3)

Step 5: Documentation

Files: .env.example, docs/setup.md, docs/architecture.md, docs/configuration.md

  • Update all references from hero_router port 9998 to hero_proxy port 9997
  • Update multi-node architecture diagrams
  • Update env var examples
    Dependencies: Steps 1-4

Acceptance Criteria

  • SDK uses hero_proxy port (9997) not hero_router port
  • hero_compute --start configures hero_proxy Mycelium listener
  • Heartbeats flow through hero_proxy
  • Explorer proxy calls flow through hero_proxy
  • Install script downloads and starts hero_router + hero_proxy
  • Single node (local) mode works unchanged
  • cargo build --workspace passes
  • cargo test --workspace passes
  • make lint passes
## Implementation Spec for Issue #83 ### Objective Enable hero_compute multi-node communication via hero_proxy over Mycelium IPv6, replacing the hero_router dependency for cross-node traffic. ### Pre-completed - hero_proxy socket-type routing (hero_proxy#16, PR#17 — merged) - Central config updated with hero_router v0.1.1 and hero_proxy v0.1.1 ### Files to Modify | File | Description | |------|-------------| | `crates/hero_compute_sdk/src/lib.rs` | Rename HERO_ROUTER_PORT/router_* to HERO_PROXY_PORT/proxy_*, port 9998 to 9997 | | `crates/hero_compute_server/src/heartbeat_sender.rs` | Update to use proxy_* functions | | `crates/hero_compute_explorer/src/explorer/proxy.rs` | Update to use proxy_* functions | | `crates/hero_compute/src/main.rs` | Update write_env(), add hero_proxy Mycelium listener setup | | `scripts/install.sh` | Add hero_router and hero_proxy download/install/start | | `scripts/uninstall.sh` | Add hero_router and hero_proxy cleanup | | `.env.example` | Update URL format examples | | `docs/setup.md` | Update multi-node docs | | `docs/architecture.md` | Update flow diagrams | | `docs/configuration.md` | Update env vars | ### Implementation Plan #### Step 1: SDK — Rename router to proxy (Foundation) Files: `crates/hero_compute_sdk/src/lib.rs` - Rename `HERO_ROUTER_PORT` to `HERO_PROXY_PORT = 9997` - Rename `ROUTER_SERVER_RPC_PREFIX` to `PROXY_SERVER_RPC_PREFIX` - Rename `ROUTER_EXPLORER_RPC_PREFIX` to `PROXY_EXPLORER_RPC_PREFIX` - Rename `router_server_rpc_url()` to `proxy_server_rpc_url()` - Rename `router_explorer_rpc_url()` to `proxy_explorer_rpc_url()` - Keep `http_rpc_tcp()` and `http_rpc_unix()` unchanged Dependencies: none #### Step 2: Update heartbeat sender + explorer proxy Files: `heartbeat_sender.rs`, `proxy.rs` - Update all references from router_* to proxy_* - Update HERO_ROUTER_PORT to HERO_PROXY_PORT Dependencies: Step 1 #### Step 3: CLI — hero_proxy Mycelium listener setup + write_env update Files: `crates/hero_compute/src/main.rs` - In write_env(): update router_* calls to proxy_* - In self_start(): after starting services, if mode is master or worker: 1. Check hero_proxy socket exists 2. Call mycelium.info RPC via http_rpc_unix to get Mycelium IPv6 3. Call listener.add RPC to create listener on [mycelium-ipv6]:9997 4. Store MYCELIUM_IP in env file - Update detect_outbound_ip() to use HERO_PROXY_PORT Dependencies: Step 1 #### Step 4: Install script — Add hero_router + hero_proxy Files: `scripts/install.sh`, `scripts/uninstall.sh` - Add hero_router and hero_proxy download steps (read from central config) - Start hero_router via `hero_router start` - Start hero_proxy via `hero_proxy --start` - Add cleanup in uninstall.sh Dependencies: none (parallel with Steps 1-3) #### Step 5: Documentation Files: `.env.example`, `docs/setup.md`, `docs/architecture.md`, `docs/configuration.md` - Update all references from hero_router port 9998 to hero_proxy port 9997 - Update multi-node architecture diagrams - Update env var examples Dependencies: Steps 1-4 ### Acceptance Criteria - [ ] SDK uses hero_proxy port (9997) not hero_router port - [ ] hero_compute --start configures hero_proxy Mycelium listener - [ ] Heartbeats flow through hero_proxy - [ ] Explorer proxy calls flow through hero_proxy - [ ] Install script downloads and starts hero_router + hero_proxy - [ ] Single node (local) mode works unchanged - [ ] cargo build --workspace passes - [ ] cargo test --workspace passes - [ ] make lint passes
mahmoud self-assigned this 2026-04-08 12:33:44 +00:00
mahmoud added this to the ACTIVE project 2026-04-08 12:33:46 +00:00
mahmoud added this to the now milestone 2026-04-08 12:33:49 +00:00
mahmoud commented 2026-04-08 13:01:31 +00:00
Author
Owner
Copy link

Implementation Summary

Changes

  • SDK: Renamed HERO_ROUTER_PORT to HERO_PROXY_PORT (9997), all router_* to proxy_*
  • CLI: Added setup_hero_proxy_mycelium_listener() for auto Mycelium config
  • Install script: Added hero_router + hero_proxy download/install/start (Steps 7-8)
  • Docs: Updated all multi-node references from Hero Router to Hero Proxy

Test Results

  • Build: pass
  • Lint: pass
  • Tests: 13 suites, 0 failures

PR: #85
Commit: c6aeeb4

## Implementation Summary ### Changes - SDK: Renamed HERO_ROUTER_PORT to HERO_PROXY_PORT (9997), all router_* to proxy_* - CLI: Added setup_hero_proxy_mycelium_listener() for auto Mycelium config - Install script: Added hero_router + hero_proxy download/install/start (Steps 7-8) - Docs: Updated all multi-node references from Hero Router to Hero Proxy ### Test Results - Build: pass - Lint: pass - Tests: 13 suites, 0 failures PR: https://forge.ourworld.tf/lhumina_code/hero_compute/pulls/85 Commit: c6aeeb4
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
development_fix_local_resource
development_hero_proxy_multinode
development_tfgrid
development_hero_router
main
development_fix_deploy_ssh_keys_target_node
v0.1.6
v0.1.5
v0.1.4
v0.1.3
v0.1.2
v0.1.1
v0.1.0
Labels
Clear labels   
prio_critical

   
prio_low

   
type_bug

   
type_contact

   
type_issue

   
type_lead

   
type_question

   
type_story

   
type_task
No labels
prio_critical
prio_low
type_bug
type_contact
type_issue
type_lead
type_question
type_story
type_task
Milestone
Clear milestone
No items
No milestone
now
Projects
Clear projects
No items
No project
ACTIVE
Assignees
Clear assignees
No assignees
mahmoud
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
lhumina_code/hero_compute#83
No description provided.