Getting-started guide aligned with hero_sdk rethinking and new socket conventions #17

New issue

Closed

opened 2026-04-06 09:51:34 +00:00 by timur · 1 comment

timur commented

2026-04-06 09:51:34 +00:00

Owner

Background

Closes the scope of the old #8. The hero_sdk rethinking (#13) and updated socket/context conventions (from hero_skills) have changed the architecture significantly. A new getting-started guide is needed.

What Changed Since #8

hero_rpc → hero_sdk rename and restructure
Socket-per-service directory ($HERO_SOCKET_DIR/<service>/rpc.sock) instead of per-context socket trees
Context via X-Hero-Context header, not socket paths
hero_proc replaces zinit for service lifecycle
HeroServer builder API replaces OServer::run_cli() pattern
hero_client! macro for typed cross-platform clients

Deliverables

1. `GETTING_STARTED.md` at repo root

Prerequisites
Creating a service with HeroServer builder (~15 line main.rs)
OSchema definitions
hero_client! usage (native + WASM)
Socket conventions: ~/hero/var/sockets/<service>/rpc.sock
Context via headers
hero_proc lifecycle (--start, --stop)
Curl examples with --unix-socket

2. Working hero_food example

Validates the full DX end-to-end
Own Makefile with build, run, test, clean
Curl smoke tests

3. Updated root Makefile

make example — build and run hero_food
make example-test — smoke tests

Acceptance Criteria

New developer can follow guide end-to-end
hero_food builds and runs
Curl commands return expected responses
Socket paths follow new convention

## Background Closes the scope of the old #8. The hero_sdk rethinking (#13) and updated socket/context conventions (from hero_skills) have changed the architecture significantly. A new getting-started guide is needed. ## What Changed Since #8 - **hero_rpc → hero_sdk** rename and restructure - **Socket-per-service directory** (`$HERO_SOCKET_DIR/<service>/rpc.sock`) instead of per-context socket trees - **Context via `X-Hero-Context` header**, not socket paths - **hero_proc** replaces zinit for service lifecycle - **HeroServer builder API** replaces OServer::run_cli() pattern - **hero_client! macro** for typed cross-platform clients ## Deliverables ### 1. `GETTING_STARTED.md` at repo root - Prerequisites - Creating a service with HeroServer builder (~15 line main.rs) - OSchema definitions - hero_client! usage (native + WASM) - Socket conventions: `~/hero/var/sockets/<service>/rpc.sock` - Context via headers - hero_proc lifecycle (`--start`, `--stop`) - Curl examples with `--unix-socket` ### 2. Working hero_food example - Validates the full DX end-to-end - Own Makefile with `build`, `run`, `test`, `clean` - Curl smoke tests ### 3. Updated root Makefile - `make example` — build and run hero_food - `make example-test` — smoke tests ## Acceptance Criteria - [ ] New developer can follow guide end-to-end - [ ] hero_food builds and runs - [ ] Curl commands return expected responses - [ ] Socket paths follow new convention

timur commented

2026-04-07 17:57:00 +00:00

Author

Owner

GETTING_STARTED.md has been fully updated:

Unified socket strategy docs
--start/--stop singlebin pattern
Correct OTOML data format in curl examples
Updated project layout reference
Removed references to old per-domain sockets

Closing as resolved.

GETTING_STARTED.md has been fully updated: - Unified socket strategy docs - `--start`/`--stop` singlebin pattern - Correct OTOML data format in curl examples - Updated project layout reference - Removed references to old per-domain sockets Closing as resolved.