Merge pull request #80 from tomq42/master

Problem: Replies can get mismatched after timeouts, or slow servers

spec_40.txt

@@ -74,15 +74,16 @@ xrap_msg        = *( POST | POST-OK
 
 ;  Create a new, dynamically named resource in some parent.
 
-POST            = signature %d1 parent content_type content_body
+POST            = signature %d1 sequence_no parent content_type content_body
 signature       = %xAA %xA5             ; two octets
+sequence_no     = number-4              ; Sequence number of request
 parent          = string                ; Schema/type/name
 content_type    = string                ; Content type
 content_body    = longstr               ; New resource specification
 
 ;  Success response for POST.
 
-POST-OK         = signature %d2 status_code location etag date_modified
+POST-OK         = signature %d2 sequence_no status_code location etag date_modified
                   content_type content_body metadata
 status_code     = number-2              ; Response status code 2xx
 location        = string                ; Schema/type/name
@@ -94,7 +95,7 @@ metadata        = hash                  ; Collection total size/version/hypermed
 
 ;  Retrieve a known resource.
 
-GET             = signature %d3 resource parameters if_modified_since
+GET             = signature %d3 sequence_no resource parameters if_modified_since
                   if_none_match content_type
 resource        = string                ; Schema/type/name
 parameters      = hash                  ; Filtering/sorting/selecting/paging
@@ -104,7 +105,7 @@ content_type    = string                ; Desired content type
 
 ;  Success response for GET.
 
-GET-OK          = signature %d4 status_code etag date_modified content_type
+GET-OK          = signature %d4 sequence_no status_code etag date_modified content_type
                   content_body metadata
 status_code     = number-2              ; Response status code 2xx
 etag            = string                ; Opaque hash tag
@@ -115,12 +116,12 @@ metadata        = hash                  ; Collection total size/version/hypermed
 
 ;  Conditional GET returned 304 Not Modified.
 
-GET-EMPTY       = signature %d5 status_code
+GET-EMPTY       = signature %d5 sequence_no status_code
 status_code     = number-2              ; Response status code 3xx
 
 ;  Update a known resource.
 
-PUT             = signature %d6 resource if_unmodified_since if_match
+PUT             = signature %d6 sequence_no resource if_unmodified_since if_match
                   content_type content_body
 resource        = string                ; Schema/type/name
 if_unmodified_since = number-8          ; Update if same date
@@ -130,7 +131,7 @@ content_body    = longstr               ; New resource specification
 
 ;  Success response for PUT.
 
-PUT-OK          = signature %d7 status_code location etag date_modified metadata
+PUT-OK          = signature %d7 sequence_no status_code location etag date_modified metadata
 status_code     = number-2              ; Response status code 2xx
 location        = string                ; Schema/type/name
 etag            = string                ; Opaque hash tag
@@ -139,20 +140,20 @@ metadata        = hash                  ; Collection total size/version/hypermed
 
 ;  Remove a known resource.
 
-DELETE          = signature %d8 resource if_unmodified_since if_match
+DELETE          = signature %d8 sequence_no resource if_unmodified_since if_match
 resource        = string                ; schema/type/name
 if_unmodified_since = number-8          ; DELETE if same date
 if_match        = string                ; DELETE if same ETag
 
 ;  Success response for DELETE.
 
-DELETE-OK       = signature %d9 status_code metadata
+DELETE-OK       = signature %d9 sequence_no status_code metadata
 status_code     = number-2              ; Response status code 2xx
 metadata        = hash                  ; Collection total size/version/hypermedia
 
 ;  Error response for any request.
 
-ERROR           = signature %d10 status_code status_text
+ERROR           = signature %d10 sequence_no status_code status_text
 status_code     = number-2              ; Response status code, 4xx or 5xx
 status_text     = string                ; Response status text
 
@@ -194,6 +195,8 @@ We use these headers, with their HTTP/1.1 meanings, implemented as individual fi
 * If-Unmodified-Since - a conditional PUT or DELETE using resource date.
 * If-Match - a conditional PUT or DELETE using resource ETag.
 
+Requests carry a sequence number. The server MUST include the sequence number from the request in the reply that it sends. The client SHOULD use a strictly increasing sequence number to enable it to detect missing replies, out of order replies, or replies to requests that had timed out due, for example, to a slow starting server, or heavily loaded server.
+
 Additionally we can pass arguments to GET as we usually would do with a HTTP query.
 
 * Parameters - A map of key/value pairs for filtering, sorting, selecting and paging. Parameter key names are case-insensitive.
@@ -612,6 +615,8 @@ The client may send requests without waiting for responses. This can improve per
 
 XRAP clients MAY pipeline GET, PUT, DELETE and POST-public methods, but SHOULD NOT pipeline POST-private methods.
 
+The server is permitted to return responses in a different order to that in which they are received. For a multithreaded server it is impractical to maintain the order, and can lead to head-of-line blocking.
+
 +++ Error Responses
 
 When the server returns an error response (4xx or 5xx), the content body MUST be in plain text, and the MIME type MUST be "text/plain". The client can print and log the content body as a text with no parsing or decoding.
@@ -856,13 +861,15 @@ This is the XRAP protocol (http://rfc.zeromq.org/spec:40/XRAP):
 <include filename = "license.xml" />
 
 <message name = "POST" id = "1">
+    <field name = "sequence_no" type = "number" size="4">Request sequence number</field>
     <field name = "parent" type = "string">Schema/type/name</field>
     <field name = "content type" type = "string">Content type</field>
     <field name = "content body" type = "longstr">New resource specification</field>
 Create a new, dynamically named resource in some parent.
 </message>
 
 <message name = "POST OK" id = "2">
+    <field name = "sequence_no" type = "number" size="4">Request sequence number</field>
     <field name = "status code" type = "number" size = "2">Response status code 2xx</field>
     <field name = "location" type = "string">Schema/type/name</field>
     <field name = "etag" type = "string">Opaque hash tag</field>
@@ -874,6 +881,7 @@ Success response for POST.
 </message>
 
 <message name = "GET" id = "3">
+    <field name = "sequence_no" type = "number" size="4">Request sequence number</field>
     <field name = "resource" type = "string">Schema/type/name</field>
     <field name = "parameters" type = "hash">Filtering/sorting/selecting/paging</field>
     <field name = "if modified since" type = "number" size="8">GET if more recent</field>
@@ -883,6 +891,7 @@ Retrieve a known resource.
 </message>
 
 <message name = "GET OK" id = "4">
+    <field name = "sequence_no" type = "number" size="4">Request sequence number</field>
     <field name = "status code" type = "number" size = "2">Response status code 2xx</field>
     <field name = "etag" type = "string">Opaque hash tag</field>
     <field name = "date modified" type = "number" size = "8">Date and time modified</field>
@@ -893,11 +902,13 @@ Success response for GET.
 </message>
 
 <message name = "GET EMPTY" id = "5">
+    <field name = "sequence_no" type = "number" size="4">Request sequence number</field>
     <field name = "status code" type = "number" size = "2">Response status code 3xx</field>
 Conditional GET returned 304 Not Modified.
 </message>
 
 <message name = "PUT" id = "6">
+    <field name = "sequence_no" type = "number" size="4">Request sequence number</field>
     <field name = "resource" type = "string">Schema/type/name</field>
     <field name = "if unmodified since" type = "number" size="8">Update if same date</field>
     <field name = "if match" type = "string">Update if same ETag</field>
@@ -907,6 +918,7 @@ Update a known resource.
 </message>
 
 <message name = "PUT OK" id = "7">
+    <field name = "sequence_no" type = "number" size="4">Request sequence number</field>
     <field name = "status code" type = "number" size = "2">Response status code 2xx</field>
     <field name = "location" type = "string">Schema/type/name</field>
     <field name = "etag" type = "string">Opaque hash tag</field>
@@ -916,19 +928,22 @@ Success response for PUT.
 </message>
 
 <message name = "DELETE" id = "8">
+    <field name = "sequence_no" type = "number" size="4">Request sequence number</field>
     <field name = "resource" type = "string">schema/type/name</field>
     <field name = "if unmodified since" type = "number" size="8">DELETE if same date</field>
     <field name = "if match" type = "string">DELETE if same ETag</field>
 Remove a known resource.
 </message>
 
 <message name = "DELETE OK" id = "9">
+    <field name = "sequence_no" type = "number" size="4">Request sequence number</field>
     <field name = "status code" type = "number" size = "2">Response status code 2xx</field>
     <field name = "metadata" type = "hash">Collection total size/version/hypermedia</field>
 Success response for DELETE.
 </message>
 
 <message name = "ERROR" id = "10">
+    <field name = "sequence_no" type = "number" size="4">Request sequence number</field>
     <field name = "status code" type = "number" size = "2">Response status code, 4xx or 5xx</field>
     <field name = "status text" type = "string">Response status text</field>
 Error response for any request.