rtapi

rtapi is a small Go client for rTorrent's XML-RPC interface over SCGI. It is the library used by rtelegram.

Requirements

• Go 1.26 or newer.
• rTorrent built with XML-RPC support.
• A local SCGI endpoint such as a protected Unix socket or scgi_port = 127.0.0.1:5000.

The rTorrent RPC endpoint has no authentication and exposes powerful methods. Prefer a permission-protected Unix socket. Never expose SCGI directly to an untrusted network; see rTorrent's official XML-RPC security guidance.

Install

go get github.com/pyed/rtapi@latest

Example

package main

import (
	"fmt"
	"log"

	"github.com/pyed/rtapi"
)

func main() {
	rt, err := rtapi.NewRtorrent("/run/user/1000/rtorrent.sock")
	if err != nil {
		log.Fatal(err)
	}

	torrents, err := rt.Torrents()
	if err != nil {
		log.Fatal(err)
	}
	for _, torrent := range torrents {
		fmt.Printf("%s: %d/%d bytes\n", torrent.Name, torrent.Completed, torrent.Size)
	}
}

TCP addresses such as 127.0.0.1:5000 are also accepted, as are http:// and https:// XML-RPC URLs for rTorrent behind a web server, such as https://user:password@seedbox.example/RPC2. Credentials in the URL are sent with HTTP basic authentication and kept out of error messages; requests use http.DefaultClient, which honors HTTPS_PROXY.

Every method has a ...Context variant, such as TorrentsContext, and NewRtorrentContext. Cancelling the context interrupts the request. Cancellations and timeouts match context.Canceled and context.DeadlineExceeded with errors.Is. Every SCGI request is bounded by rtapi.DefaultTimeout (30 seconds) unless Rtorrent.Timeout is set. Responses default to a 16 MiB safety bound; set Rtorrent.MaxResponseSize when a legitimately large library needs more. Transport errors, malformed responses, and XML-RPC faults are returned to the caller; errors.As can inspect an *rtapi.XMLRPCFault.

Important APIs and compatibility

• Transfer fields (Size, Completed, and UpTotal) contain exact byte counts.
• Path (d.base_path) is empty until rTorrent opens a torrent. Directory and MultiFile are always reported: Directory is the data directory of a multi-file torrent, or the directory containing a single-file torrent's file.
• SpeedsWithError reports failures. Speeds remains as a deprecated compatibility shim that cannot distinguish failure from zero traffic.
• DownloadRaw loads torrent bytes directly, avoiding credential-bearing intermediary URLs. DownloadWithOptions remains available for URL loading. Set DotTorrentWithOptions.Stopped to load a torrent without starting it. An empty Dir or Label leaves rTorrent's default. URL loads use rTorrent's verbose load commands, so rTorrent logs why a link failed to load.
• GetTorrent requests only the one torrent rather than listing them all.
• Torrent.Finished is when a torrent completed, in Unix seconds.
• Files lists a torrent's files, and SetFilePriorities skips or prioritizes them by index (FileSkip, FileNormal, FileHigh).
• GlobalLimits and SetGlobalLimits read and set the global download and upload rate limits, in bytes per second; zero means unlimited.
• FreeDiskSpace reports the free space on the filesystem holding a torrent.
• Torrents.Sort takes an explicit rtapi.Sorting value. The unsafe process-global CurrentSorting variable was removed; call Sort on each returned value instead. Sorting is stable and compares names case-insensitively.
• DeleteMetadata erases metadata only after rTorrent acknowledges the RPC. The older Delete(false, ...) form remains as a deprecated compatibility shim.
• Delete(true, ...) returns ErrUnsafeDataDelete before any RPC or local filesystem access. Data belongs to the rTorrent host; an application that offers data deletion must enforce its own explicit local root and containment policy.

Development

go test ./...
go vet ./...
go build ./...