shim: trackers/web-seeds + session ops + ABI-skew gate (ABI v6→v7)

README.md

@@ -150,18 +150,19 @@ These are load-bearing and enforced in the code:
 
 ## API at a glance
 
-58 public `bt*` handlers (full signatures in **[api-reference](docs/api-reference.md)**):
+69 public `bt*` handlers (full signatures in **[api-reference](docs/api-reference.md)**):
 
 | Group | Handlers |
 |---|---|
-| Session | `btStartSession` · `btStopSession` · `btLastError` · `btClearError` |
+| Session | `btStartSession` · `btStopSession` · `btLastError` · `btClearError` · `btSessionPause` · `btSessionResume` · `btSessionIsPaused` · `btListenPort` · `btFindTorrent` · `btDhtAnnounce` |
 | Settings | `btSetInt` · `btSetBool` · `btSetString` · `btGetSetting` · `btSetEncryption` |
 | Add / remove | `btAddMagnet` · `btAddTorrentFile` · `btAddTorrentWithResume` · `btRemoveTorrent` |
 | Control | `btPause` · `btResume` · `btForceRecheck` · `btForceReannounce` · `btScrapeTracker` · `btClearTorrentError` |
 | Priorities / limits | `btSetFilePriority` · `btSetFilePriorities` · `btSetPiecePriority` · `btSetTorrentLimits` · `btSetMaxConnections` · `btSetMaxUploads` |
 | Flags / modes | `btSetTorrentFlags` · `btUnsetTorrentFlags` · `btSetSequentialDownload` · `btSetAutoManaged` · `btSetSuperSeeding` · `btSetShareMode` · `btSetUploadMode` |
 | Queue / storage | `btQueuePosition` · `btQueueUp` · `btQueueDown` · `btQueueTop` · `btQueueBottom` · `btMoveStorage` |
 | Inspect | `btTorrentStatus` · `btTorrentCount` · `btTorrentHandleAt` · `btInfoHash` · `btPieceBitfield` · `btPeerList` · `btFileList` · `btPieceAvailability` |
+| Trackers / seeds | `btTrackers` · `btAddTracker` · `btWebSeeds` · `btAddWebSeed` · `btRemoveWebSeed` |
 | Events | `btPoll` |
 | DHT | `btDhtAddBootstrap` · `btDhtState` · `btDhtSaveState` · `btDhtLoadState` |
 | DHT key-value (BEP44) | `btDhtKeypair` · `btDhtPutImmutable` · `btDhtGetImmutable` · `btDhtPutMutable` · `btDhtGetMutable` |

docs/api-reference.md

@@ -119,6 +119,36 @@ MSE / protocol-encryption (PE) policy, mapped straight to libtorrent's
 
 ---
 
+## Session operations
+
+### `btSessionPause(in pSession as Integer) returns Integer` · `btSessionResume(in pSession as Integer) returns Integer`
+Pause / resume the **whole session** - every torrent at once. Distinct from the
+per-torrent `btPause` / `btResume`.
+- **Usage:** command - `btSessionPause sSession`.
+
+### `btSessionIsPaused(in pSession as Integer) returns Boolean`
+`true` if the session is paused. `false` on no session.
+- **Usage:** function - `if btSessionIsPaused(sSession) then ...`.
+
+### `btListenPort(in pSession as Integer) returns Integer`
+The TCP port the session actually ended up listening on, or `0` if it is not
+listening yet (or on a bad handle).
+- **Usage:** function - `put btListenPort(sSession) into tPort`.
+
+### `btFindTorrent(in pSession as Integer, in pInfoHash as String) returns Integer`
+Look up an already-added torrent by its **40-hex (v1) info-hash**; returns the
+torrent handle, or `0` if it is not in this session. Lets you recover a handle
+from a hash you stored earlier instead of keeping the integer around.
+- **Usage:** function - `put btFindTorrent(sSession, tHashHex) into tH`.
+
+### `btDhtAnnounce(in pSession as Integer, in pInfoHash as String, in pPort as Integer) returns Integer`
+Classic **BEP 5** DHT peer announce (not BEP 44): advertise to the DHT that we
+serve peers for `pInfoHash` (40-hex) on `pPort` (`0` == our listen port). Useful
+for announcing your own content's info-hash so others can find you swarm-side.
+- **Usage:** command - `btDhtAnnounce sSession, tHashHex, 0`.
+
+---
+
 ## Add / remove torrents
 
 ### `btAddMagnet(in pSession as Integer, in pURI as String, in pSavePath as String) returns Integer`
@@ -337,6 +367,28 @@ have) for a full piece map. Empty `Data` until the torrent has metadata and
 peers, or on a bad handle.
 - **Usage:** function - `put btPieceAvailability(tH) into tAvail`, then `byte i of tAvail`.
 
+### `btTrackers(in pTorrent as Integer) returns List`
+The torrent's trackers as a `List` of `Array`s, each with keys `url`, `tier`
+(0 == first tier tried), `verified` (`1` once the tracker has answered this
+session), and `source` (the `announce_entry` source bitmask). Empty `List` on a
+bad handle.
+- **Usage:** function - `repeat for each element tTr in btTrackers(tH)` then read `tTr["url"]`.
+
+### `btAddTracker(in pTorrent as Integer, in pUrl as String, in pTier as Integer) returns Integer`
+Add an announce URL at `pTier` (0 == first tier). A URL already in the list is
+ignored by libtorrent.
+- **Usage:** command - `btAddTracker tH, "udp://tracker.example:6969/announce", 0`.
+
+### `btWebSeeds(in pTorrent as Integer) returns List`
+The torrent's HTTP (URL / web) seeds as a `List` of URL `String`s. Empty `List`
+on a bad handle.
+- **Usage:** function - `put btWebSeeds(tH) into tSeeds`.
+
+### `btAddWebSeed(in pTorrent as Integer, in pUrl as String) returns Integer` · `btRemoveWebSeed(in pTorrent as Integer, in pUrl as String) returns Integer`
+Add or remove an HTTP (URL / web) seed (BEP 19) — a plain web server that can
+serve the torrent's data alongside peers.
+- **Usage:** command - `btAddWebSeed tH, "https://mirror.example/path/"`.
+
 ---
 
 ## Events / poll
@@ -527,6 +579,17 @@ arithmetic.
 | `progress` | 122 | int | bytes of this file downloaded |
 | `priority` | 123 | int | this file's download priority, `0..7` |
 
+### Tracker entry (`btTrackers`, one array per tracker)
+
+| key | field id | type | meaning |
+|---|---|---|---|
+| `url` | 130 | utf8 | announce URL |
+| `tier` | 131 | int | tracker tier (`0` == first) |
+| `verified` | 132 | int | `1` once it has answered this session |
+| `source` | 133 | int | `announce_entry` source bitmask |
+
+(`btWebSeeds` returns a plain list of URL strings, not records.)
+
 ### DHT state (`btDhtState`)
 
 | key | field id | type | meaning |

src/btx_abi.h

@@ -47,7 +47,7 @@ extern "C" {
  * signature, a new record fieldId or alert code, or a framing change. The LCB
  * layer hard-codes the matching number in checkABI() and refuses to run on
  * skew. Start at 1. */
-#define BTX_ABI_VERSION 5
+#define BTX_ABI_VERSION 7
 
 /* ----------------------------------------------------------- export linkage */
 
@@ -129,6 +129,28 @@ BTX_API int BTX_CALL btx_get_setting(int s, const char *key, char *out, int cap)
 BTX_API int BTX_CALL btx_set_encryption_policy(int s, int inPolicy,
                                                int outPolicy, int level);
 
+/* ====================================================================== *
+ *  Session operations (ABI v7) — whole-session pause, listen port, look up a
+ *  torrent by info-hash, classic (BEP5) DHT peer announce.
+ * ====================================================================== */
+
+/* Pause / resume the WHOLE session (all torrents); is_paused returns 1/0 (0 on
+ * no session). Distinct from per-torrent btx_pause/btx_resume. */
+BTX_API int BTX_CALL btx_session_pause(int s);
+BTX_API int BTX_CALL btx_session_resume(int s);
+BTX_API int BTX_CALL btx_session_is_paused(int s);
+
+/* The TCP port we actually ended up listening on (0 == not listening yet). */
+BTX_API int BTX_CALL btx_listen_port(int s);
+
+/* Look up an already-added torrent by its 40-hex (v1) info-hash; returns OUR
+ * torrent handle id, or 0 if not found / bad args. */
+BTX_API int BTX_CALL btx_find_torrent(int s, const char *infoHashHex);
+
+/* Classic BEP5 DHT peer announce (NOT BEP44): tell the DHT we have peers for
+ * this 40-hex info-hash on `port` (0 == our listen port). Fire-and-forget. */
+BTX_API int BTX_CALL btx_dht_announce(int s, const char *infoHashHex, int port);
+
 /* ====================================================================== *
  *  Add / remove torrents
  * ====================================================================== */
@@ -236,6 +258,24 @@ BTX_API int BTX_CALL btx_file_list(int t, void *out, int cap);
  * availability grid. bytes-written / -needed / 0, like btx_piece_bitfield. */
 BTX_API int BTX_CALL btx_piece_availability(int t, void *out, int cap);
 
+/* ---- trackers & web seeds (ABI v6) ----------------------------------------
+ * Inspect and edit a torrent's tracker list and HTTP/URL (web) seeds. The two
+ * listers return count-prefixed KV-record lists (the peer-list framing); the
+ * editors are fire-and-forget actions. */
+
+/* The torrent's trackers as a list of KV records: url, tier, verified, source. */
+BTX_API int BTX_CALL btx_trackers(int t, void *out, int cap);
+
+/* Add an announce URL at the given tier (0 == first tier; libtorrent dedups). */
+BTX_API int BTX_CALL btx_add_tracker(int t, const char *url, int tier);
+
+/* Add / remove an HTTP (URL / web) seed (BEP 19). */
+BTX_API int BTX_CALL btx_add_url_seed(int t, const char *url);
+BTX_API int BTX_CALL btx_remove_url_seed(int t, const char *url);
+
+/* The torrent's web seeds as a list of KV records (one F_URL_SEED field each). */
+BTX_API int BTX_CALL btx_url_seeds(int t, void *out, int cap);
+
 /* ====================================================================== *
  *  The alert drain (the event firehose) — one FFI round-trip per poll (§3)
  * ====================================================================== */

src/btx_record.h

@@ -131,7 +131,14 @@ enum FieldId : uint8_t {
     F_FILE_PATH         = 120, /* utf8: file path within the torrent (relative) */
     F_FILE_SIZE         = 121, /* int (64-bit): file size in bytes */
     F_FILE_PROGRESS     = 122, /* int (64-bit): bytes of this file downloaded */
-    F_FILE_PRIORITY     = 123  /* int 0..7: this file's download priority */
+    F_FILE_PRIORITY     = 123, /* int 0..7: this file's download priority */
+
+    /* ---- tracker + web-seed entries (130..139) ---- */
+    F_TRACKER_URL       = 130, /* utf8: announce URL */
+    F_TRACKER_TIER      = 131, /* int: tracker tier (0 == first tier) */
+    F_TRACKER_VERIFIED  = 132, /* int 0/1: has answered at least once this session */
+    F_TRACKER_SOURCE    = 133, /* int: announce_entry source bitmask */
+    F_URL_SEED          = 134  /* utf8: a web-seed (URL seed) address */
 };
 
 /* ------------------------------------------------------------- alert codes */