branch master updated: Update the Web API documentation.

[Mathieu Othacehe]

This is an automated email from the git hooks/post-receive script.

mothacehe pushed a commit to branch master
in repository guix-cuirass.

The following commit(s) were added to refs/heads/master by this push:
     new 2bd6e80  Update the Web API documentation.
2bd6e80 is described below

commit 2bd6e80482e915616d18ee2254f4f6101cdfb942
Author: Mathieu Othacehe <othacehe@gnu.org>
AuthorDate: Tue Mar 9 17:01:08 2021 +0100

    Update the Web API documentation.
    
    * doc/cuirass.texi (Web API): Update it.
    * src/cuirass/http.scm (build->hydra-build): Update it accordingly.
---
 doc/cuirass.texi     | 132 ++++++++++++++++++++++++++++++++++++++++++---------
 src/cuirass/http.scm |  10 ++--
 2 files changed, 112 insertions(+), 30 deletions(-)

diff --git a/doc/cuirass.texi b/doc/cuirass.texi
index 371a865..7599235 100644
--- a/doc/cuirass.texi
+++ b/doc/cuirass.texi
@@ -555,13 +555,86 @@ Display an help message that summarize all the options 
provided.
 @chapter Web API
 @cindex web api
 
-Cuirass web API is derived from Hydra one, see 
@url{https://github.com/NixOS/hydra/blob/master/doc/manual/api.xml, Hydra API 
description}.
-
-For now only a subset of this API is implemented.
+The Cuirass web API is inspired from the Hydra one.
 
 @section API description
 @cindex description, json
 
+@subsection Evaluation information
+@subsubheading Single evaluation
+
+It is possible to query the Cuirass web server for evaluation
+information. The dedicated API is "/api/evaluation?id=@var{eval-id}"
+where @var{eval-id} is the unique id associated to the evaluation in
+database.
+
+For instance, querying a local Cuirass web server can be done with
+@code{curl} and @code{jq} to format the JSON response :
+
+@example
+$ curl -s "http://localhost:8080/api/evaluation?id=1"; | jq
+
+@{
+  "id": 1,
+  "specification": "guix-master",
+  "status": 0,
+  "timestamp": 1615289011,
+  "checkouttime": 1615289011,
+  "evaltime": 1615289655,
+  "checkouts": [
+    @{
+      "commit": "bd311f5a6ccbd4696ac77f0426a036bb375a2f10",
+      "channel": "guix",
+      "directory": "/gnu/store/6978xw9vs4ybg2pc3g736p1dba2056yl-guix-bd311f5"
+    @}
+  ]
+@}
+@end example
+
+The nominal output is a JSON object whose fields are described
+hereafter.
+
+@table @code
+@item id
+The unique build id.
+
+@item specification
+The associated specification name, as a string.
+
+@item status
+The evaluation status, as an integer. Possible values are :
+
+@example
+-1 -> started
+0 -> succeeded
+1 -> failed
+2 -> aborted
+@end example
+
+@item checkouttime
+The timestamp after channel checkout.
+
+@item evaltime
+The timestamp after evaluation completion.
+
+@item checkouts
+The evaluation checkouts as a JSON object.
+
+@end table
+
+@subsubheading Multiple evaluations
+
+The latest evaluations list can be obtained with the API
+"/api/evaluations".  The output is a JSON array of
+evaluations. Evaluations are represented as in the
+"/api/evaluation?id=@var{eval-id}" API.
+
+This request accepts a mandatory parameter.
+@table @code
+@item nr
+Limit query result to nr elements. This parameter is @emph{mandatory}.
+@end table
+
 @subsection Build information
 
 It is possible to query Cuirass web server for build informations. The
@@ -572,9 +645,6 @@ The build information can also be queried by output. For 
example,
 @samp{/output/kg9mirg6xbvzcp0a98v7326n1nvvwgsj-hello-2.10} will return
 the details of the output, along with the build if available.
 
-For instance, querying a local Cuirass web server can be done with
-@code{curl} and @code{jq} to format the JSON response :
-
 @example
 $ curl -s "http://localhost:8080/build/2"; | jq
 
@@ -593,12 +663,11 @@ $ curl -s "http://localhost:8080/build/2"; | jq
   "system": "x86_64-linux",
   "nixname": "acpica-20150410",
   "buildstatus": 0,
+  "weather": 0,
   "busy": 0,
   "priority": 0,
   "finished": 1,
-  "buildproducts": null,
-  "releasename": null,
-  "buildinputs_builds": null
+  "buildproducts": null
 @}
 @end example
 
@@ -656,23 +725,28 @@ Build status, as an integer. Possible values are :
 4 -> cancelled
 @end example
 
+@item weather
+Build weather, as an integer.
+
+@example
+-1 -> unknown
+0 -> new-success
+1 -> new-failure
+2 -> still-succeeding
+3 -> still-failing
+@end example
+
 @item busy
-Whether the build is pending, as an integer (not implemented yet).
+Whether the build is pending, as an integer.
 
 @item priority
-Build priority, as an integer (not implemented yet).
+Build priority, as an integer.
 
 @item finished
-Build finished, as an integer (not implemented yet : always 1).
+Build finished, as an integer.
 
 @item buildproducts
-Build products in store as a JSON object (not implemented yet).
-
-@item releasename
-Unknown, not implemented yet.
-
-@item buildinputs_builds
-Inputs used for the build, as a JSON object (not implemented yet).
+Build products in store as a JSON object.
 
 @end table
 
@@ -705,8 +779,8 @@ $ curl -s "http://localhost:8080/build/fff/log/raw";
 @subsection Latest builds
 
 The list of latest builds can be obtained with the API
-"/api/latestbuilds".  The output is a JSON array of
-builds. Builds are represented as in "/build/@var{build-id} API.
+"/api/latestbuilds".  The output is a JSON array of builds. Builds are
+represented as in the "/build/@var{build-id}" API.
 
 This request accepts a mandatory parameter and multiple optional ones.
 
@@ -740,6 +814,18 @@ $ curl 
"http://localhost:8080/api/latestbuilds?nr=5&jobset=guix";
 If no builds matching given parameters are found, an empty JSON array is
 returned.
 
+@subsection Queued builds
+
+The list of queued builds can be obtained with the API
+"/api/queue".  The output is a JSON array of builds. Builds are
+represented as in the "/build/@var{build-id}" API.
+
+This request accepts a mandatory parameter.
+@table @code
+@item nr
+Limit query result to nr elements. This parameter is @emph{mandatory}.
+@end table
+
 @c *********************************************************************
 @node Database
 @chapter Database schema
@@ -910,8 +996,8 @@ are:
 
 @item priority
 The build priority relatively to the other builds with the same
-@code{job_name}, as an integer ranging from 0 to 9 where 0 is the
-higher priority and 9 the lowest.
+@code{job_name}, as an integer ranging from 0 to 99 where 0 is the
+higher priority and 99 the lowest.
 
 @item max_silent
 This integer field holds the number of seconds of silence after which
diff --git a/src/cuirass/http.scm b/src/cuirass/http.scm
index 0182d2c..14ba07f 100644
--- a/src/cuirass/http.scm
+++ b/src/cuirass/http.scm
@@ -90,9 +90,7 @@
     (if bool 1 0))
 
   (define finished?
-    (not (memv (assq-ref build #:status)
-               (list (build-status scheduled)
-                     (build-status started)))))
+    (>= (assq-ref build #:status) 0))
 
   `((#:id . ,(assq-ref build #:id))
     (#:evaluation . ,(assq-ref build #:eval-id))
@@ -115,12 +113,10 @@
     (#:weather . ,(assq-ref build #:weather))
     (#:busy . ,(bool->int (eqv? (build-status started)
                                 (assq-ref build #:status))))
-    (#:priority . 0)
+    (#:priority . ,(assq-ref build #:priority))
     (#:finished . ,(bool->int finished?))
     (#:buildproducts . ,(list->vector
-                         (assq-ref build #:buildproducts)))
-    (#:releasename . #nil)
-    (#:buildinputs_builds . #nil)))
+                         (assq-ref build #:buildproducts)))))
 
 (define (evaluation->json-object evaluation)
   "Turn EVALUATION into a representation suitable for 'json->scm'."