Add: pipeline sub-API

1 files changed, 168 insertions, 0 deletions

diff --git a/yarns/150-pipelines.yarn b/yarns/150-pipelines.yarn
new file mode 100644
index 0000000..f0f678e
--- /dev/null
+++ b/yarns/150-pipelines.yarn
@@ -0,0 +1,168 @@
+<!--
+
+Copyright 2017 Lars Wirzenius
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+-->
+
+# Controller pipeline management
+
+The Ick2 controller manages information about named pipelines.
+Pipelines are sequences of steps to achieve part of a project build.
+They're described like resources like this:
+
+    EXAMPLE pipeline resource
+    {
+        "name": "build-website",
+        "parameters": {
+            "foo": "bar"
+        },
+        "actions": [
+            {
+                "shell": "git clone git://git.liw.fi/ick2-website src" }
+            },
+            {
+                "shell": "cd src && ikiwiki --setup ikiwiki.setup"
+            },
+            {
+                "shell": "cd html && rsync -a --delete . server::/srv/http/ick2/."
+            }
+        ]
+    }
+
+In other words, there are several things that define a pipeline:
+
+* The `name`. This is used for referreing to the pipeline in the API.
+* A set of parameters, which are currently ignored.
+* A sequence of actions. At the moment, each action is a shell
+  command to be run, but that will change later.
+
+## Managing pipelines
+
+First we test the controller API for managing pipelines, without
+running them. We start by starting an instance of the controller.
+
+    SCENARIO managing pipelines
+    GIVEN an RSA key pair for token signing
+    AND an access token for user with scopes
+    ... uapi_pipelines_get
+    ... uapi_pipelines_post
+    ... uapi_pipelines_id_get
+    ... uapi_pipelines_id_put
+    ... uapi_pipelines_id_delete
+    AND controller config uses statedir at the state directory
+    AND a running ick controller
+
+    WHEN user makes request GET /pipelines
+    THEN result has status code 200
+    AND body matches { "pipelines": [] }
+
+    WHEN user makes request POST /pipelines with a valid token and body
+    ... {
+    ...     "name": "build_website",
+    ...     "actions": [
+    ...         { "shell": "git clone git://repo src" },
+    ...         { "shell": "mkdir html" },
+    ...         { "shell": "ikiwiki src html" }
+    ...     ]
+    ... }
+    THEN result has status code 201
+    AND body matches
+    ... {
+    ...     "name": "build_website",
+    ...     "actions": [
+    ...         { "shell": "git clone git://repo src" },
+    ...         { "shell": "mkdir html" },
+    ...         { "shell": "ikiwiki src html" }
+    ...     ]
+    ... }
+
+Creating a new pipeline with the same name is forbidden.
+
+    WHEN user makes request POST /pipelines with a valid token and body
+    ... {
+    ...     "name": "build_website"
+    ... }
+    THEN result has status code 409
+
+    WHEN user makes request GET /pipelines
+    THEN result has status code 200
+    AND body matches
+    ... {
+    ...     "pipelines": [
+    ...         {
+    ...             "name": "build_website",
+    ...              "actions": [
+    ...                 { "shell": "git clone git://repo src" },
+    ...                 { "shell": "mkdir html" },
+    ...                 { "shell": "ikiwiki src html" }
+    ...             ]
+    ...         }
+    ...     ]
+    ... }
+
+    WHEN user stops ick controller
+    GIVEN a running ick controller
+    WHEN user makes request GET /pipelines/build_website
+    THEN result has status code 200
+    AND body matches
+    ... {
+    ...     "name": "build_website",
+    ...     "actions": [
+    ...         { "shell": "git clone git://repo src" },
+    ...         { "shell": "mkdir html" },
+    ...         { "shell": "ikiwiki src html" }
+    ...     ]
+    ... }
+
+    WHEN user makes request PUT /pipelines/build_websitte with a valid token
+    ... and body
+    ... {
+    ...     "name": "build_website",
+    ...     "actions": [
+    ...         { "shell": "build-it" }
+    ...     ]
+    ... }
+    THEN result has status code 200
+    AND body matches
+    ... {
+    ...     "name": "build_website",
+    ...     "actions": [
+    ...         { "shell": "build-it" }
+    ...     ]
+    ... }
+
+    WHEN user makes request GET /pipelines/build_website
+    THEN result has status code 200
+    AND body matches
+    ... {
+    ...     "name": "build_website",
+    ...     "actions": [
+    ...         { "shell": "build-it" }
+    ...     ]
+    ... }
+
+    WHEN user makes request DELETE /pipelines/build_website
+    THEN result has status code 200
+    WHEN user makes request GET /pipelines/build_website
+    THEN result has status code 404
+
+    WHEN user makes request PUT /pipelines/doesnotexist with a valid token and body
+    ... {
+    ...     "name": "doesnotexist"
+    ... }
+    THEN result has status code 404
+
+    FINALLY stop ick controller