COBRA-4159: Akkeris Actions

docs/API-Reference.md

@@ -1,12 +1,13 @@
 # Overview
 
-The Platform Apps API empowers developers to build, extend, and combine Akkeris functionality with other services, tooling, and systems. 
+The Platform Apps API empowers developers to build, extend, and combine Akkeris functionality with other services, tooling, and systems.
 
 You can use this API to programmatically create apps, provision add-ons, promote pipelines, and perform any other tasks you can complete with the CLI or UI. In fact, both the CLI and UI use this API for all of their interactions, commands, and operations.
 
 ## Table of Contents
 
 - [Authentication](Authentication.md)
+- [Actions](Actions.md)
 - [Apps](Apps.md)
 - [App Setups](App-Setups.md)
 - [Formations](Formations.md)

docs/Actions.md

@@ -0,0 +1,251 @@
+## Actions
+
+Actions allow a user to run a script or other arbitrary code once and then exit. More specifically, an Action is created on an app to run its Docker image on a one-off basis. An action can be triggered manually or triggered automatically by an event.
+
+### Create an Action
+
+`POST /apps/{appname}/actions`
+
+Create a new action on an app.
+
+| Name | Type | Description | Example |
+|---|---|---|---|
+| name | required string | The name of the action. | testsuite |
+| description | string | A description of the action. | End-to-end automated tests |
+| size | string | The dyno size to use for the action | gp1 |
+| command | string | The command to run inside the action container | ./start.sh |
+| options | object | Override certain app configuration (see below) | {} |
+| options.image | string | Run a different image than the one configured for the application | "hello-world:latest" |
+| options.env | object | Add (or override) environment variables | { "foo": "bar", "merp": "derp" }
+
+**CURL Example**
+
+```bash
+curl \
+  -H 'Authorization: ...' \
+  -X POST \
+  https://apps.akkeris.io/apps/app-space/actions
+  -d '{ "name": "testsuite", "descripiton": "End-to-end automated tests", "size": "gp1", "command": "./start.sh", "options": { "image": "domain.io/project/image:tag-1", "env": { "foo": "bar" } } }'
+```
+
+**201 "Created" Response**
+
+```json
+{
+  "action": "5be7fc31-ac79-48df-b58d-4ce2d292ee91",
+  "app": "d5f42929-cddb-48be-8fd7-77d41d8c79be",
+  "formation": "5a4cde36-e290-45b8-a9b9-9579bdfd7a0d",
+  "name": "testsuite",
+  "description": "End-to-end automated tests",
+  "created_by": "Calaway",
+  "created": "2021-03-12T03:52:42.769Z",
+  "updated": "2021-03-12T03:52:42.769Z",
+  "deleted": false
+}
+```
+
+### List Actions
+
+`GET /apps/{appname}/actions`
+
+**CURL Example**
+
+```bash
+curl \
+  -H 'Authorization: ...' \
+  -X GET \
+  https://apps.akkeris.io/apps/app-space/actions
+```
+
+**200 "OK" Response**
+
+```json
+[
+  {
+    "action": "5be7fc31-ac79-48df-b58d-4ce2d292ee91",
+    "app": "d5f42929-cddb-48be-8fd7-77d41d8c79be",
+    "name": "testsuite",
+    "description": "End-to-end automated tests",
+    "created_by": "Calaway",
+    "created": "2021-03-12T03:52:42.769Z",
+    "updated": "2021-03-12T03:52:42.769Z",
+    "deleted": false,
+    "formation": {
+      "id": "1aa5558e-4216-46bb-a15e-627a6fe62c22",
+      "type": "actionstestsuite",
+      "size": "gp1",
+      "command": "./start.sh",
+      "options": {
+        "image": "domain.io/project/image:tag-1",
+        "env": {
+          "foo": "bar"
+        }
+      }
+    }
+  }
+]
+```
+
+### Get Action Info
+
+`GET /apps/{appname}/actions/{action_name}`
+
+**CURL Example**
+
+```bash
+curl \
+  -H 'Authorization: ...' \
+  -X GET \
+  https://apps.akkeris.io/apps/app-space/actions/testsuite
+```
+
+**200 "OK" Response**
+
+```json
+{
+  "action": "5be7fc31-ac79-48df-b58d-4ce2d292ee91",
+  "app": "d5f42929-cddb-48be-8fd7-77d41d8c79be",
+  "name": "testsuite",
+  "description": "End-to-end automated tests",
+  "created_by": "Calaway",
+  "created": "2021-03-12T03:52:42.769Z",
+  "updated": "2021-03-12T03:52:42.769Z",
+  "deleted": false,
+  "formation": {
+    "id": "1aa5558e-4216-46bb-a15e-627a6fe62c22",
+    "type": "actionstestsuite",
+    "size": "gp1",
+    "command": "./start.sh",
+    "options": {
+      "image": "domain.io/project/image:tag-1",
+      "env": {
+        "foo": "bar"
+      }
+    }
+  }
+}
+```
+
+### Create an Action Run
+
+`POST /apps/{appname}/actions/{action_name}/runs`
+
+Manually trigger an action.
+
+**CURL Example**
+
+```bash
+curl \
+  -H 'Authorization: ...' \
+  -X POST \
+  https://apps.akkeris.io/apps/app-space/actions/testsuite/runs
+```
+
+**201 "Created" Response**
+
+```json
+{
+  "action_run": "8e3cabac-afb6-44d5-8c01-de2d463460cb",
+  "action": "5be7fc31-ac79-48df-b58d-4ce2d292ee91",
+  "runid": "b8902377-11b6-4149-8a9d-36a1d4cb3271",
+  "status": "running",
+  "exit_code": null,
+  "created_by": "Calaway",
+  "created": "2021-03-12T03:52:43.125Z"
+}
+```
+
+### List Action Runs
+
+`GET /apps/{appname}/actions/{action_name}/runs`
+
+**CURL Example**
+
+```bash
+curl \
+  -H 'Authorization: ...' \
+  -X GET \
+  https://apps.akkeris.io/apps/app-space/actions/testsuite/runs
+```
+
+**200 "OK" Response**
+
+```json
+[
+  {
+    "action_run": "3e4fd725-bfb9-49c5-8393-6684fb5e3936",
+    "action": "9cad8674-d56f-4068-b293-5eb0f30ecbb4",
+    "status": "running",
+    "exit_code": null,
+    "created_by": "Calaway",
+    "created": "2021-10-14T16:35:35.069Z"
+  }
+]
+```
+
+### Get Action Run Info
+
+`GET /apps/{appname}/actions/{action_name}/runs/{run_id}`
+
+**CURL Example**
+
+```bash
+curl \
+  -H 'Authorization: ...' \
+  -X GET \
+  https://apps.akkeris.io/apps/app-space/actions/testsuite/runs/3e4fd725-bfb9-49c5-8393-6684fb5e3936
+```
+
+**200 "OK" Response**
+
+```json
+{
+    "action_run": "3e4fd725-bfb9-49c5-8393-6684fb5e3936",
+    "action": "9cad8674-d56f-4068-b293-5eb0f30ecbb4",
+    "status": "running",
+    "exit_code": null,
+    "created_by": "unknown",
+    "created": "2021-10-14T16:35:35.069Z"
+}
+```
+
+### Delete an Action
+
+`DELETE /apps/{appname}/actions/{action_name}`
+
+**CURL Example**
+
+```bash
+curl \
+  -H 'Authorization: ...' \
+  -X DELETE \
+  https://apps.akkeris.io/apps/app-space/actions/testsuite
+```
+
+**200 "OK" Response**
+
+```json
+{
+  "action": "5be7fc31-ac79-48df-b58d-4ce2d292ee91",
+  "app": "d5f42929-cddb-48be-8fd7-77d41d8c79be",
+  "name": "testsuite",
+  "description": "End-to-end automated tests",
+  "created_by": "Calaway",
+  "created": "2021-03-12T03:52:42.769Z",
+  "updated": "2021-03-12T03:52:42.769Z",
+  "deleted": false,
+  "formation": {
+    "id": "1aa5558e-4216-46bb-a15e-627a6fe62c22",
+    "type": "actionstestsuite",
+    "size": "gp1",
+    "command": "./start.sh",
+    "options": {
+      "image": "domain.io/project/image:tag-1",
+      "env": {
+        "foo": "bar"
+      }
+    }
+  }
+}
+```
+

index.js

@@ -18,6 +18,7 @@ const { simple_key, jwt_key } = require('./lib/auth.js')(config.simple_key, conf
 const common = require('./lib/common.js');
 
 const alamo = {
+  actions: require('./lib/actions.js'),
   addon_attachments: require('./lib/addon-attachments.js'),
   addon_services: require('./lib/addon-services.js'),
   addons: require('./lib/addons.js'),
@@ -841,6 +842,40 @@ routes.add.delete('/apps/([A-z0-9\\-\\_\\.]+)/recommendations(\\?[A-z0-9\\-\\_\\
   .run(alamo.recommendations.http.delete.bind(alamo.recommendations.http.delete, pg_pool))
   .and.authorization([simple_key, jwt_key]);
 
+// -- actions
+// Create Action
+routes.add.post('/apps/([A-z0-9\\-\\_\\.]+)/actions$')
+  .run(alamo.actions.http.create.bind(alamo.actions.http.create, pg_pool))
+  .and.authorization([simple_key, jwt_key]);
+// Create Action Run
+routes.add.post('/apps/([A-z0-9\\-\\_\\.]+)/actions/([A-z0-9\\-\\_\\.]+)/runs$')
+  .run(alamo.actions.http.runs.create.bind(alamo.actions.http.runs.create, pg_pool))
+  .and.authorization([simple_key, jwt_key]);
+// Get Specific Action
+routes.add.get('/apps/([A-z0-9\\-\\_\\.]+)/actions/([A-z0-9\\-\\_\\.]+)$')
+  .run(alamo.actions.http.get.bind(alamo.actions.http.get, pg_pool))
+  .and.authorization([simple_key, jwt_key]);
+// List All Actions
+routes.add.get('/apps/([A-z0-9\\-\\_\\.]+)/actions$')
+  .run(alamo.actions.http.list.bind(alamo.actions.http.list, pg_pool))
+  .and.authorization([simple_key, jwt_key]);
+// Get Specific Action Run
+routes.add.get('/apps/([A-z0-9\\-\\_\\.]+)/actions/([A-z0-9\\-\\_\\.]+)/runs/([A-z0-9\\-\\_\\.]+)$')
+  .run(alamo.actions.http.runs.get.bind(alamo.actions.http.runs.get, pg_pool))
+  .and.authorization([simple_key, jwt_key]);
+// List All Action Runs
+routes.add.get('/apps/([A-z0-9\\-\\_\\.]+)/actions/([A-z0-9\\-\\_\\.]+)/runs$')
+  .run(alamo.actions.http.runs.list.bind(alamo.actions.http.runs.list, pg_pool))
+  .and.authorization([simple_key, jwt_key]);
+// Update Action
+routes.add.patch('/apps/([A-z0-9\\-\\_\\.]+)/actions/([A-z0-9\\-\\_\\.]+)$')
+  .run(alamo.actions.http.update.bind(alamo.actions.http.update, pg_pool))
+  .and.authorization([simple_key, jwt_key]);
+// Delete Action
+routes.add.delete('/apps/([A-z0-9\\-\\_\\.]+)/actions/([A-z0-9\\-\\_\\.]+)$')
+  .run(alamo.actions.http.delete.bind(alamo.actions.http.delete, pg_pool))
+  .and.authorization([simple_key, jwt_key]);
+
 routes.add.default((req, res) => {
   res.writeHead(404, {});
   res.end();