@greendrake/service-state 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eugene Greendrake
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,60 @@
+# @greendrake/service-state
+
+A backend service an operator can turn on and off, as a state machine both halves of a dashboard share. The root entry is the contract — the states, the status, the method and push names, the transition table — and is pure types and data with no runtime dependency, so the frontend importing it pulls in nothing. `./server` is the machine behind it.
+
+```
+OFF --start--> STARTING --> ON     ON --stop--> STOPPING --> OFF
+                       \                                \
+                        --> ERROR                        --> ERROR
+```
+
+`refresh` runs from any settled state and adopts what the service actually reports.
+
+## Install
+
+```sh
+bun add @greendrake/service-state
+```
+
+The `./server` entry needs `@greendrake/rpc-server`, which is an optional peer dependency: a dashboard importing only the contract installs neither it nor bun's types.
+
+## The contract
+
+```ts
+import { SERVICE_STATE_EVENT, type ServiceStateMethods, type ServiceStatePushes, type ServiceStatus } from '@greendrake/service-state'
+
+interface ServiceStatus {
+    state: 'OFF' | 'STARTING' | 'ON' | 'STOPPING' | 'ERROR'
+    error: string | null // what went wrong, in ERROR; null everywhere else
+    changed_at: number // epoch ms
+}
+```
+
+`ServiceStateMethods` is the four methods (`service.status`, `service.start`, `service.stop`, `service.refresh`), each answering a `ServiceStatus` — hand it to an `ApiClient`. `ServiceStatePushes` types the `service.state` event, which carries the same status to **every** connected socket: a service has one state, and everyone watching it is watching the same thing.
+
+`@greendrake/dash`'s `ServiceStateControl` renders all of this; a dashboard that wants the control needs no code of its own beyond wiring it to its client and transport.
+
+## The machine
+
+```ts
+import { createServiceStateMachine, serviceStateMethods } from '@greendrake/service-state/server'
+
+const machine = await createServiceStateMachine(
+    {
+        start: () => systemd.start('thing.service'),
+        stop: () => systemd.stop('thing.service'),
+        check: () => systemd.isActive('thing.service').then(on => (on ? 'ON' : 'OFF'))
+    },
+    registry // any EventSink — @greendrake/rpc-server's ConnRegistry is one
+)
+
+const methods = { ...serviceStateMethods(machine), ...whateverElse }
+```
+
+The factory reads the service before returning, so the machine never reports a state it has not verified — one that assumed `OFF` at boot would have every dashboard showing `OFF` for a service that is up.
+
+`start` and `stop` **return as soon as the transition has begun**, with the in-flight status. Where it ends up is the machine's next state, pushed to everyone — not the caller's answer, because everyone watching needs it equally and one of them happening to have asked changes nothing. A hook that rejects lands the machine in `ERROR` carrying its message.
+
+One transition at a time, and each only from the state it is defined for. Anything else — `start` while already `ON`, `refresh` mid-transition — is refused with `SERVICE_BUSY`. A client showing the state never triggers it, because the state it is showing offers no such button.
+
+`serviceStateMethods(machine, auth = 'admin')` returns the four `MethodDef`s. Admin-only by default: turning a service off is not a read.

package/package.json

@@ -0,0 +1,54 @@
+{
+    "name": "@greendrake/service-state",
+    "version": "0.1.0",
+    "description": "A backend service as a state machine (OFF/STARTING/ON/STOPPING/ERROR): the wire contract both halves share, and the server-side machine behind it",
+    "license": "MIT",
+    "author": "Eugene Greendrake <eugene@greendrake.nz>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/greendrake/lib.git",
+        "directory": "service-state"
+    },
+    "homepage": "https://github.com/greendrake/lib/tree/main/service-state#readme",
+    "bugs": {
+        "url": "https://github.com/greendrake/lib/issues"
+    },
+    "type": "module",
+    "main": "src/main.ts",
+    "types": "src/main.ts",
+    "exports": {
+        ".": {
+            "types": "./src/main.ts",
+            "default": "./src/main.ts"
+        },
+        "./server": {
+            "types": "./src/server.ts",
+            "default": "./src/server.ts"
+        }
+    },
+    "files": [
+        "src"
+    ],
+    "sideEffects": false,
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "check": "tsc --noEmit"
+    },
+    "prettier": "@greendrake/dev-config/prettier",
+    "peerDependencies": {
+        "@greendrake/rpc-server": "0.1.0"
+    },
+    "peerDependenciesMeta": {
+        "@greendrake/rpc-server": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@greendrake/dev-config": "0.1.0",
+        "@greendrake/rpc-server": "0.1.0",
+        "@types/bun": "^1.3.5",
+        "typescript": "6.0.3"
+    }
+}

package/src/main.ts

@@ -0,0 +1,52 @@
+// The contract a service-state pair shares: the states, the status both ends
+// pass around, the method and push names, and the transition table. Pure types
+// and data — no runtime dependency at all, so a frontend importing it pulls in
+// nothing. The machine behind it is the `./server` entry.
+
+export const SERVICE_STATES = ['OFF', 'STARTING', 'ON', 'STOPPING', 'ERROR'] as const
+
+export type ServiceState = (typeof SERVICE_STATES)[number]
+
+// Wire shape: snake_case, as the envelope's own fields are.
+export interface ServiceStatus {
+    state: ServiceState
+    // What went wrong, in ERROR. Null in every other state — a stale message
+    // outliving the failure it describes is worse than none.
+    error: string | null
+    // When the service entered this state, epoch milliseconds.
+    changed_at: number
+}
+
+// Each command: the state it is accepted from, the state the service passes
+// through while it runs, and where it lands. The machine refuses anything this
+// table does not cover, and the control derives its button from it — so adding
+// a command is one row, not an edit in two packages.
+export const TRANSITIONS = {
+    start: {
+        from: 'OFF',
+        during: 'STARTING',
+        to: 'ON'
+    },
+    stop: {
+        from: 'ON',
+        during: 'STOPPING',
+        to: 'OFF'
+    }
+} as const satisfies Record<string, { from: ServiceState; during: ServiceState; to: ServiceState }>
+
+export type ServiceCommand = keyof typeof TRANSITIONS
+
+export const SERVICE_STATE_EVENT = 'service.state'
+
+// The methods a service-state backend serves. A dashboard hands this to its
+// ApiClient; the server derives its definitions from it.
+export interface ServiceStateMethods {
+    'service.status': () => ServiceStatus
+    'service.start': () => ServiceStatus
+    'service.stop': () => ServiceStatus
+    'service.refresh': () => ServiceStatus
+}
+
+// Every state change reaches every connected socket: a service has one state,
+// and everyone watching it is watching the same thing.
+export type ServiceStatePushes = { [SERVICE_STATE_EVENT]: ServiceStatus }

package/src/server.ts

@@ -0,0 +1,116 @@
+import { ApiError } from '@greendrake/rpc-server'
+import type { AuthRequirement, EventSink, MethodDef } from '@greendrake/rpc-server'
+import { SERVICE_STATE_EVENT, TRANSITIONS } from './main'
+import type { ServiceCommand, ServiceState, ServiceStateMethods, ServiceStatus } from './main'
+
+// What a concrete service plugs in. `start` and `stop` resolve once the
+// service is up or down; rejecting puts the machine in ERROR with the
+// rejection's message. `check` reports what the service is actually doing
+// right now, read from the service rather than remembered.
+export interface ServiceImplementation {
+    start(): Promise<void>
+    stop(): Promise<void>
+    check(): Promise<ServiceState>
+}
+
+export interface ServiceStateMachine {
+    status(): ServiceStatus
+    // Return as soon as the transition has begun, with the in-flight status.
+    // Where it ends up is the machine's next state, pushed to everyone — not
+    // this caller's answer, because everyone watching needs it equally and one
+    // of them happening to have asked changes nothing.
+    start(): ServiceStatus
+    stop(): ServiceStatus
+    // Re-read the service and adopt what it reports.
+    refresh(): Promise<ServiceStatus>
+}
+
+// The command a state is in no position to take. One code covers both cases —
+// a transition already under way, and a command that would take the service
+// where it already is — because the control never offers either, so this is
+// what a client that ignored the state gets told.
+const BUSY = 'SERVICE_BUSY'
+
+// The service-state machine over a concrete implementation. Reads the service
+// before returning, so it never reports a state it has not verified — a
+// machine that assumed OFF at boot would have the dashboard show OFF for a
+// service that is up.
+export const createServiceStateMachine = async (service: ServiceImplementation, sink: EventSink): Promise<ServiceStateMachine> => {
+    let current: ServiceStatus = {
+        state: 'OFF',
+        error: null,
+        changed_at: Date.now()
+    }
+    let inFlight = false
+
+    const set = (state: ServiceState, error: string | null): ServiceStatus => {
+        current = {
+            state,
+            error,
+            changed_at: Date.now()
+        }
+        sink.broadcastEvent(SERVICE_STATE_EVENT, current)
+        return current
+    }
+
+    // What a re-read yields: a push only where something actually changed, so
+    // a poll against a steady service is silent.
+    const adopt = (state: ServiceState, error: string | null): ServiceStatus => (state === current.state && error === current.error ? current : set(state, error))
+
+    const run = (command: ServiceCommand): ServiceStatus => {
+        const { from, during, to } = TRANSITIONS[command]
+        if (inFlight || current.state !== from) {
+            throw new ApiError(BUSY)
+        }
+        inFlight = true
+        const answer = set(during, null)
+        void service[command]()
+            .then(
+                () => set(to, null),
+                (e: Error) => set('ERROR', e.message)
+            )
+            .finally(() => {
+                inFlight = false
+            })
+        return answer
+    }
+
+    const refresh = async (): Promise<ServiceStatus> => {
+        if (inFlight) {
+            throw new ApiError(BUSY)
+        }
+        inFlight = true
+        try {
+            return adopt(await service.check(), null)
+        } catch (e) {
+            return adopt('ERROR', (e as Error).message)
+        } finally {
+            inFlight = false
+        }
+    }
+
+    const machine: ServiceStateMachine = {
+        status: () => current,
+        start: () => run('start'),
+        stop: () => run('stop'),
+        refresh
+    }
+    await machine.refresh()
+    return machine
+}
+
+// Derived from the client-facing contract rather than restated beside it: a
+// method added there has to be defined here before this compiles.
+export type ServiceStateMethodDefs = { [K in keyof ServiceStateMethods]: MethodDef<void, ReturnType<ServiceStateMethods[K]>> }
+
+// The four methods, ready to merge into a dispatch table. Admin-only by
+// default: turning a service off is not a read.
+export const serviceStateMethods = (machine: ServiceStateMachine, auth: AuthRequirement = 'admin'): ServiceStateMethodDefs => ({
+    'service.status': { auth, handler: () => machine.status() },
+    'service.start': { auth, handler: () => machine.start() },
+    'service.stop': { auth, handler: () => machine.stop() },
+    'service.refresh': { auth, handler: () => machine.refresh() }
+})
+
+export { SERVICE_STATE_EVENT, SERVICE_STATES, TRANSITIONS } from './main'
+export type { ServiceCommand, ServiceState, ServiceStateMethods, ServiceStatePushes, ServiceStatus } from './main'