From 16dcc224ec2cff330562662cae89020477d8b13a Mon Sep 17 00:00:00 2001 From: Charles Kerr Date: Tue, 12 Oct 2021 22:03:28 -0500 Subject: [PATCH] feat: add rpc-version-semver to RPC's session-get (#1935) * feat: add rpc-version-semver to RPC's session-get --- extras/rpc-spec.txt | 318 ++++++++++++++++-------------- libtransmission/quark.cc | 3 +- libtransmission/quark.h | 1 + libtransmission/rpcimpl.cc | 9 +- tests/libtransmission/rpc-test.cc | 3 +- 5 files changed, 178 insertions(+), 156 deletions(-) diff --git a/extras/rpc-spec.txt b/extras/rpc-spec.txt index 6adfc7aaa..456a2af7d 100644 --- a/extras/rpc-spec.txt +++ b/extras/rpc-spec.txt @@ -540,6 +540,7 @@ "rename-partial-files" | boolean | true means append ".part" to incomplete files "rpc-version" | number | the current RPC API version "rpc-version-minimum" | number | the minimum RPC API version supported + "rpc-version-semver" | number | the current RPC API version in a semver-compatible string "script-torrent-done-filename" | string | filename of the script to run "script-torrent-done-enabled" | boolean | whether or not to call the "done" script "seedRatioLimit" | double | the default seed ratio for torrents to use @@ -684,163 +685,176 @@ 5.0. Protocol Versions - The following changes have been made to the RPC interface: + This section lists the changes that have been made to the RPC protocol. - RPC | Release | Backwards | | - Vers. | Version | Compat? | Method | Description - ------+---------+-----------+----------------------+------------------------------- - 1 | 1.30 | n/a | n/a | Initial version - ------+---------+-----------+----------------------+------------------------------- - 2 | 1.34 | yes | torrent-get | new arg "peers" - ------+---------+-----------+----------------------+------------------------------- - 3 | 1.41 | yes | torrent-get | added "port" to "peers" - | | yes | torrent-get | new arg "downloaders" - | | yes | session-get | new arg "version" - | | yes | torrent-remove | new method - ------+---------+-----------+----------------------+------------------------------- - 4 | 1.50 | yes | session-get | new arg "rpc-version" - | | yes | session-get | new arg "rpc-version-minimum" - | | yes | session-stats | added "cumulative-stats" - | | yes | session-stats | added "current-stats" - | | yes | torrent-get | new arg "downloadDir" - ------+---------+-----------+----------------------+------------------------------- - 5 | 1.60 | yes | | new method "torrent-reannounce" - | | yes | | new method "blocklist-update" - | | yes | | new method "port-test" - | | | | - | | yes | session-get | new arg "alt-speed-begin" - | | yes | session-get | new arg "alt-speed-down" - | | yes | session-get | new arg "alt-speed-enabled" - | | yes | session-get | new arg "alt-speed-end" - | | yes | session-get | new arg "alt-speed-time-enabled" - | | yes | session-get | new arg "alt-speed-up" - | | yes | session-get | new arg "blocklist-enabled" - | | yes | session-get | new arg "blocklist-size" - | | yes | session-get | new arg "peer-limit-per-torrent" - | | yes | session-get | new arg "seedRatioLimit" - | | yes | session-get | new arg "seedRatioLimited" - | | NO | session-get | renamed "pex-allowed" to "pex-enabled" - | | NO | session-get | renamed "port" to "peer-port" - | | NO | session-get | renamed "peer-limit" to "peer-limit-global" - | | | | - | | yes | torrent-add | new arg "files-unwanted" - | | yes | torrent-add | new arg "files-wanted" - | | yes | torrent-add | new arg "priority-high" - | | yes | torrent-add | new arg "priority-low" - | | yes | torrent-add | new arg "priority-normal" - | | | | - | | yes | torrent-set | new arg "bandwidthPriority" - | | yes | torrent-set | new arg "honorsSessionLimits" - | | yes | torrent-set | new arg "seedRatioLimit" - | | yes | torrent-set | new arg "seedRatioLimited" - | | NO | torrent-set | renamed "speed-limit-down" to "downloadLimit" - | | NO | torrent-set | renamed "speed-limit-down-enabled" to "downloadLimited" - | | NO | torrent-set | renamed "speed-limit-up" to "uploadLimit" - | | NO | torrent-set | renamed "speed-limit-up-enabled" to "uploadLimited" - | | | | - | | yes | torrent-get | new arg "bandwidthPriority" - | | yes | torrent-get | new arg "fileStats" - | | yes | torrent-get | new arg "honorsSessionLimits" - | | yes | torrent-get | new arg "percentDone" - | | yes | torrent-get | new arg "pieces" - | | yes | torrent-get | new arg "seedRatioLimit" - | | yes | torrent-get | new arg "seedRatioMode" - | | yes | torrent-get | new arg "torrentFile" - | | yes | torrent-get | new ids option "recently-active" - | | NO | torrent-get | removed arg "downloadLimitMode" - | | NO | torrent-get | removed arg "uploadLimitMode" - ------+---------+-----------+----------------------+------------------------------- - 6 | 1.70 | yes | | new "method torrent-set-location" - ------+---------+-----------+----------------------+------------------------------- - 7 | 1.80 | NO | torrent-get | removed arg "announceResponse" - | | NO | torrent-get | removed arg "announceURL" - | | NO | torrent-get | removed arg "downloaders" - | | NO | torrent-get | removed arg "lastAnnounceTime" - | | NO | torrent-get | removed arg "lastScrapeTime" - | | NO | torrent-get | removed arg "leechers" - | | NO | torrent-get | removed arg "nextAnnounceTime" - | | NO | torrent-get | removed arg "nextScrapeTime" - | | NO | torrent-get | removed arg "scrapeResponse" - | | NO | torrent-get | removed arg "scrapeURL" - | | NO | torrent-get | removed arg "seeders" - | | NO | torrent-get | removed arg "timesCompleted" - | | NO | torrent-get | removed arg "swarmSpeed" - | | yes | torrent-get | new arg "magnetLink" - | | yes | torrent-get | new arg "metadataPercentComplete" - | | yes | torrent-get | new arg "trackerStats" - | | yes | session-set | new arg "incomplete-dir" - | | yes | session-set | new arg "incomplete-dir-enabled" - ------+---------+-----------+----------------------+------------------------------- - 8 | 1.90 | yes | session-set | new arg "rename-partial-files" - | | yes | session-get | new arg "rename-partial-files" - | | yes | session-get | new arg "config-dir" - | | yes | torrent-add | new arg "bandwidthPriority" - | | yes | torrent-get | new trackerStats arg "lastAnnounceTimedOut" - ------+---------+-----------+----------------------+------------------------------- - 8 | 1.92 | yes | torrent-get | new trackerStats arg "lastScrapeTimedOut" - ------+---------+-----------+----------------------+------------------------------- - 9 | 2.00 | yes | session-set | new arg "start-added-torrents" - | | yes | session-set | new arg "trash-original-torrent-files" - | | yes | session-get | new arg "start-added-torrents" - | | yes | session-get | new arg "trash-original-torrent-files" - | | yes | torrent-get | new arg "isFinished" - ------+---------+-----------+----------------------+------------------------------- - 10 | 2.10 | yes | session-get | new arg "cache-size-mb" - | | yes | torrent-set | new arg "trackerAdd" - | | yes | torrent-set | new arg "trackerRemove" - | | yes | torrent-set | new arg "trackerReplace" - | | yes | session-set | new arg "idle-seeding-limit" - | | yes | session-set | new arg "idle-seeding-limit-enabled" - | | yes | session-get | new arg "units" - | | yes | torrent-set | new arg "seedIdleLimit" - | | yes | torrent-set | new arg "seedIdleMode" - ------+---------+-----------+----------------------+------------------------------- - 11 | 2.12 | yes | session-get | new arg "blocklist-url" - | | yes | session-set | new arg "blocklist-url" - ------+---------+-----------+----------------------+------------------------------- - 12 | 2.20 | yes | session-get | new arg "download-dir-free-space" - | | yes | session-close | new method - ------+---------+-----------+----------------------+------------------------------- - 13 | 2.30 | yes | session-get | new arg "isUTP" to the "peers" list - | | yes | torrent-add | new arg "cookies" - | | NO | torrent-get | removed arg "peersKnown" - ------+---------+-----------+----------------------+------------------------------- - 14 | 2.40 | NO | torrent-get | values of "status" field changed - | | yes | torrent-get | new arg "queuePosition" - | | yes | torrent-get | new arg "isStalled" - | | yes | torrent-get | new arg "fromLpd" in peersFrom - | | yes | torrent-set | new arg "queuePosition" - | | yes | session-set | new arg "download-queue-size" - | | yes | session-set | new arg "download-queue-enabled" - | | yes | session-set | new arg "seed-queue-size" - | | yes | session-set | new arg "seed-queue-enabled" - | | yes | session-set | new arg "queue-stalled-enabled" - | | yes | session-set | new arg "queue-stalled-minutes" - | | yes | | new method "queue-move-top" - | | yes | | new method "queue-move-up" - | | yes | | new method "queue-move-down" - | | yes | | new method "queue-move-bottom" - | | yes | | new method "torrent-start-now" - ------+---------+-----------+----------------------+------------------------------- - 15 | 2.80 | yes | torrent-get | new arg "etaIdle" - | | yes | torrent-rename-path | new method - | | yes | free-space | new method - | | yes | torrent-add | new return arg "torrent-duplicate" - ------+---------+-----------+----------------------+------------------------------- - 16 | 3.00 | yes | session-get | new request arg "fields" - | | yes | session-get | new arg "session-id" - | | yes | torrent-get | new arg "labels" - | | yes | torrent-set | new arg "labels" - | | yes | torrent-get | new arg "editDate" - | | yes | torrent-get | new request arg "format" - ------+---------+-----------+----------------------+------------------------------- - 17 | 3.01 | yes | torrent-get | new arg "file-count" - | | yes | torrent-get | new arg "primary-mime-type" + There are two ways to check for API compatibility. Since most developers know + semver, session-get's "rpc-version-semver" is the recommended way. That value + is a semver-compatible string of the RPC protocol version number. + + Since Transmission predates the semver 1.0 spec, the previous scheme was for + the RPC version to be a whole number and to increment it whenever a change was + made. That is session-get's "rpc-version". "rpc-version-minimum" lists the + oldest version that is compatible with the current version; i.e. an app coded + to use `rpc-version-minimum` would still work on a Transmission release running + `rpc-version`. + + RPC | Sem | Tr. | Method | Description + Ver | Ver | Ver | (breaking changes | + | | | marked w/asterisk) | + ----+-------+------+----------------------+------------------------------- + 1 | 1.0.0 | 1.30 | n/a | Initial version + ----+-------+------+----------------------+------------------------------- + 2 | 1.1.0 | 1.40 | torrent-get | new arg "peers" + ----+-------+------+----------------------+------------------------------- + 3 | 1.2.0 | 1.41 | torrent-get | added "port" to "peers" + | | | torrent-get | new arg "downloaders" + | | | session-get | new arg "version" + | | | torrent-remove | new method + ----+-------+------+----------------------+------------------------------- + 4 | 1.3.0 | 1.50 | session-get | new arg "rpc-version" + | | | session-get | new arg "rpc-version-minimum" + | | | session-stats | added "cumulative-stats" + | | | session-stats | added "current-stats" + | | | torrent-get | new arg "downloadDir" + ----+-------+------+----------------------+------------------------------- + 5 | 2.0.0 | 1.60 | | new method "torrent-reannounce" + | | | | new method "blocklist-update" + | | | | new method "port-test" + | | | | + | | | session-get | new arg "alt-speed-begin" + | | | session-get | new arg "alt-speed-down" + | | | session-get | new arg "alt-speed-enabled" + | | | session-get | new arg "alt-speed-end" + | | | session-get | new arg "alt-speed-time-enabled" + | | | session-get | new arg "alt-speed-up" + | | | session-get | new arg "blocklist-enabled" + | | | session-get | new arg "blocklist-size" + | | | session-get | new arg "peer-limit-per-torrent" + | | | session-get | new arg "seedRatioLimit" + | | | session-get | new arg "seedRatioLimited" + | | | session-get * | renamed "pex-allowed" to "pex-enabled" + | | | session-get * | renamed "port" to "peer-port" + | | | session-get * | renamed "peer-limit" to "peer-limit-global" + | | | | + | | | torrent-add | new arg "files-unwanted" + | | | torrent-add | new arg "files-wanted" + | | | torrent-add | new arg "priority-high" + | | | torrent-add | new arg "priority-low" + | | | torrent-add | new arg "priority-normal" + | | | | + | | | torrent-set | new arg "bandwidthPriority" + | | | torrent-set | new arg "honorsSessionLimits" + | | | torrent-set | new arg "seedRatioLimit" + | | | torrent-set | new arg "seedRatioLimited" + | | | torrent-set * | renamed "speed-limit-down" to "downloadLimit" + | | | torrent-set * | renamed "speed-limit-down-enabled" to "downloadLimited" + | | | torrent-set * | renamed "speed-limit-up" to "uploadLimit" + | | | torrent-set * | renamed "speed-limit-up-enabled" to "uploadLimited" + | | | | + | | | torrent-get | new arg "bandwidthPriority" + | | | torrent-get | new arg "fileStats" + | | | torrent-get | new arg "honorsSessionLimits" + | | | torrent-get | new arg "percentDone" + | | | torrent-get | new arg "pieces" + | | | torrent-get | new arg "seedRatioLimit" + | | | torrent-get | new arg "seedRatioMode" + | | | torrent-get | new arg "torrentFile" + | | | torrent-get | new ids option "recently-active" + | | | torrent-get * | removed arg "downloadLimitMode" + | | | torrent-get * | removed arg "uploadLimitMode" + ----+-------+------+----------------------+------------------------------- + 6 | 2.1.0 | 1.70 | | new "method torrent-set-location" + ----+-------+------+----------------------+------------------------------- + 7 | 3.0.0 | 1.80 | torrent-get * | removed arg "announceResponse" + | | | torrent-get * | removed arg "announceURL" + | | | torrent-get * | removed arg "downloaders" + | | | torrent-get * | removed arg "lastAnnounceTime" + | | | torrent-get * | removed arg "lastScrapeTime" + | | | torrent-get * | removed arg "leechers" + | | | torrent-get * | removed arg "nextAnnounceTime" + | | | torrent-get * | removed arg "nextScrapeTime" + | | | torrent-get * | removed arg "scrapeResponse" + | | | torrent-get * | removed arg "scrapeURL" + | | | torrent-get * | removed arg "seeders" + | | | torrent-get * | removed arg "timesCompleted" + | | | torrent-get * | removed arg "swarmSpeed" + | | | torrent-get | new arg "magnetLink" + | | | torrent-get | new arg "metadataPercentComplete" + | | | torrent-get | new arg "trackerStats" + | | | session-set | new arg "incomplete-dir" + | | | session-set | new arg "incomplete-dir-enabled" + ----+-------+------+----------------------+------------------------------- + 8 | 3.1.0 | 1.90 | session-set | new arg "rename-partial-files" + | | | session-get | new arg "rename-partial-files" + | | | session-get | new arg "config-dir" + | | | torrent-add | new arg "bandwidthPriority" + | | | torrent-get | new trackerStats arg "lastAnnounceTimedOut" + ----+-------+------+----------------------+------------------------------- + 8 | 3.2.0 | 1.92 | torrent-get | new trackerStats arg "lastScrapeTimedOut" + ----+-------+------+----------------------+------------------------------- + 9 | 3.3.0 | 2.00 | session-set | new arg "start-added-torrents" + | | | session-set | new arg "trash-original-torrent-files" + | | | session-get | new arg "start-added-torrents" + | | | session-get | new arg "trash-original-torrent-files" + | | | torrent-get | new arg "isFinished" + ----+-------+------+----------------------+------------------------------- + 10 | 3.4.0 | 2.10 | session-get | new arg "cache-size-mb" + | | | torrent-set | new arg "trackerAdd" + | | | torrent-set | new arg "trackerRemove" + | | | torrent-set | new arg "trackerReplace" + | | | session-set | new arg "idle-seeding-limit" + | | | session-set | new arg "idle-seeding-limit-enabled" + | | | session-get | new arg "units" + | | | torrent-set | new arg "seedIdleLimit" + | | | torrent-set | new arg "seedIdleMode" + ----+-------+------+----------------------+------------------------------- + 11 | 3.5.0 | 2.12 | session-get | new arg "blocklist-url" + | | | session-set | new arg "blocklist-url" + ----+-------+------+----------------------+------------------------------- + 12 | 3.6.0 | | session-get | new arg "download-dir-free-space" + | | | session-close | new method + ----+-------+------+----------------------+------------------------------- + 13 | 4.0.0 | 2.30 | session-get | new arg "isUTP" to the "peers" list + | | | torrent-add | new arg "cookies" + | | | torrent-get * | removed arg "peersKnown" + ----+-------+------+----------------------+------------------------------- + 14 | 5.0.0 | 2.40 | torrent-get * | values of "status" field changed + | | | torrent-get | new arg "queuePosition" + | | | torrent-get | new arg "isStalled" + | | | torrent-get | new arg "fromLpd" in peersFrom + | | | torrent-set | new arg "queuePosition" + | | | session-set | new arg "download-queue-size" + | | | session-set | new arg "download-queue-enabled" + | | | session-set | new arg "seed-queue-size" + | | | session-set | new arg "seed-queue-enabled" + | | | session-set | new arg "queue-stalled-enabled" + | | | session-set | new arg "queue-stalled-minutes" + | | | | new method "queue-move-top" + | | | | new method "queue-move-up" + | | | | new method "queue-move-down" + | | | | new method "queue-move-bottom" + | | | | new method "torrent-start-now" + ----+-------+------+----------------------+------------------------------- + 15 | 5.1.0 | 2.80 | torrent-get | new arg "etaIdle" + | | | torrent-rename-path | new method + | | | free-space | new method + | | | torrent-add | new return arg "torrent-duplicate" + ----+-------+------+----------------------+------------------------------- + 16 | 5.2.0 | 3.00 | session-get | new request arg "fields" + | | | session-get | new arg "session-id" + | | | torrent-get | new arg "labels" + | | | torrent-set | new arg "labels" + | | | torrent-get | new arg "editDate" + | | | torrent-get | new request arg "format" + ----+-------+------+----------------------+------------------------------- + 17 | 5.3.0 | 3.xx | torrent-get | new arg "file-count" + | | | torrent-get | new arg "primary-mime-type" + | | | session-get | new arg "rpc-version-semver" 5.1. Upcoming Breakage - These features will be removed three months after 2.80's release: + These features are deprecated: 1. session-get's 'download-dir-free-space' argument will be removed. Its functionality has been superceded by the 'free-space' method. diff --git a/libtransmission/quark.cc b/libtransmission/quark.cc index b37626a6a..1500ba97d 100644 --- a/libtransmission/quark.cc +++ b/libtransmission/quark.cc @@ -21,7 +21,7 @@ namespace { -auto constexpr my_static = std::array{ "", +auto constexpr my_static = std::array{ "", "activeTorrentCount", "activity-date", "activityDate", @@ -303,6 +303,7 @@ auto constexpr my_static = std::array{ "", "rpc-username", "rpc-version", "rpc-version-minimum", + "rpc-version-semver", "rpc-whitelist", "rpc-whitelist-enabled", "scrape", diff --git a/libtransmission/quark.h b/libtransmission/quark.h index 32b87883d..86e3811d4 100644 --- a/libtransmission/quark.h +++ b/libtransmission/quark.h @@ -304,6 +304,7 @@ enum TR_KEY_rpc_username, TR_KEY_rpc_version, TR_KEY_rpc_version_minimum, + TR_KEY_rpc_version_semver, TR_KEY_rpc_whitelist, TR_KEY_rpc_whitelist_enabled, TR_KEY_scrape, diff --git a/libtransmission/rpcimpl.cc b/libtransmission/rpcimpl.cc index efe9bb06f..06358745e 100644 --- a/libtransmission/rpcimpl.cc +++ b/libtransmission/rpcimpl.cc @@ -39,8 +39,9 @@ #include "version.h" #include "web.h" -#define RPC_VERSION 16 -#define RPC_VERSION_MIN 1 +#define RPC_VERSION 17 +#define RPC_VERSION_MIN 14 +#define RPC_VERSION_SEMVER "5.3.0" #define RECENTLY_ACTIVE_SECONDS 60 @@ -2450,6 +2451,10 @@ static void addSessionField(tr_session* s, tr_variant* d, tr_quark key) tr_variantDictAddInt(d, key, RPC_VERSION); break; + case TR_KEY_rpc_version_semver: + tr_variantDictAddStr(d, key, RPC_VERSION_SEMVER); + break; + case TR_KEY_rpc_version_minimum: tr_variantDictAddInt(d, key, RPC_VERSION_MIN); break; diff --git a/tests/libtransmission/rpc-test.cc b/tests/libtransmission/rpc-test.cc index ac5ed66bc..2a10c3b71 100644 --- a/tests/libtransmission/rpc-test.cc +++ b/tests/libtransmission/rpc-test.cc @@ -102,7 +102,7 @@ TEST_F(RpcTest, sessionGet) EXPECT_TRUE(tr_variantDictFindDict(&response, TR_KEY_arguments, &args)); // what we expected - auto const expected_keys = std::array{ + auto const expected_keys = std::array{ TR_KEY_alt_speed_down, TR_KEY_alt_speed_enabled, TR_KEY_alt_speed_time_begin, @@ -139,6 +139,7 @@ TEST_F(RpcTest, sessionGet) TR_KEY_rename_partial_files, TR_KEY_rpc_version, TR_KEY_rpc_version_minimum, + TR_KEY_rpc_version_semver, TR_KEY_script_torrent_added_enabled, TR_KEY_script_torrent_added_filename, TR_KEY_script_torrent_done_enabled,