83 lines
6.0 KiB
Markdown
83 lines
6.0 KiB
Markdown
# @suaveplan/api-lifecycle - Plugin lifecycle FSM contract: 13-state discriminated union, legal-transition table, side-effect descriptors, retry policies for start_failed and crashed, per-plugin mutex contract, and reinstall criteria — the definition consumed by api-host's lifecycle driver. Pure definitions + factories; no host runtime.
|
||
|
||
Stage-1 contract package for the Suaveplan API plugin system: the
|
||
plugin-lifecycle finite state machine definition, the legal-transition
|
||
table, the side-effect descriptors per transition, the retry policies for
|
||
`start_failed` and `crashed`, the per-plugin mutex contract, and the
|
||
`requiresReinstall` criteria. `api-host` consumes this package
|
||
to execute the actual lifecycle — ships only the data and the
|
||
factory.
|
||
|
||
Backed by `@suaveplan/fsm` (state-machine runtime), `@suaveplan/retry`
|
||
(exponential backoff), `@suaveplan/error` (typed errors), and
|
||
`@suaveplan/events` (observers).
|
||
|
||
<!-- begin:auto-docs -->
|
||
## Documentation tree
|
||
|
||
- [error-codes](./src/error-codes/error-codes.md) — Defines `LIFECYCLE_CODES` — the frozen, namespaced registry of the four error codes raised by the `@suaveplan/api-lifec…
|
||
- [error-codes](./src/error-codes/error-codes.md) — Defines `LIFECYCLE_CODES` — the frozen, namespaced registry of the four error codes raised by the `@suaveplan/api-lifec…
|
||
- [fsm-factory](./src/fsm-factory/fsm-factory.md) — Binds the `@suaveplan/api-lifecycle` definitions together — states, transitions, side-effects, and the per-plugin mutex…
|
||
- [fsm-factory](./src/fsm-factory/fsm-factory.md) — Binds the `@suaveplan/api-lifecycle` definitions together — states, transitions, side-effects, and the per-plugin mutex…
|
||
- [mutex-contract](./src/mutex-contract/mutex-contract.md) — Defines `PluginMutex` — the contract guaranteeing at most one lifecycle transition per plugin in flight at any time — t…
|
||
- [mutex-contract](./src/mutex-contract/mutex-contract.md) — Defines `PluginMutex` — the contract guaranteeing at most one lifecycle transition per plugin in flight at any time — t…
|
||
- [reinstall-criteria](./src/reinstall-criteria/reinstall-criteria.md) — Decides whether a manifest update from `prev` to `next` requires a full reinstall path (`uninstalled → installing → ins…
|
||
- [reinstall-criteria](./src/reinstall-criteria/reinstall-criteria.md) — Decides whether a manifest update from `prev` to `next` requires a full reinstall path (`uninstalled → installing → ins…
|
||
- [retry-policies](./src/retry-policies/retry-policies.md) — Owns the retry-budget contract for the two automatic-recovery paths in the lifecycle FSM: `start_failed` (3 attempts wi…
|
||
- [retry-policies](./src/retry-policies/retry-policies.md) — Owns the retry-budget contract for the two automatic-recovery paths in the lifecycle FSM: `start_failed` (3 attempts wi…
|
||
- [side-effects](./src/side-effects/side-effects.md) — Encodes every side-effect the host runtime SHALL execute on each documented transition — `mount-routes`, `unmount-route…
|
||
- [side-effects](./src/side-effects/side-effects.md) — Encodes every side-effect the host runtime SHALL execute on each documented transition — `mount-routes`, `unmount-route…
|
||
- [states](./src/states/states.md) — Owns the runtime view of the plugin lifecycle's 13-state union. The `PluginState` type itself is re-exported from `@sua…
|
||
- [states](./src/states/states.md) — Owns the runtime view of the plugin lifecycle's 13-state union. The `PluginState` type itself is re-exported from `@sua…
|
||
- [testing](./src/testing/conformance.md) — Exposes `runLifecycleConformance({ factory, label })` — the reusable test harness `api-host` lifecycle driver…
|
||
- [conformance](./src/testing/conformance.md) — Exposes `runLifecycleConformance({ factory, label })` — the reusable test harness `api-host` lifecycle driver…
|
||
- [transitions](./src/transitions/transitions.md) — Encodes the complete legal-transition graph of the plugin lifecycle FSM — every `(from, to, trigger)` edge documented i…
|
||
- [transitions](./src/transitions/transitions.md) — Encodes the complete legal-transition graph of the plugin lifecycle FSM — every `(from, to, trigger)` edge documented i…
|
||
<!-- end:auto-docs -->
|
||
|
||
## Modules
|
||
|
||
- [`states`](./src/states/states.md) — `PluginState` 13-state union,
|
||
`PLUGIN_STATES` tuple, `isLive` / `isParked` predicates.
|
||
- [`transitions`](./src/transitions/transitions.md) — `PLUGIN_TRANSITIONS`
|
||
edge table, `PluginTransitions` query class.
|
||
- [`fsm-factory`](./src/fsm-factory/fsm-factory.md) — `createPluginFsm`
|
||
binding to `@suaveplan/fsm`.
|
||
- [`side-effects`](./src/side-effects/side-effects.md) — `SIDE_EFFECTS`
|
||
descriptor map keyed `<from>|<to>`.
|
||
- [`retry-policies`](./src/retry-policies/retry-policies.md) —
|
||
`RETRY_POLICIES.startFailed`, `RETRY_POLICIES.crashed`, plus
|
||
`StartFailedTracker` and `CrashBudgetTracker`.
|
||
- [`mutex-contract`](./src/mutex-contract/mutex-contract.md) —
|
||
`PluginMutex` interface and `InMemoryPluginMutex` reference impl.
|
||
- [`reinstall-criteria`](./src/reinstall-criteria/reinstall-criteria.md) —
|
||
`requiresReinstall(prev, next)` and `compareSemver`.
|
||
- [`error-codes`](./src/error-codes/error-codes.md) — `LIFECYCLE_CODES`
|
||
registry plus `LifecycleError`.
|
||
- [`testing/conformance`](./src/testing/conformance.md) —
|
||
`runLifecycleConformance({ factory, label })` harness must
|
||
pass.
|
||
|
||
## Quick start
|
||
|
||
```ts
|
||
import { createPluginFsm } from "@suaveplan/api-lifecycle";
|
||
|
||
const fsm = createPluginFsm({ plugin: "billing" });
|
||
await fsm.transition("install");
|
||
await fsm.transition("installCompleted");
|
||
await fsm.transition("start");
|
||
await fsm.transition("startCompleted");
|
||
// fsm.state === "started"
|
||
```
|
||
|
||
## Error codes
|
||
|
||
| Code | Thrown when |
|
||
|---|---|
|
||
| `LIFECYCLE.ILLEGAL_TRANSITION` | `(from, trigger)` not in the legal table |
|
||
| `LIFECYCLE.MUTEX_HELD` | `assertAcquired` called on a null `tryAcquire` result |
|
||
| `LIFECYCLE.RETRY_BUDGET_EXHAUSTED` | start_failed × 3 OR crashed × 3 in window |
|
||
| `LIFECYCLE.REINSTALL_REQUIRED_VERSION_DOWNGRADE` | `next.version < prev.version` |
|
||
|