refactor: harden and modernize rtapi

Author: pyed

.github/workflows/ci.yml

@@ -0,0 +1,49 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+env:
+  GOWORK: "off"
+
+jobs:
+  verify:
+    name: Go ${{ matrix.go }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        go: ["1.26.7", "1.27.0"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
+        with:
+          go-version: ${{ matrix.go }}
+          cache: false
+      - name: Verify module
+        run: |
+          go mod tidy -diff
+          go mod verify
+      - name: Test, vet, and build
+        run: |
+          go test -count=1 ./...
+          go vet ./...
+          go build ./...
+      - name: Race detector
+        if: matrix.go == '1.26.7'
+        run: go test -race -count=1 ./...
+      - name: 32-bit tests
+        if: matrix.go == '1.26.7'
+        run: GOARCH=386 CGO_ENABLED=0 go test -count=1 ./...
+      - name: Vulnerability scan
+        if: matrix.go == '1.26.7'
+        uses: golang/govulncheck-action@032d45514ae346b1db93c04b0c90b841c370344f # v1.1.0
+        with:
+          repo-checkout: false
+          go-version-input: "1.26.7"
+          go-package: ./...

README.md

@@ -1,39 +1,82 @@
 # rtapi
-Raw rTorrent XML-RPC in Go, Written for [rtelegram](https://github.com/pyed/rtelegram)
+
+`rtapi` is a small Go client for rTorrent's XML-RPC interface over SCGI. It is
+the library used by [rtelegram](https://github.com/pyed/rtelegram).
 
 ## Requirements
-* [`rTorrent`](https://github.com/rakshasa/rtorrent) compiled with `--with-xmlrpc-c`.
-* `scgi_port = localhost:5000` in your `.rtorrent.rc`
 
-## How to get
-`go get github.com/pyed/rtapi`
+- 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](https://github.com/rakshasa/rtorrent-doc/blob/master/RPC-Setup-XMLRPC.md).
 
-## How to use
-``` go
+## Install
+
+```sh
+go get github.com/pyed/rtapi@latest
+```
+
+## Example
+
+```go
 package main
 
 import (
 	"fmt"
+	"log"
 
 	"github.com/pyed/rtapi"
 )
 
 func main() {
-	rt, err := rtapi.NewRtorrent("localhost:5000") // Or /path/to/socket for "scgi_local".
+	rt, err := rtapi.NewRtorrent("/run/user/1000/rtorrent.sock")
 	if err != nil {
-		// ...
+		log.Fatal(err)
 	}
 
-	// Get torrents
 	torrents, err := rt.Torrents()
 	if err != nil {
-		// ...
+		log.Fatal(err)
 	}
-
-	fmt.Println("Number of torrents:", len(torrents))
-
-	for _, t := range torrents {
-		fmt.Println(t.Name)
+	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. 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.
+- `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.
+- `Torrents.Sort` takes an explicit `rtapi.Sorting` value. The unsafe
+  process-global `CurrentSorting` variable was removed; call `Sort` on each
+  returned value instead.
+- `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
+
+```sh
+go test ./...
+go vet ./...
+go build ./...
+```

go.mod

@@ -1,3 +1,3 @@
 module github.com/pyed/rtapi
 
-go 1.24.3
+go 1.26.0

public_test.go

@@ -0,0 +1,22 @@
+package rtapi_test
+
+import (
+	"testing"
+
+	"github.com/pyed/rtapi"
+)
+
+var _ interface {
+	Stats() (*rtapi.Stats, error)
+	DownloadRaw([]byte, *rtapi.DotTorrentWithOptions) error
+	DeleteMetadata(...*rtapi.Torrent) error
+	SpeedsWithError() (uint64, uint64, error)
+} = (*rtapi.Rtorrent)(nil)
+
+func TestPublicTypesAreNameable(t *testing.T) {
+	var sorting rtapi.Sorting = rtapi.ByName
+	var stats *rtapi.Stats
+	if sorting != rtapi.ByName || stats != nil {
+		t.Fatal("unexpected public type values")
+	}
+}