@sigil-dev/plugin-health 0.9.6 → 0.9.10
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +131 -131
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,132 +1,132 @@
|
|
|
1
|
-
# @sigil-dev/plugin-health
|
|
2
|
-
|
|
3
|
-
Adds a `/health` endpoint to your Grimoire application.
|
|
4
|
-
In coordinator mode it fans out to all workers and aggregates their status, respecting your names defined in the namepool plugin
|
|
5
|
-
In worker mode it reports local uptime, version, and any custom fields you provide.
|
|
6
|
-
|
|
7
|
-
## Installation
|
|
8
|
-
|
|
9
|
-
```sh
|
|
10
|
-
bun add @sigil-dev/plugin-health
|
|
11
|
-
```
|
|
12
|
-
## Why?
|
|
13
|
-
Unified health endpoint format allows for easier library development, for example a health -> Discord webhook or a
|
|
14
|
-
headless status page
|
|
15
|
-
|
|
16
|
-
## Usage
|
|
17
|
-
|
|
18
|
-
```ts
|
|
19
|
-
import { defineConfig } from "@sigil-dev/grimoire";
|
|
20
|
-
import { healthPlugin } from "@sigil-dev/plugin-health";
|
|
21
|
-
|
|
22
|
-
export default defineConfig({
|
|
23
|
-
plugins: [
|
|
24
|
-
healthPlugin(),
|
|
25
|
-
],
|
|
26
|
-
});
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
Hit `/health` to get a full cluster report:
|
|
30
|
-
|
|
31
|
-
```json
|
|
32
|
-
{
|
|
33
|
-
"ok": true,
|
|
34
|
-
"version": "1.0.0",
|
|
35
|
-
"uptime": 3600,
|
|
36
|
-
"cluster": [
|
|
37
|
-
{ "name": "api-0", "status": "up", "pid": 1234, "version": "1.0.0", "lastSeen": 1718000000000 },
|
|
38
|
-
{ "name": "ws-0", "status": "up", "pid": 1235, "version": "1.0.0", "lastSeen": 1718000000000 }
|
|
39
|
-
]
|
|
40
|
-
}
|
|
41
|
-
```
|
|
42
|
-
|
|
43
|
-
Returns `200` when all workers are up or reserved, `503` when any worker is down.
|
|
44
|
-
|
|
45
|
-
## Options
|
|
46
|
-
|
|
47
|
-
```ts
|
|
48
|
-
interface HealthPluginOptions {
|
|
49
|
-
/** Route to serve health at. Default: "/health" */
|
|
50
|
-
path?: string;
|
|
51
|
-
/** Extra fields to include in the response. */
|
|
52
|
-
extend?: () => Record<string, unknown> | Promise<Record<string, unknown>>;
|
|
53
|
-
/** Worker names to track. Auto-detected from plugin-namepool if present. */
|
|
54
|
-
names?: string[];
|
|
55
|
-
}
|
|
56
|
-
```
|
|
57
|
-
|
|
58
|
-
### Custom fields
|
|
59
|
-
|
|
60
|
-
Use `extend` to add dependency health checks or any other metadata:
|
|
61
|
-
|
|
62
|
-
```ts
|
|
63
|
-
healthPlugin({
|
|
64
|
-
extend: async () => ({
|
|
65
|
-
db: await checkPostgres(),
|
|
66
|
-
redis: await checkRedis(),
|
|
67
|
-
version_sha: process.env.GIT_SHA,
|
|
68
|
-
}),
|
|
69
|
-
})
|
|
70
|
-
```
|
|
71
|
-
|
|
72
|
-
## Worker status values
|
|
73
|
-
|
|
74
|
-
| Status | Meaning |
|
|
75
|
-
|---|---|
|
|
76
|
-
| `"up"` | Worker is running and responding. |
|
|
77
|
-
| `"down"` | Worker exists in coordinator but did not respond within 2 seconds. |
|
|
78
|
-
| `"reserved"` | Name is in the pool but no worker slot is configured for it. |
|
|
79
|
-
|
|
80
|
-
`"reserved"` workers do not fail the health check — they indicate a name is allocated but not yet deployed.
|
|
81
|
-
|
|
82
|
-
## Response shape
|
|
83
|
-
|
|
84
|
-
### Coordinator (`/health`)
|
|
85
|
-
|
|
86
|
-
```ts
|
|
87
|
-
interface HealthResponse {
|
|
88
|
-
ok: boolean;
|
|
89
|
-
version: string;
|
|
90
|
-
uptime: number; // seconds since coordinator start
|
|
91
|
-
cluster: WorkerHealth[];
|
|
92
|
-
[key: string]: unknown; // any fields added via extend()
|
|
93
|
-
}
|
|
94
|
-
|
|
95
|
-
interface WorkerHealth {
|
|
96
|
-
name: string;
|
|
97
|
-
status: "up" | "down" | "reserved";
|
|
98
|
-
pid?: number;
|
|
99
|
-
version: string;
|
|
100
|
-
lastSeen: number | null; // null if the worker never started
|
|
101
|
-
}
|
|
102
|
-
```
|
|
103
|
-
|
|
104
|
-
### Worker (`/health`)
|
|
105
|
-
|
|
106
|
-
```ts
|
|
107
|
-
{
|
|
108
|
-
ok: true,
|
|
109
|
-
version: "1.0.0",
|
|
110
|
-
uptime: 120,
|
|
111
|
-
instanceId: "alpha",
|
|
112
|
-
pid: 1234,
|
|
113
|
-
// ...any fields from extend()
|
|
114
|
-
}
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
## Integration with plugin-namepool
|
|
118
|
-
|
|
119
|
-
When `@sigil-dev/plugin-namepool` is also registered, `plugin-health` automatically detects it via the plugin registry and uses the name pool to report `reserved` workers. No configuration needed.
|
|
120
|
-
|
|
121
|
-
```ts
|
|
122
|
-
import { namepool } from "@sigil-dev/plugin-namepool";
|
|
123
|
-
import { healthPlugin } from "@sigil-dev/plugin-health";
|
|
124
|
-
|
|
125
|
-
export default defineConfig({
|
|
126
|
-
plugins: [
|
|
127
|
-
namepool({ names: ["alpha", "beta", "gamma"] }),
|
|
128
|
-
healthPlugin(),
|
|
129
|
-
],
|
|
130
|
-
scale: { api: 2 }, // only 2 workers — "gamma" shows as reserved
|
|
131
|
-
});
|
|
1
|
+
# @sigil-dev/plugin-health
|
|
2
|
+
|
|
3
|
+
Adds a `/health` endpoint to your Grimoire application.
|
|
4
|
+
In coordinator mode it fans out to all workers and aggregates their status, respecting your names defined in the namepool plugin
|
|
5
|
+
In worker mode it reports local uptime, version, and any custom fields you provide.
|
|
6
|
+
|
|
7
|
+
## Installation
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
bun add @sigil-dev/plugin-health
|
|
11
|
+
```
|
|
12
|
+
## Why?
|
|
13
|
+
Unified health endpoint format allows for easier library development, for example a health -> Discord webhook or a
|
|
14
|
+
headless status page
|
|
15
|
+
|
|
16
|
+
## Usage
|
|
17
|
+
|
|
18
|
+
```ts
|
|
19
|
+
import { defineConfig } from "@sigil-dev/grimoire";
|
|
20
|
+
import { healthPlugin } from "@sigil-dev/plugin-health";
|
|
21
|
+
|
|
22
|
+
export default defineConfig({
|
|
23
|
+
plugins: [
|
|
24
|
+
healthPlugin(),
|
|
25
|
+
],
|
|
26
|
+
});
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
Hit `/health` to get a full cluster report:
|
|
30
|
+
|
|
31
|
+
```json
|
|
32
|
+
{
|
|
33
|
+
"ok": true,
|
|
34
|
+
"version": "1.0.0",
|
|
35
|
+
"uptime": 3600,
|
|
36
|
+
"cluster": [
|
|
37
|
+
{ "name": "api-0", "status": "up", "pid": 1234, "version": "1.0.0", "lastSeen": 1718000000000 },
|
|
38
|
+
{ "name": "ws-0", "status": "up", "pid": 1235, "version": "1.0.0", "lastSeen": 1718000000000 }
|
|
39
|
+
]
|
|
40
|
+
}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
Returns `200` when all workers are up or reserved, `503` when any worker is down.
|
|
44
|
+
|
|
45
|
+
## Options
|
|
46
|
+
|
|
47
|
+
```ts
|
|
48
|
+
interface HealthPluginOptions {
|
|
49
|
+
/** Route to serve health at. Default: "/health" */
|
|
50
|
+
path?: string;
|
|
51
|
+
/** Extra fields to include in the response. */
|
|
52
|
+
extend?: () => Record<string, unknown> | Promise<Record<string, unknown>>;
|
|
53
|
+
/** Worker names to track. Auto-detected from plugin-namepool if present. */
|
|
54
|
+
names?: string[];
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Custom fields
|
|
59
|
+
|
|
60
|
+
Use `extend` to add dependency health checks or any other metadata:
|
|
61
|
+
|
|
62
|
+
```ts
|
|
63
|
+
healthPlugin({
|
|
64
|
+
extend: async () => ({
|
|
65
|
+
db: await checkPostgres(),
|
|
66
|
+
redis: await checkRedis(),
|
|
67
|
+
version_sha: process.env.GIT_SHA,
|
|
68
|
+
}),
|
|
69
|
+
})
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Worker status values
|
|
73
|
+
|
|
74
|
+
| Status | Meaning |
|
|
75
|
+
|---|---|
|
|
76
|
+
| `"up"` | Worker is running and responding. |
|
|
77
|
+
| `"down"` | Worker exists in coordinator but did not respond within 2 seconds. |
|
|
78
|
+
| `"reserved"` | Name is in the pool but no worker slot is configured for it. |
|
|
79
|
+
|
|
80
|
+
`"reserved"` workers do not fail the health check — they indicate a name is allocated but not yet deployed.
|
|
81
|
+
|
|
82
|
+
## Response shape
|
|
83
|
+
|
|
84
|
+
### Coordinator (`/health`)
|
|
85
|
+
|
|
86
|
+
```ts
|
|
87
|
+
interface HealthResponse {
|
|
88
|
+
ok: boolean;
|
|
89
|
+
version: string;
|
|
90
|
+
uptime: number; // seconds since coordinator start
|
|
91
|
+
cluster: WorkerHealth[];
|
|
92
|
+
[key: string]: unknown; // any fields added via extend()
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
interface WorkerHealth {
|
|
96
|
+
name: string;
|
|
97
|
+
status: "up" | "down" | "reserved";
|
|
98
|
+
pid?: number;
|
|
99
|
+
version: string;
|
|
100
|
+
lastSeen: number | null; // null if the worker never started
|
|
101
|
+
}
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
### Worker (`/health`)
|
|
105
|
+
|
|
106
|
+
```ts
|
|
107
|
+
{
|
|
108
|
+
ok: true,
|
|
109
|
+
version: "1.0.0",
|
|
110
|
+
uptime: 120,
|
|
111
|
+
instanceId: "alpha",
|
|
112
|
+
pid: 1234,
|
|
113
|
+
// ...any fields from extend()
|
|
114
|
+
}
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## Integration with plugin-namepool
|
|
118
|
+
|
|
119
|
+
When `@sigil-dev/plugin-namepool` is also registered, `plugin-health` automatically detects it via the plugin registry and uses the name pool to report `reserved` workers. No configuration needed.
|
|
120
|
+
|
|
121
|
+
```ts
|
|
122
|
+
import { namepool } from "@sigil-dev/plugin-namepool";
|
|
123
|
+
import { healthPlugin } from "@sigil-dev/plugin-health";
|
|
124
|
+
|
|
125
|
+
export default defineConfig({
|
|
126
|
+
plugins: [
|
|
127
|
+
namepool({ names: ["alpha", "beta", "gamma"] }),
|
|
128
|
+
healthPlugin(),
|
|
129
|
+
],
|
|
130
|
+
scale: { api: 2 }, // only 2 workers — "gamma" shows as reserved
|
|
131
|
+
});
|
|
132
132
|
```
|
package/package.json
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
"type": "module",
|
|
6
6
|
"private": false,
|
|
7
7
|
"dependencies": {
|
|
8
|
-
"@sigil-dev/grimoire": "0.9.
|
|
8
|
+
"@sigil-dev/grimoire": "0.9.10"
|
|
9
9
|
},
|
|
10
10
|
"devDependencies": {
|
|
11
11
|
"@types/bun": "latest"
|
|
@@ -13,5 +13,5 @@
|
|
|
13
13
|
"peerDependencies": {
|
|
14
14
|
"typescript": "^5"
|
|
15
15
|
},
|
|
16
|
-
"version": "0.9.
|
|
16
|
+
"version": "0.9.10"
|
|
17
17
|
}
|