release preparations

CHANGES.md

@@ -0,0 +1,3 @@
+# v0.1.0 (2021-09-14)
+
+- Initial public release

README.md

@@ -1,32 +1,26 @@
 # builder - scheduling and executing jobs
 
-This consists of two programs, a client and a server. The single server
-contains a queue of jobs, which are consumed by a client. Any number of
-clients can be connected to the server.
+This consists of three programs, a worker, a server, and a client. The single
+server contains a queue of jobs, which are consumed by a worker. Any number of
+worker can be connected to the server. The client can modify the schedule:
+add/remove/modify jobs, also observe a concrete job.
 
 The server keeps persistent state of the job queue (so restarts / crashes are
-dealt with). A client connects, provides some information about itself, and
+dealt with). A worker connects, provides some information about itself, and
 then waits for a job. Once a job is read and accepted, it is executed by the
-client. Resulting artifacts can be transferred by the client to the server.
+worker. Resulting artifacts can be transferred by the client to the server.
 
-The server has the ability to schedule jobs at regular intervals - similar to
-crontab - but clients are usually executed in sandboxes/ jailed environments.
+The client has the ability to schedule jobs at regular intervals - similar to
+crontab - but workers are usually executed in sandboxes/ jailed environments.
 
 Handled and unhandled error conditions:
-- client execution fails (timeout, restart, killed): not handled
-- client execution gets a signal: reported to server
-- client can't write job data files -> failure is captured and reported
-- client can't read job output -> logged to client's console (without artifacts gathered)
-- client errors when submitting console output -> ignored
-- client errors when submitting build artifacts -> retry
-- there's no explicit ACK for packets
+- worker execution fails (timeout, restart, killed): not handled, but server has a timeout
+- worker execution gets a signal: reported to server
+- worker can't write job data files -> failure is captured and reported
+- worker can't read job output -> logged to client's console (without artifacts gathered)
+- worker errors when submitting console output -> ignored
+- worker fails communication with server -> job is ignored (the server is responsible for restarting)
 
-Left to do:
-- client should queue up console output on server connection failure (and continue reading output at the same time)
-- client should inform when data passed to it and artifacts overlap (name / checksum)
-- client could sandbox the executed script a bit more (maybe?)
-- client should have a timeout for the script to be executed
-- retrieve artifacts even if execution failed
-- the running jobs are not stored onto disk, which may result in unexpected behaviour
-- should instead once a job is scheduled the uuid and job information being dumped to disk already (also avoids dummy job dump, and allows recovery of running jobs when server restarts)
-- potential security issue: directory traversals (server folds over output directory and collects files)
+A templating mechanism is available, look for `orb-build.template` as examples.
+Currently FreeBSD, Debian and Ubuntu are supported, and a repository that
+receives jobs is live at https://builds.robur.coop/

builder.opam

@@ -7,7 +7,7 @@ bug-reports: "https://github.com/roburio/builder/issues"
 license: "ISC"
 
 depends: [
-  "ocaml" {>= "4.08.0"}
+  "ocaml" {>= "4.10.0"}
   "dune" {>= "2.0.0"}
   "asn1-combinators"
   "bheap"
@@ -33,3 +33,14 @@ build: [
 ]
 
 synopsis: "Scheduling and executing shell jobs"
+description: """
+The builder server has a schedule of jobs to be executed, stored persistently
+on disk. Any number of workers can connect via TCP (using ASN.1 encoded
+messages) that execute a single job -- usually contained in a sandbox (FreeBSD
+jail or Docker container). A client is a command-line interface to modify the
+schedule. Access control is out of scope - run it locally on your build host.
+The server receives the output artifacts of each job, and either stores them
+on the local file system or upload them to a remote server via http.
+
+See https://builds.robur.coop for the live web frontend (builder-web).
+"""