Re: [Last-Call] [netconf] Last Call: <draft-ietf-netconf-https-notif-13.txt> (An HTTPS-based Transport for YANG Notifications) to Proposed Standard

[Mark Nottingham <[e-mail]>]

Hi Mahesh,

Responses below.

> On 29 Nov 2022, at 1:12 pm, Mahesh Jethanandani <[e-mail]> wrote:
> 
> HI Mark,
> 
> Thanks first of all for your review of the document.
> 
>> On Nov 8, 2022, at 9:52 PM, Mark Nottingham <mnot=[e-mail]> wrote:
>> 
>>> The IESG has received a request from the Network Configuration WG (netconf) to consider the following document: - 'An HTTPS-based Transport for YANG Notifications' <draft-ietf-netconf-https-notif-13.txt> as Proposed Standard
>> [...]
>>> The file can be obtained via
>>> https://datatracker.ietf.org/doc/draft-ietf-netconf-https-notif/
>> 
>> I'm reviewing this document with a focus on how it uses HTTP.
>> 
>> * The Abstract and Introduction both start with "This document defines a protocol for sending notifications over HTTPS." This is a very general statement and is likely to mislead many readers -- 'notifications' are a very broad capability. Could you please make it more specific to the intended use case?
> 
> Would it help if we said that “This document defines a protocol for sending an asynchronous event notification similar to the notifications defined in NETCONF Event Notifications [RFC 5277], but over HTTPS"?

That's great.

>> * The document talks about HTTP a lot, but doesn't actually reference RFC9110. It probably should.
> 
> Ok. Will add the reference.
> 
>> 
>> * "This document requires that the publisher is a "server" (e.g., a NETCONF or RESTCONF server), but does not assume that the receiver is a NETCONF or RESTCONF server. It does expect the receiver to be an HTTPS server to receive the notifications." This is a confusing paragraph. What is a "receiver"? More generally, it would be good if terms like "server" were consistently qualified, since it is used in both HTTP and NETCONF (apparently).
> 
> We can import the definition of a receiver and publisher from RFC 8639 to clarify those definitions. As far as the use of “server" is concerned, where it is not qualified, we can prefix it with NETCONF/RESTCONF to distinguish it from HTTP or other servers. Does that work?

I think so.

>> * Throughout, you use "target resource." What is the significance of "target" here? As far as I can tell, they're just HTTP resources.
> 
> “target resource” as a term in imported from RFC 8040, which describes it as follows. Would it help if we refer to it?
> 
> target resource: the resource that is associated with a particular
> message, identified by the "path" component of the request URI.

Yes.

>> * "These two resources share a common prefix that the publisher must know." Do you mean that the resources' identifiers (i.e., URIs) share a common prefix?
> 
> That is correct. How about we say “These two resource identifiers share a common prefix that a publisher learns from a request it issues, as defined in Section 3.2”?

That's better.

>> * "The POST messages MAY be "pipelined" (not illustrated in the diagram above), whereby multiple notifications are sent without waiting for the HTTP response for a previous POST." Did you consider this text from s 9.3.2 of RFC9112?
>> 
>>> Idempotent methods (Section 9.2.2 of [HTTP]) are significant to pipelining because they can be automatically retried after a connection failure. A user agent SHOULD NOT pipeline requests after a non-idempotent method, until the final response status code for that method has been received, unless the user agent has a means to detect and recover from partial failure conditions involving the pipelined sequence.
> 
> A relay-notification is not idempotent, in that a subsequent (duplicate) notification could confuse the receiver. Based on what you are quoting, my understanding is that we cannot pipeline such a request. If that is the case, we will remove the above statement. Would you agree?

I think so.

>> Also, the word pipelined doesn't need to be quoted.
> 
> If we remove the line, this becomes a non-issue.
> 
>> 
>> * In s 3.4: "In this example, the "Accept" states that the publisher wants to receive the capabilities response in XML but, if not supported, then in JSON." The Accept header field doesn't use ordering to indicate precedence; you need to use q values. See RFC9110 s 12.5.1.
> 
> I am not entirely clear on how to redo the example to use the q value. Can you suggest the change? Otherwise, we can change the example by saying it will accept either XML and JSON.

Something like:

Accept: application/xml;q=1.0, application/json;q=0.5



Cheers,


--
Mark Nottingham   https://www.mnot.net/