From 2be45e566dd490aabf7a45ec3474545a0817024e Mon Sep 17 00:00:00 2001 From: "James E. King III" Date: Thu, 31 Jan 2019 13:17:46 -0500 Subject: THRIFT-4405: add documentation on sequence number rules --- doc/specs/SequenceNumbers.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 doc/specs/SequenceNumbers.md (limited to 'doc') diff --git a/doc/specs/SequenceNumbers.md b/doc/specs/SequenceNumbers.md new file mode 100644 index 000000000..fef3fcff1 --- /dev/null +++ b/doc/specs/SequenceNumbers.md @@ -0,0 +1,23 @@ +# Sequence Number # + +Apache Thrift built sequence numbers into every protocol exchange to allow +for clients that may submit multiple outstanding requests on a single transport +connection. This is typically done by asynchronous clients. + +The following rules apply to sequence numbers: + +1. A sequence number is a signed 32-bit integer. Negative values are allowed. +1. Sequence numbers `MUST` be unique across all outstanding requests on a + given transport connection. There is no requirement for unique numbers + between different transport connections even if they are from the same client. +1. A server `MUST` reply to a client with the same sequence number that was + used in the request. This includes any exception-based reply. +1. A client `MAY` use sequence numbers if it needs them for proper operation. +1. A client `SHOULD` set the sequence number to zero if it does not rely + on them. +1. Wrapped protocols (such as THeaderProtocol) `SHOULD` use the same sequence + number on the wrapping as is used on the payload protocol. + +Servers will not inspect or make any logic choices based on the sequence number +sent by the client. The server's only job is to process the request and reply +with the same sequence number. -- cgit v1.2.1