home *** CD-ROM | disk | FTP | other *** search
/ zankasoftware.com / zankasoftware.com.tar / zankasoftware.com / wired / rfc3.txt < prev    next >
Text File  |  2008-03-21  |  14KB  |  435 lines
  1. Zanka Software                                            Axel Andersson
  2. Request for Comments: 3                                    February 2005
  3.  
  4.                       Wired Tracker Protocol 1.0
  5.  
  6. Status of this Memo
  7.  
  8.    This memo provides information for the Internet community. It 
  9.    describes an Internet protocol. Distribution of this memo is 
  10.    unlimited.
  11.  
  12. Copyright Notice
  13.  
  14.    Copyright (C) Axel Andersson 2004-2005. All Rights Reserved.
  15.  
  16. Abstract
  17.  
  18.    The Wired Tracker protocol is an application-level protocol for
  19.    exchanging information of presently online Wired servers. Servers
  20.    connect to the tracker and register themselves using the Wired
  21.    Tracker protocol. Clients can then fetch information about servers
  22.    by connecting to the tracker and requesting a server listing.
  23.    
  24. Table of Contents
  25.  
  26.    1   Introduction ...................................................2
  27.    1.1   Purpose ......................................................2
  28.    1.2   Terminology ..................................................2
  29.    1.3   Overall Operation ............................................3
  30.    2   Sequences ......................................................3
  31.    2.1   Login Sequence ...............................................3
  32.    3   Registration ...................................................3
  33.    4   Commands .......................................................4
  34.    4.1  Command Format ...,............................................4
  35.    4.2  Command Listing ...............................................4
  36.    4.2.1    CATEGORIES ................................................4
  37.    4.2.2    CLIENT ....................................................4
  38.    4.2.3    HELLO .....................................................5
  39.    4.2.4    REGISTER ..................................................5
  40.    4.2.5    SERVERS ...................................................5
  41.    4.2.6    UPDATE ....................................................6
  42.    5.1  Message Format ................................................6
  43.    5.2  200 Class Messages ............................................6
  44.    5.2.1    200 Tracker Information ...................................6
  45.    5.3  500 Class Messages ............................................7
  46.    5.3.1    500 Command Failed ........................................7
  47.    5.3.2    501 Command Not Recognized ................................7
  48.    5.3.3    502 Command Not Implemented ...............................7
  49.    5.3.4    503 Syntax Error ..........................................7
  50.    5.3.5    511 Banned ................................................7
  51.    5.3.6    516 Permission Denied .....................................7
  52.    5.3.7    530 Address Registered ....................................8
  53.    5.3.8    531 Address Mismatch ......................................8
  54.    5.4  700 Class Messages ............................................8
  55.    5.4.1    700 Registered ............................................8
  56.    5.4.2    710 Category Listing ......................................8
  57.    5.4.3    711 Category Listing Done .................................8
  58.    5.4.4    720 Server Listing ........................................8
  59.    5.4.5    721 Server Listing Done ...................................9
  60.    6   References .....................................................9
  61.    7   Author's Address ...............................................9
  62.    8   Full Copyright Statement .......................................10
  63.  
  64. 1 Introduction
  65.  
  66. 1.1 Purpose
  67.  
  68.    The Wired Tracker protocol is an application-level protocol for
  69.    exchanging information of presently online Wired servers. Servers
  70.    connect to the tracker and register themselves using the Wired
  71.    Tracker protocol. Clients can then fetch information about servers
  72.    by connecting to the tracker and requesting a server listing.
  73.  
  74.    This protocols draws heavily upon the Wired client/server
  75.    protocol. It relies on the same structure, and only adds new
  76.    commands and messages. Refer to the Wired Protocol specification
  77.    [1] for definitions of the protocol parameters that are not
  78.    duplicated in this specification.
  79.  
  80. 1.2 Terminology
  81.  
  82.    client
  83.       A program that establishes connections for the purpose of 
  84.       sending commands and interpreting messages. In this context,
  85.       a client is either a program that connects to the tracker for
  86.       the purpose of retrieving information about servers, or a program
  87.       that connects to the tracker for the purpose of making itself
  88.       available to clients.
  89.  
  90.    command
  91.       A command sent from a client to a tracker, as defined in section 
  92.       4.
  93.  
  94.    identifier
  95.       A unique 3-digit number that describes the type of message.
  96.  
  97.    field
  98.       A part of a command or a message that conveys a particular 
  99.       pre-defined type of information.
  100.  
  101.    message
  102.       A message sent from a tracker to a client, as defined in section 
  103.       4.
  104.  
  105.    tracker
  106.       A program that accepts connections in order to service commands 
  107.       by sending back messages. In this context, a server that has
  108.       both servers and clients as clients.
  109.  
  110. 1.3 Overall Operation
  111.  
  112.    The Wired Tracker protocol is a textual command/message protocol. A
  113.    client sends a command in a specific format to the tracker, and the
  114.    tracker interprets this command, and if needed, sends back a message
  115.    with requested information.
  116.  
  117.    Normal Wired Tracker communication takes place over a TCP/IP
  118.    connection using TLS [2]. The default port is TCP 2002. Servers also
  119.    send status updates to the tracker over UDP on the same port.
  120.  
  121. 2 Sequences
  122.  
  123. 2.1 Login Sequence
  124.  
  125.    The login sequence takes place directly after the client has 
  126.    established a connection with the tracker.
  127.  
  128.    1.  The client initiates the sequence by sending the "HELLO" command.
  129.    
  130.    2.  The tracker responds with the 200 Tracker Information or
  131.        511 Banned  message.
  132.  
  133.    3.  The client optionally sends the "CLIENT" command.
  134.  
  135. 3 Registration
  136.  
  137.    Maintaining a server in the servers list requires that the server
  138.    first connects to the tracker and registers itself, and then
  139.    sends regular status update to verify that it is online.
  140.  
  141.    Registration takes place over the normal TCP/IP connection, using
  142.    the "REGISTER" command. When registering, the tracker associates
  143.    the server with a key, that the server needs to retain. The key
  144.    is sent in the 700 message.
  145.  
  146.    If the URL [3] given in the "REGISTER" command does not match the
  147.    originating host, the tracker can refuse registration.
  148.  
  149.    To send a status update, send the "UPDATE" command to the tracker
  150.    over UDP, with the key as the first argument. It is recommended
  151.    that status updates are sent every minute or so. The tracker
  152.    can interpret a missing status update as a disconnected server
  153.    and remove it from the listing.
  154.  
  155.    Status update messages should be encrypted with the public key
  156.    used for TLS communication over the TCP/IP channel.
  157.  
  158.    The tracker should support re-registration, that is, sending
  159.    a "REGISTER" command with the same URL. This is the only way
  160.    to update the name and description fields.
  161.  
  162. 4 Commands
  163.  
  164. 4.1 Command Format
  165.  
  166.    A command from a client to a server includes a unique command, 
  167.    optionally followed by a single space and arguments. The command is 
  168.    terminated with EOT.
  169.  
  170.       command     = name [SP argument] EOT
  171.       name        = "CATEGORIES"  | "CLIENT"      | "HELLO" |
  172.                     "REGISTER"    | "SERVERS"     | "UPDATE"
  173.  
  174. 4.2 Command Listing
  175.  
  176. 4.2.1 CATEGORIES
  177.  
  178.       "CATEGORIES" EOT
  179.  
  180.    Retrieve the categories list.
  181.  
  182.    On success, returns a chain of 710 and a terminating 711.
  183.  
  184. 4.2.2 CLIENT
  185.  
  186.       "CLIENT" SP app-version EOT
  187.  
  188.    Send the client version information. See section 2.1 for more
  189.    information on the login sequence.
  190.  
  191. 4.2.3 HELLO
  192.  
  193.       "HELLO" EOT
  194.    
  195.    Start a conversation with a tracker. See section 2.1 for more
  196.    information on the login sequence.
  197.  
  198.    On success, returns a 200.
  199.  
  200.    On failure, may return the error 511.
  201.  
  202. 4.2.4 REGISTER
  203.  
  204.       "REGISTER" SP category FS url FS name FS bandwidth FS description
  205.                  EOT
  206.  
  207.       category       = STRING
  208.       url            = STRING
  209.       name           = URL
  210.       bandwidth      = 1*DIGIT
  211.       description    = STRING
  212.    
  213.    Register the sender as a new server. The server will be listed under
  214.    "category", with the URL "url", with "name" and "description" as
  215.    strings that are presented to the user. "bandwidth" is the
  216.    registering server's available bandwidth in bytes/second. See
  217.    section 3 for more information on registration.
  218.  
  219.    On success, returns a 700.
  220.  
  221.    On failure, may return the errors 516, 530 or 531.
  222.  
  223. 4.2.5 SERVERS
  224.  
  225.       "SERVERS" EOT
  226.  
  227.    Retrieve the servers list.
  228.  
  229.    On success, returns a chain of 720 and a terminating 721.
  230.  
  231. 4.2.6 UPDATE
  232.  
  233.       "UPDATE" SP hash FS users FS guest FS download FS files FS
  234.                size EOT
  235.  
  236.       hash        = STRING
  237.       users       = 1*DIGIT
  238.       guest       = BOOLEAN
  239.       download    = BOOLEAN
  240.       files       = 1*DIGIT
  241.       size        = 1*DIGIT
  242.    
  243.    Updates a previously registered server with "hash". "users" is
  244.    the number of online users, "guest" indicates whether the guest
  245.    account can connect, "download" whether the guest account can
  246.    download files, "files" is the number of files and "size" is the
  247.    total byte size of all files.
  248.  
  249. 5 Server Messages
  250.  
  251. 5.1 Message Format
  252.  
  253.    A message from a server to a client includes a unique three-digit 
  254.    number, followed by a space, then optional fields, and a terminator.
  255.  
  256.       message       = identifier [SP argument] EOT
  257.       identifier    = "200"
  258.                       "500" | "501" | "502" | "503" | "511" | "516" |
  259.                       "530"
  260.                       "700" | "710" | "711" | "720" | "720"
  261.  
  262.    The first digit of the identifier defines the class of response. The 
  263.    last two digits do not have any categorization role. There are three 
  264.    values for the first digit:
  265.  
  266.       2xx Information
  267.       5xx Errors
  268.       7xx Tracker
  269.  
  270. 5.2 200 Class Messages
  271.  
  272. 5.2.1 200 Tracker Information
  273.  
  274.       "200" SP app-version FS protocol-version FS
  275.                server-name FS server-description FS
  276.                start-time
  277.  
  278.       server-name           = STRING
  279.       server-description    = STRING
  280.       start-time            = date-time
  281.  
  282.    Basic information about the tracker.
  283.  
  284.    In response to "HELLO".
  285.  
  286. 5.3 500 Class Messages
  287.  
  288. 5.3.1 500 Command Failed
  289.  
  290.       "500" SP "Command Failed" EOT
  291.  
  292.    An undefined internal error prevented the command from completing.
  293.  
  294. 5.3.2 501 Command Not Recognized
  295.  
  296.       "501" SP "Command Not Recognized" EOT
  297.  
  298.    The command was not recognized.
  299.  
  300. 5.3.3 502 Command Not Implemented
  301.  
  302.       "502" SP "Command Not Implemented" EOT
  303.  
  304.    The command has not been implemented by the server.
  305.  
  306. 5.3.4 503 Syntax Error
  307.  
  308.       "503 Syntax Error" EOT
  309.  
  310.    There was a syntax error in the command.
  311.  
  312. 5.3.6 511 Banned
  313.  
  314.       "511" SP "Banned" EOT
  315.  
  316.    The login could not complete, the user is banned.
  317.  
  318. 5.3.11 516 Permission Denied
  319.  
  320.       "516" SP "Permission Denied" EOT
  321.  
  322.    The command could not complete, the client lacks sufficient 
  323.    privileges.
  324.  
  325. 5.3.11 530 Address Registered
  326.  
  327.       "530" SP "Address Registered" EOT
  328.  
  329.    Registration could not complete, a server with that address has already
  330.    been registered.
  331.  
  332. 5.3.11 531 Address Mismatch
  333.  
  334.       "531" SP "Address Mismatch" EOT
  335.  
  336.    Registration could not complete, the address given does not resolve
  337.    back to the originating host.
  338.  
  339. 5.4 500 Class Messages
  340.  
  341. 5.4.1 700 Registered
  342.  
  343.       "700" SP hash EOT
  344.  
  345.    The server was successfully registered and has been associated with the
  346.    key "hash".
  347.  
  348.    In response to "REGISTER".
  349.  
  350. 5.4.2 710 Category Listing
  351.  
  352.       "711" SP category EOT
  353.  
  354.    A category in the categories listing.
  355.  
  356.    The sorting of the categories listing is undefined.
  357.  
  358.    In response to "CATEGORIES".
  359.  
  360. 5.4.3 711 Category Listing Done
  361.  
  362.       "711" SP "Done" EOT
  363.  
  364.    End of categories listing.
  365.  
  366.   In response to "CATEGORIES".
  367.  
  368. 5.4.4 720 Server Listing
  369.  
  370.       "720" SP category FS url FS name FS users FS bandwidth FS guest FS
  371.             download FS files FS size FS description EOT
  372.  
  373.       url            = STRING
  374.       name           = STRING
  375.       users          = 1*DIGIT
  376.       bandwidth      = 1*DIGIT
  377.       guest          = BOOLEAN
  378.       download       = BOOLEAN
  379.       files          = 1*DIGIT
  380.       size           = 1*DIGIT
  381.       description    = STRING
  382.  
  383.    The server was successfully registered and has been associated with the
  384.    A server in the servers listing. "url" is the full URL to server,
  385.    "name" is the name of the server, "users" the number of online clients,
  386.    "bandwidth" the available bandwidth in bytes/second. "guest" indicates
  387.    whether the guest account can connect, and "download" whether the guest
  388.    account can download files. "files" is the number of files on the server,
  389.    and "size" the total size of all files in bytes. "description" is a
  390.    description of the server.
  391.  
  392.    The sorting of the servers listing is undefined.
  393.  
  394.    In response to "SERVERS".
  395.  
  396. 5.4.5 721 Server Listing Done
  397.  
  398.       "721" SP "Done" EOT
  399.  
  400.    End of servers listing.
  401.  
  402.    In response to "SERVERS".
  403.  
  404. 6 References
  405.  
  406.    [1] Andersson, A., "Wired Protocol 1.1", Zanka Software RFC 2, August
  407.        2004.
  408.    
  409.    [2] Dierks, D. and Allen, C., "The TLS Protocol Version 1.0", RFC 
  410.        2246, January 1999.
  411.  
  412.    [3] Berners-Lee T. et al, "Uniform Resource Locators (URL)", RFC 1738,
  413.        December 1994.
  414.  
  415. 7 Author's Address
  416.  
  417.    Axel Andersson, axel@zankasoftware.com
  418.  
  419. 8 Full Copyright Statement
  420.  
  421.    Copyright (C) Axel Andersson 2004-2005. All Rights Reserved.
  422.  
  423.    This document and translations of it may be copied and furnished to
  424.    others, and derivative works that comment on or otherwise explain
  425.    it or assist in its implementation may be prepared, copied,
  426.    published and distributed, in whole or in part, without restriction
  427.    of any kind, provided that the above copyright notice, this
  428.    paragraph and the following disclaimer are included on all such
  429.    copies and derivative works.
  430.  
  431.    THIS DOCUMENT AND THE INFORMATION CONTAINED HEREIN IS PROVIDED BY
  432.    THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  433.    INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  434.    MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  435.