55 lines
3.6 KiB
Markdown
55 lines
3.6 KiB
Markdown
## MODIFIED Requirements
|
|
|
|
### Requirement: Task submission and status via the SDK
|
|
The system SHALL allow an external integrator to submit a task (goal or workflow reference plus constraints) through the platform SDK's API, to query that task's current status by id, and to request cancellation of that task by id, backed by the `task-scheduler` capability.
|
|
|
|
#### Scenario: Submit a task via the API
|
|
- **WHEN** an integrator calls the task-submission endpoint with a valid goal and optional constraints
|
|
- **THEN** the API returns a task id that can be used to poll status, and the underlying `task-scheduler` records a new `queued` `ScheduledTask`
|
|
|
|
#### Scenario: Query status of a known task
|
|
- **WHEN** an integrator requests status for a task id that exists
|
|
- **THEN** the API returns that task's current status (`queued`, `assigned`, `dispatched`, `done`, `failed`, or `cancelled`)
|
|
|
|
#### Scenario: Query status of an unknown task
|
|
- **WHEN** an integrator requests status for a task id that does not exist
|
|
- **THEN** the API returns a not-found response rather than an unhandled server error
|
|
|
|
#### Scenario: Cancel a known task via the API
|
|
- **WHEN** an integrator with the required scope calls the cancel endpoint for a task id that exists and is not already `done` or `failed`
|
|
- **THEN** the API accepts the request and the underlying `task-scheduler` records the cancellation per its immediate or collaborative rules for that task's current status
|
|
|
|
#### Scenario: Cancel an unknown task
|
|
- **WHEN** an integrator calls the cancel endpoint for a task id that does not exist
|
|
- **THEN** the API returns a not-found response rather than an unhandled server error
|
|
|
|
### Requirement: Public API operations enforce scopes
|
|
The public platform API SHALL require operation-specific scopes, including task submission, task cancellation, task reading, pool reading, plugin reading, and plugin administration.
|
|
|
|
#### Scenario: Submit token has task scope
|
|
- **WHEN** a principal with `tasks:submit` calls the task-submission endpoint
|
|
- **THEN** the request is authorized subject to normal task validation
|
|
|
|
#### Scenario: Submit-scoped token cancels a task
|
|
- **WHEN** a principal with `tasks:submit` calls the task-cancellation endpoint for any task id
|
|
- **THEN** the request is authorized; the platform SDK does not restrict cancellation to the task's original submitter, since no per-task submitter identity is tracked
|
|
|
|
#### Scenario: Read-only token attempts cancellation
|
|
- **WHEN** a principal that holds only `tasks:read` calls the task-cancellation endpoint
|
|
- **THEN** the API rejects the request before contacting the scheduler
|
|
|
|
#### Scenario: Non-admin token attempts plugin registration
|
|
- **WHEN** an authenticated principal without `plugins:admin` calls plugin registration
|
|
- **THEN** the API rejects the request before resolving or loading the plugin target
|
|
|
|
### Requirement: Python SDK client mirrors the REST API
|
|
The system SHALL provide a Python client (`CloudClient`) exposing methods corresponding to each `/v1/...` route (submit task, get task status, cancel task, list devices, list hosts, list plugins, register plugin), so integrators do not need to hand-construct HTTP requests.
|
|
|
|
#### Scenario: Client submits a task and retrieves status
|
|
- **WHEN** a caller uses `CloudClient` to submit a task and then fetch its status by the returned id
|
|
- **THEN** the client's methods produce the same result as calling the corresponding `/v1/...` endpoints directly over HTTP
|
|
|
|
#### Scenario: Client cancels a task
|
|
- **WHEN** a caller uses `CloudClient` to cancel a task by id
|
|
- **THEN** the client's method produces the same result as calling the cancel endpoint directly over HTTP
|