Skip to content
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 68 additions & 36 deletions content/docs/protocol/kernel/lifecycle.mdx
Original file line numberDiff line numberDiff line change
Expand Up@@ -609,13 +609,16 @@ ObjectStack includes **built-in health monitoring** to validate system state.

```
GET /health
→ 200 with { status, version, uptime } if the process is alive (liveness)
→ 200 { success: true, data: { status: "ok", timestamp, version, uptime } }
if the process is alive (liveness)
→ never fails on a dependency — see below

GET /ready
→ 200 if the kernel is running AND every data driver answers (readiness)
→ 200 { success: true, data: { status: "ready", state } } when the kernel is
running AND every data driver answers (readiness)
→ 503 while still booting or shutting down
→ 503 with { state, drivers: [...] } when a data driver stops answering
→ 503 carrying { state, drivers: [...] } in error.details when a data driver
stops answering
```

The two probes answer deliberately different questions (#3756). `/health`
Expand All@@ -629,9 +632,9 @@ kernel with no data engine, or a probe that itself errors, still reads as ready
rather than black-holing a working deployment.

<Callout type="info">
`GET /health` returns a compact liveness body (`status`, `version`, `uptime`) and
`GET /ready` returns readiness. The richer per-subsystem report and the
plugin-declared custom checks below describe the internal health-monitor model
`GET /health` returns a compact liveness body (`status`, `timestamp`, `version`,
`uptime`) and `GET /ready` returns readiness. The richer per-subsystem report
and the plugin-declared custom checks below describe the internal health-monitor model
(`PluginHealthMonitor`), which covers **plugins, not driver connections** — they
are **not yet** exposed as a dedicated HTTP endpoint or as a declarative plugin
field.
Expand All@@ -641,40 +644,25 @@ field.

```json
{
"status": "healthy",
"uptime": 3600,
"version": "2.0.0",
"timestamp": "2024-01-15T11:00:00.000Z",
"checks": {
"database": {
"status": "healthy",
"latency_ms": 5,
"connections": {
"active": 8,
"idle": 2,
"max": 10
}
},
"redis": {
"status": "healthy",
"latency_ms": 2
},
"plugins": {
"status": "healthy",
"loaded": 3,
"enabled": 3,
"failed": 0
},
"jobs": {
"status": "healthy",
"pending": 5,
"running": 2,
"failed": 0
}
"success": true,
"data": {
"status": "ok",
"timestamp": "2024-01-15T11:00:00.000Z",
"version": "<the serving artifact's version>",
"uptime": 3600
}
}
```

`status` is the fixed string `"ok"`: the probe reports that the process is
executing code and has nothing else to report. `version` is the serving
artifact's version — the `OS_RUNTIME_VERSION` stamp when a deployment injects
one, otherwise the resolved `@objectstack/runtime` version (#10993) — never a
hardcoded literal. `uptime` is process uptime in seconds, and is omitted
entirely outside Node-like runtimes, where there is no `process` to read it
from. There is no `checks` key: per-subsystem results belong to the internal
health-monitor model below, not to this body.

### Custom Health Checks

Plugins can register custom health checks:
Expand DownExpand Up@@ -706,6 +694,50 @@ export default {
};
```

The richer per-subsystem view the callout above refers to is sketched below. It
is **illustrative only**: no endpoint serves this shape, and it is not the
monitor's own serialized type either — `PluginHealthReport`
(`@objectstack/spec/kernel`) is per-plugin, carries `checks` as an array of
`{ name, status: "passed" | "failed" | "warning" }`, and reports `uptime` under
`metrics`. Read the sketch as a picture of what per-subsystem health reporting
would carry, not as a contract.

```json
{
"status": "healthy",
"uptime": 3600,
"version": "2.0.0",
"timestamp": "2024-01-15T11:00:00.000Z",
"checks": {
"database": {
"status": "healthy",
"latency_ms": 5,
"connections": {
"active": 8,
"idle": 2,
"max": 10
}
},
"redis": {
"status": "healthy",
"latency_ms": 2
},
"plugins": {
"status": "healthy",
"loaded": 3,
"enabled": 3,
"failed": 0
},
"jobs": {
"status": "healthy",
"pending": 5,
"running": 2,
"failed": 0
}
}
}
```

## Shutdown Sequence

Graceful shutdown ensures in-flight requests complete before process exits.
Expand Down
Loading