Transmission/transmission
1
0
Fork 0
mirror of https://github.com/transmission/transmission.git synced 2025-12-25 04:45:56 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: add rpc-version-semver to RPC's session-get (#1935)

Browse Source 
* feat: add rpc-version-semver to RPC's session-get
This commit is contained in:
Charles Kerr
2021-10-12 22:03:28 -05:00
committed by GitHub
parent ba6513ed4a
commit 16dcc224ec
5 changed files with 178 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

318
extras/rpc-spec.txt
View File

@@ -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.

3
libtransmission/quark.cc
View File

@@ -21,7 +21,7 @@
namespace
{
auto constexpr my_static = std::array<std::string_view, 390>{ "",
auto constexpr my_static = std::array<std::string_view, 391>{ "",
"activeTorrentCount",
"activity-date",
"activityDate",
@@ -303,6 +303,7 @@ auto constexpr my_static = std::array<std::string_view, 390>{ "",
"rpc-username",
"rpc-version",
"rpc-version-minimum",
"rpc-version-semver",
"rpc-whitelist",
"rpc-whitelist-enabled",
"scrape",

1
libtransmission/quark.h
View File

@@ -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,

9
libtransmission/rpcimpl.cc
View File

@@ -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;

3
tests/libtransmission/rpc-test.cc
View File

@@ -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<tr_quark, 54>{
auto const expected_keys = std::array<tr_quark, 55>{
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,