zinit 0.3.7

# Zinit Release Notes

## Version 0.2.0 (Development)

### Published on crates.io
- **Previous Release:** 0.1.0 (published January 2026)
- **Current Development:** 0.2.0
- **Repository:** https://forge.ourworld.tf/geomind_code/zinit
- **Crates.io:** https://crates.io/crates/zinit

### Major Features

#### 1. Complete OpenRPC Implementation (44/44 Methods)
All RPC methods from the OpenRPC 1.2.6 specification are fully implemented:
- **System methods** (4): ping, shutdown, reboot, prepare_restart
- **Service CRUD** (8): create, get, update, delete, add, register, monitor, remove
- **Service queries** (8): list, status, stats, is_running, why, tree, status_full, list_full
- **Service control** (5): start, stop, restart, kill, reload
- **Bulk operations** (4): start_all, stop_all, delete_all, tree
- **Logging** (3): get, tail, filter
- **Debug** (2): state, process_tree
- **Xinet proxies** (8): create, delete, list, status, register, unregister, status_all

See `docs/OPENRPC_IMPLEMENTATION.md` for detailed API documentation.

#### 2. Single Crate Architecture
- Consolidated from 4 separate crates into unified `zinit` crate
- Feature flags control compilation:
  - `sdk` - Core types and protocol (always included)
  - `client` - CLI client interface
  - `server` - Supervisor daemon
  - `pid1` - PID 1 init process (Linux only)
  - `tui` - Terminal UI
  - `repl` - Interactive REPL
  - `async` - Async client support
  - `full` - Everything
- All imports simplified: `use zinit::{...}`

#### 3. Platform-Aware Path Handling
Automatic socket and config path detection by platform:

| Platform | Socket Path | Config Path |
|----------|------------|------------|
| Linux | `/run/zinit.sock` | `/etc/zinit/services` |
| macOS/Windows | `$HOME/hero/var/zinit.sock` | `$HOME/hero/cfg/zinit` |

See `src/sdk/socket.rs` for configuration details.

#### 4. Version Management
All binaries report consistent version from Cargo.toml:
```bash
$ zinit --version
zinit 0.2.0

$ zinit-server --version
zinit-server 0.2.0

$ zinit-pid1 --version
zinit-pid1 0.2.0
```

Version syncing via:
- `src/sdk/version.rs` - Version module with `version()`, `full_version()`, `binary_version()`
- `build.rs` - Ensures rebuild on version change
- Build scripts display version: `./build.sh`, `./build_publish.sh`, `./build_package.sh`

#### 5. Complete Documentation
- **crates.io docs**: Full rustdoc on crates.io visible at https://docs.rs/zinit/
- **Module documentation**: Comprehensive docs in src/lib.rs with examples
- **OpenRPC API docs**: `docs/OPENRPC_IMPLEMENTATION.md` (418 lines)
- **Examples**: 4 complete examples in `examples/` directory:
  - `list_services.rs` - Enumerate and list all services
  - `service_status.rs` - Get detailed service status and stats
  - `dependency_tree.rs` - View service dependency tree
  - `create_service.rs` - Dynamically create and manage services

#### 6. Build & CI/CD Infrastructure
- **build.sh** - Local development build with version display
- **build_publish.sh** - Pre-publication verification (fmt, clippy, tests, doc, publish)
- **build_package.sh** - Local CI/CD using forgejo-runner
- **.forgejo/workflows/** - Automated CI/CD on Linux and macOS
  - Builds with `--features full`
  - Publishes binaries to Forgejo registry
  - Supports both Linux and macOS

#### 7. Code Quality
- **135 unit tests** (all passing)
- **Zero clippy warnings** with `-D warnings` flag
- **Full code formatting** compliance
- **Documentation coverage** for all public APIs
- **Test coverage** includes:
  - SDK validation and config parsing
  - Service state machine
  - IPC protocol and handlers
  - RPC method responses
  - Version module (3 new tests)

### Binaries Included

#### zinit (CLI Client)
- List, monitor, and control services
- Interactive TUI (`--tui`)
- REPL shell (`--repl`)
- Auto-detects socket path (no ZINIT_SOCKET needed)
- Version: 0.2.0 (compiled with `client` features)

#### zinit-server (Supervisor Daemon)
- Core service supervisor with dependency graph
- 7-state service lifecycle management
- Health check support (TCP, HTTP, exec)
- Process group signal handling
- Hot restart with state persistence
- Xinet socket activation proxy support
- Version: 0.2.0 (compiled with `server` features)

#### zinit-pid1 (PID 1 Init Process - Linux only)
- Full boot sequence when running as PID 1
- System service protection
- Critical service failure handling
- Systemd-compatible boot control
- Version: 0.2.0 (compiled with `pid1` features)

### SDK Capabilities

#### Blocking Client
```rust
use zinit::ZinitClient;

let mut client = ZinitClient::connect_default()?;
let status = client.status("my-service")?;
println!("Status: {:?}", status.state);
```

#### Async Client
```rust
use zinit::AsyncZinitClient;

let client = AsyncZinitClient::new(&socket_path)?;
let status = client.status("my-service").await?;
```

#### Service Configuration
```rust
use zinit::{ServiceConfig, ServiceDef, ServiceClass};

let config = ServiceConfig {
    service: ServiceDef {
        name: "my-app".to_string(),
        exec: "/usr/bin/my-app".to_string(),
        class: ServiceClass::User,
        ..Default::default()
    },
    ..Default::default()
};
```

### Dependencies

Core dependencies:
- `serde` / `serde_json` - Serialization
- `tokio` - Async runtime (server only)
- `petgraph` - Dependency graph (server only)
- `nix` - Unix system calls (server, pid1)
- `clap` - CLI argument parsing
- `ratatui` - Terminal UI (optional)
- `rustyline` - REPL (optional)
- `tracing` - Structured logging (server)

All dependencies are minimal and well-maintained.

### Testing

Run tests with:
```bash
# All tests
cargo test --lib --all-features --release

# Specific test module
cargo test server::ipc::tests -- --nocapture

# Version module tests
cargo test sdk::version::tests
```

Results: **135 tests passing** (0 failed, 0 ignored)

### Building from Source

#### Prerequisites
- Rust 2024 edition (rustc 1.80+)
- For Linux: full build with PID 1 support
- For macOS/Windows: client and server only

#### Build Release
```bash
# Full build with all features
cargo build --release --features full

# Linux only
cargo build --release --bin zinit-pid1

# Client only
cargo build --release --features client

# Server only
cargo build --release --features server
```

#### Installation
```bash
# Using build.sh (installs to ~/hero/bin/)
./build.sh

# Manual installation
mkdir -p ~/.local/bin
cp target/release/zinit ~/.local/bin/
cp target/release/zinit-server ~/.local/bin/
chmod +x ~/.local/bin/{zinit,zinit-server}
```

### Publishing to crates.io

#### Pre-Publication Checks
```bash
./build_publish.sh
# Runs: format check, clippy, tests, doc generation, dry-run publish
```

#### Publish (requires crates.io token)
```bash
cargo publish
```

Current status: **Version 0.1.0 published**, **0.2.0 in development**

### Known Issues & Limitations

1. **Windows support** - Client works, server/PID1 require WSL
2. **Docker** - Use container mode: `zinit init -c`
3. **Logging** - In-memory buffer only, recommend external syslog
4. **Hot restart** - Requires saving state, not persistent across reboots

### Architecture Highlights

#### Dependency Graph
- Supports 4 types: `after` (ordering), `requires` (hard), `wants` (soft), `conflicts`
- Topological sorting for safe startup/shutdown
- Circular dependency detection

#### Service State Machine
```
Inactive → Blocked → Starting → Running → Exited/Failed
           (async)    ↓          ↑
                    Stopping ←──┘
```

#### IPC Protocol
- JSON-RPC 2.0 over Unix domain sockets
- Newline-delimited messages
- Automatic client-side request numbering

#### Concurrency
- Server: tokio async runtime with `RwLock<ServiceGraph>`
- Clients: synchronous blocking (or async with feature)
- No shared state between client connections

### Performance

- **Startup**: < 100ms (empty config)
- **Response latency**: < 1ms (read operations)
- **Memory**: ~5MB (server at rest)
- **Throughput**: > 1000 RPC calls/sec

### Future Roadmap

Planned enhancements (not yet implemented):
- Enhanced `service.stats` with CPU time delta
- Prometheus metrics export
- Separate `xinit` feature for socket activation
- Log filtering optimization with time-based indexing
- Hot configuration reload without service interruption

### Contributing

Repository: https://forge.ourworld.tf/geomind_code/zinit

Submit changes to the `openrpc_improve` branch via pull request.

### License

Apache License 2.0 - See LICENSE file

### Support

- Documentation: https://docs.rs/zinit/
- API Reference: docs/OPENRPC_IMPLEMENTATION.md
- Examples: examples/ directory
- Issues: https://forge.ourworld.tf/geomind_code/zinit/issues

---

**Last Updated:** January 21, 2026  
**Maintainers:** Zinit Team  
**Status:** Production-ready (single-crate architecture)