From 95a98d969e2fdffb73559aab40d7d46f16d3d4f7 Mon Sep 17 00:00:00 2001 From: Alberto Ricart Date: Thu, 28 May 2020 18:24:01 -0500 Subject: [PATCH 1/4] Header specification from the perspective of client libraries. [ci skip] --- doc/adr/0003-nats-headers.md | 72 ++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) create mode 100644 doc/adr/0003-nats-headers.md diff --git a/doc/adr/0003-nats-headers.md b/doc/adr/0003-nats-headers.md new file mode 100644 index 00000000..722e423e --- /dev/null +++ b/doc/adr/0003-nats-headers.md @@ -0,0 +1,72 @@ +# 3. nats-headers + +Date: 2020-05-28 + +## Status + +Accepted + +## Context + +This document describes NATS Headers from the perspective of clients. NATS headers allow clients to specify additional metadata in the form of headers. The headers borrow strongly from [HTTP Headers](https://tools.ietf.org/html/rfc7230#section-3.2). + +The salient points of the HTTP header specification are: + +- Each header field consists of a case-insensitive field name followed by a colon (":"), optional leading whitespace, the field value, and optional trailing whitespace. +- No spaces are allowed between the header field name and colon. +- Field value may be preceeded or followed by optional whitespace. +- The specification may allow any number of strange things like comments/tokens etc. +- The keys can repeat. + +The reference NATS Go client repurposes the `http.Header` infrastructure for serializing NATS headers. Other language clients may not be able to reuse header infrastructure outside of the context of HTTP. Furthermore, the implementation of the header library may diverge from what is allowed by the Go `http.Header`. + +NATS Headers: + +- First line is `NATS/X.x` +- Each header key is separated from its value by a ': ' `` +- Headers are formatted as MIMEHeaders. +- Keys are case-insensitive even if formatted otherwise. +- Value is ASCII and may not contains line folding (`\n`, etc) +- Value is terminated by a `` +- Final value adds an extra `` + +### Publishing Messages With A Header + +_For purposes of easily counting characters on these examples, `` sequences are encoded as `rn`._ +Messages that include a header have a `HPUB` protocol: + +``` +HPUB SUBJECT REPLY 23 30rnNATS/1.0rnHeader: XrnrnPAYLOADrn +HPUB SUBJECT REPLY 23 23rnNATS/1.0rnHeader: Xrnrnrn + +HPUB [REPLY]
+``` + +#### NOTES: + +- `HEADER_LEN` includes the entire serialized header including s +- `TOT_LEN` includes the entire payload length including the header + +### MSG with Headers + +Clients will see `HMSG` protocol lines for `MSG`s that contain headers + +``` +HMSG SUBJECT 1 REPLY 23 30rnNATS/1.0rnHeader: XrnrnPAYLOADrn +HPUB SUBJECT 1 REPLY 23 23rnNATS/1.0rnHeader: Xrnrnrn + +HMSG [REPLY] +``` + +- `HEADER_LEN` includes the entire header including the a double +- `TOT_LEN` includes the entire payload length including the header + + + +## Decision + +Implemented and merged to master. + +## Consequences + +Use of headers is possible. From a10d1a45e10d1904379d52454359e30e2b656226 Mon Sep 17 00:00:00 2001 From: Alberto Ricart Date: Fri, 29 May 2020 10:07:09 -0500 Subject: [PATCH 2/4] review comments removed synopsys of http header spec --- doc/adr/0003-nats-headers.md | 72 ------------------------------- doc/adr/0004-nats-headers.md | 84 ++++++++++++++++++++++++++++++++++++ 2 files changed, 84 insertions(+), 72 deletions(-) delete mode 100644 doc/adr/0003-nats-headers.md create mode 100644 doc/adr/0004-nats-headers.md diff --git a/doc/adr/0003-nats-headers.md b/doc/adr/0003-nats-headers.md deleted file mode 100644 index 722e423e..00000000 --- a/doc/adr/0003-nats-headers.md +++ /dev/null @@ -1,72 +0,0 @@ -# 3. nats-headers - -Date: 2020-05-28 - -## Status - -Accepted - -## Context - -This document describes NATS Headers from the perspective of clients. NATS headers allow clients to specify additional metadata in the form of headers. The headers borrow strongly from [HTTP Headers](https://tools.ietf.org/html/rfc7230#section-3.2). - -The salient points of the HTTP header specification are: - -- Each header field consists of a case-insensitive field name followed by a colon (":"), optional leading whitespace, the field value, and optional trailing whitespace. -- No spaces are allowed between the header field name and colon. -- Field value may be preceeded or followed by optional whitespace. -- The specification may allow any number of strange things like comments/tokens etc. -- The keys can repeat. - -The reference NATS Go client repurposes the `http.Header` infrastructure for serializing NATS headers. Other language clients may not be able to reuse header infrastructure outside of the context of HTTP. Furthermore, the implementation of the header library may diverge from what is allowed by the Go `http.Header`. - -NATS Headers: - -- First line is `NATS/X.x` -- Each header key is separated from its value by a ': ' `` -- Headers are formatted as MIMEHeaders. -- Keys are case-insensitive even if formatted otherwise. -- Value is ASCII and may not contains line folding (`\n`, etc) -- Value is terminated by a `` -- Final value adds an extra `` - -### Publishing Messages With A Header - -_For purposes of easily counting characters on these examples, `` sequences are encoded as `rn`._ -Messages that include a header have a `HPUB` protocol: - -``` -HPUB SUBJECT REPLY 23 30rnNATS/1.0rnHeader: XrnrnPAYLOADrn -HPUB SUBJECT REPLY 23 23rnNATS/1.0rnHeader: Xrnrnrn - -HPUB [REPLY]
-``` - -#### NOTES: - -- `HEADER_LEN` includes the entire serialized header including s -- `TOT_LEN` includes the entire payload length including the header - -### MSG with Headers - -Clients will see `HMSG` protocol lines for `MSG`s that contain headers - -``` -HMSG SUBJECT 1 REPLY 23 30rnNATS/1.0rnHeader: XrnrnPAYLOADrn -HPUB SUBJECT 1 REPLY 23 23rnNATS/1.0rnHeader: Xrnrnrn - -HMSG [REPLY] -``` - -- `HEADER_LEN` includes the entire header including the a double -- `TOT_LEN` includes the entire payload length including the header - - - -## Decision - -Implemented and merged to master. - -## Consequences - -Use of headers is possible. diff --git a/doc/adr/0004-nats-headers.md b/doc/adr/0004-nats-headers.md new file mode 100644 index 00000000..e36f89f6 --- /dev/null +++ b/doc/adr/0004-nats-headers.md @@ -0,0 +1,84 @@ +# 4. nats-headers + +Date: 2020-05-28 + +## Status + +Accepted + +## Context + +This document describes NATS Headers from the perspective of clients. NATS headers allow clients to specify additional meta-data in the form of headers. The headers are effectively [HTTP Headers](https://tools.ietf.org/html/rfc7230#section-3.2). The reference Go implementation internally uses `http.Header` for their serialization and parsing. + +The salient points of the HTTP header specification are: + +- Each header field consists of a case-insensitive field name followed by a colon (`:`), optional leading whitespace, the field value, and optional trailing whitespace. +- No spaces are allowed between the header field name and colon. +- Field value may be preceded or followed by optional whitespace. +- The specification may allow any number of strange things like comments/tokens etc. +- The keys can repeat. + +The reference NATS Go client uses the `http.Header` infrastructure for serializing NATS headers. Other language clients may not be able to reuse header serialization infrastructure outside of the context of an HTTP request. Furthermore, the implementation of the native header library may diverge from the Go `http.Header` while still being standard. + +NATS Headers: + +The only difference between a NATS header and HTTP is the first line. Instead of an HTTP method followed by a resource and the HTTP version (`GET / HTTP/1.1`), NATS will provide a string identifying the header version (`NATS/X.x\r\n`), currently 1.0, so it is rendered as `NATS/1.0\r\n`. + +Please refer to the [specification](https://tools.ietf.org/html/rfc7230#section-3.2) for information on how to encode/decode HTTP headers, and the [Go implementation](https://golang.org/src/net/http/header.go). + + +### Enabling Message Headers + +The server that is able to send and receive headers will specify so in it's [`INFO`](https://docs.nats.io/nats-protocol/nats-protocol#info) protocol message. The `headers` field if present, will have a boolean value. If the client wishes to send headers, it has to enable it must add a `headers` field with the `true` value in its [`CONNECT` message](https://docs.nats.io/nats-protocol/nats-protocol#connect): + +``` +"lang": "node", +"version": "1.2.3", +"protocol": 1, +"headers": true, +... +``` + +### Publishing Messages With A Header + + +Messages that include a header have a `HPUB` protocol: + +``` +HPUB SUBJECT REPLY 23 30\r\nNATS/1.0\r\nHeader: X\r\n\r\nPAYLOAD\r\n +HPUB SUBJECT REPLY 23 23\r\nNATS/1.0\r\nHeader: X\r\n\r\n\r\n + +HPUB [REPLY] ` +`
` +` +``` + +#### NOTES: + +- `HDR_LEN` includes the entire serialized header +- `TOT_LEN` includes the entire payload length including the header + +### MSG with Headers + +Clients will see `HMSG` protocol lines for `MSG`s that contain headers + +``` +HMSG SUBJECT 1 REPLY 23 30\r\nNATS/1.0\r\nHeader: X\r\n\r\nPAYLOAD\r\n +HPUB SUBJECT 1 REPLY 23 23\r\nNATS/1.0\r\nHeader: X\r\n\r\n\r\n + +HMSG [REPLY] ` +`` +` +``` + +- `HDR_LEN` includes the entire header +- `TOT_LEN` includes the entire payload length including the header + + +## Decision + +Implemented and merged to master. + +## Consequences + +Use of headers is possible. From 8b04a8988fad4969fbe49b00f78b0c721645ebe9 Mon Sep 17 00:00:00 2001 From: Alberto Ricart Date: Tue, 2 Jun 2020 09:17:44 -0500 Subject: [PATCH 3/4] removed extraneous ticks from md --- doc/adr/0004-nats-headers.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/doc/adr/0004-nats-headers.md b/doc/adr/0004-nats-headers.md index e36f89f6..41347c98 100644 --- a/doc/adr/0004-nats-headers.md +++ b/doc/adr/0004-nats-headers.md @@ -48,9 +48,9 @@ Messages that include a header have a `HPUB` protocol: HPUB SUBJECT REPLY 23 30\r\nNATS/1.0\r\nHeader: X\r\n\r\nPAYLOAD\r\n HPUB SUBJECT REPLY 23 23\r\nNATS/1.0\r\nHeader: X\r\n\r\n\r\n -HPUB [REPLY] ` -`
` -` +HPUB [REPLY] +
+ ``` #### NOTES: @@ -66,9 +66,8 @@ Clients will see `HMSG` protocol lines for `MSG`s that contain headers HMSG SUBJECT 1 REPLY 23 30\r\nNATS/1.0\r\nHeader: X\r\n\r\nPAYLOAD\r\n HPUB SUBJECT 1 REPLY 23 23\r\nNATS/1.0\r\nHeader: X\r\n\r\n\r\n -HMSG [REPLY] ` -`` -` +HMSG [REPLY] + ``` - `HDR_LEN` includes the entire header From 3c3ee22e9fdca6046d5e1b6990353d994ae1bf36 Mon Sep 17 00:00:00 2001 From: Alberto Ricart Date: Thu, 11 Jun 2020 12:11:43 -0500 Subject: [PATCH 4/4] =?UTF-8?q?changed=20`\r`=20to=20`=E2=90=8D`=20and=20`?= =?UTF-8?q?\n`=20to=20`=E2=90=8A`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- doc/adr/0004-nats-headers.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/adr/0004-nats-headers.md b/doc/adr/0004-nats-headers.md index 41347c98..b74d3752 100644 --- a/doc/adr/0004-nats-headers.md +++ b/doc/adr/0004-nats-headers.md @@ -22,7 +22,7 @@ The reference NATS Go client uses the `http.Header` infrastructure for serializi NATS Headers: -The only difference between a NATS header and HTTP is the first line. Instead of an HTTP method followed by a resource and the HTTP version (`GET / HTTP/1.1`), NATS will provide a string identifying the header version (`NATS/X.x\r\n`), currently 1.0, so it is rendered as `NATS/1.0\r\n`. +The only difference between a NATS header and HTTP is the first line. Instead of an HTTP method followed by a resource and the HTTP version (`GET / HTTP/1.1`), NATS will provide a string identifying the header version (`NATS/X.x`), currently 1.0, so it is rendered as `NATS/1.0␍␊`. Please refer to the [specification](https://tools.ietf.org/html/rfc7230#section-3.2) for information on how to encode/decode HTTP headers, and the [Go implementation](https://golang.org/src/net/http/header.go). @@ -45,8 +45,8 @@ The server that is able to send and receive headers will specify so in it's [`IN Messages that include a header have a `HPUB` protocol: ``` -HPUB SUBJECT REPLY 23 30\r\nNATS/1.0\r\nHeader: X\r\n\r\nPAYLOAD\r\n -HPUB SUBJECT REPLY 23 23\r\nNATS/1.0\r\nHeader: X\r\n\r\n\r\n +HPUB SUBJECT REPLY 23 30␍␊NATS/1.0␍␊Header: X␍␊␍␊PAYLOAD␍␊ +HPUB SUBJECT REPLY 23 23␍␊NATS/1.0␍␊Header: X␍␊␍␊␍␊ HPUB [REPLY]
@@ -63,8 +63,8 @@ HPUB [REPLY] Clients will see `HMSG` protocol lines for `MSG`s that contain headers ``` -HMSG SUBJECT 1 REPLY 23 30\r\nNATS/1.0\r\nHeader: X\r\n\r\nPAYLOAD\r\n -HPUB SUBJECT 1 REPLY 23 23\r\nNATS/1.0\r\nHeader: X\r\n\r\n\r\n +HMSG SUBJECT 1 REPLY 23 30␍␊NATS/1.0␍␊Header: X␍␊␍␊PAYLOAD␍␊ +HPUB SUBJECT 1 REPLY 23 23␍␊NATS/1.0␍␊Header: X␍␊␍␊␍␊ HMSG [REPLY]