lhumina_code/hero_rpc
21
0
Fork 0
Code Issues 3 Pull requests Projects Releases 1 Packages Wiki Activity Actions

feat: getting-started guide with working examples and enhanced Makefile #8

New issue
Closed
opened 2026-03-20 23:41:44 +00:00 by timur · 4 comments
timur commented 2026-03-20 23:41:44 +00:00
Owner
Copy link

Problem

A developer picking up hero_rpc today cannot easily:

  • Understand how to create a new OpenRPC server from scratch
  • Run a working example end-to-end (schema → generated code → running server → curl test)
  • Know what make targets to run and in what order

The repo has examples buried in crates/osis/examples/basic/ and crates/server/examples/recipe_server/ but there is no clear "start here" path that ties them together.

Deliverables

1. GETTING_STARTED.md at repo root

Step-by-step guide covering:

  • Prerequisites (Rust 1.93+, edition 2024)
  • make build to build the workspace
  • How to create a new service from scratch:
    1. Write an .oschema file (reference the recipe_server example)
    2. Set up build.rs with OschemaBuildConfig + generate_server()
    3. Write main.rs using OServer::new() + server.register() + server.run()
    4. Build → server binds to ~/hero/var/sockets/{context}/{domain}.sock
    5. Test with curl --unix-socket calls
  • Link to OSchema syntax reference (exists in docs/)
  • Link to openrpc_client! macro docs (exists in docs/openrpc_client.md)
  • Link to openrpc_proxy! docs (exists in docs/openrpc_proxy.md)

2. Working example/ at repo root

Take the existing crates/server/examples/recipe_server/ and make sure it:

  • Builds standalone with cd example/recipe_server && cargo build
  • Has its own Makefile with targets: build, run, test, seed, clean
  • Has a README.md explaining what it demonstrates
  • Includes curl examples that work against the running socket
  • Documents the socket path: ~/hero/var/sockets/root/recipe_server.sock

3. Enhanced root Makefile

Add targets:

  • make example — build and run the recipe_server example
  • make example-test — run curl smoke tests against the example server

4. Socket convention documentation

Document clearly in GETTING_STARTED.md:

~/hero/var/sockets/{context}/{domain}.sock   — per-context domain sockets
~/hero/var/sockets/{service}_core.sock       — core management socket

Acceptance Criteria

  • A new developer can follow GETTING_STARTED.md end-to-end without asking questions
  • make example builds and runs a working server
  • curl commands in the docs return expected JSON-RPC responses
  • Socket paths follow ~/hero/var/sockets/{context}/{domain} convention
## Problem A developer picking up `hero_rpc` today cannot easily: - Understand how to create a new OpenRPC server from scratch - Run a working example end-to-end (schema → generated code → running server → curl test) - Know what `make` targets to run and in what order The repo has examples buried in `crates/osis/examples/basic/` and `crates/server/examples/recipe_server/` but there is no clear "start here" path that ties them together. ## Deliverables ### 1. `GETTING_STARTED.md` at repo root Step-by-step guide covering: - Prerequisites (Rust 1.93+, edition 2024) - `make build` to build the workspace - How to create a new service from scratch: 1. Write an `.oschema` file (reference the recipe_server example) 2. Set up `build.rs` with `OschemaBuildConfig` + `generate_server()` 3. Write `main.rs` using `OServer::new()` + `server.register()` + `server.run()` 4. Build → server binds to `~/hero/var/sockets/{context}/{domain}.sock` 5. Test with `curl --unix-socket` calls - Link to OSchema syntax reference (exists in `docs/`) - Link to `openrpc_client!` macro docs (exists in `docs/openrpc_client.md`) - Link to `openrpc_proxy!` docs (exists in `docs/openrpc_proxy.md`) ### 2. Working `example/` at repo root Take the existing `crates/server/examples/recipe_server/` and make sure it: - Builds standalone with `cd example/recipe_server && cargo build` - Has its own `Makefile` with targets: `build`, `run`, `test`, `seed`, `clean` - Has a `README.md` explaining what it demonstrates - Includes curl examples that work against the running socket - Documents the socket path: `~/hero/var/sockets/root/recipe_server.sock` ### 3. Enhanced root `Makefile` Add targets: - `make example` — build and run the recipe_server example - `make example-test` — run curl smoke tests against the example server ### 4. Socket convention documentation Document clearly in GETTING_STARTED.md: ``` ~/hero/var/sockets/{context}/{domain}.sock — per-context domain sockets ~/hero/var/sockets/{service}_core.sock — core management socket ``` ## Acceptance Criteria - [ ] A new developer can follow GETTING_STARTED.md end-to-end without asking questions - [ ] `make example` builds and runs a working server - [ ] curl commands in the docs return expected JSON-RPC responses - [ ] Socket paths follow `~/hero/var/sockets/{context}/{domain}` convention
timur commented 2026-03-20 23:51:03 +00:00
Author
Owner
Copy link

🚧 Starting implementation of this issue.

Plan:

  1. Create GETTING_STARTED.md at repo root
  2. Create standalone example/recipe_server/ with Makefile, README, curl tests
  3. Enhance root Makefile with example and example-test targets
  4. Document socket conventions

Will post progress updates as I go.

🚧 **Starting implementation** of this issue. Plan: 1. Create `GETTING_STARTED.md` at repo root 2. Create standalone `example/recipe_server/` with Makefile, README, curl tests 3. Enhance root `Makefile` with `example` and `example-test` targets 4. Document socket conventions Will post progress updates as I go.
timur commented 2026-03-21 00:13:47 +00:00
Author
Owner
Copy link

Progress update:

  • GETTING_STARTED.md created at repo root — covers prerequisites, building, creating a service from scratch, socket conventions, curl testing, and links to all existing docs
  • example/recipe_server/ created as workspace member with:
    • Cargo.toml (workspace deps)
    • build.rs (OSchema code generation)
    • Makefile with targets: build, run, test, test-full, seed, clean
    • README.md explaining what the example demonstrates
    • scripts/recipe_curl_test.sh curl smoke tests
    • Full source copied from crates/server/examples/recipe_server/
    • Seed data (3 recipes + 1 collection)
  • Root Makefile enhanced with example and example-test targets
  • Root Cargo.toml updated to include example/recipe_server as workspace member

Now building and testing...

**Progress update:** - [x] `GETTING_STARTED.md` created at repo root — covers prerequisites, building, creating a service from scratch, socket conventions, curl testing, and links to all existing docs - [x] `example/recipe_server/` created as workspace member with: - `Cargo.toml` (workspace deps) - `build.rs` (OSchema code generation) - `Makefile` with targets: `build`, `run`, `test`, `test-full`, `seed`, `clean` - `README.md` explaining what the example demonstrates - `scripts/recipe_curl_test.sh` curl smoke tests - Full source copied from `crates/server/examples/recipe_server/` - Seed data (3 recipes + 1 collection) - [x] Root `Makefile` enhanced with `example` and `example-test` targets - [x] Root `Cargo.toml` updated to include `example/recipe_server` as workspace member Now building and testing...
timur commented 2026-03-21 00:17:53 +00:00
Author
Owner
Copy link

Progress update: Build successful

Completed so far:

  • GETTING_STARTED.md at repo root — step-by-step guide covering prerequisites, building, creating a service from scratch, socket conventions, CRUD methods, and project layout reference
  • example/recipe_server/ — standalone example with:
    • Cargo.toml (workspace member, shares target/)
    • build.rs (OSchema code generation)
    • Makefile with targets: build, run, test, test-full, seed, clean
    • README.md explaining what it demonstrates
    • scripts/recipe_curl_test.sh — curl smoke tests for all CRUD methods
    • Copied source from crates/server/examples/recipe_server/ with seed data
  • Root Makefile enhanced with example and example-test targets
  • Cargo.toml updated — recipe_server added as workspace member

cargo build --release -p recipe_server compiles successfully.

Next: run the server and smoke tests, then commit and push.

**Progress update: Build successful** Completed so far: - [x] `GETTING_STARTED.md` at repo root — step-by-step guide covering prerequisites, building, creating a service from scratch, socket conventions, CRUD methods, and project layout reference - [x] `example/recipe_server/` — standalone example with: - `Cargo.toml` (workspace member, shares `target/`) - `build.rs` (OSchema code generation) - `Makefile` with targets: `build`, `run`, `test`, `test-full`, `seed`, `clean` - `README.md` explaining what it demonstrates - `scripts/recipe_curl_test.sh` — curl smoke tests for all CRUD methods - Copied source from `crates/server/examples/recipe_server/` with seed data - [x] Root `Makefile` enhanced with `example` and `example-test` targets - [x] `Cargo.toml` updated — `recipe_server` added as workspace member `cargo build --release -p recipe_server` compiles successfully. Next: run the server and smoke tests, then commit and push.
timur commented 2026-04-06 09:50:42 +00:00
Author
Owner
Copy link

Closing — the getting-started guide needs to be rewritten from scratch to align with the hero_sdk rethinking (#13). The socket conventions, workspace structure, and server API have all changed significantly. A new issue will be created for the updated guide once the rethinking stabilizes.

Closing — the getting-started guide needs to be rewritten from scratch to align with the hero_sdk rethinking (#13). The socket conventions, workspace structure, and server API have all changed significantly. A new issue will be created for the updated guide once the rethinking stabilizes.
timur closed this issue 2026-04-06 09:50:42 +00:00
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
development
development_13
development_rethinking
feat/os-server-prd-hero-rpc-prerequisites
main
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
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
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_rpc#8
No description provided.