@khalido/home 0.1.2 → 0.2.0

package/src/home.ts

@@ -9,15 +9,18 @@ export const envName = z
     /^[A-Z_][A-Z0-9_]*$/,
     "an environment variable name (e.g. AMBER_KEY), not the secret itself",
   );
-/** A file a connector needs (a CA, a token), relative to the config file. The caller reads it; the library reads no files. */
+/** A file a connector needs (a CA, a token), relative to the config file or from `~/`. The caller reads it, and expands `~/`; the library reads no files. */
 export const filePath = z.string().min(1);
 
 /** How an integration is doing. "unavailable" means it stopped and will not retry by itself. */
 export type Status =
   "connecting" | "connected" | "disconnected" | "unavailable";
 
+/** Why a part is `unavailable`, for code to switch on; `detail` is the text for people. `auth`: a key or token was rejected or is unusable, so a person must re-key. `config`: a setting or a file is wrong. `crashed`: its `run` threw. */
+export type Reason = "auth" | "config" | "crashed";
+
 /**
- * One integration's slice of the home: its status, a human detail, anything odd the device reported, and its state.
+ * One integration's slice of the home: its status, a human detail, `reason` (why it is `unavailable`, for code to switch on), anything odd the device reported, and its state.
  * `createHome` stamps the times (UTC ISO). `lastGoodAt`: its last report while connected, or the read time a connected report
  * gives when it repeats an older read (weather's 5-minute sun tick). `downSince`: when it stopped being connected (or started,
  * if it never has); none while connected. Any other time an integration sets is ignored.
@@ -25,12 +28,68 @@ export type Status =
 export type Part<S = unknown> = {
   status: Status;
   detail?: string;
+  reason?: Reason;
   anomaly?: string;
   state?: S;
   lastGoodAt?: string;
   downSince?: string;
 };
 
+/**
+ * The few things every device answers, whatever it is, in the same words; a connector's `<name>HomeDevices(part)` returns
+ * these and `homeDevices(snapshot)` collects them. Everything particular to its kind is in `detail`, the connector's own
+ * typed row, and `connector` (with `kind`) says which type that is. Unknown stays absent, never guessed.
+ * - `id`: the device's own stable id (a Hue light id, a castId, a printer's UUID), or the connector's name when it has one device.
+ * - `kind`: light, group, speaker, display, tv, ac, printer, solar (and `cast` for a Cast model this library doesn't know).
+ * - `available`: it answered and can be used now. When it is false, `reason` says why in one word: `offline`, or the
+ *   connector's own reason for being `unavailable` (`auth`, `config`, `crashed`).
+ * - `asOf`: when the device last reported (a push connector) or was last read (a polled one). A quiet light can be hours
+ *   old and current: `available` says whether it is.
+ * - `state`: one short word in that kind's vocabulary: on, off, idle, busy, cool, printing.
+ * - `text`: one line for people, "Kitchen: on · 60%".
+ * - `room`: a room id from the home config, when one places it.
+ * - `members`: a group's device ids.
+ */
+export type DeviceRecord<
+  C extends string = string,
+  K extends string = string,
+  S extends string = string,
+  D = unknown,
+> = {
+  connector: C;
+  id: string;
+  name: string;
+  kind: K;
+  available?: boolean;
+  reason?: Reason | "offline";
+  asOf?: string;
+  state?: S;
+  text: string;
+  room?: string;
+  members?: string[];
+  detail: D;
+};
+
+/**
+ * A connector's device records from its part. While the connector isn't connected none is `available`, and each keeps its
+ * last values, as the part's state does. A device that isn't available gets its `reason`: the part's when it stopped for
+ * good, else `offline`.
+ */
+export const deviceRecords = <R extends DeviceRecord>(
+  part: Part | undefined,
+  records: R[],
+): R[] => {
+  const up = part?.status === "connected";
+  // A part that stopped for good without saying why is a custom integration's: `config` is the nearest true word, since it won't come back by itself.
+  const why =
+    part?.status === "unavailable" ? (part.reason ?? "config") : "offline";
+  return records.map((r) =>
+    up && r.available !== false
+      ? r
+      : { ...r, available: false, reason: up ? "offline" : why },
+  );
+};
+
 /**
  * An integration is a folder in `src/` that exports a factory returning this.
  * `run` keeps its state current until `signal` aborts, reporting each change through `update`.
@@ -81,7 +140,7 @@ function stamped(part: Part, before: Part | undefined, now: string): Part {
 
 /**
  * Load a home: run each integration, keep one snapshot, call `onChange` with it and what changed after every report.
- * `clock` stamps each part's `lastGoodAt` and `downSince`.
+ * `clock` stamps each part's `lastGoodAt` and `downSince`. `add` and `remove` change the set while it runs.
  */
 export function createHome<I extends Integration<any, string>>(
   integrations: readonly I[],
@@ -89,22 +148,80 @@ export function createHome<I extends Integration<any, string>>(
   options: { clock?: Clock } = {},
 ) {
   type Name = I["name"];
+  type Run = { stop: AbortController; done: Promise<void> };
   const clock = options.clock ?? realClock;
+  const list: I[] = [...integrations]; // the integrations now: `add` and `remove` change it
+  const parts = () => snapshot as Record<string, Part>;
   let snapshot = Object.fromEntries(
-    integrations.map((i) => [i.name, { status: "connecting" }]),
+    list.map((i) => [i.name, { status: "connecting" }]),
   ) as HomeSnapshot<I>;
   const waiting = new Map<string, (() => void)[]>(); // refresh() callers, resolved by the integration's next report
-  const finished = new Set<string>(); // integrations whose run has ended: a refresh of one resolves at once, nothing will report
-  const set = (name: Name, reported: Part) => {
-    const before = (snapshot as Record<string, Part>)[name]!;
+  const runs = new Map<I, Run>(); // the ones running: before start or after its run ended, a refresh resolves at once, nothing will report
+  const latest = new WeakMap<I, Run>(); // each integration's newest run: a report from an older run of the same object is dropped
+  let started: AbortSignal | undefined; // start()'s signal, while it runs
+  let changing: Promise<unknown> = Promise.resolve(); // add and remove, one at a time: two on one name must not overlap
+  let changes = 0; // those under way or queued: start outlasts a replace of its only integration
+  const change = <T>(fn: () => Promise<T>): Promise<T> => {
+    changes++;
+    const done = changing.then(fn).finally(() => changes--);
+    changing = done.catch(() => {});
+    return done;
+  };
+  const heard = (name: string) => {
+    for (const resolve of waiting.get(name) ?? []) resolve();
+    waiting.delete(name);
+  };
+  // A report counts only from the integration now listed under its name: one replaced or removed may still be finishing.
+  const set = (i: I, run: Run, reported: Part) => {
+    const name: Name = i.name;
+    const before = parts()[name];
+    if (latest.get(i) !== run || !list.includes(i) || !before) return;
     const part = stamped(reported, before, asOf(clock));
     snapshot = { ...snapshot, [name]: part };
-    onChange?.(snapshot, { name, before, after: part } as Change<I>);
-    const w = waiting.get(name);
-    if (w) {
-      waiting.delete(name);
-      for (const resolve of w) resolve();
-    }
+    Promise.try(() =>
+      onChange?.(snapshot, { name, before, after: part } as Change<I>),
+    ).catch((error) =>
+      console.error(`onChange threw on ${name}: ${errorText(error)}`),
+    ); // the caller's bug, thrown or async, not the device's: the integration keeps running
+    heard(name);
+  };
+  /** Run one integration until the home's signal or its own `stop` aborts. One failing marks itself unavailable. */
+  const launch = (i: I, signal: AbortSignal) => {
+    const stop = new AbortController();
+    const run: Run = { stop, done: Promise.resolve() };
+    runs.set(i, run);
+    latest.set(i, run);
+    run.done = Promise.try(() =>
+      i.run(AbortSignal.any([signal, stop.signal]), (part) =>
+        set(i, run, part),
+      ),
+    )
+      .catch((error) =>
+        set(i, run, {
+          status: "unavailable",
+          reason: "crashed",
+          detail: errorText(error),
+          state: parts()[i.name]?.state, // the last good state stays, as it does through a failed read
+        }),
+      )
+      .finally(() => {
+        if (runs.get(i) !== run) return;
+        runs.delete(i);
+        if (list.includes(i)) heard(i.name); // nothing more will report
+      });
+  };
+  /** Take one out of the list and the snapshot, and wait for its run to end. */
+  const drop = async (name: string) => {
+    const at = list.findIndex((i) => i.name === name);
+    if (at < 0) return false;
+    const [old] = list.splice(at, 1);
+    const { [name]: _, ...rest } = parts();
+    snapshot = rest as HomeSnapshot<I>;
+    heard(name);
+    const run = runs.get(old!);
+    run?.stop.abort();
+    await run?.done;
+    return true;
   };
   return {
     /** The latest snapshot. Never touches a device. */
@@ -115,57 +232,67 @@ export function createHome<I extends Integration<any, string>>(
     integration: <N extends Name>(
       name: N,
     ): Extract<I, { name: N }> | undefined =>
-      integrations.find((i) => i.name === name) as
-        Extract<I, { name: N }> | undefined,
+      list.find((i) => i.name === name) as Extract<I, { name: N }> | undefined,
     /**
      * Read now: one integration by name, or every one. Results arrive through the snapshot and `onChange` as usual; the
-     * promise resolves once each target has reported (its next update, good or bad), or at once for one whose run has ended.
+     * promise resolves once each target has reported (its next update, good or bad), or at once for one that isn't running.
      */
     refresh(name?: Name): Promise<void> {
       const targets =
-        name === undefined
-          ? integrations
-          : integrations.filter((i) => i.name === name);
-      if (!targets.length)
+        name === undefined ? [...list] : list.filter((i) => i.name === name);
+      if (!targets.length && name !== undefined)
         throw new Error(
-          `no integration "${name}"; have ${integrations.map((i) => i.name).join(", ")}`,
+          `no integration "${name}"; have ${list.map((i) => i.name).join(", ")}`,
         );
       const reported = targets.map(
         (i) =>
           new Promise<void>((resolve) => {
-            if (finished.has(i.name)) return resolve();
+            if (!runs.has(i)) return resolve();
             waiting.set(i.name, [...(waiting.get(i.name) ?? []), resolve]);
           }),
       );
       for (const i of targets) i.refresh();
       return Promise.all(reported).then(() => undefined);
     },
-    /** Run every integration until `signal` aborts. One failing marks itself unavailable; the rest carry on. */
+    /**
+     * Add an integration while the home runs, or before it starts: a bridge paired just now, a key that arrived late. One
+     * already there under that name is stopped first and its part dropped, so the new one starts from `connecting` and
+     * the two never run together. Resolves once the new one is running; its reports arrive as any other's. Calls on
+     * one home run one at a time. Once `start`'s signal has aborted, an added one waits for the next `start`.
+     */
+    add: (integration: I): Promise<void> =>
+      change(async () => {
+        await drop(integration.name);
+        list.push(integration);
+        const live = started && !started.aborted ? started : undefined;
+        snapshot = {
+          ...snapshot,
+          [integration.name]: {
+            status: "connecting",
+            ...(live ? { downSince: asOf(clock) } : {}),
+          },
+        };
+        if (live) launch(integration, live);
+      }),
+    /** Stop one integration and drop its part from the snapshot. Resolves once its run has ended; false if there was none by that name. */
+    remove: (name: Name): Promise<boolean> => change(() => drop(name)),
+    /** Run every integration, and any added meanwhile, until `signal` aborts. One failing marks itself unavailable; the rest carry on. */
     async start(signal: AbortSignal): Promise<void> {
-      finished.clear(); // a second start, after the first has stopped, runs them all again
+      started = signal;
       const now = asOf(clock); // the wait for a first report counts from here, not from createHome
       snapshot = Object.fromEntries(
-        Object.entries(snapshot as Record<string, Part>).map(([name, p]) => [
+        Object.entries(parts()).map(([name, p]) => [
           name,
           p.status === "connecting"
             ? { ...p, downSince: p.downSince ?? now }
             : p,
         ]),
       ) as HomeSnapshot<I>;
-      await Promise.all(
-        integrations.map((i) =>
-          i
-            .run(signal, (part) => set(i.name, part))
-            .catch((error) =>
-              set(i.name, { status: "unavailable", detail: errorText(error) }),
-            )
-            .finally(() => {
-              finished.add(i.name);
-              for (const resolve of waiting.get(i.name) ?? []) resolve(); // nothing more will report
-              waiting.delete(i.name);
-            }),
-        ),
-      );
+      for (const i of list) launch(i, signal); // a second start, after the first has stopped, runs them all again
+      // Until every run has ended, those added meanwhile too.
+      while (runs.size || changes)
+        await Promise.all([...[...runs.values()].map((r) => r.done), changing]);
+      // `started` stays: one added after every run has ended still runs, until the signal aborts.
     },
   };
 }

package/src/index.ts

@@ -3,12 +3,15 @@
 export {
   type Change,
   createHome,
+  type DeviceRecord,
+  deviceRecords,
   envName,
   filePath,
   settle,
   type HomeSnapshot,
   type Integration,
   type Part,
+  type Reason,
   type StateOf,
   type Status,
 } from "./home.ts";
@@ -19,8 +22,15 @@ export {
   PUSH_DOWN_MS,
   STALE_POLLS,
 } from "./health.ts";
+export {
+  byRoom,
+  type HomeDevice,
+  homeDevices,
+  type RoomDevices,
+  spotifyElsewhere,
+} from "./devices.ts";
 export { asOf, type Clock, realClock } from "./clock.ts";
-export { ConnectorError } from "./connector.ts";
+export { type ConnectorCode, ConnectorError } from "./connector.ts";
 export {
   bestWindow,
   type EnergyNow,

package/src/node-fetch.ts

@@ -1,5 +1,6 @@
 import { Agent, fetch as undiciFetch } from "undici";
 import type { LoadOptions } from "./config.ts";
+import { HUE_BRIDGE_ROOT_CA } from "./connectors/hue/ca.ts";
 
 // `@khalido/home/node`: the fetches Hue and Enphase need under Node, where Bun's `tls` fetch option does not exist. Node's
 // global `fetch` takes no CA, so these use undici's own `fetch` and `Agent` (one undici on both sides). Outside the
@@ -13,8 +14,11 @@ const through = (dispatcher: Agent) =>
       { ...init, dispatcher } as never,
     )) as unknown as typeof fetch;
 
-/** A `fetch` that trusts only `ca` and accepts only a certificate whose CN is `bridgeId`: Node's `bunPinnedFetch`. */
-export function nodePinnedFetch(bridgeId: string, ca: string): typeof fetch {
+/** A `fetch` that trusts only `ca` (Signify's roots when left out) and accepts only a certificate whose CN is `bridgeId`: Node's `bunPinnedFetch`. */
+export function nodePinnedFetch(
+  bridgeId: string,
+  ca: string = HUE_BRIDGE_ROOT_CA,
+): typeof fetch {
   const checkServerIdentity = (
     _host: string,
     cert: { subject?: { CN?: string | string[] } },