spec

2026-07-06 23:52:53 +08:00
parent d899b875ce
commit 8e29fcf3c2
54 changed files with 736 additions and 0 deletions
@@ -0,0 +1,49 @@
+# device-pool Specification
+
+## Purpose
+TBD - created by archiving change cloud-runtime. Update Purpose after archive.
+## Requirements
+### Requirement: Host registration and heartbeat sync
+The system SHALL provide a `DevicePool` that tracks a `HostRegistration` (host id, address, last-seen timestamp) for each host process that registers itself, and SHALL update a host's last-seen timestamp whenever that host pushes a device snapshot via `sync_host_devices(host_id, snapshot)`.
+
+#### Scenario: New host registers and syncs devices
+- **WHEN** a previously-unknown `host_id` calls `sync_host_devices` with a list of devices
+- **THEN** the pool creates a new `HostRegistration` for that host, records the current time as its last-seen timestamp, and stores each synced device as a `PooledDevice` owned by that host
+
+#### Scenario: Known host re-syncs
+- **WHEN** an already-registered `host_id` calls `sync_host_devices` again with an updated device snapshot
+- **THEN** the pool updates that host's last-seen timestamp and replaces its previously-stored `PooledDevice` records with the new snapshot, without duplicating or losing devices from other hosts
+
+### Requirement: Aggregated device listing across hosts
+The system SHALL provide a way to list all `PooledDevice` records across every registered host, including each device's owning `host_id`, `driver_type`, status, and capability tags.
+
+#### Scenario: Listing devices across multiple hosts
+- **WHEN** two hosts have each synced a non-empty device snapshot
+- **THEN** a caller listing pool devices sees devices from both hosts in one combined result, each tagged with its correct `host_id`
+
+#### Scenario: No hosts registered
+- **WHEN** a caller lists pool devices before any host has ever synced
+- **THEN** the pool returns an empty list rather than raising an error
+
+### Requirement: Stale host devices degrade to unreachable
+The system SHALL mark all `PooledDevice`s belonging to a host `unreachable` once that host's last-seen timestamp exceeds a configured staleness threshold, computed at read time, without requiring any background process and without raising an error for the stale host's absence.
+
+#### Scenario: Host misses its sync interval
+- **WHEN** a host's last-seen timestamp is older than `config.stale_after_seconds` at the time of a `list_devices()`/`get_device()` call
+- **THEN** every `PooledDevice` owned by that host is reported with status `unreachable`, regardless of the status value in its last-synced snapshot
+
+#### Scenario: Host resumes syncing after being stale
+- **WHEN** a host previously marked stale calls `sync_host_devices` again
+- **THEN** its devices immediately stop being reported `unreachable` and reflect the statuses in the new snapshot
+
+### Requirement: Device lookup by id across the pool
+The system SHALL allow looking up a single `PooledDevice` by `device_id` regardless of which host owns it, returning a clear not-found result when no host has ever reported that device id.
+
+#### Scenario: Lookup finds device on any host
+- **WHEN** a caller requests a device by id that exists in some host's synced snapshot
+- **THEN** the pool returns that `PooledDevice` including its owning `host_id`
+
+#### Scenario: Lookup for unknown device id
+- **WHEN** a caller requests a device by id that no host has ever synced
+- **THEN** the pool returns a not-found result (e.g. `None`) rather than raising an unhandled exception
+