@greendrake/service-state 0.2.0 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # @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.
+Backend services an operator can turn on and off, each a state machine both halves of a dashboard share, any number of them over one socket. 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
@@ -24,37 +24,37 @@ The `./server` entry needs `@greendrake/rpc-server`, which is an optional peer d
 import { SERVICE_STATE_EVENT, type ServiceStateMethods, type ServiceStatePushes, type ServiceStatus } from '@greendrake/service-state'
 
 interface ServiceStatus {
+    service: string // which service this is the status of
     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.
+`ServiceStateMethods` is the four methods (`service.status`, `service.start`, `service.stop`, `service.refresh`), each taking a `ServiceRef` — `{ service }`, the name of the service it is about — and answering its `ServiceStatus`; hand it to a typed client. `ServiceStatePushes` types the `service.state` event, which carries a status to **every** connected socket: a service has one state, and everyone watching it is watching the same thing. The status names its service, so a socket watching several tells their pushes apart by it.
 
 ## 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 unit = (name: string) => ({
+    start: () => systemd.start(name),
+    stop: () => systemd.stop(name),
+    check: () => systemd.isActive(name).then(on => (on ? 'ON' : 'OFF'))
+})
+
+// Each machine is named for the wire; the registry — any EventSink, and
+// @greendrake/rpc-server's ConnRegistry is one — is where its pushes go.
+const machines = await Promise.all([createServiceStateMachine('web', unit('web.service'), registry), createServiceStateMachine('worker', unit('worker.service'), registry)])
 
-const methods = { ...serviceStateMethods(machine), ...whateverElse }
+const methods = { ...serviceStateMethods(machines), ...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.
+The name is what a call's `{ service }` reaches the machine by and what its every status carries. 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.
+`serviceStateMethods(machines, auth = 'admin')` returns the four `MethodDef`s over every machine given, so one dispatch table — and one socket — serves them all. A call's argument is checked for its shape before any machine is reached (`INVALID_ARGUMENT` on `service`); one naming a service the table does not serve is refused with `SERVICE_NOT_FOUND` — a `_NOT_FOUND` code, which clients following `@greendrake/rpc-server`'s convention treat as not found. Two machines under one name are refused as the table is built. Admin-only by default: turning a service off is not a read.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@greendrake/service-state",
-    "version": "0.2.0",
+    "version": "0.4.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>",
@@ -38,7 +38,7 @@
     },
     "prettier": "@greendrake/dev-config/prettier",
     "peerDependencies": {
-        "@greendrake/rpc-server": "0.2.0"
+        "@greendrake/rpc-server": "0.4.0"
     },
     "peerDependenciesMeta": {
         "@greendrake/rpc-server": {
@@ -46,8 +46,8 @@
         }
     },
     "devDependencies": {
-        "@greendrake/dev-config": "0.2.0",
-        "@greendrake/rpc-server": "0.2.0",
+        "@greendrake/dev-config": "0.4.0",
+        "@greendrake/rpc-server": "0.4.0",
         "@types/bun": "^1.3.5",
         "typescript": "6.0.3"
     }

package/src/main.ts

@@ -7,8 +7,17 @@ export const SERVICE_STATES = ['OFF', 'STARTING', 'ON', 'STOPPING', 'ERROR'] as
 
 export type ServiceState = (typeof SERVICE_STATES)[number]
 
+// Which service a call is about. Every method takes it, so one socket serves
+// any number of services side by side.
+export interface ServiceRef {
+    service: string
+}
+
 // Wire shape: snake_case, as the envelope's own fields are.
 export interface ServiceStatus {
+    // The service this is the status of — what a push is told apart by, since
+    // every service's pushes arrive on the same socket.
+    service: string
     state: ServiceState
     // What went wrong, in ERROR. Null in every other state — a stale message
     // outliving the failure it describes is worse than none.
@@ -39,14 +48,15 @@ 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.
+// typed client; the server derives its definitions from it.
 export interface ServiceStateMethods {
-    'service.status': () => ServiceStatus
-    'service.start': () => ServiceStatus
-    'service.stop': () => ServiceStatus
-    'service.refresh': () => ServiceStatus
+    'service.status': (ref: ServiceRef) => ServiceStatus
+    'service.start': (ref: ServiceRef) => ServiceStatus
+    'service.stop': (ref: ServiceRef) => ServiceStatus
+    'service.refresh': (ref: ServiceRef) => ServiceStatus
 }
 
 // Every state change reaches every connected socket: a service has one state,
-// and everyone watching it is watching the same thing.
+// and everyone watching it is watching the same thing. The status names its
+// service, so a socket watching several follows each by its name.
 export type ServiceStatePushes = { [SERVICE_STATE_EVENT]: ServiceStatus }

package/src/server.ts

@@ -1,7 +1,7 @@
 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'
+import type { ServiceCommand, ServiceRef, 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
@@ -14,6 +14,9 @@ export interface ServiceImplementation {
 }
 
 export interface ServiceStateMachine {
+    // What the service is called on the wire: what a call names to reach it,
+    // and what each of its pushes carries.
+    readonly name: string
     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
@@ -31,12 +34,17 @@ export interface ServiceStateMachine {
 // what a client that ignored the state gets told.
 const BUSY = 'SERVICE_BUSY'
 
+// A call naming a service the table does not serve. A `_NOT_FOUND` code, so
+// clients following rpc-server's convention treat it as not found.
+const NOT_FOUND = 'SERVICE_NOT_FOUND'
+
 // 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> => {
+export const createServiceStateMachine = async (name: string, service: ServiceImplementation, sink: EventSink): Promise<ServiceStateMachine> => {
     let current: ServiceStatus = {
+        service: name,
         state: 'OFF',
         error: null,
         changed_at: Date.now()
@@ -45,6 +53,7 @@ export const createServiceStateMachine = async (service: ServiceImplementation,
 
     const set = (state: ServiceState, error: string | null): ServiceStatus => {
         current = {
+            service: name,
             state,
             error,
             changed_at: Date.now()
@@ -90,6 +99,7 @@ export const createServiceStateMachine = async (service: ServiceImplementation,
     }
 
     const machine: ServiceStateMachine = {
+        name,
         status: () => current,
         start: () => run('start'),
         stop: () => run('stop'),
@@ -101,16 +111,48 @@ export const createServiceStateMachine = async (service: ServiceImplementation,
 
 // 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]>> }
+export type ServiceStateMethodDefs = { [K in keyof ServiceStateMethods]: MethodDef<Parameters<ServiceStateMethods[K]>[0], ReturnType<ServiceStateMethods[K]>> }
+
+// The argument every method takes, checked for its shape. Whether it names a
+// service the table serves is the table's to say, as SERVICE_NOT_FOUND. Written
+// against Standard Schema directly, so this package carries no validator.
+const SERVICE_REF: NonNullable<MethodDef<ServiceRef>['args']> = {
+    '~standard': {
+        version: 1,
+        vendor: 'greendrake',
+        validate: value => (typeof value === 'object' && value !== null && 'service' in value && typeof value.service === 'string' ? { value: { service: value.service } } : { issues: [{ message: 'Expected the name of a service', path: ['service'] }] })
+    }
+}
 
-// 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() }
-})
+// The four methods over every machine given, ready to merge into a dispatch
+// table: one socket serves them all, each call naming its service. Admin-only
+// by default: turning a service off is not a read.
+export const serviceStateMethods = (machines: readonly ServiceStateMachine[], auth: AuthRequirement = 'admin'): ServiceStateMethodDefs => {
+    const byName = new Map(machines.map(machine => [machine.name, machine]))
+    if (byName.size !== machines.length) {
+        throw new Error(`serviceStateMethods: two machines share a name among ${machines.map(machine => machine.name).join(', ')}`)
+    }
+    // Each method is the same three steps — the argument checked, the service
+    // it names found, one thing asked of that service's machine — and differs
+    // only in what is asked.
+    const asking = (ask: (machine: ServiceStateMachine) => ServiceStatus | Promise<ServiceStatus>): MethodDef<ServiceRef, ServiceStatus> => ({
+        auth,
+        args: SERVICE_REF,
+        handler: (_ctx, { service }) => {
+            const machine = byName.get(service)
+            if (!machine) {
+                throw new ApiError(NOT_FOUND)
+            }
+            return ask(machine)
+        }
+    })
+    return {
+        'service.status': asking(machine => machine.status()),
+        'service.start': asking(machine => machine.start()),
+        'service.stop': asking(machine => machine.stop()),
+        'service.refresh': asking(machine => machine.refresh())
+    }
+}
 
 export { SERVICE_STATE_EVENT, SERVICE_STATES, TRANSITIONS } from './main'
-export type { ServiceCommand, ServiceState, ServiceStateMethods, ServiceStatePushes, ServiceStatus } from './main'
+export type { ServiceCommand, ServiceRef, ServiceState, ServiceStateMethods, ServiceStatePushes, ServiceStatus } from './main'