ARCH: Use terms "{Down,Up}stream Host" instead of "Trove"

Lorry Controller is not limited to working with Trove, and we probably
shouldn't limit it to mirroring to a co-hosted git server.  So:

* In the Requirements section, introduce the terms "Downstream Host"
  to replace "local Trove" and "Upstream Host" to replace "remote
  Trove" and "upstream Trove".

* In the Requirements section, use the term "Host specification"
  instead of "Trove specification".

* In the Entities section, refer back to those definitions.

* Replace all references to Troves accordingly, except the code sample
  (since the API has not yet been changed) and an example that is
  specific to Trove.

Related to #3, #5.

1 files changed, 30 insertions, 22 deletions

diff --git a/ARCH b/ARCH
index 5721aba..de1db0c 100644
--- a/ARCH
+++ b/ARCH
@@ -21,13 +21,19 @@ Some concepts/terminology:
   upstream version control repository or tarball. Note that a `.lorry`
   file may contain several specifications.
 
-* Trove specification: which remote Trove to mirror. This gets
+* Upstream Host: a git hosting server that Lorry Controller mirrors
+  from.
+
+* Host specification: which Upstream Host to mirror. This gets
   broken into generated Lorry specifications, one per git repository
-  on the other Trove. There can be many Trove specifications to
-  mirror many Troves.
+  on the other Host. There can be many Host specifications to
+  mirror many Hosts.
+
+* Downstream Host: a git hosting server that Lorry Controller mirrors
+  to.
 
 * run queue: all the Lorry specifications (from CONFGIT or generated
-  from the Trove specifications) a Lorry Controller knows about; this
+  from the Host specifications) a Lorry Controller knows about; this
   is the set of things that get scheduled. The queue has a linear
   order (first job in the queue is the next job to execute).
 
@@ -38,6 +44,9 @@ Some concepts/terminology:
 * admin: a person who can control or reconfigure a Lorry Controller
   instance. All users of the HTTP API are admins, for example.
 
+For historical reasons, Hosts are also referred to as Troves in many
+places.
+
 Original set of requirements, which have been broken down and detailed
 up below:
 
@@ -62,15 +71,15 @@ up below:
 The detailed requirements (prefixed by a unique identfier, which is
 used elsewhere to refer to the exact requirement):
 
-* (FW) Lorry Controller can access upstream Troves from behind firewalls.
-    * (FW/H) Lorry Controller can access the upstream Trove using HTTP or
+* (FW) Lorry Controller can access Upstream Hosts from behind firewalls.
+    * (FW/H) Lorry Controller can access the Upstream Host using HTTP or
       HTTPS only, without using ssh, in order to get a list of
       repositories to mirror. (Lorry itself also needs to be able to
-      access the upstream Trove using HTTP or HTTPS only, bypassing
+      access the Upstream Host using HTTP or HTTPS only, bypassing
       ssh, but that's a Lorry problem and outside the scope of Lorry
       Controller, so it'll need to be dealt separately.)
     * (FW/C) Lorry Controller does not verify SSL/TLS certificates
-      when accessing the upstream Trove.
+      when accessing the Upstream Host.
 * (RC) Lorry Controller can be reconfigured at runtime.
     * (RC/ADD) A new Lorry specification can be added to CONFGIT, and
       a running Lorry Controller will add them to its run queue as
@@ -101,7 +110,7 @@ used elsewhere to refer to the exact requirement):
       the run queue for any information the Lorry Controller holds for
       them, such as the last time they successfully finished running.
 * (RR) Lorry Controller is reasonably robust.
-    * (RR/CONF) Lorry Controller ignores any broken Lorry or Trove
+    * (RR/CONF) Lorry Controller ignores any broken Lorry or Host
       specifications in CONFGIT, and runs without them.
     * (RR/TIMEOUT) Lorry Controller stops a job that runs for too
       long.
@@ -153,10 +162,9 @@ Entities
   communicate with the Lorry Controller.
 * Lorry Controller runs Lorry appropriately, and consists of several
   components described below.
-* The local Trove is where Lorry Controller tells its Lorry to push
-  the results.
-* Upstream Trove is a Trove that Lorry Controller mirrors to the local
-  Trove. There can be multiple upstream Troves.
+* The Downstream Host is as defined in Requirements.
+* An Upstream Host is as defined in Requirements.  There can be
+  multiple Upstream Hosts.
 
 Components of Lorry Controller
 ------------------------------
@@ -164,11 +172,11 @@ Components of Lorry Controller
 * CONFGIT is a git repository for Lorry Controller configuration,
   which the Lorry Controller (see WEBAPP below) can access and pull
   from. Pushing is not required and should be prevented by Gitano.
-  CONFGIT is hosted on the local Trove.
+  CONFGIT is hosted on the Downstream Host.
 
 * STATEDB is persistent storage for the Lorry Controller's state: what
   Lorry specs it knows about (provided by the admin, or generated from
-  a Trove spec by Lorry Controller itself), their ordering, jobs that
+  a Host spec by Lorry Controller itself), their ordering, jobs that
   have been run or are being run, information about the jobs, etc. The
   idea is that the Lorry Controller process can terminate (cleanly or
   by crashing), and be restarted, and continue approximately from
@@ -218,8 +226,8 @@ How the components work together
   report state as stored in STATEDB. Commands cause the WEBAPP
   instance to do something and alter STATEDB accordingly.
 
-* When an admin makes changes to CONFGIT, and pushes them to the local
-  Trove, the Trove's git post-update hook makes an HTTP request to
+* When an admin makes changes to CONFGIT, and pushes them to the Downstream
+  Host, the Host's git post-update hook makes an HTTP request to
   WEBAPP to update STATEDB from CONFGIT. (RC/ADD, RC/RM)
 
 * Each MINION likewise communicates only with the WEBAPP using HTTP
@@ -349,13 +357,13 @@ Other requests:
   admin (there is a button on the `/1.0/status-html` web page).
 
 * `POST /1.0/ls-troves` causes WEBAPP to refresh its list of
-  repositories in each remote Trove, if the current list is too old
-  (see the `ls-interval` setting for each remote trove in
+  repositories in each Upstream Host, if the current list is too old
+  (see the `ls-interval` setting for each Upstream Host in
   `lorry-controller.conf`). This gets called from a systemd timer unit
   at a suitable interval.
 
 * `POST /1.0/force-ls-troves` causes the repository refresh to happen
-  for all remote Troves, regardless of whether it is due or not. This
+  for all Upstream Hosts, regardless of whether it is due or not. This
   can be called manually by an admin.
 
 
@@ -397,7 +405,7 @@ requests.
 The `lorries` table implements the run-queue: all the Lorry specs that
 WEBAPP knows about. It has the following columns:
 
-* `path` is the path of the git repository on the local Trove, i.e.,
+* `path` is the path of the git repository on the Downstream Host, i.e.,
   the git repository to which Lorry will push. This is a unique
   identifier. It is used, for example, to determine if a Lorry spec
   is obsolete after a CONFGIT update.
@@ -433,7 +441,7 @@ The Lorry Controller code base is laid out as follows:
 
 * `static` has static content to be served over HTTP. Primarily, the
   CSS file for the HTML interfaces. When LC is integrated within the
-  Trove, the web server gets configured to serve these files directly.
+  Downstream Host, the web server gets configured to serve these files directly.
   The `static` directory will be accessible over plain HTTP on port
   80, and on port 12765 via the WEBAPP, to allow HTML pages to refer
   to it via a simple path.