Document 'just serve' protocol and implementation

3 files changed, 79 insertions, 2 deletions

diff --git a/share/man/just-mr.1.md b/share/man/just-mr.1.md
index 1ef324ac..e05828c6 100644
--- a/share/man/just-mr.1.md
+++ b/share/man/just-mr.1.md
@@ -121,6 +121,10 @@ be used to peer verify archive fetches from remote.
 Address of a remote execution service. This is used as an intermediary fetch
 location for archives, between local CAS (or distdirs) and the network.
 
+**`--remote-serve-address`** *`NAME`*:*`PORT`*  
+Address of a **`just`** **`serve`** service. This is used as intermediary fetch
+location for Git commits, between local CAS and the network.
+
 **`--compatible`**  
 At increased computational effort, be compatible with the original remote build
 execution protocol. If a remote execution service address is provided, this 
diff --git a/share/man/just-serve-config.5.md b/share/man/just-serve-config.5.md
new file mode 100644
index 00000000..ee42692c
--- /dev/null
+++ b/share/man/just-serve-config.5.md
@@ -0,0 +1,65 @@
+% JUST SERVE CONFIG(5) | File Formats Manual
+
+NAME
+====
+
+**`just`** **`serve`** configuration - The format of the configuration used by
+the **`serve`** subcommand of **`just`**(1)
+
+DESCRIPTION
+===========
+
+The file is read as JSON. Any other serialization describing the same
+JSON object is equivalent. We assume, that in JSON objects, each key
+occurs at most once; it is implementation defined how repetitions of the
+same key are treated.
+
+The just-serve configuration format
+-----------------------------------
+
+The configuration file is given by a JSON object.
+
+ - The value for the key *`"repositories"`* is a list of strings specifying
+   paths to Git repositories for **`just`** **`serve`** to use as additional
+   object lookup locations. The paths are to be used in the order given and
+   only if requested objects are not found in the local build root.  
+
+ - The value for the key *`"logging"`* is a JSON object specifying logging
+   options.  
+   For subkey *`"files"`* the value is a list of strings specifying one or more
+   local log files to use. The files will store the information printed on
+   stderr, along with the thread id and timestamp when the output has been
+   generated.  
+   For subkey *`"limit"`* the value is an integer setting the default for
+   the log limit.  
+   For subkey *`"plain"`* the value is a flag. If set, do not use ANSI escape
+   sequences to highlight messages.  
+   For subkey *`"append"`* the value is a flag. If set, append messages to log
+   file instead of overwriting existing.
+
+  - The value for the key *`"authentication"`* is a JSON object specifying
+   client-side authentication options for **`just`** **`serve`** when
+   communicating with the remote execution endpoint.  
+   For subkey *`"ca cert"`* the value is a string specifying the path to a TLS
+   CA certificate.  
+
+ - The value for the key *`"remote service"`* is a JSON object specifying the
+   server arguments for running **`just`** **`serve`** as a service.  
+   For subkey *`"interface"`* the value specifies the interface of the service.
+   If unset, the loopback device is used.  
+   For subkey *`"port"`* the value specifies the port to which the service is to
+   listen. If unset, the service will choose to the first available one.  
+   For subkey *`"pid file"`* the value specifies a file to which the pid should
+   be stored in plain text. If the file exists, it will be overwritten.  
+   For subkey *`"info file"`* the value specifies a file to which the used port,
+   interface, and pid should be stored in JSON format. If the file exists, it
+   will be overwritten.  
+   For subkey *`"server cert"`* the value is a string specifying the path to a
+   TLS server certificate.  
+   For subkey *`"server key"`* the value is a string specifying the path to a
+   TLS server key.  
+
+See also
+========
+
+**`just`**(1)
diff --git a/share/man/just.1.md b/share/man/just.1.md
index 6ca9ab1c..b2cce8d2 100644
--- a/share/man/just.1.md
+++ b/share/man/just.1.md
@@ -273,6 +273,14 @@ the just native remote protocol.
 If the flag **`--compatible`** is provided, the execution service will
 honor the original remote build execution protocol.
 
+**`serve`**
+-----------
+
+This subcommand starts a service that provides target dependencies needed for a
+remote execution build. It expects as its only and mandatory argument the path
+to a configuration file, following the format described in
+**`just-serve-config`**(5).
+
 OPTIONS
 =======
 
@@ -503,7 +511,7 @@ Supported by: analyse|build|install-cas|install|rebuild|traverse.
 
 **`--endpoint-configuration`** FILE  
 File containing a description on how to dispatch to different
-remote-execution endpoints based on the the execution properties.
+remote-execution endpoints based on the execution properties.
 The format is a JSON list of pairs (lists of length two) of an object
 of strings and a string. The first entry describes a condition (the
 remote-execution properties have to agree on the domain of this
@@ -514,7 +522,6 @@ as specified by **`-r`**, or local execution if no endpoint is
 specified).  
 Supported by: analyse|build|install-cas|install|rebuild|traverse.
 
-
 Authentication options
 ----------------------
 
@@ -696,4 +703,5 @@ See also
 ========
 
 **`just-repository-config`**(5),
+**`just-serve-config`**(5),
 **`just-mr`**(1)