PDA

View Full Version : Client File Format



anthony-joal
11.08.17, 19:42
Hi there !
While reading this keep in mind that it is a proposal and your ideas are welcome.

1. Client file format
In order to share client file definition, we should agree on a format that everyone could understand. This thread is a proposal on this subject.
The below definition is a definition format example.


{
"keyGenerator": {
"length": 8,
"type": "hash",
"refreshOn": "TIMED_OR_AFTER_STARTED_ANNOUNCE",
"refreshEvery": 10,
"case": "upper"
},
"peerIdGenerator": {
"pattern": "-NOP1000(\u008d\u00ab)[\u0001-\u00ff]{10}",
"refreshOn": "NEVER",
"shouldUrlEncode": true
},
"urlEncoder": {
"encodingExclusionPattern": "[A-Za-z0-9-]",
"encodedHexCase": "lower"
},
"query": "info_hash={infohash}&peer_id={peerid}&port={port}&uploaded={uploaded}&downloaded={downloaded}&left={left}&corrupt=0&key={key}&event={event}&numwant={numwant}&compact=1&no_peer_id=1",
"numwant": 200,
"numwantOnStop": 0,
"requestHeaders": [
{ "name": "host", "value": "xxxxx"}
{ "name": "User-Agent", "value": "xxxxx" },
.....
]
}

Key generator:

length: Length of the key, however if type is hash_no_leading_zero, the key may be shorter.
type: Type of the key (see available types in CFT (https://www.sb-innovation.de/f275/client-file-terminology-33446/)).
refreshOn: When the key should be refreshed (see available triggers in CFT (https://www.sb-innovation.de/f275/client-file-terminology-33446/)).
refreshEvery: If the key refresh is triggered by a timer, this defines the timer (in seconds). If the trigger is not a timer this parameter MUST be ommited.
case: Define the casing of the key (lower, upper, none). With none accepting both upper and lower in the key.


PeerId generator:

pattern: A regex pattern that matches the peerId (accepting unicode characters).
refreshOn: When the peerid should be refreshed (see available triggers in CFT (https://www.sb-innovation.de/f275/client-file-terminology-33446/)).
refreshEvery: If the peerid refresh is triggered by a timer, this defines the timer (in seconds). If the trigger is not a timer this parameter MUST be ommited.
shouldUrlEncode: Define if the peerid should be url encoded or not.


Url encoder:

encodingExclusionPattern: Define which characters musn't be encoded, if empty all characters must be encoded.
encodedHexCase: Define the casing of the encoded characters (lower, upper, none) and only the encoded characters. For example, if the url-encoded string is %a2Pmb and the casing is upper it will result in %A2Pmb.


query:
The query format (with placeholders for values).

Numwants

numwant: The numwant to be reported on all events except for STOPPED.
numwantOnStop: The numwant to be reported on STOPPED events.


requestHeaders
A list of headers and theirs values, some values can be replaced by placeholders.



2. Placeholders
In announce queries and HTTP Headers there is a lot of dynamical values :{infohash}, {downloaded} and so on. The following values have been identified so far.
In Announce URL
Some clients URL encode some of these properties.

infohash: Each torrent have an info-hash this is some kind of an ID card. This is an hash and every BitTorrent clients will have the same info-hash for a given .torrent file.
peerid: This is the client identifier in the crowd, follows a specific pattern for each BitTorrent clients. Also, the peerid is refreshed by different triggers (triggers can be found in CFT (https://www.sb-innovation.de/f275/client-file-terminology-33446)).
port: The port that the BitTorrent client listen on for peer connection.
uploaded: How many bytes have been uploaded since announce STARTED.
downloaded: How many bytes have been downloaded since announce STARTED.
left: How many bytes needs to be downloaded in order to have fully ownlaoded the torrent content.
key: Each BitTorrent clients will generate his key with a specific pattern (types can be found in CFT (https://www.sb-innovation.de/f275/client-file-terminology-33446)). Also, the key is refreshed by different triggers (triggers can be found in CFT (https://www.sb-innovation.de/f275/client-file-terminology-33446)).
event: Define for which purpose the BitTorrent client is sending the announce, if NONE, the event MUST be removed from the announce URL.
numwant: number of peers to be returned by trackers.
ip: The BitTorrent's client public IP.
ipv6: The BitTorrent's client public IPV6.
localip: The BitTorrent's client private (local) IP (192.xxx.xxx.xxx).



In HTTP headers

host: The host to send the request to.
java: The Java Runtime Environment version used by BitTorrent client (like so: 1.8.0_66).
os: The OS BitTorrent client is running on (Windows 10, Linux, ...).
locale: The system locale (like so: en-US, en-GB, fr-FR, ...).

anthony-joal
13.08.17, 15:31
Updated to make the client file definition more readable.

If an admin comes by, can you please rename this Thread to : "Client file format"?