tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 7846

 
 
 

Peer-to-Peer Streaming Tracker Protocol (PPSTP)

Part 2 of 3, p. 16 to 38
Prev RFC Part       Next RFC Part

 


prevText      Top      ToC       Page 16 
3.  Protocol Specification

3.1.  Presentation Language

   PPSTP uses a REST-like design, encoding the requests and responses
   using JSON [RFC7159].  For a generalization of the definition of
   protocol elements and fields, as well as their types and structures,
   this document uses a C-style notation, similar to the presentation
   language used to define TLS [RFC5246].

   A JSON object consists of name/value pairs with the grammar specified
   in [RFC7159].  In this document, comments begin with "//", and the
   "ppsp_tp_string_t" and "ppsp_tp_integer_t" types are used to indicate
   the JSON string and number, respectively.  Optional fields are
   enclosed in "[ ]" brackets.  An array is indicated by two numbers in
   angle brackets, <min..max>, where "min" indicates the minimal number
   of values and "max" the maximum.  An "*" is used to denote a no
   upper-bound value for "max".

3.2.  Resource Element Types

   This section details the format of PPSTP resource element types.

3.2.1.  Version

   For both requests and responses, the version of PPSTP being used MUST
   be indicated by the attribute version, defined as follows:

      ppsp_tp_integer_t ppsp_tp_version_t = 1

   The defined value for ppsp_tp_version_t is listed in Table 2.

     +----------------------------------------------------------+
     | ppsp_tp_version_t |  Description                         |
     +----------------------------------------------------------+
     | 0                 |  Reserved                            |
     | 1                 |  PPSTP version 1                     |
     | 2-255             |  Unassigned                          |
     +----------------------------------------------------------+

                Table 2: PPSTP Version Numbers

Top      Up      ToC       Page 17 
3.2.2.  Peer Number Element

   The peer number element is a scope selector optionally present in
   CONNECT and FIND requests.

   This element contains the attribute peer_count to indicate the
   maximum number of peers in the returned peer list.  peer_count should
   be less than 30 in this specification.  The other 4 attributes, i.e.,
   ability_nat, concurrent_links, online_time, and upload_bandwidth may
   also be contained in this element to inform the tracker the status of
   the peer so that the tracker could return some eligible peers based
   on the implementing rules set by the service providers:

   o  ability_nat is used to indicate the preferred NAT traversal
      situation of the requesting peer.

   o  concurrent_links means the number of P2P links the peer currently
      has.

   o  online_time represents online duration time of the peer.  The unit
      is second.

   o  upload_bandwidth is the maximum upload bandwidth capability of the
      peer.  The unit is Kbps.

   The scope selector element and its attributes are defined as follows:

      Object {
              ppsp_tp_integer_t   peer_count;
              [ppsp_tp_string_t   ability_nat = "NO_NAT"
                                              | "STUN"
                                              | "TURN";]
              [ppsp_tp_integer_t   concurrent_links;]
              [ppsp_tp_integer_t   online_time;]
              [ppsp_tp_integer_t   upload_bandwidth;]
      } ppsp_tp_peer_num_t;

Top      Up      ToC       Page 18 
3.2.3.  Swarm Action Element

   The swarm action element identifies the action(s) to be taken in the
   named swarm(s) as well as the corresponding peer mode (if the peer is
   LEECH or SEEDER in that swarm).

      Object {
              ppsp_tp_string_t  swarm_id;   //swarm ID
              ppsp_tp_string_t  action = "JOIN"
                                        |"LEAVE"; // Action type of
                                                  // the CONNECT
                                                  // message

              ppsp_tp_string_t  peer_mode = "SEEDER"
                                          | "LEECH"; // Mode of the peer
                                                     // participating
                                                     // in this swarm
      } ppsp_tp_swarm_action_t;

3.2.4.  Peer Information Elements

   The peer information elements provide network identification
   information of peers.  A peer information element consists of a peer
   identifier and the IP-related addressing information.

      Object {
              ppsp_tp_string_t    peer_id;
              ppsp_tp_peer_addr_t peer_addr;
      } ppsp_tp_peer_info_t;

   The ppsp_tp_peer_addr_t element includes the IP address and port,
   with a few optional attributes related to connection type and network
   location (in terms of ASN) as well as, optionally, the identifier of
   the peer protocol being used.

      Object {
              ppsp_tp_ip_address       ip_address;
              ppsp_tp_integer_t        port;
              ppsp_tp_integer_t        priority;
              ppsp_tp_string_t         type = "HOST"
                                            | "REFLEXIVE"
                                            | "PROXY";
             [ppsp_tp_string_t         connection = "wireless"
                                                  | "wired";]
             [ppsp_tp_string_t         asn;]
             [ppsp_tp_string_t         peer_protocol;]
      } ppsp_tp_peer_addr_t;

Top      Up      ToC       Page 19 
   The semantics of ppsp_tp_peer_addr_t attributes are listed in
   Table 3:

      +----------------------+----------------------------------+
      | Element or Attribute | Description                      |
      +----------------------+----------------------------------+
      |      ip_address      | IP address information           |
      |      port            | IP service port value            |
      |      priority        | The priority of this interface.  |
      |                      | It may be determined by network  |
      |                      | topology preference, operator    |
      |                      | policy preference, etc.  How to  |
      |                      | create a priority is outside of  |
      |                      | the scope.  The larger the value,|
      |                      | the higher the priority.         |
      |      type            | Describes the address for NAT    |
      |                      | traversal, which can be HOST     |
      |                      | REFLEXIVE or PROXY               |
      |      connection      | Access type (wireless or wired)  |
      |      asn             | Autonomous System Number         |
      |      peer_protocol   | Peer-to-Peer Streaming Peer      |
      |                      | Protocol (PPSPP) supported       |
      +----------------------+----------------------------------+

              Table 3: Semantics of ppsp_tp_peer_addr_t

   In this document, IP address is specified as ppsp_tp_addr_value.  The
   exact characters and format depend on address_type:

   o  The IPv4 address is encoded as specified by the "IPv4address" rule
      in Section 3.2.2 of [RFC3986].

   o  The IPv6 address is encoded as specified in Section 4 of
      [RFC5952].

      Object {
              ppsp_tp_string_t   address_type;
              ppsp_tp_addr_value address;
      } ppsp_tp_ip_address;

   The peer information in responses is grouped in a
   ppsp_tp_peer_group_t element:

      Object {
              ppsp_tp_peer_info_t peer_info<1..*>;
      } ppsp_tp_peer_group_t;

Top      Up      ToC       Page 20 
3.2.5.  Statistics and Status Information Element

   The statistics element (stat) is used to describe several properties
   relevant to the P2P network.  These properties can be related to
   stream statistics and peer status information.  Each stat element
   will correspond to a property type, and several stat blocks can be
   reported in a single STAT_REPORT message, corresponding to some or
   all the swarms the peer is actively involved.  This specification
   only defines the property type "STREAM_STATS".

   The definition of the statistic element and attributes is as follows:

      Object {
             ppsp_tp_string_t  swarm_id;
             ppsp_tp_integer_t uploaded_bytes;
             ppsp_tp_integer_t downloaded_bytes;
             ppsp_tp_integer_t available_bandwidth;
             ppsp_tp_integer_t concurrent_links;
      } stream_stats;

   The semantics of stream_stats attributes are listed in Table 4:

      +----------------------+----------------------------------+
      | Element or Attribute | Description                      |
      +----------------------+----------------------------------+
      | swarm_id             | Swarm ID                         |
      | uploaded_bytes       | Bytes sent to swarm              |
      | downloaded_bytes     | Bytes received from swarm        |
      | available_bandwidth  | Available instantaneous upload   |
      |                      | bandwidth                        |
      | concurrent_links     | Number of concurrent links       |
      +----------------------+----------------------------------+

                  Table 4: Semantics of stream_stats

   The stat information is grouped in the ppsp_tp_stat_group_t element:

      Object {
         ppsp_tp_string_t     type = "STREAM_STATS"; // property type
         stream_stats         stat<1..*>;
      } ppsp_tp_stat_group_t

   Other properties may be defined, related, for example, to incentives
   and reputation mechanisms like "peer online time" or connectivity
   conditions like physical "link status", etc.

Top      Up      ToC       Page 21 
   For that purpose, the stat element may be extended to provide
   additional specific information for new properties, elements, or
   attributes (see the guidelines in Section 7).

3.3.  Requests and Responses

   This section defines the structure of PPSTP requests and responses.

3.3.1.  Request Types

   The request type includes CONNECT, FIND, and STAT_REPORT, defined as
   follows:

      ppsp_tp_string_t ppsp_tp_request_type_t = "CONNECT"
                                              | "FIND"
                                              | "STAT_REPORT";

3.3.2.  Response Types

   Response type corresponds to the response method type of the message,
   defined as follows:

      JSONValue ppsp_tp_response_type_t = 0x00    // SUCCESSFUL
                                        | 0x01;   // FAILED

Top      Up      ToC       Page 22 
3.3.3.  Request Element

   The request element MUST be present in requests and corresponds to
   the request method type for the message.

   The generic definition of a request element is as follows:

      Object {
              [ppsp_tp_peer_num_t      peer_num;]
              [ppsp_tp_peer_addr_t     peer_addr<1..*>;]
              ppsp_tp_swarm_action_t   swarm_action<1..*>;
      } ppsp_tp_request_connect;

      Object {
              ppsp_tp_string_t         swarm_id;
             [ppsp_tp_peer_num_t       peer_num;]
      } ppsp_tp_request_find;

      Object {
              ppsp_tp_version_t        version;
              ppsp_tp_request_type_t   request_type;
              ppsp_tp_string_t         transaction_id;
              ppsp_tp_string_t         peer_id;
              JSONValue request_data = ppsp_tp_req_connect connect
                                     | ppsp_tp_req_find     find
                                     | ppsp_tp_stat_group_t stat_report;
      } ppsp_tp_request;

   A request element consists of the version of PPSTP, the request type,
   a transaction ID, the requesting peer ID, and requesting body (i.e.,
   request_data).  The request_data MUST be correctly set to the
   corresponding element based on the request type (see Table 5).

          +----------------------+----------------------+
          | request_type         | request_data         |
          +----------------------+----------------------+
          | "CONNECT"            | "connect"            |
          | "FIND"               | "find"               |
          | "STAT_REPORT"        | "stat_report"        |
          +----------------------+----------------------+

   Table 5: The Relationship between request_type and request_data

Top      Up      ToC       Page 23 
3.3.4.  Response Element

   The generic definition of a response element is as follows:

      Object {
              ppsp_tp_version_t             version;
              ppsp_tp_response_type_t       response_type;
              ppsp_tp_integer_t             error_code;
              ppsp_tp_string_t              transaction_id;
             [ppsp_tp_peer_addr_t           peer_addr;]
             [ppsp_tp_swarm_action_result_t swarm_result<1..*>;]
      } ppsp_tp_response;

   A response element consists of the version of PPSTP, the response
   type, the error code, a transaction ID, and optionally the public
   address of the requesting peer and one or multiple swarm action
   result elements.  Normally, swarm action result elements SHOULD be
   present and error_code MUST be set to 00 (No Error) when
   response_type is 0x00.  Swarm action result elements SHOULD NOT be
   set when error_code is 01 (Bad Request).  Detailed selection of
   error_code is introduced in Section 4.3.

      Object {
          ppsp_tp_string_t           swarm_id;
          ppsp_tp_response_type_t    result;
          [ppsp_tp_peer_group_t      peer_group;]
      } ppsp_tp_swarm_action_result_t;

   A swarm action result element represents the result of an action
   requested by the peer.  It contains a swarm identifier that globally
   indicates the swarm, the result for the peer of this action (which
   could be CONNECT ("JOIN" or "LEAVE"), FIND, or STAT_REPORT), and
   optionally one peer group element.  The attribute result indicates
   the operation result of the corresponding request.  When the response
   element corresponds to the STAT_REPORT request or the result
   attribute is set to 0x01, the peer group element SHOULD NOT be set.

Top      Up      ToC       Page 24 
3.4.  PPSTP Message Element

   PPSTP messages (requests or responses) are designed to have a similar
   structure with a root field named "PPSPTrackerProtocol" containing
   meta information and data pertaining to a request or a response.

   The base type of a PPSTP message is defined as follows:

      Object {
              JSONValue PPSPTrackerProtocol = ppsp_tp_request  Request
                                            | ppsp_tp_response Response;
      } ppsp_tp_message_root;

4.  Protocol Specification: Encoding and Operation

   PPSTP is a message-oriented request/response protocol.  PPSTP
   messages use a text type encoding in JSON [RFC7159], which MUST be
   indicated in the Content-Type field in HTTP/1.1 [RFC7231], specifying
   the "application/ppsp-tracker+json" media type for all PPSTP request
   parameters and responses.

   Implementations MUST support the "https" URI scheme [RFC2818] and
   Transport Layer Security (TLS) [RFC5246].

   For deployment scenarios where peer (client) authentication is
   desired at the tracker, HTTP Digest Access Authentication [RFC7616]
   MUST be supported, with TLS Client Authentication as the preferred
   mechanism, if available.

   PPSTP uses the HTTP POST method to send parameters in requests to
   provide information resources that are the function of one or more of
   those input parameters.  Input parameters are encoded in JSON in the
   HTTP entity body of the request.

   The section describes the operation of the three types of requests of
   PPSTP and provides some examples of usage.

Top      Up      ToC       Page 25 
4.1.  Requests and Responses

4.1.1.  CONNECT Request

   This method is used when a peer registers to the system and/or
   requests some swarm actions (join/leave).  The peer MUST properly set
   the request type to CONNECT, generate and set the transaction_ids,
   set the peer_id, and include swarms the peer is interested in,
   followed by the corresponding action type and peer mode.

   o  When a peer already possesses content and agrees to share it with
      others, it should set the action type to the value JOIN, as well
      as set the peer mode to SEEDER during its start (or re-start)
      period.

   o  When a peer makes a request to join a swarm to consume content, it
      should set the action type to the value JOIN, as well as set the
      peer mode to LEECH during its start (or re-start) period.

   In the above cases, the peer can provide optional information on the
   addresses of its network interface(s), for example, the priority,
   type, connection, and ASN.

   When a peer plans to leave a previously joined swarm, it should set
   action type to LEAVE, regardless of the peer mode.

   When receiving a well-formed CONNECT request message, the tracker
   starts by pre-processing the peer authentication information
   (provided as authorization scheme and token in the HTTP message) to
   check whether it is valid and that it can connect to the service,
   then proceed to register the peer in the service and perform the
   swarm actions requested.  If successful, a response message with a
   corresponding response value of SUCCESSFUL will be generated.

   The valid sets of the number of swarms whose action type is combined
   with peer mode for the CONNECT request logic are enumerated in
   Table 6 (referring to the "per-Peer-ID" State Machine in
   Section 2.3).

Top      Up      ToC       Page 26 
   +-----------+-----------+---------+----------+-----------+----------+
   | Swarm     | peer_mode |  action | Initial  | Final     | Request  |
   | Number    |  Value    |  Value  |  State   | State     | Validity |
   +-----------+-----------+---------+----------+-----------+----------|
   |     1     |  LEECH    |  JOIN   |  START   | TRACKING  |  Valid   |
   +-----------+-----------+---------+----------+-----------+----------+
   |     1     |  LEECH    |  LEAVE  |  START   | TERMINATE | Invalid  |
   +-----------+-----------+---------+----------+-----------+----------+
   |     1     |  LEECH    |  LEAVE  | TRACKING | TERMINATE |  Valid   |
   +-----------+-----------+---------+----------+-----------+----------+
   |     1     |  LEECH    |  JOIN   |  START   | TERMINATE | Invalid  |
   |     1     |  LEECH    |  LEAVE  |          |           |          |
   +-----------+-----------+---------+----------+-----------+----------+
   |     1     |  LEECH    |  JOIN   | TRACKING | TRACKING  |  Valid   |
   |     1     |  LEECH    |  LEAVE  |          |           |          |
   +-----------+-----------+---------+----------+-----------+----------+
   |     N     |  SEEDER   |  JOIN   |  START   | TRACKING  |  Valid   |
   +-----------+-----------+---------+----------+-----------+----------+
   |     N     |  SEEDER   |  JOIN   | TRACKING | TERMINATE | Invalid  |
   +-----------+-----------+---------+----------+-----------+----------+
   |     N     |  SEEDER   |  LEAVE  | TRACKING | TERMINATE |  Valid   |
   +-----------+-----------+---------+----------+-----------+----------+

       Table 6: Validity of Action Combinations in CONNECT Requests

   In the CONNECT request message, multiple swarm action elements
   ppsp_tp_swarm_action_t could be contained.  Each of them contains the
   request action and the peer_mode of the peer.  The peer_mode
   attribute MUST be set to the type of participation of the peer in the
   swarm (SEEDER or LEECH).

   The CONNECT message may contain multiple peer_addr elements with
   attributes ip_address, port, priority, and type (if Interactive
   Connectivity Establishment (ICE) [RFC5245] NAT traversal techniques
   are used), and optionally connection, asn, and peer_protocol
   corresponding to each of the network interfaces the peer wants to
   advertise.

   The element peer_num indicates the maximum number of peers to be
   returned in a list from the tracker.  The returned peer list can be
   optionally filtered by some indicated properties, such as ability_nat
   for NAT traversal, and concurrent_links, online_time and
   upload_bandwidth for the preferred capabilities.

   The element transaction_id MUST be present in requests to uniquely
   identify the transaction.  Responses to completed transactions use
   the same transaction_id as the request they correspond to.

Top      Up      ToC       Page 27 
   The response may include peer_addr data of the requesting peer public
   IP address.  Peers can use Session Traversal Utilities for NAT (STUN)
   [RFC5389] and Traversal Using Relays around NAT (TURN) [RFC5766] to
   gather their candidates, in which case peer_addr SHOULD NOT present
   in the response.  If no STUN is used and the tracker is able to work
   as a "STUN-like" server that can inspect the public address of a
   peer, the tracker can return the address back with a "REFLEXIVE"
   attribute type.  The swarm_result may also include peer_addr data
   corresponding to the peer IDs and public IP addresses of the selected
   active peers in the requested swarm.  The tracker may also include
   the attribute asn with network location information of the transport
   address, corresponding to the Autonomous System Number of the access
   network provider of the referenced peer.

   If the peer_mode is SEEDER, the tracker responds with a SUCCESSFUL
   response and enters the peer information into the corresponding swarm
   activity.  If the peer_mode is LEECH (or if a SEEDER includes a
   peer_num element in the request), the tracker will search and select
   an appropriate list of peers satisfying the conditions set by the
   requesting peer.  The peer list returned MUST contain the peer IDs
   and the corresponding IP addresses.  To create the peer list, the
   tracker may take peer status and network location information into
   consideration to express network topology preferences or operators'
   policy preferences with regard to the possibility of connecting with
   other IETF efforts such as Application-Layer Traffic Optimization
   (ALTO) [RFC7285].

   IMPLEMENTATION NOTE: If no peer_num attributes are present in the
   request, the tracker may return a random sample from the peer
   population.

Top      Up      ToC       Page 28 
4.1.1.1.  Example

   The following example of a CONNECT request corresponds to a peer that
   wants to start (or re-start) sharing its previously streamed content
   (peer_mode is SEEDER).

      POST https://tracker.example.com/video_1 HTTP/1.1
      Host: tracker.example.com
      Content-Length: 494
      Content-Type: application/ppsp-tracker+json
      Accept: application/ppsp-tracker+json

      {
        "PPSPTrackerProtocol": {
          "version":              1,
          "request_type":         "CONNECT",
          "transaction_id":       "12345",
          "peer_id":              "656164657220",
          "connect":{
              "peer_addr": {
                     "ip_address": {
                          "address_type":     "ipv4",
                          "address":          "192.0.2.2"
                     },
                     "port":         80,
                     "priority":     1,
                     "type":         "HOST",
                     "connection":   "wired",
                     "asn":          "45645"
              },
              "swarm_action": [{
                  "swarm_id":       "1111",
                  "action":         "JOIN",
                  "peer_mode":      "SEEDER"
              },
              {
                  "swarm_id":       "2222",
                  "action":         "JOIN",
                  "peer_mode":      "SEEDER"
              }]
          }
        }
      }

   Another example of the message-body of a CONNECT request corresponds
   to a peer (peer_mode is LEECH, meaning that the peer is not in
   possession of the content) requesting join to a swarm, in order to

Top      Up      ToC       Page 29 
   start receiving the stream and providing optional information on the
   addresses of its network interface(s):

      {
        "PPSPTrackerProtocol": {
          "version":               1,
          "request_type":          "CONNECT",
          "transaction_id":        "12345.0",
          "peer_id":               "656164657221",
          "connect":{
              "peer_num": {
                  "peer_count":        5,
                  "ability_nat":       "STUN",
                  "concurrent_links":  "5",
                  "online_time":       "200",
                  "upload_bandwidth":  "600"
               },
               "peer_addr": [{
                     "ip_address": {
                          "address_type":     "ipv4",
                          "address":          "192.0.2.2"
                     },
                     "port":         80,
                     "priority":     1,
                     "type":         "HOST",
                     "connection":   "wired",
                     "asn":          "3256546"
               },
               {
                     "ip_address":{
                         "address_type":     "ipv6",
                         "address":          "2001:db8::2"
                     },
                     "port":         80,
                     "priority":     2,
                     "type":         "HOST",
                     "connection":   "wireless",
                     "asn":          "34563456",
                     "peer_protocol": "PPSP-PP"
               }],
               "swarm_action": {
                  "swarm_id":       "1111",
                  "action":         "JOIN",
                  "peer_mode":      "LEECH"
               }
          }
        }
      }

Top      Up      ToC       Page 30 
   The next example of a CONNECT request corresponds to a peer leaving a
   previously joined swarm and requesting to join a new swarm.  This is
   the typical example of a user watching a live channel but then
   deciding to switch to a different one:

      {
        "PPSPTrackerProtocol": {
          "version":              1,
          "request_type":         "CONNECT",
          "transaction_id":       "12345",
          "peer_id":              "656164657221",
          "connect":{
              "peer_num": {
                  "peer_count":        5,
                  "ability_nat":       "STUN",
                  "concurrent_links":  "5",
                  "online_time":       "200",
                  "upload_bandwidth":  "600"
              },
              "swarm_action": [{
                  "swarm_id":          "1111",
                  "action":            "LEAVE",
                  "peer_mode":         "LEECH"
              },
              {
                  "swarm_id":          "2222",
                  "action":            "JOIN",
                  "peer_mode":         "LEECH"
              }]
          }
        }
      }

   The next example illustrates the response for the previous example of
   a CONNECT request where the peer requested two swarm actions and not
   more than 5 other peers, receiving from the tracker a peer list with
   only two other peers in the swarm "2222":

      HTTP/1.1 200 OK
      Content-Length: 1342
      Content-Type: application/ppsp-tracker+json

      {
        "PPSPTrackerProtocol": {
          "version":               1,
          "response_type":         0,
          "error_code":            0,
          "transaction_id":        "12345",

Top      Up      ToC       Page 31 
          "peer_addr": {
              "ip_address": {
                  "address_type":     "ipv4",
                  "address":          "198.51.100.1"
              },
              "port":          80,
              "priority":      1,
              "asn":           "64496"
         },
         "swarm_result": {
              "swarm_id":        "2222",
              "result":          0,
              "peer_group": {
                  "peer_info": [{
                      "peer_id":    "956264622298",
                      "peer_addr": {
                          "ip_address": {
                              "address_type":     "ipv4",
                              "address":          "198.51.100.22"
                          },
                          "port":          80,
                          "priority":      2,
                          "type":          "REFLEXIVE",
                          "connection":    "wired",
                          "asn":           "64496",
                          "peer_protocol": "PPSP-PP"
                      }
                  },
                  {
                      "peer_id":    "3332001256741",
                      "peer_addr": {
                          "ip_address": {
                              "address_type":     "ipv4",
                              "address":          "198.51.100.201"
                          },
                          "port":          80,
                          "priority":      2,
                          "type":          "REFLEXIVE",

                          "connection":    "wired",
                          "asn":           "64496",
                          "peer_protocol": "PPSP-PP"
                      }
                  }]
                }
             }
         }
      }

Top      Up      ToC       Page 32 
4.1.2.  FIND Request

   This method allows peers to request a new peer list for the swarm
   from the tracker whenever needed.

   The FIND request may include a peer_number element to indicate to the
   tracker the maximum number of peers to be returned in a list
   corresponding to the indicated conditions set by the requesting peer,
   being ability_nat for NAT traversal (considering that PPSP-ICE NAT
   traversal techniques may be used), and optionally concurrent_links,
   online_time, and upload_bandwidth for the preferred capabilities.

   When receiving a well-formed FIND request, the tracker processes the
   information to check if it is valid.  If successful, a response
   message with a response value of SUCCESSFUL will be generated, and
   the tracker will search out the list of peers for the swarm and
   select an appropriate peer list satisfying the conditions set by the
   requesting peer.  The peer list returned MUST contain the peer IDs
   and the corresponding IP addresses.

   The tracker may take the ability of peers and popularity of the
   requested content into consideration.  For example, the tracker could
   select peers with higher ability than the current peers that provide
   the content if the content is relatively popular (see Section 5.1.1);
   the tracker could also select peers with lower ability than the
   current peers that provide the content when the content is relatively
   uncommon.  The tracker may take network location information into
   consideration as well, to express network topology preferences or
   operators' policy preferences.  It can implement other IETF efforts
   like ALTO [RFC7285], which is out of the scope of this document.

   The response MUST include a peer_group element that contains the peer
   IDs and the corresponding IP addresses; it may also include the
   attribute asn with network location information of the transport
   address, corresponding to the Autonomous System Number of the access
   network provider of the referenced peer.

   The response may also include a peer_addr element that includes the
   requesting peer public IP address.  If no STUN is used and the
   tracker is able to work as a "STUN-like" server that can inspect the
   public address of a peer, the tracker can return the address back
   with a "REFLEXIVE" attribute type.

   IMPLEMENTATION NOTE: If no peer_num attributes are present in the
   request, the tracker may return a random sample from the peer
   population.

Top      Up      ToC       Page 33 
4.1.2.1.  Example

   An example of the message-body of a FIND request, where the peer
   requests from the tracker a list of not more than 5 peers in the
   swarm "1111" conforming to the characteristics expressed (concurrent
   links, online time, and upload bandwidth level) is as follows:

      {
        "PPSPTrackerProtocol": {
            "version":             1,
            "request_type":        "FIND",
            "transaction_id":      "12345",
            "peer_id":             "656164657221",
            "swarm_id":            "1111",
            "peer_num": {
                "peer_count":        5,
                "ability_nat":       "STUN",
                "concurrent_links":  "5",
                "online_time":       "200",
                "upload_bandwidth":  "600"
            }
        }
      }

   An example of the message-body of a response for the above FIND
   request, including the requesting peer public IP address information,
   is as follows:

      {
        "PPSPTrackerProtocol": {
            "version":             1,
            "response_type":       0,
            "error_code":          0,
            "transaction_id":      "12345",
            "swarm_result": {
                "swarm_id":        "1111",
                "result":          0,
                "peer_group": {
                    "peer_info": [{

                        "peer_id":    "656164657221",
                        "peer_addr": {
                            "ip_address": {
                                "address_type":     "ipv4",
                                "address":          "198.51.100.1"
                            },
                            "port":          80,
                            "priority":      1,

Top      Up      ToC       Page 34 
                            "type":          "REFLEXIVE",
                            "connection":    "wireless",
                            "asn":           "64496"
                        }
                    },
                    {
                        "peer_id":    "956264622298",
                        "peer_addr": {
                            "ip_address": {
                                "address_type":     "ipv4",
                                "address":          "198.51.100.22"
                            },
                            "port":          80,
                            "priority":      1,
                            "type":          "REFLEXIVE",
                            "connection":    "wireless",
                            "asn":           "64496"
                        }
                    },
                    {
                        "peer_id":    "3332001256741",
                        "peer_addr": {
                            "ip_address": {
                                "address_type":     "ipv4",
                                "address":          "198.51.100.201"
                            },
                            "port":          80,
                            "priority":      1,
                            "type":          "REFLEXIVE",

                            "connection":    "wireless",
                            "asn":           "64496"
                        }
                    }]
                }
            }
        }
      }

4.1.3.  STAT_REPORT Request

   This method allows peers to send status and statistic data to
   trackers.  The method is periodically initiated by the peer while it
   is active.

   The peer MUST set the request_type to "STAT_REPORT", set the peer_id
   with the identifier of the peer, and generate and set the
   transaction_id.

Top      Up      ToC       Page 35 
   The report may include multiple statistics elements describing
   several properties relevant to a specific swarm.  These properties
   can be related with stream statistics and peer status information,
   including uploaded_bytes, downloaded_bytes, available_bandwidth,
   concurrent_links, etc.

   Other properties may be defined (see the guidelines in Section 7.1),
   for example, those related to incentives and reputation mechanisms.
   If no Statistics Group is included, the STAT_REPORT is used as a
   "keep-alive" message to prevent the tracker from de-registering the
   peer when the "track timer" expires.

   If the request is valid, the tracker processes the received
   information for future use and generates a response message with a
   response value of SUCCESSFUL.

   The response MUST have the same transaction_id value as the request.

4.1.3.1.  Example

   An example of the message-body of a STAT_REPORT request is:

      {
        "PPSPTrackerProtocol": {
            "version":             1,
            "request_type":        "STAT_REPORT",
            "transaction_id":      "12345",
            "peer_id":             "656164657221",
            "stat_report": {
                "type":  "STREAM_STATS",
                "Stat": {
                      "swarm_id":              "1111",
                      "uploaded_bytes":        512,
                      "downloaded_bytes":      768,
                      "available_bandwidth":   1024000,
                      "concurrent_links":      5
                }
            }
        }
      }

Top      Up      ToC       Page 36 
   An example of the message-body of a response for the START_REPORT
   request is:

      {
        "PPSPTrackerProtocol": {
            "version":              1,
            "response_type":        0,
            "error_code":           0,
            "transaction_id":       "12345",
            "swarm_result": {
                "swarm_id":     "1111",
                "result":       0
            }
        }
      }

4.2.  Response Element in Response Messages

   Table 7 indicates the response type and corresponding semantics.

              +--------------------+---------------------+
              | Response Type      | Semantics           |
              |                    |                     |
              +--------------------+---------------------+
              | 0                  |   SUCCESSFUL        |
              | 1                  |   FAILED            |
              +--------------------+---------------------+

          Table 7: Semantics for the Value of Response Type

   SUCCESSFUL: Indicates that the request has been processed properly
   and the desired operation has completed.  The body of the response
   message includes the requested information and MUST include the same
   transaction_id as the corresponding request.

      CONNECT:  Returns information about the successful registration of
      the peer and/or of each swarm action requested.  May additionally
      return the list of peers corresponding to the action attribute
      requested.

      FIND:  Returns the list of peers corresponding to the requested
      scope.

      STAT_REPORT:  Confirms the success of the requested operation.

   FAILED: Indicates that the request has not been processed properly.
   A corresponding error_code SHOULD be set according to the conditions
   described in Section 4.3.

Top      Up      ToC       Page 37 
4.3.  Error and Recovery Conditions

   If the peer receives an invalid response, the same request with
   identical content including the same transaction_id MUST be repeated.

   The transaction_id on a request can be reused if and only if all of
   the content is identical, including date/time information.  Details
   of the retry process (including time intervals to pause, number of
   retries to attempt, and timeouts for retrying) are implementation
   dependent.

   The tracker MUST be prepared to receive a request with a repeated
   transaction_id.

   Error situations resulting from normal operation or from abnormal
   conditions (Section 2.3.2) MUST be responded to with response_type
   set to 0x01 and with the adequate error_code, as described here:

   o  If the message is found to be incorrectly formed, the receiver
      MUST respond with a 01 (Bad Request) error_code with an empty
      message-body (no peer_addr and swarm_result attributes).

   o  If the version number of the protocol is for a version the
      receiver does not support, the receiver MUST respond with a 02
      (Unsupported Version Number) error_code with an empty message-body
      (no peer_addr and swarm_result attributes).

   o  In the PEER REGISTERED and TRACKING states of the tracker, certain
      requests are not allowed (Section 2.3.2).  The tracker MUST
      respond with a 03 (Forbidden Action) error_code with an empty
      message-body (no peer_addr and swarm_result attributes).

   o  If the tracker is unable to process a request message due to an
      unexpected condition, it SHOULD respond with a 04 (Internal Server
      Error) error_code with an empty message-body (no peer_addr and
      swarm_result attributes).

   o  If the tracker is unable to process a request message because it
      is in an overloaded state, it SHOULD respond with a 05 (Service
      Unavailable) error_code with an empty message-body (no peer_addr
      and swarm_result attributes).

   o  If authentication is required for the peer to make the request,
      the tracker SHOULD respond with a 06 (Authentication Required)
      error_code with an empty message-body (no peer_addr and
      swarm_result attributes).

Top      Up      ToC       Page 38 
4.4.  Parsing of Unknown Fields in message-body

   This document only details object members used by this specification.
   Extensions may include additional members within JSON objects defined
   in this document.  PPSTP implementations MUST ignore unknown members
   when processing PPSTP messages.



(page 38 continued on part 3)

Next RFC Part