examples: restructure + drop per-service _examples placeholder #116

Merged

timur merged 1 commit from examples-restructure into development

2026-05-21 13:13:54 +00:00

timur commented

2026-05-21 13:13:48 +00:00

Owner

Three related cleanups in one PR — all driven by the maintainer call that the example layout was confusing.

1. Walkthrough is now a top-level crate

Before: examples/recipe_server/crates/hero_recipes_examples/examples/01_walkthrough.rs
After: examples/walkthrough/src/main.rs

The walkthrough scaffolds a new service called hero_demo and drives RPC against an in-process server — it has nothing to do with the recipes domain. Living inside recipe_server/crates/hero_recipes_examples was pure path confusion. It's now a standalone root-workspace-member crate, runnable as:

cargo run -p hero_walkthrough

Step 6 used to depend on hero_recipes_server::OsisRecipes (one of the reasons the walkthrough lived inside recipe_server's nested workspace). That dependency is replaced by an inline DemoApp — a ~80-line OsisAppRpcHandler impl with an in-memory store, defined in the same main.rs. The walkthrough is now fully self-contained: zero recipe dependency. Step 6 exercises a real greeting.set + greeting.list_full + hello.greet roundtrip end-to-end.

2. Codegen temp-dir leak (`target/schemas_<domain>/`)

build/emit/domain.rs used to write a "temp" copy of the per-domain schemas into <output_dir>/target/schemas_<domain>/. The path was inside the user's emitted tree, so the "temp" copy was actually persistent litter — visible in every scaffolded core-crate dir and flagged by anyone browsing the output (the maintainer caught it in the walkthrough demo tree).

Fix: stage the per-domain schemas into a real tempfile::TempDir which gets cleaned up on drop. tempfile was already a dev-dep; promoted to a runtime dep. The intermediate copy now lives in the system temp dir during codegen and disappears when the build finishes.

3. Stale + dead-weight cleanup

examples/hero_food/ deleted — entirely cruft, no source files, just leftover target/schemas_<domain>/ directories from an old codegen run.
examples/walkthrough_demo/ cleaned (already gitignored; the walkthrough recreates it).
Per-service hero_<name>_examples crate generation dropped from the scaffolder. It was a placeholder with a single TODO-stub 01_connect.rs that became the hosting crate for the walkthrough pre-restructure. With the walkthrough now standalone, the per-service placeholder is dead weight. Services that want bespoke examples can add a regular bin crate by hand.
examples/recipe_server/crates/hero_recipes_examples/ deleted (was hosting the walkthrough).
examples/recipe_server/Cargo.toml workspace members list dropped hero_recipes_examples.
Scaffolder docstring + PURPOSE.md table + layout comments updated to reflect the dropped crate. Two now-stale unit tests deleted; one updated to no longer reference _examples.
examples/README.md rewritten from a 4-row table to a 3-row table with clear "when to read it" guidance for each example (walkthrough / recipe_server / petstore pair).

Test plan

136/136 generator lib tests pass.
Full cargo test --workspace --lib passes (all 8 lib test suites green).
cargo run -p hero_walkthrough completes all six steps from the repo root; step 6 does live greeting.set + list_full + hello.greet against the inline DemoApp.
examples/walkthrough_demo/ after the run contains exactly the expected tree — no target/schemas_<domain>/ leak.
cargo build --manifest-path examples/recipe_server/Cargo.toml still completes clean across every workspace member.

Three related cleanups in one PR — all driven by the maintainer call that the example layout was confusing. ## 1. Walkthrough is now a top-level crate **Before:** `examples/recipe_server/crates/hero_recipes_examples/examples/01_walkthrough.rs` **After:** `examples/walkthrough/src/main.rs` The walkthrough scaffolds a *new* service called `hero_demo` and drives RPC against an in-process server — it has nothing to do with the recipes domain. Living inside `recipe_server/crates/hero_recipes_examples` was pure path confusion. It's now a standalone root-workspace-member crate, runnable as: ```bash cargo run -p hero_walkthrough ``` Step 6 used to depend on `hero_recipes_server::OsisRecipes` (one of the reasons the walkthrough lived inside recipe_server's nested workspace). That dependency is replaced by an inline `DemoApp` — a ~80-line `OsisAppRpcHandler` impl with an in-memory store, defined in the same `main.rs`. The walkthrough is now fully self-contained: zero recipe dependency. Step 6 exercises a real `greeting.set` + `greeting.list_full` + `hello.greet` roundtrip end-to-end. ## 2. Codegen temp-dir leak (`target/schemas_<domain>/`) `build/emit/domain.rs` used to write a "temp" copy of the per-domain schemas into `<output_dir>/target/schemas_<domain>/`. The path was *inside* the user's emitted tree, so the "temp" copy was actually persistent litter — visible in every scaffolded core-crate dir and flagged by anyone browsing the output (the maintainer caught it in the walkthrough demo tree). Fix: stage the per-domain schemas into a real `tempfile::TempDir` which gets cleaned up on drop. `tempfile` was already a dev-dep; promoted to a runtime dep. The intermediate copy now lives in the system temp dir during codegen and disappears when the build finishes. ## 3. Stale + dead-weight cleanup - `examples/hero_food/` deleted — entirely cruft, no source files, just leftover `target/schemas_<domain>/` directories from an old codegen run. - `examples/walkthrough_demo/` cleaned (already gitignored; the walkthrough recreates it). - Per-service `hero_<name>_examples` crate generation dropped from the scaffolder. It was a placeholder with a single TODO-stub `01_connect.rs` that became the hosting crate for the walkthrough pre-restructure. With the walkthrough now standalone, the per-service placeholder is dead weight. Services that want bespoke examples can add a regular bin crate by hand. - `examples/recipe_server/crates/hero_recipes_examples/` deleted (was hosting the walkthrough). - `examples/recipe_server/Cargo.toml` workspace members list dropped `hero_recipes_examples`. - Scaffolder docstring + PURPOSE.md table + layout comments updated to reflect the dropped crate. Two now-stale unit tests deleted; one updated to no longer reference `_examples`. - `examples/README.md` rewritten from a 4-row table to a 3-row table with clear "when to read it" guidance for each example (walkthrough / recipe_server / petstore pair). ## Test plan - [x] 136/136 generator lib tests pass. - [x] Full `cargo test --workspace --lib` passes (all 8 lib test suites green). - [x] `cargo run -p hero_walkthrough` completes all six steps from the repo root; step 6 does live `greeting.set` + `list_full` + `hello.greet` against the inline DemoApp. - [x] `examples/walkthrough_demo/` after the run contains exactly the expected tree — no `target/schemas_<domain>/` leak. - [x] `cargo build --manifest-path examples/recipe_server/Cargo.toml` still completes clean across every workspace member.

timur added 1 commit

2026-05-21 13:13:48 +00:00

examples: restructure + drop per-service _examples placeholder

Test / test (push) Failing after 1m44s

Details

Test / test (pull_request) Failing after 2m31s

Details

26b1170daa

Three related cleanups in one PR — all driven by the maintainer call
that the example layout was confusing.

## 1. Walkthrough is now a top-level crate

Before: `examples/recipe_server/crates/hero_recipes_examples/examples/01_walkthrough.rs`
After:  `examples/walkthrough/src/main.rs`

The walkthrough scaffolds a *new* service called `hero_demo` and drives
RPC against an in-process server — it has nothing to do with the
recipes domain. Living inside `recipe_server/crates/hero_recipes_examples`
was pure path confusion. It's now a standalone workspace member at
`examples/walkthrough/`, runnable as:

    cargo run -p hero_walkthrough

Step 6 used to depend on `hero_recipes_server::OsisRecipes` (one of the
reasons the walkthrough lived inside recipe_server's nested workspace).
That dependency is replaced by an inline `DemoApp` — a ~80-line
`OsisAppRpcHandler` impl with an in-memory store, defined in the same
`main.rs`. The walkthrough is now fully self-contained: zero recipe
dependency. Step 6 exercises a real `greeting.set` + `greeting.list_full`
+ `hello.greet` roundtrip end-to-end.

## 2. Codegen temp-dir leak (`target/schemas_<domain>/`)

`build/emit/domain.rs` used to write a "temp" copy of the per-domain
schemas into `<output_dir>/target/schemas_<domain>/`. The path was
*inside* the user's emitted tree, so the "temp" copy was actually
persistent litter — visible in every scaffolded core-crate dir and
flagged by anyone browsing the output (the maintainer caught it in
the walkthrough demo tree).

Fix: stage the per-domain schemas into a real `tempfile::TempDir`
which gets cleaned up on drop. `tempfile` was already a dev-dep;
promoted to a runtime dep with a comment explaining the move. The
intermediate copy of the schemas now lives in the system temp dir
during codegen and disappears when the build finishes.

## 3. Stale + dead-weight cleanup

- `examples/hero_food/` deleted — entirely cruft, no source files,
  just leftover `target/schemas_<domain>/` directories from an old
  codegen run (closes the obvious "what is this?" stumbling block).
- `examples/walkthrough_demo/` cleaned (already gitignored; the
  walkthrough recreates it).
- Per-service `hero_<name>_examples` crate generation dropped from
  the scaffolder. It was a placeholder with a single TODO-stub
  `01_connect.rs` that became the hosting crate for the walkthrough
  pre-restructure. With the walkthrough now standalone, the per-
  service placeholder is dead weight. Services that want bespoke
  examples can add a regular bin crate by hand.
- `examples/recipe_server/crates/hero_recipes_examples/` deleted
  (was hosting the walkthrough).
- `examples/recipe_server/Cargo.toml` workspace members list dropped
  `hero_recipes_examples`.
- Scaffolder docstring + PURPOSE.md table + layout comments updated
  to reflect the dropped crate. Two now-stale unit tests
  (`test_scaffold_emits_examples_crate`,
  `test_scaffold_workspace_includes_examples`) deleted; one updated
  to no longer reference `_examples`.
- `examples/README.md` rewritten from a 4-row table to a 3-row table
  with clear "when to read it" guidance for each example
  (walkthrough / recipe_server / petstore pair).

## Test plan

- [x] 136/136 generator lib tests pass.
- [x] Full `cargo test --workspace --lib` passes (all 8 lib test
      suites green).
- [x] `cargo run -p hero_walkthrough` completes all six steps from
      the repo root; step 6 does live `greeting.set` + `list_full`
      + `hello.greet` against the inline DemoApp.
- [x] `examples/walkthrough_demo/` after the run contains exactly
      the expected tree — no `target/schemas_<domain>/` leak.
- [x] `cargo build --manifest-path examples/recipe_server/Cargo.toml`
      still completes clean across every workspace member.