Add: ControllerAPI, ControllerState

1 files changed, 132 insertions, 0 deletions

diff --git a/yarns/100-projects.yarn b/yarns/100-projects.yarn
new file mode 100644
index 0000000..315116f
--- /dev/null
+++ b/yarns/100-projects.yarn
@@ -0,0 +1,132 @@
+# Controller project management
+
+The Ick2 controller manages information about projects. Projects are
+things the controller builds. A project is described by a resource
+like this:
+
+    EXAMPLE project resource
+    {
+        "name": "ick2-website",
+        "shell_commands": [
+            "git clone git://git.liw.fi/ick2-website src",
+            "cd src && ikiwiki --setup ikiwiki.setup",
+            "cd html && rsync -a --delete . www-data@www.example.com:/srv/http/ick2/."
+        ]
+    }
+
+In other words, there are two things that define a project:
+
+* The name. This is used for referreing to the project in the API.
+* A sequence of shell commands to be run to build the project. At this
+  point Ick2 does not know about git repositories, so the shell
+  commands need to do the cloning explicitly; this will obviously have
+  to be changed later on. Note also that each string in the list is
+  run by a new shell process, and that the current working directory,
+  or environment variables, do not get preserved. Ick2 will create a
+  new, empty directory for running the commands.
+
+## Managing projects
+
+First we test the controller API for managing projects, without
+building them. We start by starting an instance of the controller.
+
+    SCENARIO managing projects
+    GIVEN an RSA key pair for token signing
+    AND an access token for scopes 
+    ... uapi_projects_get
+    ... uapi_projects_post
+    ... uapi_projects_id_get
+    ... uapi_projects_id_put
+    ... uapi_projects_id_delete
+    AND controller config uses statedir at the state directory
+    AND a running ick controller
+
+    WHEN user makes request GET /projects
+    THEN result has status code 200
+    AND body matches { "projects": [] }
+
+    WHEN user makes request POST /projects
+    ... {
+    ...     "project": "website",
+    ...     "shell_steps": [
+    ...         "git clone git://repo src",
+    ...         "mkdir html",
+    ...         "ikiwiki src html"
+    ...     ]
+    ... }
+    THEN result has status code 201
+    AND body matches 
+    ... {
+    ...     "project": "website",
+    ...     "shell_steps": [
+    ...         "git clone git://repo src",
+    ...         "mkdir html",
+    ...         "ikiwiki src html"
+    ...     ]
+    ... }
+    AND controller state directory contains project website
+
+    WHEN user makes request GET /projects
+    THEN result has status code 200
+    AND body matches 
+    ... {
+    ...     "projects": [
+    ...         {
+    ...             "project": "website",
+    ...             "shell_steps": [
+    ...                 "git clone git://repo src",
+    ...                 "mkdir html",
+    ...                 "ikiwiki src html"
+    ...             ]
+    ...         }
+    ...     ]
+    ... }
+
+    WHEN user stops ick controller
+    GIVEN a running ick controller
+    WHEN user makes request GET /projects/website
+    THEN result has status code 200
+    AND body matches 
+    ... {
+    ...     "project": "website",
+    ...     "shell_steps": [
+    ...         "git clone git://repo src",
+    ...         "mkdir html",
+    ...         "ikiwiki src html"
+    ...     ]
+    ... }
+
+    WHEN user makes request PUT /projects/website
+    ... {
+    ...     "project": "website",
+    ...     "shell_steps": [
+    ...         "build-it"
+    ...     ]
+    ... }
+    THEN result has status code 200
+    AND body matches 
+    ... {
+    ...     "project": "website",
+    ...     "shell_steps": [
+    ...         "build-it"
+    ...     ]
+    ... }
+    AND controller state directory contains project website
+
+    WHEN user makes request GET /projects/website
+    THEN result has status code 200
+    AND body matches 
+    ... {
+    ...     "project": "website",
+    ...     "shell_steps": [
+    ...         "build-it"
+    ...     ]
+    ... }
+
+    WHEN user makes request DELETE /projects/website
+    THEN result has status code 200
+    WHEN user makes request GET /projects/website
+    THEN result has status code 404
+
+
+    FINALLY stop ick controller