From fdc3e0eb0b61818c20e2f22150c01404b8f3932d Mon Sep 17 00:00:00 2001 From: Eric Callahan Date: Wed, 19 Jul 2023 07:56:28 -0400 Subject: [PATCH] docs: document changes to update_manager Signed-off-by: Eric Callahan --- docs/api_changes.md | 19 ++++++++++- docs/changelog.md | 4 ++- docs/user_changes.md | 16 ++++++++-- docs/web_api.md | 76 ++++++++++++++++++++++++++++---------------- 4 files changed, 83 insertions(+), 32 deletions(-) diff --git a/docs/api_changes.md b/docs/api_changes.md index 30f92fd..29d6a92 100644 --- a/docs/api_changes.md +++ b/docs/api_changes.md @@ -1,5 +1,22 @@ ## -This document keeps a record of all changes to Moonraker's web APIs. +This document keeps a record of notable changes to Moonraker's Web API. + +### July 18th 2023 +- Moonraker API Version 1.3.0 +- Added [Spoolman](web_api.md#spoolman-apis) APIs. +- Added [Rollback](web_api.md#rollback-to-the-previous-version) API to + the `update_manager` +- The `update_manager` status response has new fields for items of the + `git_repo` and `web` types: + - `recovery_url`: Url of the repo a "hard" recovery will fetch from + - `rollback_version`: Version the extension will revert to when a rollback + is requested + - `warnings`: An array of strings containing various warnings detected + during repo init. Some warnings may explain an invalid state while + others may alert users to potential issues, such as a `git_repo` remote + url not matching the expected (ie: configured) url. + - Additionally, the `need_channel_update` field has been removed as the method + changing channels is done exclusively in the configuration. ### February 20th 2023 - The following new endpoints are available when at least one `[sensor]` diff --git a/docs/changelog.md b/docs/changelog.md index f51cf8e..615ae12 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -17,6 +17,8 @@ The format is based on [Keep a Changelog]. - **zeroconf**: Added support for UPnP/SSDP Discovery. - **spoolman**: Added integration to the [Spoolman](https://github.com/Donkie/Spoolman) filament manager. +- **update_manager**: Added support for update rollbacks +- **update_manager**: Added support for stable `git_repo` updates ### Fixed @@ -47,7 +49,7 @@ The format is based on [Keep a Changelog]. configurations should use the `virtualenv` option. - **update_manager**: The `install_script` option for the `git_repo` has been deprecated, new configurations should use the `system_dependencies` option. -- **API**: The `update_manager` APIs that return status report additional fields. +- **update_manager**: APIs that return status report additional fields. See the [API Documentation](./web_api.md#get-update-status) for details. ## [0.8.0] - 2023-02-23 diff --git a/docs/user_changes.md b/docs/user_changes.md index b8f6ab3..a082354 100644 --- a/docs/user_changes.md +++ b/docs/user_changes.md @@ -1,6 +1,18 @@ ## -This file will track changes that require user intervention, -such as a configuration change or a reinstallation. +This file tracks configuration changes and deprecations. Additionally +changest to Moonraker that require user intervention will be tracked +here. + +### July 18th 2023 +- The following changes have been made to `[update_manager ]` + extensions of the `git_repo` type: + - The `env` option has been deprecated. New configurations should + use the `virtualenv` option in its place. + - The `install_script` option has been deprecated. New configurations + should use the `system_dependencies` option to specify system package + dependencies. +- Configuration options for `[spoolman]` have been added +- Configuration options for `[sensor]` have been added ### Februrary 8th 2023 - The `provider` option in the `[machine]` section no longer accepts diff --git a/docs/web_api.md b/docs/web_api.md index d8eec80..74cdde2 100644 --- a/docs/web_api.md +++ b/docs/web_api.md @@ -4144,7 +4144,6 @@ and `fluidd` are present as clients configured in `moonraker.conf` "moonraker": { "channel": "dev", "debug_enabled": true, - "need_channel_update": false, "is_valid": true, "configured_type": "git_repo", "corrupt": false, @@ -4156,6 +4155,7 @@ and `fluidd` are present as clients configured in `moonraker.conf` "repo_name": "moonraker", "version": "v0.7.1-364", "remote_version": "v0.7.1-364", + "rollback_version": "v0.7.1-360", "current_hash": "ecfad5cff15fff1d82cb9bdc64d6b548ed53dfaf", "remote_hash": "ecfad5cff15fff1d82cb9bdc64d6b548ed53dfaf", "is_dirty": false, @@ -4173,6 +4173,7 @@ and `fluidd` are present as clients configured in `moonraker.conf` "owner": "mainsail-crew", "version": "v2.1.1", "remote_version": "v2.1.1", + "rollback_version": "v2.0.0", "configured_type": "web", "channel": "stable", "info_tags": [ @@ -4187,6 +4188,7 @@ and `fluidd` are present as clients configured in `moonraker.conf` "owner": "fluidd-core", "version": "v1.16.2", "remote_version": "v1.16.2", + "rollback_version": "v1.15.0", "configured_type": "web", "channel": "beta", "info_tags": [], @@ -4196,7 +4198,6 @@ and `fluidd` are present as clients configured in `moonraker.conf` "klipper": { "channel": "dev", "debug_enabled": true, - "need_channel_update": false, "is_valid": true, "configured_type": "git_repo", "corrupt": false, @@ -4208,6 +4209,7 @@ and `fluidd` are present as clients configured in `moonraker.conf` "repo_name": "klipper", "version": "v0.10.0-1", "remote_version": "v0.10.0-41", + "rollback_version": "v0.9.1-340", "current_hash": "4c8d24ae03eadf3fc5a28efb1209ce810251d02d", "remote_hash": "e3cbe7ea3663a8cd10207a9aecc4e5458aeb1f1f", "is_dirty": false, @@ -4252,23 +4254,18 @@ Below is an explanation for each field: - `github_limit_reset_time`: the time when the rate limit will reset, reported as seconds since the epoch (aka Unix Time). -The `moonraker`, `klipper` packages, along with and clients configured -as applications have the following fields: +Extensions configured with the `git_repo` type will contain the following +fields: - `configured_type`: the application type configured by the user - `detected_type`: the application 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. +- `pristine`: Indicates that there are no modified files or untracked + source files in a `git_repo`. A repo with untracked files can still + be updated, however a repo with modified files (ie: `dirty`) cannot + be updated. - `owner`: the owner of the repo / application - `branch`: the name of the current git branch. This should typically be "master". @@ -4276,26 +4273,22 @@ as applications have the following fields: "origin". - `version`: abbreviated version of the current repo on disk - `remote_version`: abbreviated version of the latest available update +- `rollback_version`: version the repo will revert to when a rollback is + requested - `full_version_string`: The complete version string of the current repo. - `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. For `zip` and `zip_beta` - types this will report false if Moonraker is unable to fetch the - current repo state from GitHub. +- `is_valid`: true if the `git_repo` is valid and can be updated. - `corrupt`: Indicates that the git repo has been corrupted. When a repo is in this state it a hard recovery (ie: re-cloning the repo) is necessary. Note that the most common cause of repo corruption is removing power from the host machine without safely shutting down. Damaged storage can also lead to repo corruption. -- `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). +- `is_dirty`: true if a `git_repo` has modified files. A dirty repo cannot + be updated. +- `detached`: true if the `git_repo` is currently in a detached state. +- `debug_enabled`: True when debug flag has been set via the command line. + When debug is enabled Moonraker will allow detached updates. - `commits_behind`: A list of commits behind. Up to 30 "untagged" commits will be reported. Moonraker checks the last 100 commits for tags, any commits beyond the last 30 with a tag will also be reported. @@ -4316,9 +4309,9 @@ as applications have the following fields: - `warnings`: An array of strings that describe warnings detected during repo init. These warnings describe potential issues, such as a mismatch between the detected remote and the configured remote. If the `is_valid` - field reports `False` then the warnings will contain additional context. + field reports `false` then the warnings will contain additional context. -Web clients have the following fields: +Extensions configured with the `web` type will contain the following fields: - `channel`: channel to fetch updates from - `configured_type`: will be `web` @@ -4326,6 +4319,8 @@ Web clients have the following fields: - `owner`: the owner of the client - `version`: version of the installed client. - `remote_version`: version of the latest release published to GitHub +- `rollback_version`: version the client will revert to when a rollback is + requested - `info_tags`: These are tags defined in the `[update_manager client_name]` configuration for each client. Client developers my define what tags, if any, users will configure. They can choose to use those tags to display @@ -4338,7 +4333,7 @@ Web clients have the following fields: field reports `False` then the warnings will contain additional context. -The `system` package has the following fields: +The `system` object contains the following fields: - `package_count`: the number of system packages available for update - `package_list`: an array containing the names of packages available @@ -4545,6 +4540,31 @@ Returns: `ok` when complete +### Rollback to the previous version + +HTTP request: + +```http +POST /machine/update/rollback?name=moonraker +``` + +JSON-RPC request: + +```json +{ + "jsonrpc": "2.0", + "method": "machine.update.rollback", + "params": { + "name": "moonraker" + }, + "id": 4564 +} +``` + +Returns: + +`ok` when complete + ### Power APIs The APIs below are available when the `[power]` component has been configured.