class

Transmission::RPC::Client

Inherits Reference < Object

A client for the Transmission BitTorrent RPC API.

Speaks both Transmission dialects (see {Protocol}): the JSON-RPC 2.0 modern protocol of 4.1.0+ and the classic protocol understood by every version (the only one 4.0.x speaks). The public API is snake_case throughout regardless of dialect; classic translation happens internally via {ClassicCodec}.

By default the client auto-detects the daemon's dialect on its first call (probing once and caching the result). Pass protocol: to force one.

Built on json-rpc: a {SessionTransport} handles the X-Transmission-Session-Id CSRF dance (shared by both dialects), and a JSON::RPC::Client handles the modern envelope.

client = Transmission::RPC::Client.new(
  "http://nas.local:9091/transmission/rpc",
  username: "admin", password: "secret")

client.torrent_get.each do |torrent|
  puts "#{torrent.name}: #{torrent.state}"
end

Constants

DEFAULT_FIELDS = (["id", "hashString", "name", "status", "totalSize", "sizeWhenDone", "leftUntilDone", "percentDone", "percentComplete", "metadataPercentComplete", "recheckProgress", "rateDownload", "rateUpload", "eta", "uploadRatio", "uploadedEver", "downloadedEver", "seedRatioLimit", "seedRatioMode", "bandwidthPriority", "queuePosition", "peersConnected", "downloadDir", "isFinished", "isStalled", "isPrivate", "error", "errorString", "labels", "addedDate", "doneDate", "startDate", "activityDate"] of ::String).map do |field| field.gsub(/[A-Z]/) do |match| "_#{match.downcase}" end end

A sensible default set of fields to request from torrent_get. Covers everything in the {Torrent} struct's commonly used attributes.

DEFAULT_URL = "http://localhost:9091/transmission/rpc"

The default RPC endpoint exposed by a stock Transmission daemon.

Constructors

new(url : String | URI, *, username : String | Nil = nil, password : String | Nil = nil, protocol : Protocol = Protocol::Auto)

Builds a client speaking to url, optionally with HTTP Basic auth.

protocol selects the dialect; the default {Protocol::Auto} probes the daemon on first use.

new(rpc : JSON::RPC::Client, *, protocol : Protocol = Protocol::Auto)

Builds a client over an existing JSON-RPC client. Useful for injecting a custom or stubbed transport.

new(*, username : String | Nil = nil, password : String | Nil = nil, protocol : Protocol = Protocol::Auto) : self

Builds a client speaking to {DEFAULT_URL}, optionally with HTTP Basic auth. (Separate from the url overload so the JSON-RPC-client injection overload below stays unambiguous.)

Instance methods

blocklist_update

Updates the blocklist and returns the new blocklist size.

free_space(path : String) : FreeSpace

Reports free and total space for the filesystem containing path.

group_get(name = nil) : JSON::Any

Retrieves bandwidth group settings. Pass name (a string or array of strings) to fetch specific groups; omit for all. Returned as raw JSON::Any.

group_set(name : String, **fields) : Nil

Updates a bandwidth group's settings, creating it if necessary.

port_test(ip_protocol : String | Nil = nil) : PortTest

Tests whether the peer port is reachable. ip_protocol may be "ipv4" or "ipv6".

protocol

The configured protocol mode. {Protocol::Auto} resolves to {Protocol::Modern} or {Protocol::Classic} on the first call.

queue_move_bottom(ids) : Nil

Moves the given torrents to the bottom of the queue.

queue_move_down(ids) : Nil

Moves the given torrents down one position in the queue.

queue_move_top(ids) : Nil

Moves the given torrents to the top of the queue.

queue_move_up(ids) : Nil

Moves the given torrents up one position in the queue.

resolved_protocol

The dialect resolved by auto-detection, or nil until the first call under {Protocol::Auto}. When protocol is forced this mirrors it.

rpc

The underlying JSON-RPC client.

session_close

Asks the daemon to shut down.

session_get(fields : Array(String) | Nil = nil) : JSON::Any

Retrieves session settings. Pass fields to fetch a subset; omit for all settings. Returned as raw JSON::Any given the large, evolving set of session fields.

session_set

Updates session settings. Pass any mutable setting as a keyword argument, e.g. session_set(speed_limit_down: 100, speed_limit_down_enabled: true).

session_stats

Retrieves session statistics.

torrent_add(filename : String | Nil = nil, metainfo : String | Nil = nil, *, download_dir : String | Nil = nil, paused : Bool | Nil = nil, labels : Array(String) | Nil = nil, peer_limit : Int32 | Nil = nil, bandwidth_priority : Int32 | Nil = nil, cookies : String | Nil = nil, files_wanted : Array(Int32) | Nil = nil, files_unwanted : Array(Int32) | Nil = nil, priority_high : Array(Int32) | Nil = nil, priority_normal : Array(Int32) | Nil = nil, priority_low : Array(Int32) | Nil = nil) : AddedTorrent

Adds a torrent from a .torrent file path/URL (filename) or from base64-encoded torrent contents (metainfo). Exactly one is required.

Returns the added (or, if already present, duplicate) torrent.

torrent_get(ids = nil, fields : Array(String) = DEFAULT_FIELDS, *, recently_active : Bool = false, table : Bool = false) : Array(Torrent)

Retrieves torrents, parsed into {Torrent} structs.

ids: a single id/hash, an array of them, or nil for all torrents.
fields: the fields to fetch (defaults to {DEFAULT_FIELDS}).
recently_active: true: fetch only recently active torrents.
table: true: request the compact "table" response format (arrays instead of per-field objects) — a smaller payload for large result sets. The rows are reassembled into {Torrent}s transparently.

torrent_get_raw(ids = nil, fields : Array(String) = DEFAULT_FIELDS, *, recently_active : Bool = false, table : Bool = false) : JSON::Any

Like {#torrent_get} but returns the raw JSON::Any result, for fields not covered by the {Torrent} struct. With table: true the torrents member is in Transmission's table layout (a header row followed by value rows).

torrent_reannounce(ids = nil) : Nil

Asks the given torrents to re-announce to their trackers immediately.

torrent_remove(ids, delete_local_data : Bool = false) : Nil

Removes the given torrents, optionally deleting their downloaded data.

torrent_rename_path(ids, path : String, name : String) : JSON::Any

Renames a file or directory within a single torrent. path is the current path within the torrent; name is the new name.

torrent_set(ids, **fields) : Nil

Sets properties on the given torrents. Pass any mutable field as a keyword argument, e.g. torrent_set(ids, labels: ["a"], upload_limit: 50, upload_limited: true).

torrent_set_location(ids, location : String, move : Bool | Nil = nil) : Nil

Moves the given torrents' data to location. With move: true the files are moved; with move: false Transmission searches location for already-present files.

torrent_start(ids = nil, *, now : Bool = false) : Nil

Starts the given torrents (all torrents when ids is nil). With now: true, bypasses the download queue (torrent_start_now).

torrent_stop(ids = nil) : Nil

Stops the given torrents (all torrents when ids is nil).

torrent_verify(ids = nil) : Nil

Verifies the local data of the given torrents.