RFC 7846
Peer-to-Peer Streaming Tracker Protocol (PPSTP)
Pages: 55
Proposed Standard
Proposed Standard
Part 2 of 3 – Pages 16 to 38
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
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;
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;
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;
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.
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
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
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.
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.
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).
+-----------+-----------+---------+----------+-----------+----------+ | 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.
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.
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
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"
}
}
}
}
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",
"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"
}
}]
}
}
}
}
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.
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,
"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.
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 } } } }
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.
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).
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)