@systemfsoftware/effect-daemon-spec 4.1.1 → 5.0.0

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/CHANGELOG.md CHANGED
@@ -1,5 +1,40 @@
1
1
  # @systemfsoftware/effect-daemon-spec
2
2
 
3
+ ## 5.0.0
4
+
5
+ ### Major Changes
6
+
7
+ - A supervisor that exhausts its restart intensity now stops every child and then fails `Supervisor.awaitTerminated` and `Supervisor.shutdown` with `Supervisor.SupervisorTerminated`. The error's `cause` is the failure of the child that exhausted it. A supervisor running as another supervisor's child ends abnormally when it gives up, so its parent counts it against its own intensity and escalation reaches the top-level owner. A requested shutdown, and a supervisor with `coolDown` declared, still succeed.
8
+
9
+ - The package now exports a single `Supervisor` namespace that builds Erlang/OTP supervision trees: `Supervisor.make(name)` with `strategy`, `intensity`, `autoShutdown`, `coolDown`, `backoff`, `dynamic` and `children`, acquired through `.scoped` or `.layer`. Children run as fibers by default, and `Supervisor.ChildSpecs.on(port)` declares a child on another medium, whose layer the tree's `.layer` then requires. Restart strategies, restart types, restart intensity and shutdown modes follow OTP's `supervisor`, and exhausting the intensity now terminates the supervisor unless `coolDown` is declared. `Daemon`, `LeaderLock`, `LockPrimitive` and the `run` entry points are removed; declare a supervisor with `Supervisor.make` and its children with `Supervisor.ChildSpecs.make` instead. A running supervisor's decisions are observable through `Supervisor.traceOf`.
10
+
11
+ ### Minor Changes
12
+
13
+ - Adds an `@systemfsoftware/effect-daemon-spec/testing` entry point that checks a `LockPrimitive` implementation for linearizability. It exports the lock command schema (`LockCommand`), a pure lock model (`lockModel`, `stepLock`), `leadershipOver(primitive)`, which builds the `LeaderLock` the daemon uses over your primitive, and `runLockCommand`. Pass them to `Conformance.linearizable` from `@systemfsoftware/conformance-spec`, which is an optional peer dependency. The root entry point pulls in no test code.
14
+
15
+ - Add `Supervisor.livenessTick(millis)`, which declares how often the kernel's liveness tick fires for a ready child, beside the other policy knobs. Declare a longer tick when children run on a medium whose lifecycle steps take longer than the default one-second interval.
16
+
17
+ ### Patch Changes
18
+
19
+ - Every tagged error class now has a one-line message built from its fields, so a failure shows what went wrong instead of an empty message.
20
+
21
+ - Update peer and runtime dependency on `effect` and companion packages to `4.0.0-rc.117`.
22
+
23
+ - Updated dependencies:
24
+ - @systemfsoftware/conformance-spec@0.2.0
25
+
26
+ ## 4.2.0
27
+
28
+ ### Major Changes
29
+
30
+ - A supervisor that exhausts its restart intensity now stops every child and then fails `Supervisor.awaitTerminated` and `Supervisor.shutdown` with `Supervisor.SupervisorTerminated`. The error's `cause` is the failure of the child that exhausted it. A supervisor running as another supervisor's child ends abnormally when it gives up, so its parent counts it against its own intensity and escalation reaches the top-level owner. A requested shutdown, and a supervisor with `coolDown` declared, still succeed.
31
+
32
+ - The package now exports a single `Supervisor` namespace that builds Erlang/OTP supervision trees: `Supervisor.make(name)` with `strategy`, `intensity`, `autoShutdown`, `coolDown`, `backoff`, `dynamic` and `children`, acquired through `.scoped` or `.layer`. Children run as fibers by default, and `Supervisor.ChildSpecs.on(port)` declares a child on another medium, whose layer the tree's `.layer` then requires. Restart strategies, restart types, restart intensity and shutdown modes follow OTP's `supervisor`, and exhausting the intensity now terminates the supervisor unless `coolDown` is declared. `Daemon`, `LeaderLock`, `LockPrimitive` and the `run` entry points are removed; declare a supervisor with `Supervisor.make` and its children with `Supervisor.ChildSpecs.make` instead. A running supervisor's decisions are observable through `Supervisor.traceOf`.
33
+
34
+ ### Minor Changes
35
+
36
+ - Add `Supervisor.livenessTick(millis)`, which declares how often the kernel's liveness tick fires for a ready child, beside the other policy knobs. Declare a longer tick when children run on a medium whose lifecycle steps take longer than the default one-second interval.
37
+
3
38
  ## 4.1.1
4
39
 
5
40
  ### Patch Changes
package/README.md CHANGED
@@ -1,41 +1,156 @@
1
1
  # @systemfsoftware/effect-daemon-spec
2
2
 
3
- Supervise dynamic worker trees in [Effect](https://effect.website) — restart policies, leader election, and health-gated retries built on top of Effect's supervision primitives.
3
+ Erlang/OTP supervision trees for [Effect](https://effect.website). A supervisor starts its children in order, restarts the ones that fail according to its strategy, each child's restart type and its restart intensity, and stops them in reverse order when its scope closes. It does this the way OTP's `supervisor` does.
4
4
 
5
- Effect's built-in `Supervisor` tracks fibre lifecycles but doesn't give you daemon semantics. This library fills the gap: exponential backoff on restart, distributed leader election via `Duration`-based fencing, and poll-based health checks that gate restart decisions.
5
+ Every supervision decision is made by a pure fold over supervision events, and each step of that fold is published on the supervisor's trace, so what the supervisor did and why is something you can read, not guess.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ pnpm add @systemfsoftware/effect-daemon-spec effect
11
+ ```
12
+
13
+ > [!NOTE]
14
+ > `effect` is a peer dependency: you bring your own.
15
+
16
+ ## Quick start
17
+
18
+ A child is an Effect. A bare Effect counts as started as soon as it runs; a function of `ready` counts as started when it calls `ready`, for example once a server is listening.
6
19
 
7
20
  ```ts
8
- import { Daemon, RestartPolicy } from '@systemfsoftware/effect-daemon-spec'
9
- import { Effect } from 'effect'
10
-
11
- const pool = Daemon.supervised('worker-pool', {
12
- bootstrap: [worker, worker, worker],
13
- policy: RestartPolicy.exponential({
14
- minDelay: '100 millis',
15
- maxDelay: '10 seconds',
16
- }),
17
- })
18
-
19
- Effect.scoped(pool).pipe(Effect.runFork)
21
+ import { Supervisor } from '@systemfsoftware/effect-daemon-spec'
22
+ import { Effect, Layer } from 'effect'
23
+
24
+ const database = Effect.andThen(Effect.log('database connected'), Effect.never)
25
+
26
+ const httpServer = (ready: Effect.Effect<void>) =>
27
+ Effect.gen(function*() {
28
+ yield* Effect.log('listening on :8080')
29
+ yield* ready
30
+ return yield* Effect.never
31
+ })
32
+
33
+ const app = Supervisor.make('app').pipe(
34
+ Supervisor.strategy('rest_for_one'),
35
+ Supervisor.intensity(3, 5_000),
36
+ Supervisor.children([
37
+ Supervisor.ChildSpecs.make('database', database),
38
+ Supervisor.ChildSpecs.make('http', httpServer),
39
+ ]),
40
+ )
41
+
42
+ Layer.launch(app.layer).pipe(Effect.runFork)
20
43
  ```
21
44
 
22
- A leader-lock coordinator ensures only one node acts as the leader for a given key:
45
+ If the database fails, `rest_for_one` stops the HTTP server, restarts the database, and starts the server again. A fourth restart within five seconds stops both children and terminates the supervisor.
46
+
47
+ Use `app.scoped` instead of `app.layer` to get the running supervisor handle inside your own scope.
48
+
49
+ ## Restart strategies
50
+
51
+ | Strategy | When a child terminates and must restart |
52
+ | ----------------------- | ------------------------------------------------------------------------------------------------ |
53
+ | `one_for_one` (default) | Only that child restarts. |
54
+ | `one_for_all` | Every child stops in reverse order, then all start again in declared order. |
55
+ | `rest_for_one` | The children declared after it stop in reverse order; it and they start again in declared order. |
56
+
57
+ `Supervisor.intensity(n, periodMillis)` allows at most `n` restarts within `periodMillis`. The default is OTP's: one restart in five seconds. One more restart than that stops every child and terminates the supervisor; whoever is waiting on it observes a give-up (see [Observing a running supervisor](#observing-a-running-supervisor)).
58
+
59
+ ## Children
60
+
61
+ `Supervisor.ChildSpecs.make(id, program, options)` declares a child. Every option is optional; the first three default as OTP does.
62
+
63
+ | Option | Values | Default |
64
+ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ |
65
+ | `restartType` | `permanent` always restarts; `transient` restarts only after an abnormal exit; `temporary` never restarts | `permanent` |
66
+ | `shutdown` | `{ _tag: 'Brutal' }` interrupts without waiting; `{ _tag: 'Graceful', millis }` interrupts and waits up to `millis` for finalizers; `{ _tag: 'Infinity' }` waits for them however long they take | `Graceful` 5000 ms, `Infinity` for a nested supervisor |
67
+ | `significant` | with `Supervisor.autoShutdown('any_significant' \| 'all_significant')`, the exit of a significant child shuts the supervisor down | `false` |
68
+ | `startTimeoutMillis` | a child not ready within this time counts as an abnormal termination | 5000 |
69
+
70
+ `Supervisor.child(id, program, options)` appends a single child.
71
+
72
+ ### Choosing the medium a child runs on
73
+
74
+ `Supervisor.ChildSpecs.make` binds a child to the fiber medium. When a child should run on something else — a process, a socket, a machine — declare a medium port and bind the child to it. A port is a `Context.Service` keyed to the program type it interprets; its driver provides the medium as a layer, so one tree can mix media while the strategy, order and policy never mention one.
23
75
 
24
76
  ```ts
25
- import { LeaderLock } from '@systemfsoftware/effect-daemon-spec'
77
+ import { Effect, Layer, Scope } from 'effect'
78
+
79
+ const DocumentPort = Supervisor.Medium.MediumPort<
80
+ Effect.Effect<void, never, Scope.Scope>,
81
+ never,
82
+ Scope.Scope
83
+ >('DocumentMedium')
26
84
 
27
- const myLock = LeaderLock.make({
28
- key: 'daemon-leader',
29
- leaseDuration: '5 seconds',
30
- renewInterval: '1 second',
31
- })
85
+ const tree = Supervisor.make('app').pipe(
86
+ Supervisor.children([
87
+ Supervisor.ChildSpecs.make('http', httpServer), // the fiber medium
88
+ Supervisor.ChildSpecs.on(DocumentPort)('document', documentTask), // the port's medium
89
+ ]),
90
+ )
91
+
92
+ const provided = tree.layer.pipe(
93
+ Layer.provideMerge(Layer.succeed(DocumentPort, { medium: documentMedium })),
94
+ )
32
95
  ```
33
96
 
34
- ## Install
97
+ A port a child is bound to joins the tree's requirements, so `tree.scoped` and `tree.layer` wait for it. A port medium whose `start` fails reports that incarnation as an abnormal termination; nothing claims the child started.
35
98
 
36
- ```bash
37
- pnpm add @systemfsoftware/effect-daemon-spec
99
+ ## Nested supervisors
100
+
101
+ A supervisor spec is itself a valid child program, so trees nest to any depth:
102
+
103
+ ```ts
104
+ const workers = Supervisor.make('workers').pipe(
105
+ Supervisor.strategy('one_for_all'),
106
+ Supervisor.children([
107
+ Supervisor.ChildSpecs.make('ingest', database),
108
+ Supervisor.ChildSpecs.make('export', database),
109
+ ]),
110
+ )
111
+
112
+ const root = Supervisor.make('root').pipe(
113
+ Supervisor.children([Supervisor.ChildSpecs.make('workers', workers)]),
114
+ )
38
115
  ```
39
116
 
40
- > [!NOTE]
41
- > `effect` is a peer dependency — you bring your own.
117
+ Stopping the nested supervisor waits for its whole subtree to shut down first.
118
+
119
+ ## Dynamic children
120
+
121
+ A supervisor declared with `Supervisor.dynamic` starts children on request, up to a ceiling. Each start allocates the child's id and answers whether it was accepted:
122
+
123
+ ```ts
124
+ const pool = Supervisor.make('jobs').pipe(
125
+ Supervisor.dynamic({ ceiling: 100, restartType: 'temporary' }),
126
+ )
127
+
128
+ const runJob = (job: Effect.Effect<void>) =>
129
+ Effect.scoped(
130
+ Effect.gen(function*() {
131
+ const jobs = yield* pool.scoped
132
+ const reply = yield* Supervisor.startChild(jobs, Supervisor.readyOnStart(job))
133
+ // { outcome: 'accepted', childId, generation } or { outcome: 'refused' } at the ceiling
134
+ return reply
135
+ }),
136
+ )
137
+ ```
138
+
139
+ `Supervisor.stopChild(running, childId, generation)` stops that incarnation and answers `stopped`, or `missed` when it is no longer current.
140
+
141
+ ## Beyond OTP
142
+
143
+ Two behaviours OTP does not have are available when you declare them:
144
+
145
+ - `Supervisor.coolDown(millis)`: on intensity exhaustion, stop the children, wait, and start them again instead of terminating.
146
+ - `Supervisor.backoff({ baseMillis, multiplier, capMillis })`: space out consecutive restarts of the same child.
147
+
148
+ ## Observing a running supervisor
149
+
150
+ `Supervisor.traceOf(running)` is a `Stream` of every step the supervisor takes: the event it received (a child started, terminated, a timer elapsed, a request arrived) and the decision it made, including the children it stopped and started. `Supervisor.statusOf(running)` reads its current phase and children, and `Supervisor.awaitTerminated(running)` settles when it has terminated.
151
+
152
+ The wait succeeds when the supervisor ended because it was asked to shut down or because a significant child's exit shut it down. It fails with `Supervisor.SupervisorTerminated` when the supervisor gave up after exceeding its restart intensity: the error carries the supervisor's name, its own termination reason, and the `Cause` of the child termination that exhausted it — a fiber child's real exit cause, or the child's termination reason for any other medium. Every child has stopped and its finalizers have run before the wait settles. A supervisor that gives up under a parent ends as an abnormal child of that parent, so a chain of give-ups escalates to the top-level owner.
153
+
154
+ ## License
155
+
156
+ [Apache-2.0](https://github.com/systemfsoftware/systemfsoftware/blob/main/packages/daemon/effect-daemon-spec/LICENSE)