Hero RPC

Schema-driven code generation and RPC framework for building distributed services. Define your data model in .oschema files, and Hero RPC generates everything: Rust types, database persistence, JSON-RPC server, cross-platform client SDK, and workspace scaffolding.

Packages

Crate	Description
hero_rpc_osis	Core framework: OSchema parsing, code generation, SmartID storage, JSON-RPC server, workspace scaffolding
hero_rpc_derive	Procedural macros: OsisObject, openrpc_client!, MCP client generation
hero_rpc_client	Cross-platform HTTP/WASM RPC client for generated services

How It Works

1. Define your schema

Create .oschema files that describe your data model:

Difficulty = "easy" | "medium" | "hard"

# Recipe [rootobject]
Recipe = {
    sid: str
    @index
    name: str
    @index
    description: str
    difficulty: Difficulty
    prep_time: u32
    ingredients: [str]
    created_at: otime
}

service RecipeService {
    version: "1.0.0"
    description: "Recipe management"

    get_by_category(category: Category) -> [Recipe]
}

2. Scaffold a workspace

Generate a complete 5-crate workspace from your schemas:

cargo run -p hero_rpc_osis --bin hero_rpc_generator -- --name hero_recipes --schemas-dir schemas

This creates:

hero_recipes/
├── Cargo.toml                          # Workspace root
├── schemas/
│   └── recipes/recipes.oschema
├── crates/
│   ├── hero_recipes/                   # Core types + DB persistence
│   │   ├── Cargo.toml
│   │   └── build.rs                    # Code generation on cargo build
│   ├── hero_recipes_server/            # JSON-RPC server binary
│   │   ├── Cargo.toml
│   │   └── src/main.rs
│   ├── hero_recipes_client/            # Cross-platform client SDK
│   │   └── Cargo.toml
│   ├── hero_recipes_rhai/              # Rhai scripting bindings
│   │   ├── Cargo.toml
│   │   └── src/lib.rs
│   └── hero_recipes_admin/            # Admin panel (Unix socket)
│       ├── Cargo.toml
│       └── src/main.rs
└── docs/schemas/

3. Build and run

Use Nu shell to build and manage generated services:

cargo build -p hero_recipes                   # Generates types + handlers
service recipes install                        # Build + install binaries
service recipes start                          # Start via hero_proc
service recipes start --update                 # Rebuild, reinstall, restart
service recipes start --update --reset         # Rebuild + reset data
service recipes stop                           # Stop via hero_proc
service recipes status                         # Check status

The server exposes a single unified Unix socket:

$HERO_SOCKET_DIR/hero-recipes/rpc.sock    (default: ~/hero/var/sockets/hero-recipes/rpc.sock)

All domains, management methods, and discovery are served through this one socket:

• POST /rpc — JSON-RPC 2.0 API with CRUD operations per root object
• GET /health — Health check
• GET /openrpc.json — OpenRPC specification
• GET /.well-known/heroservice.json — Discovery manifest

Context isolation is handled via the X-Hero-Context header (integer, default 0 = admin).

4. Use the client

Generated client code provides typed access:

use hero_recipes_client::RecipeClient;

let client = RecipeClient::new("http://localhost:8080", "root", "recipes")?;
let recipes = client.recipe_list().await?;

Package Details

hero_rpc_osis

The core framework. Handles:

• OSchema parsing — Reads .oschema files and produces an AST
• Code generation — Generates Rust types, server handlers, client SDKs, and Rhai bindings via build.rs
• SmartID (SID) — 4-6 character base-36 distributed identifiers for all objects
• Filesystem persistence — OTOML-format storage with directory-based organization
• JSON-RPC server — Axum-based server with CRUD + custom service methods (behind rpc feature)
• Web inspector — Built-in data browser for development
• Workspace scaffolding — hero_rpc_generator CLI generates complete 5-crate workspaces

Key features:

• rpc — Enables the Axum JSON-RPC server, Redis caching, and remote index client
• rhai — Enables Rhai scripting bindings generation

hero_rpc_derive

Procedural macros:

• #[derive(OsisObject)] — Generates the OsisObject trait for database persistence. Requires sid: SmartId field. Supports #[osis(type_name = "...")] and #[osis(index = "field1, field2")].

• openrpc_client! — Generates typed RPC clients from OpenRPC specifications:

  openrpc_client!("specs/myservice.openrpc.json");
  openrpc_client!(socket = "/tmp/myservice.sock");
  openrpc_client!("spec.json", name = "CustomClient");
  

• mcp_client_from_json! / mcp_client_from_file! — Generate typed MCP (Model Context Protocol) client structs from JSON specifications.

hero_rpc_client

Lightweight cross-platform RPC client:

• Native (desktop, iOS, Android) — Uses reqwest for HTTP transport
• WASM (browser) — Uses gloo-net for fetch API
• JSON-RPC 2.0 framing with authentication token support
• Generated domain clients compose OsisClient for typed API access

use hero_rpc_client::OsisClient;

// Native
let client = OsisClient::new("http://localhost:8080", "root", "recipes")?;

// With auth
let client = OsisClient::with_token("http://...", "root", "recipes", "my-token")?;

// JSON-RPC call
let result: Vec<String> = client.rpc_call("recipe.list", serde_json::json!({})).await?;

Architecture

.oschema files
    │
    ▼
hero_rpc_osis (build.rs)  ─── generates ──→  Rust types, server handlers,
    │                                          client SDK, Rhai bindings
    │
    ├── hero_rpc_derive        (compile-time macros)
    └── hero_rpc_client        (runtime HTTP client)

Code generation flow:

1. build.rs in the core crate calls OschemaBuilder::generate()
2. OSchema files are parsed into an AST
3. Rust types with #[derive(OsisObject)] are generated for each root object
4. Server handlers (CRUD + custom methods) are generated for the _server crate
5. Client methods are generated for the _client crate
6. OpenRPC specification JSON is emitted alongside

Runtime flow:

1. _server binary starts, creates a single Unix socket per service
2. Registers domain handlers with the unified Axum JSON-RPC router
3. Context isolation via X-Hero-Context header (integer: 0 = admin, ≥1 = user)
4. hero_router maps external TCP to service sockets (services never open TCP ports)
5. _client SDK connects via HTTP and sends JSON-RPC 2.0 requests

Building

cargo check --workspace
cargo build --workspace

Note: This repo uses Nu shell scripts for all build and lifecycle management. Makefiles and bash scripts are not used. Do not add them.

Requirements

• Rust 1.93.0+
• Edition 2024
• Nu shell for service lifecycle management

Related Projects

• hero_lib — Core Rust libraries (otoml, derive, sid, infra)
• hero_skills — Hero service conventions (hero_sockets, hero_context, hero_proc_sdk)
• hero_proc — Process supervisor and lifecycle manager

License

Apache-2.0