From d60b852b27a68b9730fbd0225056e15b5bc21c68 Mon Sep 17 00:00:00 2001
From: Eric Callahan <arksine.code@gmail.com>
Date: Thu, 8 Jul 2021 10:52:56 -0400
Subject: [PATCH] docs: add documentation for latest changes to the update
 manager

Signed-off-by: Eric Callahan <arksine.code@gmail.com>
---
 docs/configuration.md | 48 ++++++++++++++++++++++++++-------
 docs/web_api.md       | 63 +++++++++++++++++++++++++++++++++++++++----
 2 files changed, 96 insertions(+), 15 deletions(-)

diff --git a/docs/configuration.md b/docs/configuration.md
index 4084847..023a9e7 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -394,10 +394,22 @@ enable_auto_refresh: False
 #   When set to False Moonraker will only fetch update state on startup
 #   and clients will need to request that Moonraker updates state.  The
 #   default is False.
-distro: debian
-#   The disto in which moonraker has been installed.  Currently the
-#   update manager only supports "debian", which encompasses all of
-#   its derivatives.  The default is debain.
+enable_system_updates: True
+#   A boolean value that can be used to toggle system package updates.
+#   Currently Moonraker only supports updating packages via APT, so
+#   this option is useful for users that wish to experiment with linux
+#   distros that use other package management applications, or users
+#   that prefer to manage their packages directly.  Note that if this
+#   is set to False users will be need to make sure that all system
+#   dependencies are up to date.  The default is True.
+channel: dev
+#   The update channel applied to Klipper and Moonraker.  May be 'dev'
+#   which will fetch updates using git, or 'beta' which will fetch
+#   zipped beta releases.  Note that this channel does not apply to
+#   client updates, a client's update channel is determined by its
+#   'type' option.  When this option is changed the next "update" will
+#   swap channels, any untracked files in the application's path will be
+#   removed during this process.  The default is dev.
 ```
 
 ### Client Configuration
@@ -412,8 +424,9 @@ service restart such as Fluidd/Mainsail.
 ```ini
 # moonraker.conf
 
-[update_manager client client_name]
+[update_manager client_name]
 type: web
+# Indicates that this is a web client.
 repo:
 #   This is the GitHub repo of the client, in the format of user/client.
 #   For example, this could be set to cadriel/fluidd to update Fluidd or
@@ -426,22 +439,29 @@ persistent_files:
 #   themes.  The default is no persistent files.
 ```
 
-This second example is for git repositories that have a service that need
-updating.  Note that git repos must have at least one tag for Moonraker
+This second example is for "applications".  These may be git repositories
+or zipped distributions.
+
+Note that git repos must have at least one tag for Moonraker
 to identify its version.
 
 ```ini
 # moonraker.conf
 
 # service_name must be the name of the systemd service
-[update_manager client service_name]
+[update_manager service_name]
 type: git_repo
+#   Can be git_repo, zip, or zip_beta.  See your the client's documentation
+#   for recommendations on which value to use.  Generally a git_repo is
+#   an applications "dev" channel, zip_beta is its "beta" channel, and zip
+#   is its "stable" channel.  This parameter must be provided.
 path:
-#   The absolute path to the client's files on disk. This parameter must be provided.
+#   The absolute path to the client's files on disk. This parameter must be
+#   provided.
 #   Example:
 #     path: ~/service_name
 origin:
-#   The full GitHub URL of the "origin" remote for the repository.  This can
+#   The full git URL of the "origin" remote for the repository.  This can
 #   be be viewed by navigating to your repository and running:
 #     git remote -v
 #   This parameter must be provided.
@@ -468,6 +488,14 @@ enable_node_updates:
 #   to package-lock.json.  Note that if your project does not have a
 #   package-lock.json in its root directory then the plugin will fail to load.
 #   Default is False.
+host_repo:
+#   The GitHub repo in which zipped releases are hosted.  Note that this does
+#   not need to match the repository in the "origin" option, as it is possible
+#   to use a central GitHub repository to host multiple client builds.  As
+#   an example, Moonraker's repo hosts builds for both Moonraker and Klipper.
+#   This option defaults to the repo extracted from the "origin" option,
+#   however if the origin is not hosted on GitHub then this parameter must
+#   be provided.
 ```
 
 ## `[mqtt]`
diff --git a/docs/web_api.md b/docs/web_api.md
index 972444a..904ca2e 100644
--- a/docs/web_api.md
+++ b/docs/web_api.md
@@ -2057,6 +2057,10 @@ and `fluidd` are present as clients configured in `moonraker.conf`
             ]
         },
         "moonraker": {
+            "type": "zip_beta",
+            "channel": "beta",
+            "need_channel_update": false,
+            "pristine": true,
             "remote_alias": "origin",
             "branch": "master",
             "owner": "Arksine",
@@ -2084,6 +2088,10 @@ and `fluidd` are present as clients configured in `moonraker.conf`
             "remote_version": "v1.10.0"
         },
         "klipper": {
+            "type": "zip_beta",
+            "channel": "beta",
+            "need_channel_update": false,
+            "pristine": true,
             "remote_alias": "origin",
             "branch": "master",
             "owner": "KevinOConnor",
@@ -2133,9 +2141,23 @@ Below is an explanation for each field:
   reported as seconds since the epoch (aka Unix Time).
 
 The `moonraker`, `klipper` packages, along with and clients configured
-as git repos have the following fields:
+as applications have the following fields:
 
-- `owner`: the owner of the repo
+- `configured_type`: the application type configured by the user
+- `detected_type`:  the applicaiton type as detected by Moonraker.
+- `channel`:  the currently configured update channel.  For Moonraker
+  and Klipper this is set in the `[update_manager]` configuration.
+  For clients the channel is determined by the configured type
+- `need_channel_update`: This will be set to `true` if Moonraker has
+  detected that a channel swap is necessary (ie: the configured type does
+  not match the detected type). The channel swap will be performed on the
+  next update.
+- `pristine`: For `zip` and `zip_beta` types this is set to `true` if an
+  applications source checksum matches the one generated  when the app was
+  built.  This value will be set to the opposite of "dirty" for git repos.
+  Note that a zip application can still be updated if the repo is not
+  pristine.
+- `owner`: the owner of the repo / application
 - `branch`: the name of the current git branch.  This should typically
     be "master".
 - `remote_alias`: the alias for the remote.  This should typically be
@@ -2146,9 +2168,14 @@ as git repos have the following fields:
 - `current_hash`: hash of the most recent commit on disk
 - `remote_hash`: hash of the most recent commit pushed to the remote
 - `is_valid`: true if installation is a valid git repo on the master branch
-    and an "origin" set to the official remote
-- `is_dirty`: true if the repo has been modified
-- `detached`: true if the repo is currently in a detached state
+    and an "origin" set to the official remote.  For `zip` and `zip_beta`
+    types this will report false if Moonraker is unable to fetch the
+    current repo state from GitHub.
+- `is_dirty`: true if the repo has been modified.  This will always be false
+  for `zip` and `zip_beta` types.
+- `detached`: true if the repo is currently in a detached state.  For `zip`
+  and `zip_beta` types it is considered detached if the local release info
+  does not match what is present on the remote.
 - `debug_enabled`: True when `enable_repo_debug` has been configured.  This
     will bypass repo validation allowing detached updates, and updates from
     a remote/branch other than than the primary (typically origin/master).
@@ -2175,6 +2202,32 @@ The `system` package has the following fields:
 - `package_list`: an array containing the names of packages available
   for update
 
+### Perform a full update
+Attempts to update all configured items in Moonraker.  Updates are
+performed in the following order:
+
+- `system` if enabled
+- All configured clients
+- Klipper
+- Moonraker
+
+HTTP request:
+```http
+POST /machine/update/full
+```
+JSON-RPC request:
+```json
+{
+    "jsonrpc": "2.0",
+    "method": "machine.update.full",
+    "id": 4645
+}
+```
+Returns:
+
+`ok` when complete
+
+
 #### Update Moonraker
 Pulls the most recent version of Moonraker from GitHub and restarts
 the service. If an update is requested while a print is in progress then