walkthrough: show real generated code + rename example/ → examples/ #107

Merged

timur merged 1 commit from walkthrough-improvements into development

2026-05-21 11:17:42 +00:00

timur commented

2026-05-21 11:17:36 +00:00

Owner

Two changes:

1. Show real generated code in the walkthrough

Step 4 (SDK trait) and Step 5 (server-side CRUD dispatcher) now run the actual codegen pipeline and print the emitted files — no more illustrative hand-written snippets.

Step 4 invokes OschemaBuilder::with_manifest_dir(...).generate() against the scaffolded workspace, then reads back sdk/rust/src/generated/greetings.rs and prints the #[rpc(server, client)] pub trait Greetings { ... } block. All seven CRUD methods + the hello.greet service method appear as actually emitted, with the right #[method(..., param_kind = map)] attributes and signatures.
Step 5 reads crates/hero_demo_server/src/greetings/generated/server.rs and prints the match request.method.as_str() dispatch arm — eight cases (seven CRUD + one service method), exactly what the OSIS server-side emitter produces.

Also fixes the demo schema: the OSIS server-side emitter requires the explicit [rootobject] marker (the OpenRPC + Rust SDK emitters accept either marker OR a sid field; the OSIS emitter is stricter). Without it, the dispatcher only carried the service method — confusing for a walkthrough.

2. Rename top-level `example/` → `examples/`

Cargo convention is plural examples/. Rename via git mv preserves history. References updated in:

root Cargo.toml (workspace members + exclude list)
crates/oschema/tests/real_schemas.rs (test asset path)
GETTING_STARTED.md (3 mentions)
docs/adr/001-configurable-socket-and-data-paths.md
examples/recipe_server/Cargo.toml (in-tree-patch comment)
examples/recipe_server/README.md (4 mentions)
the walkthrough's own doc-comment

Test plan

cargo check --workspace passes.
cargo test -p hero_rpc_oschema --test real_schemas — 4/4 pass (schema-path test still finds files).
cargo run --manifest-path examples/recipe_server/Cargo.toml --example 01_walkthrough completes end-to-end with all six steps producing real output.

Two changes: ## 1. Show real generated code in the walkthrough Step 4 (SDK trait) and Step 5 (server-side CRUD dispatcher) now run the actual codegen pipeline and print the emitted files — no more illustrative hand-written snippets. - **Step 4** invokes `OschemaBuilder::with_manifest_dir(...).generate()` against the scaffolded workspace, then reads back `sdk/rust/src/generated/greetings.rs` and prints the `#[rpc(server, client)] pub trait Greetings { ... }` block. All seven CRUD methods + the `hello.greet` service method appear as actually emitted, with the right `#[method(..., param_kind = map)]` attributes and signatures. - **Step 5** reads `crates/hero_demo_server/src/greetings/generated/server.rs` and prints the `match request.method.as_str()` dispatch arm — eight cases (seven CRUD + one service method), exactly what the OSIS server-side emitter produces. Also fixes the demo schema: the OSIS server-side emitter requires the explicit `[rootobject]` marker (the OpenRPC + Rust SDK emitters accept either marker OR a `sid` field; the OSIS emitter is stricter). Without it, the dispatcher only carried the service method — confusing for a walkthrough. ## 2. Rename top-level `example/` → `examples/` Cargo convention is plural `examples/`. Rename via `git mv` preserves history. References updated in: - root `Cargo.toml` (workspace members + exclude list) - `crates/oschema/tests/real_schemas.rs` (test asset path) - `GETTING_STARTED.md` (3 mentions) - `docs/adr/001-configurable-socket-and-data-paths.md` - `examples/recipe_server/Cargo.toml` (in-tree-patch comment) - `examples/recipe_server/README.md` (4 mentions) - the walkthrough's own doc-comment ## Test plan - [x] `cargo check --workspace` passes. - [x] `cargo test -p hero_rpc_oschema --test real_schemas` — 4/4 pass (schema-path test still finds files). - [x] `cargo run --manifest-path examples/recipe_server/Cargo.toml --example 01_walkthrough` completes end-to-end with all six steps producing real output.

timur added 1 commit

2026-05-21 11:17:36 +00:00

walkthrough: show real generated code + rename example/ → examples/

Test / test (push) Failing after 3m2s

Details

Test / test (pull_request) Failing after 2m56s

Details

df6fe435f3

Two changes:

## 1. Show actual codegen output (not illustrative snippets)

Step 4 (the SDK trait) and Step 5 (the server-side CRUD dispatcher)
of the walkthrough now run the real codegen pipeline and print the
emitted file contents:

- **Step 4** invokes `OschemaBuilder::with_manifest_dir(...).generate()`
  against the scaffolded workspace, then reads back
  `sdk/rust/src/generated/greetings.rs` and prints the
  `#[rpc(server, client)] pub trait Greetings { ... }` block. All seven
  CRUD methods + the `hello.greet` service method appear as actually
  emitted, with the right `#[method(..., param_kind = map)]` attributes
  and signatures.
- **Step 5** reads `crates/hero_demo_server/src/greetings/generated/server.rs`
  and prints the `match request.method.as_str()` dispatch arm — eight
  cases (seven CRUD + one service method), exactly what the OSIS
  server-side emitter produces.

The previous illustrative snippets are gone. Every step's output is now
real codegen, not hand-written.

Also adds the `[rootobject]` marker to the demo schema. The OSIS
server-side emitter requires the explicit marker (the OpenRPC + Rust
SDK emitters accept either marker OR a sid field; the OSIS emitter is
stricter). Without it the dispatch arm only carries the service
method — confusing for a walkthrough.

## 2. Rename top-level `example/` → `examples/`

Cargo convention is plural `examples/`. The directory rename is done
via `git mv` to preserve history. Updated references:

- root `Cargo.toml` (workspace members + exclude)
- `crates/oschema/tests/real_schemas.rs` (test path)
- `GETTING_STARTED.md` (3 mentions)
- `docs/adr/001-configurable-socket-and-data-paths.md`
- `examples/recipe_server/Cargo.toml` (in-tree patch comment)
- `examples/recipe_server/README.md` (4 mentions)
- the walkthrough's own doc-comment

Verified: `cargo check --workspace` passes; the schema parsing test
still picks up `examples/recipe_server/schemas/...`; the walkthrough
runs end-to-end from the repo root via `--manifest-path
examples/recipe_server/Cargo.toml --example 01_walkthrough`.