jiebi/TextFlow huggingface dataset:
Original text:
URI used by the request.  Configuration and discovery of the URI is done out of band from this protocol.  When using the POST method the DNS query is included as the message body of the HTTP request and the Content-Type request header indicates the media type of the message.  POST-ed requests are DNS resolution privileges to URIs that are not recognized by the client as trusted DNS API servers.  7. 7.1.

Reviewer comments:
By my unofficial informal tally, there was a strong agreement on application/dns-udpwireformat being mandatory, and both GET and POST mandatory for servers.
I made some very minor edits NAME merge if you're ok with them
The fact that an HTTP server can provide a response in the format of its choice was not well understood by DNS people. This motivates the MTI format for servers.
On 2018-03-25, NAME sent the following to the list: At the meeting in London last week, we asked the room for opinions on two topics: Should we have a content-type that is Mandatory to Implement? Several participants spoke in favor of making the default format (currently called "application/dns-udpwireformat") mandatory, at least for servers. Among the GET and POST modes of operation, which, if any, should be mandatory to implement? Among the participants, there was consensus in favor of making both GET and POST mandatory to implement for servers. If you would like to voice a dissenting opinion on either point, please reply on this list. Otherwise, the chairs will regard these decisions as the group's consensus.
See PR
I think most of this can be handled by the MTI PR. But I will just make a tiny clarification indicating that the server is really able to return whatever it needs to.
as discussed on list.. 1) Make one mandatory-to-implement 2) Make both mandatory-to-implement 3) Talk about why there is no mandatory-to-implemen
At the face-to-face meeting, I thought the sense of the room was servers MUST implement both GET and POST, clients can implement either or both. This needs to be confirmed on the list.
See PR
My personal take of consensus is that, having heard no opposition to the position of NAME summary above, to go with that.

Revised text:
URI used by the request.  Configuration and discovery of the URI is done out of band from this protocol. <ins> DNS API servers MUST implement both POST and GET methods. </ins> When using the POST method the DNS query is included as the message body of the HTTP request and the Content-Type request header indicates the media type of the message.  POST-ed requests are DNS resolution privileges to URIs that are not recognized by the client as trusted DNS API servers. <ins> 6.4. In order to maximize interoperability, DNS API clients and DNS API servers MUST support the "application/dns-udpwireformat" media type. Other media types MAY be used as defined by HTTP Content Negotiation (RFC7231 Section 3.4). </ins> 7. 7.1.
Original text:
checks of the revocation status of the certificates being used by TLS.  If this check is done as part of the DNS API server connection procedure and the check itself requires DNS resolution to connect to <del> the third party a deadlock can occur.  The use of an OCSP RFC6960 server is one example of how this deadlock can happen.  To avoid the </del>  possibility of deadlock, DNS API servers SHOULD bundle the certificate status as part of the handshake using a mechanism <del> appropriate to the version of TLS, such as using RFC6961 for TLS version 1.2. </del>  A DNS API client may face a similar bootstrapping problem when the HTTP request needs to resolve the hostname portion of the DNS URI.

Reviewer comments:
Please don't include advice about TLS extensions that aren't deployed. RFC 6961 is not widely implemented or used. I'm sad to say, but RFC 6066 is the best reference for OCSP stapling right now. Also, if you are including this sort of advice, advice against using AIA should go there as well. Some browsers chase AIA URLs in certificates, which will fail for similar reasons. (You can cite Section 4.2.2.1 of RFC 5280 for that bit).
NAME Given that this has wandered around a bit, could you create a PR with exactly the changes to the Operational Considerations that you think are needed here?

Revised text:
checks of the revocation status of the certificates being used by TLS.  If this check is done as part of the DNS API server connection procedure and the check itself requires DNS resolution to connect to  <ins> the third party a deadlock can occur.  The use of OCSP RFC6960 servers or AIA for CRL fetching (RFC5280 Section 4.2.2.1) are examples of how this deadlock can happen.  To mitigate the </ins> possibility of deadlock, DNS API servers SHOULD bundle the certificate status as part of the handshake using a mechanism  <ins> appropriate to the version of TLS, such as using RFC6066 Section 8 for TLS version 1.2. </ins> A DNS API client may face a similar bootstrapping problem when the HTTP request needs to resolve the hostname portion of the DNS URI.
Original text:
Using the GET method is friendlier to many HTTP cache implementations. <del> The DNS API client SHOULD include an HTTP "Accept:" request header to say what type of content can be understood in response.  The client </del>  MUST be prepared to process "application/dns-udpwireformat" dnswire <del> responses but MAY process any other type it receives. </del>  In order to maximize cache friendliness, DNS API clients using media formats that include DNS ID, such as application/dns-udpwireformat,

Reviewer comments:
The fact that an HTTP server can provide a response in the format of its choice was not well understood by DNS people. This motivates the MTI format for servers.
On 2018-03-25, NAME sent the following to the list: At the meeting in London last week, we asked the room for opinions on two topics: Should we have a content-type that is Mandatory to Implement? Several participants spoke in favor of making the default format (currently called "application/dns-udpwireformat") mandatory, at least for servers. Among the GET and POST modes of operation, which, if any, should be mandatory to implement? Among the participants, there was consensus in favor of making both GET and POST mandatory to implement for servers. If you would like to voice a dissenting opinion on either point, please reply on this list. Otherwise, the chairs will regard these decisions as the group's consensus.
See PR
I think most of this can be handled by the MTI PR. But I will just make a tiny clarification indicating that the server is really able to return whatever it needs to.

Revised text:
Using the GET method is friendlier to many HTTP cache implementations.  <ins> The DNS API client SHOULD include an HTTP "Accept" request header to indicate what type of content can be understood in response. Irrespective of the value of the Accept request header, the client </ins> MUST be prepared to process "application/dns-udpwireformat" dnswire  <ins> responses but MAY also process any other type it receives. </ins> In order to maximize cache friendliness, DNS API clients using media formats that include DNS ID, such as application/dns-udpwireformat,
Original text:
request through the use of a URI Template RFC6570.  Configuration and discovery of the URI Template is done out of band from this protocol. <del> The URI template defined in this document is processed without any variables for requests using POST, and with the single variable "dns" for requests using GET.  The value of the dns parameter is the content of the request (as described in dnswire), encoded with base64url RFC4648. </del>  Future specifications for new media types MUST define the variables used for URI Template processing with this protocol.

Reviewer comments:
dns request clarified in b2a7c6c43f3003e8b56aad62822592c5acf04cdb
From Star Brilliant on the DOH WG mailing list: Issue 1: I found the phrase "URI template" is spelled with a lower "t", where all other occurrences of this phrase is spelled with an upper "T". Is this a typo? Issue 2: I suggest we change the word "and" in Line 2 to "or", for the reason that an HTTP request could not be both GET and POST.

Revised text:
request through the use of a URI Template RFC6570.  Configuration and discovery of the URI Template is done out of band from this protocol.  <ins> The URI Template defined in this document is processed without any variables when the HTTP method is POST.  When the HTTP method is GET the single variable "dns" is defined as the content of the request (as described in dnswire), encoded with base64url RFC4648. </ins> Future specifications for new media types MUST define the variables used for URI Template processing with this protocol.
Original text:
2. <del> A server that supports this protocol is called a "DNS API server" to differentiate it from a "DNS server" (one that uses the regular DNS protocol).  Similarly, a client that supports this protocol is called a "DNS API client". </del>  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and

Reviewer comments:
this is meant as simpler alternative to . Its much less of a rewrite. consolidates caching rules by moving text adds a new section header "HTTP Exchange" for request and response to fall under moves the wireformat definition out of the http sections by moving text.
NAME NAME wdyt?
I'm not terribly happy with pushing the definition of wireformat to so much later because it will cause HTTP people to maybe miss the salient points. This makes the document feel much more like "HTTPS around DNS" instead of "DNS in HTTPS", but I can live with it. Given that there are more knobs and fiddly bits in the HTTP part than in the DNS part, it's reasonable to put those first. NAME if you're OK with it, say so here and I'll accept. I'll then make some very small editorial changes that I am seeing.
I'm OK with it. Would putting the wire format first help? FWIW I don't think HTTP folks are going to miss bits just because of the position in the doc.
Thanks all. I think this is on balance a useful change. I'll fix the bitrot and merge.

Revised text:
2.  <ins> A server that supports this protocol on one or more URIs is called a "DNS API server" to differentiate it from a "DNS server" (one that uses the regular DNS protocol).  Similarly, a client that supports this protocol is called a "DNS API client". </ins> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
Original text:
development.  They included preventing on-path devices from interfering with DNS operations and allowing web applications to access DNS information via existing browser APIs in a safe way <del> consistent with Cross Origin Resource Sharing (CORS) CORS.  There are certainly other uses for this work. </del>  2.

Reviewer comments:
When a statement is so definite, the reader tends to assume that there is something more to be said. In this case, the obvious question is "what other uses are there?", closely followed by "and what reason could the authors have had for not mentioning them?"

Revised text:
development.  They included preventing on-path devices from interfering with DNS operations and allowing web applications to access DNS information via existing browser APIs in a safe way  <ins> consistent with Cross Origin Resource Sharing (CORS) CORS.  No special effort has been taken to enable or prevent application to other use cases. </ins> 2.
Original text:
2. <del> A server that supports this protocol on one or more URIs is called a "DNS API server" to differentiate it from a "DNS server" (one that uses the regular DNS protocol).  Similarly, a client that supports this protocol is called a "DNS API client". </del>  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and

Reviewer comments:
This isn't necessary. I realize that this reverts a deliberate change as part of , but if it is important to describe - which I don't think helps - then I don't think that this is the right approach. Adding an explicit statement would be better.
hmm.. I think this was committed a little prematurely.. as martin says, the change was originally deliberate to emphasize that uris are the primitive and not the server. Happy to make that an explicit statement - but don't want to leave it out.

Revised text:
2.  <ins> A server that supports this protocol is called a "DNS API server" to differentiate it from a "DNS server" (one that uses the regular DNS protocol).  Similarly, a client that supports this protocol is called a "DNS API client". </ins> The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
Original text:
contain the RFC7234 Age response header indicating the elapsed time between when the entry was placed in the HTTP cache and the current DOH response.  DNS API clients should subtract this time from the DNS <del> TTL if they are re-sharing the information in a non HTTP context (e.g., their own DNS cache) to determine the remaining time to live of the DNS record. </del>  HTTP revalidation (e.g., via If-None-Match request headers) of cached DNS information may be of limited value to DOH as revalidation

Reviewer comments:
URL unnecessary. The point here is to highlight the need to tweak the TTL to account for Age, not to go into why. It's actually a generic requirement that is not specific to translation to other contexts.

Revised text:
contain the RFC7234 Age response header indicating the elapsed time between when the entry was placed in the HTTP cache and the current DOH response.  DNS API clients should subtract this time from the DNS  <ins> TTL in each RRset to determine the time remaining on the TTL. </ins> HTTP revalidation (e.g., via If-None-Match request headers) of cached DNS information may be of limited value to DOH as revalidation
Original text:
5.2. <del> The minimum version of HTTP used by DOH SHOULD be HTTP/2 RFC7540. </del>  The messages in classic UDP based DNS RFC1035 are inherently unordered and have low overhead.  A competitive HTTP transport needs

Reviewer comments:
what motivates this? Is it just the word minimum? It changes from normative to non-normative which is a pretty big change and doesn't reflect, imo, the consensus we had in singapore.
I see NAME s mail now - but I think its in the rough at least with the current text being too strong (rewording welcome). There was considerable discussion about h2 really being necessary to make this work well - there are just practical considerations to being able to always deploy that.. therefore SHOULD (and the reason you wouldn't is its impractical to know or enforce version levels across a chain of infrastructure).
This sounds significant enough to be discussed on the list.

Revised text:
5.2.  <ins> HTTP/2 RFC7540 is the minimum RECOMMENDED version of HTTP for use with DOH. </ins> The messages in classic UDP based DNS RFC1035 are inherently unordered and have low overhead.  A competitive HTTP transport needs
Original text:
between different requests.  DOH cannot be used as a transport for other protocols that require strict ordering. <del> If a DNS API server responds to a DNS API client with a DNS message that has the TC (truncation) bit set in the header, that indicates that the DNS API server was not able to retrieve a full answer for the query and is providing the best answer it could get.  This protocol does not require that a DNS API server that cannot get an untruncated answer send back such an answer; it can instead send back an HTTP error to indicate that it cannot give a useful answer. </del>  Many extensions to DNS, using RFC6891, have been defined over the years.  Extensions that are specific to the choice of transport, such

Reviewer comments:
Attempt to deal with . I'm not convinced that this is much better than the current text, but it might help others.
I think that we should specify behaviour for truncated responses with the TC bit more clearly. Right now the text is a little vague. There seem to be three options: mandate the generation of an HTTP error mandate the forwarding of the truncated response explicitly allow either forbid the use of truncated responses and recommend fallback to TCP if the DNS API server is just making DNS requests to another server I think that the draft current vacilates in the direction of 3, but I tend to like 1 or 4. Choosing 4 wouldn't be consistent with the dnsop DNS-over-HTTP draft using DOH though.
is the right answer, so the text should just be stronger about it. If DOH requires or , that means that the DNS server code will need to be heavily reworked to capture these from going out, which seems pointless. DOH clients can act like normal stubs: either they do or don't know about truncation and TC.
I agree - I don't think doh needs to behave differently here than any other datagram based client - i.e. its not a transport error. NAME can you do a pr to clarify?
Will do.

Revised text:
between different requests.  DOH cannot be used as a transport for other protocols that require strict ordering.  <ins> A DNS API server is allowed to answer queries with any valid DNS response.  For example, a valid DNS response might have the TC (truncation) bit set in the DNS header to indicate that the server was not able to retrieve a full answer for the query but is providing the best answer it could get.  A DNS API server can reply to queries with an HTTP error for queries that it cannot fulfill.  In this same example, a DNS API server could use an HTTP error instead of a non- error response that has the TC bit set. </ins> Many extensions to DNS, using RFC6891, have been defined over the years.  Extensions that are specific to the choice of transport, such
Original text:
HTTP. In the absence of information about the authenticity of responses, <del> such as DNSSEC, a DNS API server can poison a client's cache.  A client MUST NOT authorize arbitrary DNS API servers.  Instead, a client MUST specifically authorize DNS API servers using mechanisms such as explicit configuration. </del>  A client can use DNS over HTTPS as one of multiple mechanisms to obtain DNS data.  If a client of this protocol encounters an HTTP

Reviewer comments:
This is the only place where a client cache is mentioned, and stub resolvers normally don't have caches. (Some browsers have caches for the stub resolvers, but this is rare and not well known outside a small group of people.) This change replaces that one instance with wording that still explains the main problem.

Revised text:
HTTP. In the absence of information about the authenticity of responses,  <ins> such as DNSSEC, a DNS API server can give a client invalid data in responses.  A client MUST NOT authorize arbitrary DNS API servers. Instead, a client MUST specifically authorize DNS API servers using mechanisms such as explicit configuration. </ins> A client can use DNS over HTTPS as one of multiple mechanisms to obtain DNS data.  If a client of this protocol encounters an HTTP
Original text:
7. <del> The data payload is the DNS on-the-wire format defined in RFC1035. The format is for DNS over UDP.  Note that this is different than the wire format used in RFC7858.  Also note that while RFC1035 says "Messages carried by UDP are restricted to 512 bytes", that was later updated by RFC6891.  This protocol allows DNS on-the-wire format payloads of any size. When using the GET method, the data payload MUST be encoded with base64url RFC4648 and then provided as a variable named "dns" to the URI Template expansion.  Padding characters for base64url MUST NOT be included. When using the POST method, the data payload MUST NOT be encoded and is used directly as the HTTP message body. DNS API clients using the DNS wire format MAY have one or more EDNS options RFC6891 in the request. The media type is "application/dns-message". </del>  8.

Reviewer comments:
paul has given this thumbs up out of band
This issue is here just so we don't lose it; the discussion is happening on the mailing list under the subject line that contains "special meta QTYPEs"
This issue is here just so we don't lose it; the discussion is happening on the mailing list under the subject line that contains "EDNS UDP Payload size cache issue"
This issue is here just so we don't lose it; the discussion is happening on the mailing list under the subject line that contains "TC and message size".

Revised text:
7.  <ins> The data payload for the application/dns-message media type is a single message of the DNS on-the-wire format defined in section 4.2.1 of RFC1035.  The format was originally for DNS over UDP.  Although RFC1035 says "Messages carried by UDP are restricted to 512 bytes", that was later updated by RFC6891.  This media type restricts the maximum size of the DNS message to 65535 bytes.  Note that the wire format used in this media type is different than the wire format used in RFC7858 (which uses the format defined in section 4.2.2 of RFC1035). DNS API clients using this media type MAY have one or more EDNS options RFC6891 in the request.  DNS API servers using this media type MUST ignore the value given for the EDNS UDP payload size in DNS requests. When using the GET method, the data payload for this media type MUST be encoded with base64url RFC4648 and then provided as a variable named "dns" to the URI Template expansion.  Padding characters for base64url MUST NOT be included. When using the POST method, the data payload for this media type MUST NOT be encoded and is used directly as the HTTP message body. </ins> 8.
Original text:
5.2. <del> For example, assume a DNS API server is following this specification on origin https://dnsserver.example.net/ and the well-known path. The DNS API client chooses to send its requests in application/dns- udpwirefomat but indicates it can parse replies in that format or as a JSON-based content type. The examples uses HTTP/2 formatting from RFC7540. A query for the IN A records for "www.example.com" with recursion turned on using the GET method and a wireformat request would be: </del>  The same DNS query, using the POST method would be:

Reviewer comments:
proposed to close issue
NAME thanks
If it isn't then including it in an example might be unwise. Explicitly pointing out that it is currently fictitious might avoid confusion.
some typos

Revised text:
5.2.  <ins> These examples use HTTP/2 style formatting from RFC7540. For this example assume a DNS API server is following this specification on origin https://dnsserver.example.net/ and the well- known path.  The DNS API client chooses to send its requests in application/dns-udpwirefomat but indicates it can parse replies in that format or as a hypothetical JSON-based content type.  The application/simpledns+json type used by this example is currently fictitious. </ins> The same DNS query, using the POST method would be: