q792602257andClaude Opus 4.6
989fdbf878
Tests / Test passed: 794
Sync delta specs into main specs before archiving: modified cloud-control-plane, device-pool, and host-agent-protocol; created new edge-host-enrollment capability spec. openspec validate --specs reports 18/18 passing. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
97 lines
6.5 KiB
Markdown
97 lines
6.5 KiB
Markdown
# cloud-control-plane Specification
|
|
|
|
## Purpose
|
|
Provide a runnable, authenticated Cloud Control Plane with durable scheduling,
|
|
lease maintenance, health reporting, and restart recovery.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: Runnable Cloud Control Plane application
|
|
The system SHALL provide an independently runnable Cloud Control Plane application that composes the cloud repository, device pool, task scheduler, plugin registry, authentication providers, public platform router, internal Host Agent router, and lifecycle services without modifying the local Runtime API application.
|
|
|
|
#### Scenario: Start the cloud application
|
|
- **WHEN** an operator starts the Cloud Control Plane with valid configuration and an available database
|
|
- **THEN** the application exposes its versioned public, internal, and health routes and starts its configured lifecycle workers
|
|
|
|
#### Scenario: Local Runtime remains separately runnable
|
|
- **WHEN** an operator starts the existing local Runtime API without the cloud application
|
|
- **THEN** local Runtime routes operate without initializing cloud persistence, scheduling, or Host Agent services
|
|
|
|
### Requirement: Scheduler and lease maintenance run through application lifecycle
|
|
The Cloud Control Plane SHALL run configurable scheduler and expired-lease maintenance loops after application startup and SHALL stop them cleanly during shutdown.
|
|
|
|
#### Scenario: Queued work becomes assigned
|
|
- **WHEN** a queued task has an eligible device and the scheduler loop runs
|
|
- **THEN** the task receives an atomic assignment and becomes available to the owning Host Agent
|
|
|
|
#### Scenario: Lifecycle iteration fails transiently
|
|
- **WHEN** one scheduler or lease-maintenance iteration raises an operational error
|
|
- **THEN** the error is recorded and subsequent configured iterations continue rather than permanently terminating the worker
|
|
|
|
#### Scenario: Application shuts down
|
|
- **WHEN** the Cloud Control Plane receives a graceful shutdown signal
|
|
- **THEN** its lifecycle workers stop accepting new iterations and terminate without abandoning an in-process database transaction
|
|
|
|
### Requirement: Deployment and local persistence modes share one contract
|
|
The cloud repository SHALL support PostgreSQL for deployed operation and SQLite for local development and tests through the same behavioral contract, including hosts, dynamic Host credential bindings, device enrollments, pooled devices, tasks, leases, attempts, and plugins.
|
|
|
|
#### Scenario: Start with PostgreSQL
|
|
- **WHEN** the configured database URL selects PostgreSQL and the schema is current
|
|
- **THEN** the control plane uses PostgreSQL for cloud state, enrollment idempotency, authentication lookup, and transactional assignment operations
|
|
|
|
#### Scenario: Start in local SQLite mode
|
|
- **WHEN** the configured database URL selects SQLite in a local or test environment
|
|
- **THEN** the same repository contract, including Host and device enrollment, is available with the documented single-control-plane concurrency limitation
|
|
|
|
### Requirement: Cloud schema is versioned with migrations
|
|
The system SHALL provide versioned forward and downgrade database migrations and SHALL refuse readiness when the database schema is incompatible with the running application.
|
|
|
|
#### Scenario: Upgrade an existing cloud database
|
|
- **WHEN** an operator applies the enrollment release migration to a database at revision 0001
|
|
- **THEN** existing hosts, pooled devices, tasks, attempts, and plugins are retained while nullable Host enrollment fields and durable device enrollment storage are added
|
|
|
|
#### Scenario: Downgrade the enrollment schema
|
|
- **WHEN** an operator downgrades revision 0002 while no enrollment-capable application process is connected
|
|
- **THEN** dynamic Host credential and device enrollment storage is removed while legacy cloud state from revision 0001 remains available
|
|
|
|
#### Scenario: Schema is behind at startup
|
|
- **WHEN** the application connects to a database whose schema version is not accepted by the running release
|
|
- **THEN** readiness fails with a diagnostic that does not expose credentials
|
|
|
|
### Requirement: Restart recovery preserves durable work
|
|
The Cloud Control Plane SHALL recover persisted queued tasks and SHALL requeue or fail expired assigned/dispatched attempts according to retry policy after process restart.
|
|
|
|
#### Scenario: Restart with queued tasks
|
|
- **WHEN** the control plane restarts while tasks are queued
|
|
- **THEN** those tasks remain queued and are considered by later scheduler iterations
|
|
|
|
#### Scenario: Restart after a lease expires
|
|
- **WHEN** the control plane restarts and finds an assigned or dispatched task with an expired lease
|
|
- **THEN** lease maintenance requeues it when attempts remain or marks it failed when the retry limit is exhausted
|
|
|
|
### Requirement: Liveness, readiness, and safe operational logging
|
|
The application SHALL expose separate liveness and readiness endpoints and SHALL emit structured lifecycle logs with correlation identifiers while excluding credentials and sensitive device payloads.
|
|
|
|
#### Scenario: Database is unavailable
|
|
- **WHEN** the process is running but cannot reach its configured database
|
|
- **THEN** liveness succeeds and readiness fails
|
|
|
|
#### Scenario: Task lifecycle is logged
|
|
- **WHEN** a task is assigned, claimed, renewed, completed, retried, or failed
|
|
- **THEN** the log event includes available task, host, device, attempt, lease, and correlation identifiers but excludes bearer tokens, screenshots, UI trees, and typed text
|
|
|
|
### Requirement: Dynamic Host authentication uses durable credential digests
|
|
The Cloud Control Plane SHALL authenticate dynamically enrolled Host bearer credentials through indexed repository lookup of a cryptographic token digest and SHALL compose that lookup with existing configured credentials.
|
|
|
|
#### Scenario: Enrolled Host authenticates after Cloud API restart
|
|
- **WHEN** a non-revoked enrolled Host presents its bearer credential after the Cloud API restarts
|
|
- **THEN** the repository-backed authentication provider resolves the stored Host binding and authorizes only Host-scoped internal operations
|
|
|
|
#### Scenario: Dynamic Host credential calls a public route
|
|
- **WHEN** a dynamically enrolled Host credential is presented to a public SDK operation requiring a scope
|
|
- **THEN** the request is rejected for missing scope rather than inheriting public operator privileges
|
|
|
|
#### Scenario: Static credential deployment remains active
|
|
- **WHEN** an operator continues to configure a Host-bound credential through the existing environment configuration
|
|
- **THEN** that Host can use the existing operational protocol without performing bootstrap enrollment
|