Belajar Aria2 - RPC: JSON-RPC & XML-RPC

#Pendahuluan

Di episode 14 pintu RPC sudah terkunci dengan token. Sekarang saatnya belajar bahasa yang dipakai di balik pintu itu: JSON-RPC. Selama ini kalian mengendalikan aria2 lewat command line; mulai episode ini kalian mengendalikannya lewat perintah yang dikirim sebagai data — dan itulah fondasi dari seluruh ekosistem frontend, script otomasi, dan download server yang akan kita bangun di episode-episode berikutnya.

Episode 15 membedah antarmuka RPC dari bawah ke atas: menyalakan daemon, memahami struktur request dan respons JSON-RPC 2.0, mengenal method-method inti, memanfaatkan notifikasi event, lalu mempraktikkan semuanya dengan curl dan jq dari terminal.

#Menyalakan Daemon RPC

RPC tidak aktif secara default — harus dihidupkan eksplisit:

enable-rpc.sh

aria2c --enable-rpc \
  --rpc-secret="rahasia-panjang-acak" \
  --rpc-listen-port=6800

--enable-rpc menyalakan daemon RPC, --rpc-secret menguncinya (episode 14), dan --rpc-listen-port=6800 memastikan port standarnya — 6800 — yang didengar. Setelah daemon berjalan, endpoint JSON-RPC hidup di http://127.0.0.1:6800/jsonrpc.

#Dua Dialek: JSON-RPC dan XML-RPC

aria2 berbicara dua protokol RPC sekaligus: JSON-RPC 2.0 di path /jsonrpc dan XML-RPC di path /xmlrpc. JSON lebih ringkas, lebih mudah dibaca, dan menjadi pilihan default semua tool modern; XML-RPC adalah dialek warisan yang tetap didukung untuk kompatibilitas. Kita fokus ke JSON-RPC, dan XML-RPC kita sentuh sekilas di akhir episode.

#Anatomi Request JSON-RPC 2.0

Setiap request adalah satu objek JSON dengan empat kunci: jsonrpc, id, method, dan params. Contoh nyata untuk menambah download baru:

request-adduri.json

{
  "jsonrpc": "2.0",
  "id": "add-1",
  "method": "aria2.addUri",
  "params": [
    "token:rahasia-panjang-acak",
    ["https://example.com/file.zip", "https://mirror.example.com/file.zip"]
  ]
}

Empat kunci tersebut punya peran yang jelas:

jsonrpc — versi protokol, selalu "2.0".
id — penanda request agar respons bisa dicocokkan; nilainya bebas, string atau angka.
method — nama fungsi yang dipanggil, selalu berawalan aria2..
params — argumen method; saat RPC dilindungi token, elemen pertama adalah string token berawalan token:.

Setiap request berbalas satu respons yang membawa id yang sama. Untuk aria2.addUri, hasilnya adalah gid — identitas unik download:

response.json

{
  "id": "add-1",
  "jsonrpc": "2.0",
  "result": "2089b05ecca3d829"
}

result dari aria2.addUri berupa string gid 16 karakter. Setiap operasi lanjutan terhadap download itu — memeriksa status, menjeda, menghapus — memakai gid ini sebagai alamatnya.

#Method-Method Inti

Beberapa method yang akan kalian pakai hampir setiap hari:

Semua method mengikuti pola yang sama: params berisi token (elemen pertama), lalu argumen sesuai kebutuhan. aria2.tellStatus meminta gid, aria2.getGlobalStat tanpa argumen selain token, dan aria2.remove maupun aria2.pause meminta gid. Hafalkan pasangan method-gid ini — ia akan menjadi bahasa sehari-hari kalian bersama daemon.

#Curl + jq: RPC dari Terminal

Cara tercepat menguji dan memakai RPC adalah curl. Tambah download baru:

rpc-add.sh

curl -s http://127.0.0.1:6800/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"add-1","method":"aria2.addUri","params":["token:rahasia-panjang-acak",["https://example.com/file.zip"]]}'

Responsnya berupa JSON mentah. Untuk membaca status download dengan gid, kirim aria2.tellStatus dan olah hasilnya dengan jq — pipeline favorit di dunia script:

rpc-status-jq.sh

curl -s http://127.0.0.1:6800/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"s-1","method":"aria2.tellStatus","params":["token:rahasia-panjang-acak","2089b05ecca3d829"]}' \
  | jq '.result | {gid, status, totalLength, completedLength, downloadSpeed}'

Filter jq memilih hanya field yang menarik: gid, status, ukuran total dan selesai, serta kecepatan saat ini. Untuk statistik seluruh daemon:

rpc-global.sh

curl -s http://127.0.0.1:6800/jsonrpc \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"g-1","method":"aria2.getGlobalStat","params":["token:rahasia-panjang-acak"]}' \
  | jq '.result'

Kombinasi curl dan jq ini adalah dasar dari hampir semua integrasi: daemon tetap diendalikan lewat data, bukan lewat interaksi manusia — dan data itu mudah diolah oleh script apa pun.

#Notifikasi dan Event

Polling terus-menerus itu boros. aria2 menyediakan jalan yang lebih elegan: notifikasi. Ketika peristiwa tertentu terjadi, daemon mendorong event kepada klien yang terhubung, misalnya aria2.onDownloadStart, aria2.onDownloadComplete, dan aria2.onDownloadError. Notifikasi dikirim lewat koneksi WebSocket di endpoint yang sama (/jsonrpc); untuk koneksi HTTP murni, klien biasanya memakai polling dengan aria2.tellActive atau aria2.tellStatus.

Pola event-driven ini membalik cara berpikir: alih-alih menanyai daemon "sudah selesai belum?" setiap dua detik, klien cukup menunggu diberi tahu "sudah selesai". Untuk satu download, polling sederhana cukup; untuk sistem yang mengelola ratusan download, notifikasi adalah perbedaan antara mesin yang ribut dan mesin yang tenang.

#Integrasi ke Script

Semua bagian tadi dirangkai menjadi script monitoring lengkap: tambah download, catat gid, lalu polling sampai selesai.

rpc-monitor.sh

#!/usr/bin/env bash
set -euo pipefail
 
SECRET="rahasia-panjang-acak"
URL="https://example.com/file.zip"
RPC="http://127.0.0.1:6800/jsonrpc"
 
GID=$(curl -s "$RPC" -H "Content-Type: application/json" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":\"add\",\"method\":\"aria2.addUri\",\"params\":[\"token:$SECRET\",[\"$URL\"]]}" \
  | jq -r '.result')
echo "download dimulai: $GID"
 
while :; do
  STATUS=$(curl -s "$RPC" -H "Content-Type: application/json" \
    -d "{\"jsonrpc\":\"2.0\",\"id\":\"s\",\"method\":\"aria2.tellStatus\",\"params\":[\"token:$SECRET\",\"$GID\"]}" \
    | jq -r '.result.status')
  echo "status: $STATUS"
  [ "$STATUS" = "complete" ] && break
  sleep 2
done
 
echo "selesai: $URL"

Perhatikan pola yang dipakai: JSON-RPC request dibangun dengan string yang di-escape di dalam double quote, nilai dari variabel disisipkan saat request, dan jq -r mengambil satu nilai saja. Script semacam ini bisa diperluas menjadi antrean download, pemberitahuan ke chat, atau pemicu proses setelah download selesai — kita dalami di episode scripting nanti.

#XML-RPC Selintas

Untuk kelengkapan, begini wujud dialek lama yang sama di endpoint /xmlrpc:

xmlrpc-getversion.xml

<?xml version="1.0"?>
<methodCall>
  <methodName>aria2.getVersion</methodName>
  <params>
    <param>
      <value>
        <string>token:rahasia-panjang-acak</string>
      </value>
    </param>
  </params>
</methodCall>

Struktur yang sama — method dan params — hanya dibungkus markup XML yang lebih berisik. Itulah sebabnya hampir semua ekosistem modern memilih JSON-RPC, dan kita pun akan terus memakainya di episode-episode berikutnya.

#Penutup

Episode 15 membuka bahasa di balik pintu RPC: menyalakan daemon dengan --enable-rpc, memahami struktur request dan respons JSON-RPC 2.0, mengenal method inti seperti aria2.addUri dan aria2.tellStatus, memanfaatkan notifikasi event, serta mempraktikkan curl dan jq untuk interaksi langsung dan integrasi script.

Inti yang perlu diingat: RPC mengubah aria2 dari alat yang kalian ketik menjadi layanan yang kalian panggil — dan siapa pun yang bisa memanggilnya, bisa mengendalikannya. Bahasa ini adalah jembatan menuju seluruh ekosistem di sekitarnya.

Di episode 16 berikutnya kita memanfaatkan jembatan itu: Web UI & ekosistem frontend — memasang AriaNg sebagai dashboard berbasis browser, menghubungkannya dengan token, serta mengintegrasikan ekstensi browser agar klik download diarahkan ke aria2. Sampai jumpa!