related: #298
- Added PauseActionWorkspaceHandler to handle pausing or unpausing a given workspace
- Introduced single new route for starting and pausing workspaces in the API.
- `api/v1/workspaces/{namespace}/{name}/actions/pause`
- pausing or unpausing operation is specified in the request payload
- Created a new WorkspaceActionPauseEnvelope type for successful responses.
- Leveraging JSONPatch / client.RawPatch to ensure Workspace in "valid state" before attempting action
- for `start`: `spec.paused` must be `true`, and `status.state` must be `Paused`
- for `pause`: `spec.paused` must be `false`
- note: I would love to have a `status.state` check here of `status.state != Paused`, but that type of comparison is not supported in [JSONPatch](https://datatracker.ietf.org/doc/html/rfc6902#section-4.6)
- Added tests for the new API, including success and error cases.
- Updated README/OpenAPI documentation to include the new endpoints.
---
As an interesting "edge case" worth calling out, the following payload is currently honored by the API:
```
{
"data": {}
}
```
Given the `WorkspaceActionPause` struct is simply `{"paused": true|false}`, the "empty" Envelope presented above deserializes the JSON using the zero value of `bool` (which is `false`).
Our validation today is always performed against the **deserialized** object, and as such impossible to distinguish the following cases:
```
{
"data": {}
}
```
vs
```
{
"data": {
"paused": false
}
}
```
The effort and (relative) complexity to prevent this and return a `422` in this scenario was not deemed "worth it" for the time being. As a result, a test case has been added for this specific scenario to at minimum document this "strange" behavior.
- Clients, however, should **NOT** rely on this behavior and always provide a fully defined `WorkspaceActionPause` JSON object to ensure future compatibility.
Signed-off-by: Andy Stoneberg <astonebe@redhat.com>
843e5c3c48