4.9 KiB
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, 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 all cloud state 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 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 release's migrations to a supported previous schema
- THEN existing hosts, devices, tasks, and plugins are retained and the new lease fields become 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