lhumina_code/hero_books

Fork 0

Integrate zinit SDK: ZinitLifecycle for all binaries, logging via zinit, health checks #77

New issue

Closed

opened 2026-03-10 08:59:32 +00:00 by timur · 4 comments

timur commented

2026-03-10 08:59:32 +00:00

Owner

Context

Parent issue: lhumina_code/hero_os#24

Hero Books already has basic zinit integration for service registration (zinit_integration.rs), but it uses a custom approach rather than the standard ZinitLifecycle pattern. Logging goes through a custom in-memory OperationLogger rather than zinit's log system.

Important: In-process long-running operations (PDF generation, AI Q&A extraction, embedding upload, book export, background init pipeline, library rescan/reembed) stay as in-process async tasks. They work with in-memory state (loaded collections, Chrome CDP sessions, cached embedders, server config) and cannot be externalized to zinit subprocess jobs. However, they should log through zinit for centralized visibility.

1. Adopt `ZinitLifecycle` for hero_books_server

Files:

crates/hero_books_server/src/main.rs
crates/hero_books_server/src/zinit_integration.rs (to be removed)

Currently uses a custom --start flag and hand-written zinit registration code. Should adopt the standard ZinitLifecycle pattern (non-OpenRPC binary) with run/start/stop/status/logs/serve subcommands.

Add hero_rpc_server dependency for ZinitLifecycle. Remove zinit_integration.rs.

2. Add `ZinitLifecycle` to hero_books_ui

File: crates/hero_books_ui/src/main.rs

Currently standalone binary with no lifecycle management. Add same ZinitLifecycle subcommand pattern.

3. Add `ZinitLifecycle` to hero_books_viewer

File: crates/hero_books_viewer/src/main.rs

Same — add ZinitLifecycle subcommands.

4. Replace custom OperationLogger with zinit logs

Files:

crates/hero_books_server/src/admin/logger.rs — Custom circular-buffer OperationLogger (390 lines)
crates/hero_books_server/src/logging.rs — hb_log! macro (dual-channel: console + in-memory)

Replace with zinit logs.insert() using structured source names. The hb_log! macro should forward to zinit instead of the in-memory buffer.

Log source naming convention

Operation	Zinit Log Source
Server startup	`hero_books.startup`
Namespace discovery	`hero_books.discover.{namespace}`
Library rescan	`hero_books.rescan.{namespace}`
Re-embed	`hero_books.reembed.{namespace}`
Collection scan	`hero_books.scan.{collection}`
Q&A extraction	`hero_books.qa.{collection}`
Book export	`hero_books.export.{book}`
PDF generation	`hero_books.pdf.{book}`
Search indexing	`hero_books.index.{namespace}`
Git push AI	`hero_books.push_ai.{repo}`

5. Health checks in zinit service registration

File: crates/hero_books_server/src/zinit_integration.rs (currently no health check)

Configure HTTP health checks for all three services:

Server: /health on Unix socket
UI: /health on Unix socket
Viewer: /health on Unix socket

6. Remove shell scripts, use binary subcommands

Files to remove:

scripts/run-services.sh
scripts/stop.sh
scripts/status.sh

Replace with Makefile targets that call binary subcommands:

run: build
	cargo run -p hero_books_server -- run

start: build
	cargo run -p hero_books_server -- start
	cargo run -p hero_books_ui -- start
	cargo run -p hero_books_viewer -- start

stop:
	@cargo run -p hero_books_server -- stop 2>/dev/null || true
	@cargo run -p hero_books_ui -- stop 2>/dev/null || true
	@cargo run -p hero_books_viewer -- stop 2>/dev/null || true

7. Update zinit_sdk dependency

File: crates/hero_books_server/Cargo.toml

Update to development_kristof branch. Add hero_rpc_server dependency for ZinitLifecycle.

Summary

Area	Current	Target
Server lifecycle	Custom `zinit_integration.rs` + `--start` flag	`ZinitLifecycle` subcommands
UI lifecycle	Standalone binary	`ZinitLifecycle` subcommands
Viewer lifecycle	Standalone binary	`ZinitLifecycle` subcommands
Logging	Custom `OperationLogger` (1000-entry buffer) + `hb_log!` macro	Zinit `logs.insert()` with source naming
Health checks	Not configured in zinit	HTTP health check on `/health`
Shell scripts	`run-services.sh`, `stop.sh`, `status.sh`	Binary subcommands via Makefile
In-process ops	Background threads / async tasks	Stay in-process, log through zinit

Acceptance Criteria

All 3 binaries have run/start/stop/status/logs/serve subcommands via ZinitLifecycle
zinit_integration.rs removed (replaced by ZinitLifecycle)
hb_log! macro forwards to zinit with structured source names
Custom OperationLogger removed or reduced to thin wrapper around zinit logs
Health checks configured in service registration for all 3 services
Shell scripts removed, Makefile uses binary subcommands
zinit_sdk dependency updated to development_kristof

## Context Parent issue: https://forge.ourworld.tf/lhumina_code/hero_os/issues/24 Hero Books already has **basic zinit integration** for service registration (`zinit_integration.rs`), but it uses a custom approach rather than the standard `ZinitLifecycle` pattern. Logging goes through a custom in-memory `OperationLogger` rather than zinit's log system. **Important:** In-process long-running operations (PDF generation, AI Q&A extraction, embedding upload, book export, background init pipeline, library rescan/reembed) stay as in-process async tasks. They work with in-memory state (loaded collections, Chrome CDP sessions, cached embedders, server config) and cannot be externalized to zinit subprocess jobs. However, they should **log through zinit** for centralized visibility. --- ## 1. Adopt `ZinitLifecycle` for hero_books_server **Files:** - `crates/hero_books_server/src/main.rs` - `crates/hero_books_server/src/zinit_integration.rs` (to be removed) Currently uses a custom `--start` flag and hand-written zinit registration code. Should adopt the standard `ZinitLifecycle` pattern (non-OpenRPC binary) with `run`/`start`/`stop`/`status`/`logs`/`serve` subcommands. Add `hero_rpc_server` dependency for `ZinitLifecycle`. Remove `zinit_integration.rs`. --- ## 2. Add `ZinitLifecycle` to hero_books_ui **File:** `crates/hero_books_ui/src/main.rs` Currently standalone binary with no lifecycle management. Add same `ZinitLifecycle` subcommand pattern. --- ## 3. Add `ZinitLifecycle` to hero_books_viewer **File:** `crates/hero_books_viewer/src/main.rs` Same — add `ZinitLifecycle` subcommands. --- ## 4. Replace custom OperationLogger with zinit logs **Files:** - `crates/hero_books_server/src/admin/logger.rs` — Custom circular-buffer `OperationLogger` (390 lines) - `crates/hero_books_server/src/logging.rs` — `hb_log!` macro (dual-channel: console + in-memory) Replace with zinit `logs.insert()` using structured source names. The `hb_log!` macro should forward to zinit instead of the in-memory buffer. ### Log source naming convention | Operation | Zinit Log Source | |-----------|------------------| | Server startup | `hero_books.startup` | | Namespace discovery | `hero_books.discover.{namespace}` | | Library rescan | `hero_books.rescan.{namespace}` | | Re-embed | `hero_books.reembed.{namespace}` | | Collection scan | `hero_books.scan.{collection}` | | Q&A extraction | `hero_books.qa.{collection}` | | Book export | `hero_books.export.{book}` | | PDF generation | `hero_books.pdf.{book}` | | Search indexing | `hero_books.index.{namespace}` | | Git push AI | `hero_books.push_ai.{repo}` | --- ## 5. Health checks in zinit service registration **File:** `crates/hero_books_server/src/zinit_integration.rs` (currently no health check) Configure HTTP health checks for all three services: - Server: `/health` on Unix socket - UI: `/health` on Unix socket - Viewer: `/health` on Unix socket --- ## 6. Remove shell scripts, use binary subcommands **Files to remove:** - `scripts/run-services.sh` - `scripts/stop.sh` - `scripts/status.sh` Replace with Makefile targets that call binary subcommands: ```makefile run: build cargo run -p hero_books_server -- run start: build cargo run -p hero_books_server -- start cargo run -p hero_books_ui -- start cargo run -p hero_books_viewer -- start stop: @cargo run -p hero_books_server -- stop 2>/dev/null || true @cargo run -p hero_books_ui -- stop 2>/dev/null || true @cargo run -p hero_books_viewer -- stop 2>/dev/null || true ``` --- ## 7. Update zinit_sdk dependency **File:** `crates/hero_books_server/Cargo.toml` Update to `development_kristof` branch. Add `hero_rpc_server` dependency for `ZinitLifecycle`. --- ## Summary | Area | Current | Target | |------|---------|--------| | Server lifecycle | Custom `zinit_integration.rs` + `--start` flag | `ZinitLifecycle` subcommands | | UI lifecycle | Standalone binary | `ZinitLifecycle` subcommands | | Viewer lifecycle | Standalone binary | `ZinitLifecycle` subcommands | | Logging | Custom `OperationLogger` (1000-entry buffer) + `hb_log!` macro | Zinit `logs.insert()` with source naming | | Health checks | Not configured in zinit | HTTP health check on `/health` | | Shell scripts | `run-services.sh`, `stop.sh`, `status.sh` | Binary subcommands via Makefile | | In-process ops | Background threads / async tasks | **Stay in-process**, log through zinit | ## Acceptance Criteria - [ ] All 3 binaries have `run`/`start`/`stop`/`status`/`logs`/`serve` subcommands via `ZinitLifecycle` - [ ] `zinit_integration.rs` removed (replaced by `ZinitLifecycle`) - [ ] `hb_log!` macro forwards to zinit with structured source names - [ ] Custom `OperationLogger` removed or reduced to thin wrapper around zinit logs - [ ] Health checks configured in service registration for all 3 services - [ ] Shell scripts removed, Makefile uses binary subcommands - [ ] `zinit_sdk` dependency updated to `development_kristof`

timur referenced this issue from lhumina_code/hero_os

2026-03-10 08:59:41 +00:00

use zinit jobs & logs for all long running jobs #24

timur commented

2026-03-10 09:17:31 +00:00

Author

Owner

Additional: Adopt `ZinitLifecycle` pattern from hero_rpc

lhumina_code/hero_rpc#7 — Hero RPC servers should use zinit for lifecycle
lhumina_code/hero_skills#51 — Skill for OServer::run_cli() / ZinitLifecycle pattern
lhumina_code/home#6 — Core services (AI Broker, Embedder, Indexer, Redis) all must start via zinit with OpenRPC

What this means for hero_books

Hero Books is not a standard OpenRPC-generated server (it predates the OServer::run_cli() pattern), but it should adopt the same CLI subcommand model using ZinitLifecycle directly — the "Non-OpenRPC Binaries" pattern from hero_rpc.

Current state

hero_books_server currently uses a --start flag to optionally register with zinit via custom code in zinit_integration.rs. This is the old pattern.

Target state

All three hero_books binaries should use ZinitLifecycle with standard subcommands:

hero_books_server <COMMAND>
  run      Start via zinit + stream logs + stop on Ctrl-C (developer command)
  start    Register with zinit and start in background
  stop     Stop the zinit-managed service
  serve    Run the server process (internal — zinit calls this)
  status   Query zinit for service status
  logs     Fetch service logs from zinit

Same for hero_books_ui and hero_books_viewer.

Implementation approach

Add hero_rpc_server dependency to all three binary crates (for ZinitLifecycle)
Replace clap arg parsing in each main.rs with the standard subcommand enum
Wire run/start/stop/status/logs to ZinitLifecycle methods
Move current server startup code into serve subcommand handler
Remove zinit_integration.rs (replaced by ZinitLifecycle)
Remove scripts/run-services.sh and scripts/stop.sh (each binary manages itself)

Update Makefile targets:

run: build    ## Start + stream logs (Ctrl-C stops)
	cargo run -p hero_books_server -- run

start: build  ## Start all services via zinit (background)
	cargo run -p hero_books_server -- start
	cargo run -p hero_books_ui -- start
	cargo run -p hero_books_viewer -- start

stop:         ## Stop all services
	@cargo run -p hero_books_server -- stop 2>/dev/null || true
	@cargo run -p hero_books_ui -- stop 2>/dev/null || true
	@cargo run -p hero_books_viewer -- stop 2>/dev/null || true

Why this matters

This aligns hero_books with the ecosystem-wide standard (hero_rpc #7). Every Hero service binary — whether OpenRPC-generated or hand-written — should follow the same run/start/stop/status/logs/serve pattern. No more custom zinit_integration.rs per repo, no more shell scripts for service orchestration.

## Additional: Adopt `ZinitLifecycle` pattern from hero_rpc ### Related issues - https://forge.ourworld.tf/lhumina_code/hero_rpc/issues/7 — Hero RPC servers should use zinit for lifecycle - https://forge.ourworld.tf/lhumina_code/hero_skills/issues/51 — Skill for `OServer::run_cli()` / `ZinitLifecycle` pattern - https://forge.ourworld.tf/lhumina_code/home/issues/6 — Core services (AI Broker, Embedder, Indexer, Redis) all must start via zinit with OpenRPC ### What this means for hero_books Hero Books is **not** a standard OpenRPC-generated server (it predates the `OServer::run_cli()` pattern), but it should adopt the same CLI subcommand model using `ZinitLifecycle` directly — the "Non-OpenRPC Binaries" pattern from hero_rpc. ### Current state hero_books_server currently uses a `--start` flag to optionally register with zinit via custom code in `zinit_integration.rs`. This is the old pattern. ### Target state All three hero_books binaries should use `ZinitLifecycle` with standard subcommands: ``` hero_books_server <COMMAND> run Start via zinit + stream logs + stop on Ctrl-C (developer command) start Register with zinit and start in background stop Stop the zinit-managed service serve Run the server process (internal — zinit calls this) status Query zinit for service status logs Fetch service logs from zinit ``` Same for `hero_books_ui` and `hero_books_viewer`. ### Implementation approach 1. Add `hero_rpc_server` dependency to all three binary crates (for `ZinitLifecycle`) 2. Replace `clap` arg parsing in each `main.rs` with the standard subcommand enum 3. Wire `run`/`start`/`stop`/`status`/`logs` to `ZinitLifecycle` methods 4. Move current server startup code into `serve` subcommand handler 5. Remove `zinit_integration.rs` (replaced by `ZinitLifecycle`) 6. Remove `scripts/run-services.sh` and `scripts/stop.sh` (each binary manages itself) 7. Update `Makefile` targets: ```makefile run: build ## Start + stream logs (Ctrl-C stops) cargo run -p hero_books_server -- run start: build ## Start all services via zinit (background) cargo run -p hero_books_server -- start cargo run -p hero_books_ui -- start cargo run -p hero_books_viewer -- start stop: ## Stop all services @cargo run -p hero_books_server -- stop 2>/dev/null || true @cargo run -p hero_books_ui -- stop 2>/dev/null || true @cargo run -p hero_books_viewer -- stop 2>/dev/null || true ``` ### Why this matters This aligns hero_books with the ecosystem-wide standard (hero_rpc #7). Every Hero service binary — whether OpenRPC-generated or hand-written — should follow the same `run`/`start`/`stop`/`status`/`logs`/`serve` pattern. No more custom `zinit_integration.rs` per repo, no more shell scripts for service orchestration.

timur commented

2026-03-10 09:47:17 +00:00

Author

Owner

Implementation Plan: Integrate zinit SDK for all long-running jobs, logging, and process lifecycle

Context

Hero Books has basic zinit integration (zinit_integration.rs) using the old ServiceConfigBuilder API from the development branch. All long-running operations use raw std::thread::spawn() with a custom in-memory OperationLogger. The hero_rpc ecosystem has standardized on a ZinitLifecycle pattern with run/start/stop/serve/status/logs subcommands using the new ServiceBuilder/ActionBuilder/RetryPolicyBuilder APIs from the development_kristof branch.

This plan migrates hero_books to the standard lifecycle pattern, replaces the custom logger with zinit-captured stdout logging, converts background threads to async tasks, and adds health checks.

Phase 1: Update zinit_sdk dependency + Adopt ZinitLifecycle for server

1.1 Update zinit_sdk branch in Cargo.toml

File: crates/hero_books_server/Cargo.toml:72

Change branch = "development" to branch = "development_kristof"
This provides ServiceBuilder, ActionBuilder, RetryPolicyBuilder, LogsGetInput, ServiceStartInput with context field

1.2 Rewrite `zinit_integration.rs` → `lifecycle.rs`

File: crates/hero_books_server/src/zinit_integration.rs → rename to lifecycle.rs

Replace the old start_as_managed_service() with a ZinitLifecycle struct modeled on hero_rpc/crates/server/src/server/lifecycle.rs
Methods: start(), stop(), status(), logs(lines), run()
Use ServiceBuilder::new() + ActionBuilder::new() + RetryPolicyBuilder::new() (new API)
exec_command() returns "{binary} serve [--libraries-dir X] [--embedder-url Y] [flags]"
Health check: .health_http() pointing to the Unix socket health endpoint (or .health_tcp() if Unix socket URLs not supported)

1.3 Restructure server CLI with subcommands

File: crates/hero_books_server/src/main.rs

Replace flat Cli struct with subcommand enum:
- Run — start via zinit, stream logs, stop on Ctrl-C (dev mode)
- Start — register with zinit and start in background
- Stop — stop the zinit-managed service
- Serve { all current args } — actually run the server (called by zinit)
- Status — query zinit service status
- Logs { -n lines } — fetch zinit logs
Serve variant holds all existing CLI args (--libraries-dir, --embedder-url, etc.)
Run/Start/Stop/Status/Logs dispatch through the new ZinitLifecycle
Serve runs the current server logic (moved from the else branch)
Backward compat: If no subcommand given, default to Serve behavior (or print help)

1.4 Update lib.rs module declarations

File: crates/hero_books_server/src/lib.rs

Rename pub mod zinit_integration; → pub mod lifecycle;

Phase 2: Adopt ZinitLifecycle for UI and Viewer

2.1 hero_books_ui

Files: crates/hero_books_ui/Cargo.toml, crates/hero_books_ui/src/main.rs

Add zinit_sdk = { ..., branch = "development_kristof" } dependency
Restructure CLI with same subcommand pattern (Run/Start/Stop/Serve/Status/Logs)
Serve variant gets --socket arg (current behavior)
Inline a small ZinitLifecycle instance for "hero_books_ui" service
Register with zinit using .requires("hero_books_server") dependency
Add /api/health JSON endpoint returning {"status":"ok","service":"hero_books_ui","version":"..."}

2.2 hero_books_viewer

Files: crates/hero_books_viewer/Cargo.toml, crates/hero_books_viewer/src/main.rs

Same pattern as UI: add zinit_sdk dep, restructure CLI with subcommands
Already has /health handler — reuse it
Register with zinit using .requires("hero_books_server") dependency

Phase 3: Replace OperationLogger with structured stdout logging

3.1 Remove OperationLogger from AdminRpcState

File: crates/hero_books_server/src/admin/rpc.rs

Replace logger: Arc<OperationLogger> with zinit_socket: String in AdminRpcState
handle_library_rescan(): replace logger.log_operation_start/complete/error with log::info!("[rescan:{ns}] ...")
handle_library_reembed(): same — use log::info!("[reembed:{ns}] ...")
handle_search(): replace logger calls with log::info!("[search] ...")
handle_export(): replace logger calls with log::info!("[export] ...")
handle_logs_get(): rewrite to query zinit via ZinitRPCAPIClient::logs_get(), parse log lines into compatible JSON format
handle_logs_clear(): become a no-op or return success (zinit logs are append-only)
handle_stats(): remove log_count or derive from zinit

3.2 Update admin server

File: crates/hero_books_server/src/admin/server.rs

build_admin_router(): replace logger: Arc<OperationLogger> param with zinit_socket: String
Pass zinit_socket through AdminRpcState

3.3 Remove global logger plumbing

File: crates/hero_books_server/src/web/server.rs

Remove set_operation_logger(), get_logger(), and the operation_logger() OnceLock
Replace any get_logger() calls with log::info!() / log::warn!()

3.4 Remove unused parameters

File: crates/hero_books_server/src/web/axum_server.rs

Remove _logger and _start_time parameters from start_rpc_only_server() signature (already unused)

3.5 Clean up main.rs

File: crates/hero_books_server/src/main.rs

Remove OperationLogger::new() and set_operation_logger() calls

3.6 Delete or simplify logging macro

File: crates/hero_books_server/src/logging.rs

Delete hb_log! macro (it is not used in actual code, only in specs)
Update lib.rs to remove #[macro_use] pub mod logging;

3.7 Delete OperationLogger

File: crates/hero_books_server/src/admin/logger.rs

Keep LogLevel, OperationType, OperationStatus, LogEntry types (needed for admin API response format)
Remove OperationLogger struct and all its methods
Rename file to types.rs (or keep as logger.rs with just types)

3.8 Update admin mod.rs exports

File: crates/hero_books_server/src/admin/mod.rs

Remove OperationLogger from pub use line
Keep type exports: LogEntry, LogLevel, OperationStatus, OperationType

Phase 4: Convert background threads to async tasks

4.1 Convert startup pipeline thread

File: crates/hero_books_server/src/web/axum_server.rs:102

Replace std::thread::spawn(move || { ... }) with tokio::spawn(async move { ... })
Wrap the blocking operations in tokio::task::spawn_blocking() where needed
Add CancellationToken support for graceful shutdown
All logs already go through log::info!() (already the case in this code)

4.2 Convert admin rescan thread

File: crates/hero_books_server/src/admin/rpc.rs:584

Replace std::thread::spawn(move || { ... }) with tokio::spawn(async move { tokio::task::spawn_blocking(move || { ... }).await })
Use structured log format: log::info!("[rescan:{}] ...", ns)

4.3 Convert admin reembed thread

File: crates/hero_books_server/src/admin/rpc.rs:643

Same pattern as rescan: tokio::spawn + spawn_blocking
Use structured log format: log::info!("[reembed:{}] ...", ns)

4.4 Convert import job thread

File: crates/hero_books_server/src/web/server.rs (import job at ~line 4516)

Replace std::thread::spawn with tokio::spawn
Simplify import job tracking — remove ImportJob struct's log field
Keep status tracking via existing mechanism but use zinit logs for log retrieval

Phase 5: Health checks and shell script updates

5.1 Add health check to zinit service registration

File: crates/hero_books_server/src/lifecycle.rs (new in Phase 1)

When registering hero_books_server, add health check configuration
Try .health_http("http+unix:///path/to/hero_books_server.sock/health") first
Fallback to .health_tcp() for socket connectivity check

5.2 Simplify shell scripts

Files: scripts/run-services.sh, scripts/stop.sh, scripts/status.sh

Keep scripts but simplify service management portions to use new subcommands
run-services.sh: Replace $ZINIT add-service calls with hero_books_server start, hero_books_ui start, hero_books_viewer start
stop.sh: Replace $ZINIT stop/remove calls with hero_books_server stop, etc.
status.sh: Replace manual socket checks with hero_books_server status, etc.
Keep auxiliary operations (seed-git, embedder setup, env sourcing) in scripts

Files Summary

Action	File	Phase
Modify	`crates/hero_books_server/Cargo.toml`	1
Rewrite	`crates/hero_books_server/src/zinit_integration.rs` → `lifecycle.rs`	1
Rewrite	`crates/hero_books_server/src/main.rs`	1
Modify	`crates/hero_books_server/src/lib.rs`	1
Modify	`crates/hero_books_ui/Cargo.toml`	2
Modify	`crates/hero_books_ui/src/main.rs`	2
Modify	`crates/hero_books_viewer/Cargo.toml`	2
Modify	`crates/hero_books_viewer/src/main.rs`	2
Modify	`crates/hero_books_server/src/admin/rpc.rs`	3, 4
Modify	`crates/hero_books_server/src/admin/server.rs`	3
Modify	`crates/hero_books_server/src/admin/mod.rs`	3
Modify	`crates/hero_books_server/src/web/server.rs`	3, 4
Modify	`crates/hero_books_server/src/web/axum_server.rs`	3, 4
Delete	`crates/hero_books_server/src/logging.rs`	3
Reduce	`crates/hero_books_server/src/admin/logger.rs` (keep types only)	3
Simplify	`scripts/run-services.sh`	5
Simplify	`scripts/stop.sh`	5
Simplify	`scripts/status.sh`	5

Key Reference Files

hero_rpc/crates/server/src/server/lifecycle.rs — ZinitLifecycle pattern to replicate
hero_rpc/crates/server/src/server/server.rs — OServer::run_cli() subcommand dispatch pattern

Verification

cargo build -p hero_books_server -p hero_books_ui -p hero_books_viewer — all 3 crates compile
hero_books_server --help — shows subcommands (run/start/stop/serve/status/logs)
hero_books_server serve --libraries-dir ~/hero/var/books/ — server starts and serves RPC
hero_books_server start — registers with zinit and starts
hero_books_server status — shows zinit service status
hero_books_server logs -n 50 — shows recent logs from zinit
hero_books_server stop — stops the service
Same for hero_books_ui and hero_books_viewer
No std::thread::spawn remaining for long-running operations
grep -r "OperationLogger" crates/ — only type references remain (no buffer/storage)

# Implementation Plan: Integrate zinit SDK for all long-running jobs, logging, and process lifecycle ## Context Hero Books has basic zinit integration (`zinit_integration.rs`) using the **old** `ServiceConfigBuilder` API from the `development` branch. All long-running operations use raw `std::thread::spawn()` with a custom in-memory `OperationLogger`. The hero_rpc ecosystem has standardized on a `ZinitLifecycle` pattern with `run/start/stop/serve/status/logs` subcommands using the **new** `ServiceBuilder`/`ActionBuilder`/`RetryPolicyBuilder` APIs from the `development_kristof` branch. This plan migrates hero_books to the standard lifecycle pattern, replaces the custom logger with zinit-captured stdout logging, converts background threads to async tasks, and adds health checks. --- ## Phase 1: Update zinit_sdk dependency + Adopt ZinitLifecycle for server ### 1.1 Update zinit_sdk branch in Cargo.toml **File:** `crates/hero_books_server/Cargo.toml:72` - Change `branch = "development"` to `branch = "development_kristof"` - This provides `ServiceBuilder`, `ActionBuilder`, `RetryPolicyBuilder`, `LogsGetInput`, `ServiceStartInput` with `context` field ### 1.2 Rewrite `zinit_integration.rs` → `lifecycle.rs` **File:** `crates/hero_books_server/src/zinit_integration.rs` → rename to `lifecycle.rs` - Replace the old `start_as_managed_service()` with a `ZinitLifecycle` struct modeled on `hero_rpc/crates/server/src/server/lifecycle.rs` - Methods: `start()`, `stop()`, `status()`, `logs(lines)`, `run()` - Use `ServiceBuilder::new()` + `ActionBuilder::new()` + `RetryPolicyBuilder::new()` (new API) - `exec_command()` returns `"{binary} serve [--libraries-dir X] [--embedder-url Y] [flags]"` - Health check: `.health_http()` pointing to the Unix socket health endpoint (or `.health_tcp()` if Unix socket URLs not supported) ### 1.3 Restructure server CLI with subcommands **File:** `crates/hero_books_server/src/main.rs` - Replace flat `Cli` struct with subcommand enum: - `Run` — start via zinit, stream logs, stop on Ctrl-C (dev mode) - `Start` — register with zinit and start in background - `Stop` — stop the zinit-managed service - `Serve { all current args }` — actually run the server (called by zinit) - `Status` — query zinit service status - `Logs { -n lines }` — fetch zinit logs - `Serve` variant holds all existing CLI args (`--libraries-dir`, `--embedder-url`, etc.) - `Run`/`Start`/`Stop`/`Status`/`Logs` dispatch through the new `ZinitLifecycle` - `Serve` runs the current server logic (moved from the else branch) - **Backward compat:** If no subcommand given, default to `Serve` behavior (or print help) ### 1.4 Update lib.rs module declarations **File:** `crates/hero_books_server/src/lib.rs` - Rename `pub mod zinit_integration;` → `pub mod lifecycle;` --- ## Phase 2: Adopt ZinitLifecycle for UI and Viewer ### 2.1 hero_books_ui **Files:** `crates/hero_books_ui/Cargo.toml`, `crates/hero_books_ui/src/main.rs` - Add `zinit_sdk = { ..., branch = "development_kristof" }` dependency - Restructure CLI with same subcommand pattern (Run/Start/Stop/Serve/Status/Logs) - `Serve` variant gets `--socket` arg (current behavior) - Inline a small `ZinitLifecycle` instance for `"hero_books_ui"` service - Register with zinit using `.requires("hero_books_server")` dependency - Add `/api/health` JSON endpoint returning `{"status":"ok","service":"hero_books_ui","version":"..."}` ### 2.2 hero_books_viewer **Files:** `crates/hero_books_viewer/Cargo.toml`, `crates/hero_books_viewer/src/main.rs` - Same pattern as UI: add zinit_sdk dep, restructure CLI with subcommands - Already has `/health` handler — reuse it - Register with zinit using `.requires("hero_books_server")` dependency --- ## Phase 3: Replace OperationLogger with structured stdout logging ### 3.1 Remove OperationLogger from AdminRpcState **File:** `crates/hero_books_server/src/admin/rpc.rs` - Replace `logger: Arc<OperationLogger>` with `zinit_socket: String` in `AdminRpcState` - `handle_library_rescan()`: replace `logger.log_operation_start/complete/error` with `log::info!("[rescan:{ns}] ...")` - `handle_library_reembed()`: same — use `log::info!("[reembed:{ns}] ...")` - `handle_search()`: replace logger calls with `log::info!("[search] ...")` - `handle_export()`: replace logger calls with `log::info!("[export] ...")` - `handle_logs_get()`: rewrite to query zinit via `ZinitRPCAPIClient::logs_get()`, parse log lines into compatible JSON format - `handle_logs_clear()`: become a no-op or return success (zinit logs are append-only) - `handle_stats()`: remove `log_count` or derive from zinit ### 3.2 Update admin server **File:** `crates/hero_books_server/src/admin/server.rs` - `build_admin_router()`: replace `logger: Arc<OperationLogger>` param with `zinit_socket: String` - Pass `zinit_socket` through `AdminRpcState` ### 3.3 Remove global logger plumbing **File:** `crates/hero_books_server/src/web/server.rs` - Remove `set_operation_logger()`, `get_logger()`, and the `operation_logger()` OnceLock - Replace any `get_logger()` calls with `log::info!()` / `log::warn!()` ### 3.4 Remove unused parameters **File:** `crates/hero_books_server/src/web/axum_server.rs` - Remove `_logger` and `_start_time` parameters from `start_rpc_only_server()` signature (already unused) ### 3.5 Clean up main.rs **File:** `crates/hero_books_server/src/main.rs` - Remove `OperationLogger::new()` and `set_operation_logger()` calls ### 3.6 Delete or simplify logging macro **File:** `crates/hero_books_server/src/logging.rs` - Delete `hb_log!` macro (it is not used in actual code, only in specs) - Update `lib.rs` to remove `#[macro_use] pub mod logging;` ### 3.7 Delete OperationLogger **File:** `crates/hero_books_server/src/admin/logger.rs` - Keep `LogLevel`, `OperationType`, `OperationStatus`, `LogEntry` types (needed for admin API response format) - Remove `OperationLogger` struct and all its methods - Rename file to `types.rs` (or keep as `logger.rs` with just types) ### 3.8 Update admin mod.rs exports **File:** `crates/hero_books_server/src/admin/mod.rs` - Remove `OperationLogger` from `pub use` line - Keep type exports: `LogEntry, LogLevel, OperationStatus, OperationType` --- ## Phase 4: Convert background threads to async tasks ### 4.1 Convert startup pipeline thread **File:** `crates/hero_books_server/src/web/axum_server.rs:102` - Replace `std::thread::spawn(move || { ... })` with `tokio::spawn(async move { ... })` - Wrap the blocking operations in `tokio::task::spawn_blocking()` where needed - Add `CancellationToken` support for graceful shutdown - All logs already go through `log::info!()` (already the case in this code) ### 4.2 Convert admin rescan thread **File:** `crates/hero_books_server/src/admin/rpc.rs:584` - Replace `std::thread::spawn(move || { ... })` with `tokio::spawn(async move { tokio::task::spawn_blocking(move || { ... }).await })` - Use structured log format: `log::info!("[rescan:{}] ...", ns)` ### 4.3 Convert admin reembed thread **File:** `crates/hero_books_server/src/admin/rpc.rs:643` - Same pattern as rescan: `tokio::spawn` + `spawn_blocking` - Use structured log format: `log::info!("[reembed:{}] ...", ns)` ### 4.4 Convert import job thread **File:** `crates/hero_books_server/src/web/server.rs` (import job at ~line 4516) - Replace `std::thread::spawn` with `tokio::spawn` - Simplify import job tracking — remove `ImportJob` struct's `log` field - Keep status tracking via existing mechanism but use zinit logs for log retrieval --- ## Phase 5: Health checks and shell script updates ### 5.1 Add health check to zinit service registration **File:** `crates/hero_books_server/src/lifecycle.rs` (new in Phase 1) - When registering hero_books_server, add health check configuration - Try `.health_http("http+unix:///path/to/hero_books_server.sock/health")` first - Fallback to `.health_tcp()` for socket connectivity check ### 5.2 Simplify shell scripts **Files:** `scripts/run-services.sh`, `scripts/stop.sh`, `scripts/status.sh` - Keep scripts but simplify service management portions to use new subcommands - `run-services.sh`: Replace `$ZINIT add-service` calls with `hero_books_server start`, `hero_books_ui start`, `hero_books_viewer start` - `stop.sh`: Replace `$ZINIT stop/remove` calls with `hero_books_server stop`, etc. - `status.sh`: Replace manual socket checks with `hero_books_server status`, etc. - Keep auxiliary operations (seed-git, embedder setup, env sourcing) in scripts --- ## Files Summary | Action | File | Phase | |--------|------|-------| | Modify | `crates/hero_books_server/Cargo.toml` | 1 | | Rewrite | `crates/hero_books_server/src/zinit_integration.rs` → `lifecycle.rs` | 1 | | Rewrite | `crates/hero_books_server/src/main.rs` | 1 | | Modify | `crates/hero_books_server/src/lib.rs` | 1 | | Modify | `crates/hero_books_ui/Cargo.toml` | 2 | | Modify | `crates/hero_books_ui/src/main.rs` | 2 | | Modify | `crates/hero_books_viewer/Cargo.toml` | 2 | | Modify | `crates/hero_books_viewer/src/main.rs` | 2 | | Modify | `crates/hero_books_server/src/admin/rpc.rs` | 3, 4 | | Modify | `crates/hero_books_server/src/admin/server.rs` | 3 | | Modify | `crates/hero_books_server/src/admin/mod.rs` | 3 | | Modify | `crates/hero_books_server/src/web/server.rs` | 3, 4 | | Modify | `crates/hero_books_server/src/web/axum_server.rs` | 3, 4 | | Delete | `crates/hero_books_server/src/logging.rs` | 3 | | Reduce | `crates/hero_books_server/src/admin/logger.rs` (keep types only) | 3 | | Simplify | `scripts/run-services.sh` | 5 | | Simplify | `scripts/stop.sh` | 5 | | Simplify | `scripts/status.sh` | 5 | ## Key Reference Files - `hero_rpc/crates/server/src/server/lifecycle.rs` — ZinitLifecycle pattern to replicate - `hero_rpc/crates/server/src/server/server.rs` — OServer::run_cli() subcommand dispatch pattern ## Verification 1. `cargo build -p hero_books_server -p hero_books_ui -p hero_books_viewer` — all 3 crates compile 2. `hero_books_server --help` — shows subcommands (run/start/stop/serve/status/logs) 3. `hero_books_server serve --libraries-dir ~/hero/var/books/` — server starts and serves RPC 4. `hero_books_server start` — registers with zinit and starts 5. `hero_books_server status` — shows zinit service status 6. `hero_books_server logs -n 50` — shows recent logs from zinit 7. `hero_books_server stop` — stops the service 8. Same for `hero_books_ui` and `hero_books_viewer` 9. No `std::thread::spawn` remaining for long-running operations 10. `grep -r "OperationLogger" crates/` — only type references remain (no buffer/storage)

timur commented

2026-03-10 11:25:10 +00:00

Author

Owner

Correction: scope of zinit jobs vs in-process operations

After further discussion, the recommendation to convert in-process operations to zinit jobs was incorrect for most items listed above. Zinit jobs are subprocess-based — they spawn external commands. Most hero_books operations work with in-memory state and cannot be externalized to subprocesses.

What should NOT become zinit jobs (stays in-process)

PDF generation (items 7) — Builds complete HTML in memory with base64-inlined images (can be 100s of MB), maintains a live Chrome CDP session, and returns the result synchronously via RPC. Cannot be serialized to a subprocess boundary.
AI Q&A extraction (item 6) — Batch LLM API calls operating on loaded collections with in-memory context.
Search indexing / embedding upload (item 8) — Uses in-process embedder SDK with loaded state.
Background initialization pipeline (item 1) — Each step depends on the server's in-memory config and caches (namespace maps, books cache, indexed state).
Library rescan/reembed (items 2, 3) — Operates on server's in-memory config and updates shared state (books cache, indexed namespaces set).
Collection scanning (item 5) — While git clone/pull is subprocess-friendly, the scan itself updates in-memory DocTree state.

What SHOULD use zinit

Area	Zinit Feature	Still Valid
Service lifecycle	`ZinitLifecycle` pattern for server, UI, viewer	✅ Yes (items 9, 10, plus ZinitLifecycle comment)
Logging	`logs.insert()` with structured source names	✅ Yes (item 4)
Health checks	Health check in service registration config	✅ Yes (item 9)
Git clone/pull	Could be a zinit job (it's a subprocess operation)	✅ Partial — only the git subprocess part, not the in-memory scan
Custom OperationLogger removal	Replace with zinit logs	✅ Yes (item 4)
Log source naming convention	Structured `hero_books.{op}.{target}`	✅ Yes (item 11)
zinit_sdk dependency update	Switch to `development_kristof`	✅ Yes (item 12)

Revised summary

The core improvements are:

ZinitLifecycle for all 3 binaries (server, UI, viewer) — replacing custom zinit_integration.rs and shell scripts
Logging through zinit — replace custom OperationLogger and hb_log! macro with zinit logs.insert() using structured source names
Health checks in zinit service registration
Dependency update to development_kristof branch

In-process long-running operations stay as they are (async tasks / background threads) but should log through zinit for centralized visibility.

## Correction: scope of zinit jobs vs in-process operations After further discussion, the recommendation to convert **in-process operations to zinit jobs** was incorrect for most items listed above. Zinit jobs are subprocess-based — they spawn external commands. Most hero_books operations work with **in-memory state** and cannot be externalized to subprocesses. ### What should NOT become zinit jobs (stays in-process) - **PDF generation** (items 7) — Builds complete HTML in memory with base64-inlined images (can be 100s of MB), maintains a live Chrome CDP session, and returns the result synchronously via RPC. Cannot be serialized to a subprocess boundary. - **AI Q&A extraction** (item 6) — Batch LLM API calls operating on loaded collections with in-memory context. - **Search indexing / embedding upload** (item 8) — Uses in-process embedder SDK with loaded state. - **Background initialization pipeline** (item 1) — Each step depends on the server's in-memory config and caches (namespace maps, books cache, indexed state). - **Library rescan/reembed** (items 2, 3) — Operates on server's in-memory config and updates shared state (books cache, indexed namespaces set). - **Collection scanning** (item 5) — While git clone/pull is subprocess-friendly, the scan itself updates in-memory DocTree state. ### What SHOULD use zinit | Area | Zinit Feature | Still Valid | |------|--------------|-------------| | **Service lifecycle** | `ZinitLifecycle` pattern for server, UI, viewer | ✅ Yes (items 9, 10, plus ZinitLifecycle comment) | | **Logging** | `logs.insert()` with structured source names | ✅ Yes (item 4) | | **Health checks** | Health check in service registration config | ✅ Yes (item 9) | | **Git clone/pull** | Could be a zinit job (it's a subprocess operation) | ✅ Partial — only the git subprocess part, not the in-memory scan | | **Custom OperationLogger removal** | Replace with zinit logs | ✅ Yes (item 4) | | **Log source naming convention** | Structured `hero_books.{op}.{target}` | ✅ Yes (item 11) | | **zinit_sdk dependency update** | Switch to `development_kristof` | ✅ Yes (item 12) | ### Revised summary The core improvements are: 1. **`ZinitLifecycle`** for all 3 binaries (server, UI, viewer) — replacing custom `zinit_integration.rs` and shell scripts 2. **Logging through zinit** — replace custom `OperationLogger` and `hb_log!` macro with zinit `logs.insert()` using structured source names 3. **Health checks** in zinit service registration 4. **Dependency update** to `development_kristof` branch In-process long-running operations stay as they are (async tasks / background threads) but should **log through zinit** for centralized visibility.

timur changed title from ~~Integrate zinit SDK for all long-running jobs, logging, and process lifecycle~~ to Integrate zinit SDK: ZinitLifecycle for all binaries, logging via zinit, health checks

2026-03-10 11:26:28 +00:00

timur referenced this issue from lhumina_code/hero_os

2026-03-10 11:28:05 +00:00

use zinit jobs & logs for all long running jobs #24

timur commented

2026-03-10 11:38:06 +00:00

Author

Owner

Implementation audit — code is correct

Audited all uncommitted changes. The implementation is well-structured:

3 lifecycle modules created (hero_books_server, hero_books_ui, hero_books_viewer) using ServiceConfigBuilder — ✅ correct, uses service/action APIs only
zinit_integration.rs deleted — replaced by lifecycle.rs — ✅ correct
logging.rs (hb_log! macro) deleted — ✅ per plan
No zinit jobs API misuse — all in-process operations stay in-process
Workspace compiles clean (cargo check --workspace passes)

Remaining: code is uncommitted (staged + untracked files). Needs to be committed and pushed.

## Implementation audit — code is correct Audited all uncommitted changes. The implementation is well-structured: - **3 lifecycle modules** created (`hero_books_server`, `hero_books_ui`, `hero_books_viewer`) using `ServiceConfigBuilder` — ✅ correct, uses service/action APIs only - **`zinit_integration.rs` deleted** — replaced by `lifecycle.rs` — ✅ correct - **`logging.rs` (hb_log! macro) deleted** — ✅ per plan - **No zinit jobs API misuse** — all in-process operations stay in-process - **Workspace compiles clean** (`cargo check --workspace` passes) Remaining: code is uncommitted (staged + untracked files). Needs to be committed and pushed.

timur referenced this issue from a commit

2026-03-10 11:42:59 +00:00

feat: add ZinitLifecycle to all binaries, replace custom logging with zinit

timur closed this issue

2026-03-10 11:42:59 +00:00

No labels

No milestone

No project

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_books#77

No description provided.

Rows
Columns

Integrate zinit SDK: ZinitLifecycle for all binaries, logging via zinit, health checks #77

Context

1. Adopt ZinitLifecycle for hero_books_server

2. Add ZinitLifecycle to hero_books_ui

3. Add ZinitLifecycle to hero_books_viewer

4. Replace custom OperationLogger with zinit logs

Log source naming convention

5. Health checks in zinit service registration

6. Remove shell scripts, use binary subcommands

7. Update zinit_sdk dependency

Summary

Acceptance Criteria

Additional: Adopt ZinitLifecycle pattern from hero_rpc

Related issues

What this means for hero_books

Current state

Target state

Implementation approach

Why this matters

Implementation Plan: Integrate zinit SDK for all long-running jobs, logging, and process lifecycle

Context

Phase 1: Update zinit_sdk dependency + Adopt ZinitLifecycle for server

1.1 Update zinit_sdk branch in Cargo.toml

1.2 Rewrite zinit_integration.rs → lifecycle.rs

1.3 Restructure server CLI with subcommands

1.4 Update lib.rs module declarations

Phase 2: Adopt ZinitLifecycle for UI and Viewer

2.1 hero_books_ui

2.2 hero_books_viewer

Phase 3: Replace OperationLogger with structured stdout logging

3.1 Remove OperationLogger from AdminRpcState

3.2 Update admin server

3.3 Remove global logger plumbing

3.4 Remove unused parameters

3.5 Clean up main.rs

3.6 Delete or simplify logging macro

3.7 Delete OperationLogger

3.8 Update admin mod.rs exports

Phase 4: Convert background threads to async tasks

4.1 Convert startup pipeline thread

4.2 Convert admin rescan thread

4.3 Convert admin reembed thread

4.4 Convert import job thread

Phase 5: Health checks and shell script updates

5.1 Add health check to zinit service registration

5.2 Simplify shell scripts

Files Summary

Key Reference Files

Verification

Correction: scope of zinit jobs vs in-process operations

What should NOT become zinit jobs (stays in-process)

What SHOULD use zinit

Revised summary

Implementation audit — code is correct

1. Adopt `ZinitLifecycle` for hero_books_server

2. Add `ZinitLifecycle` to hero_books_ui

3. Add `ZinitLifecycle` to hero_books_viewer

Additional: Adopt `ZinitLifecycle` pattern from hero_rpc

1.2 Rewrite `zinit_integration.rs` → `lifecycle.rs`