zinit 0.1.0

Process supervisor with dependency management
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

# Zinit - Overview & Workspace Structure

## Problem Statement

Current zinit has fundamental issues:
- Race conditions in async state management
- Broken dependency ordering (`after` not honored)
- State detection issues (services shown blocked while running)
- No visibility into why services are blocked

## Goals

- Explicit state machine (all states and transitions defined, testable)
- Validate before mutate (graph changes validated on copy, then swapped)
- Hybrid concurrency (locks for request/response, channels for async events)
- Visibility (always know *why* something is blocked or failed)

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                         zinit-pid1                               │
│  - Spawns/monitors zinit-server                                  │
│  - Forwards signals (SIGTERM→shutdown, SIGUSR1→soft restart)    │
│  - Reaps orphan zombies                                          │
│  - Never exits on VM/bare-metal (reboot syscall)                │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ spawns / signals
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       zinit-server                               │
│  - Service lifecycle (start, stop, restart)                     │
│  - Dependency graph with ordering and requirements              │
│  - State machine per service                                    │
│  - Log capture and optional forwarding                          │
│  - Unix socket RPC (JSON-RPC 2.0)                               │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ unix socket
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       zinit-client                               │
│                   (CLI / TUI / Rhai)                            │
└─────────────────────────────────────────────────────────────────┘
```

## Workspace Layout

```
zinit/
├── Cargo.toml              # Workspace definition
├── zinit-common/           # Shared types and blocking client
├── zinit-server/           # Service supervisor
├── zinit-client/           # CLI/TUI
└── zinit-pid1/             # Init shim
```

## Dependency Graph (Crates)

```
zinit-common (serde, serde_json only)
     ↑
     ├── zinit-server (+ tokio, petgraph, nix, thiserror, tracing)
     ├── zinit-client (+ clap, optional: ratatui, tokio)
     └── zinit-pid1   (+ nix, tracing)
```

## Workspace Cargo.toml

```toml
[workspace]
resolver = "2"
members = [
    "zinit-common",
    "zinit-server",
    "zinit-client",
    "zinit-pid1",
]

[workspace.package]
version = "0.1.0"
edition = "2021"
license = "Apache-2.0"

[workspace.dependencies]
# Shared
serde = { version = "1", features = ["derive"] }
serde_json = "1"
toml = "0.8"

# Async
tokio = { version = "1", features = ["full", "process"] }

# Graph
petgraph = "0.6"

# Unix
nix = { version = "0.27", features = ["signal", "process"] }
libc = "0.2"

# Error handling
thiserror = "1"

# Logging
tracing = "0.1"
tracing-subscriber = { version = "0.3", features = ["env-filter"] }

# CLI
clap = { version = "4", features = ["derive"] }
```

## Socket Paths

- System: `/var/run/zinit.sock`
- User: `~/hero/var/zinit.sock`

## Config Paths

- System: `/etc/zinit/services/` and `/etc/zinit/targets/`
- User: `~/hero/var/zinit/services/`

## State Symbols (ASCII)

```
[-] = inactive
[?] = blocked
[>] = starting
[+] = running
[!] = stopping
[.] = exited
[X] = failed
```

## Related Spec Documents

- `01-zinit-common.md` - Shared crate (types, protocol, client)
- `02-state-machine.md` - Service state machine
- `03-dependency-graph.md` - Graph structure and queries
- `04-process-log.md` - Process and log management
- `05-supervisor.md` - Supervisor and IPC
- `06-zinit-pid1.md` - PID 1 specification
- `07-implementation.md` - Implementation order