Subject: Re: [yang-doctors] Yangdoctors last call review of draft-ietf-netconf-https-notif-06

From: Mahesh Jethanandani <[email-masked]>
Date: Mon, 8 Feb 2021 20:26:56 -0800

Hi Acee,

Thank you first of all for the review of the document. You reviewed -06, and we have since submitted -07. I will in my responses reflect the changes in -07 that might affect the comments you have provided.

> On Jan 27, 2021, at 9:01 AM, Acee Lindem via Datatracker <[email-masked]> wrote:
> 
> Reviewer: Acee Lindem
> Review result: Almost Ready
> 
> The document is almost ready for WG Last Call. I have the following comments:
> 
> Model ietf-sub-notif-recv-list:
> 
>    Seems odd to have a model that adds a choice statement without any
>    valid options. I realize you expect other transports in the future but
>    having a separate module the one defined in the same draft seems like a
>    profligate design choice.

The draft contains two models as you have noted. While the ietf-sub-notif-recv-list adds a choice statement, the second model goes on to adding a case statement for that choice statement. We could have hard coded the two models together, but believe that by separating them, we offer the flexibility to implementations that may choose not to implement both the models. Also, other transports can augment "receiver-instances", without including the entire http transport model.

If it helps, we can add a comment to that effect in the model to explain our motivation.

> 
> Model ietf-sub-notif-recv-list:
>    1. The prefix "hn" seems inconsistent to lose the context. I'd use
>        "snrlhn".  This wouldn't be an issue if you combined the modules.

The updated model in -07 now carries the prefix “hnt”.

>    2. This comment is incomprehensible:
> 
>               // create the logical impossibility of enabling "tcp"
>               // transport

Would it help if we expanded the comment to say:

// The "http-client-stack-grouping” supports both HTTP and HTTPS stacks by default. This draft, however supports HTTPS only. The following 
// if-feature statement makes it logically impossible to configure HTTP transport.

> 
> In the IANA section, the security considerations for the media types
> point to this draft's security considerations. However, they don't
> include the referenced information. It seems these IANA references
> should point to other RFCs.

The updated IANA section no longer carries the media-types.

> 
> It should be noted that ietf-subscribed-notifications has a number of YANG
> errors and warnings.
> 
> I also have the following editorial comments:

> Acee-Lindems-iMac-2:Desktop acee$ diff -c
> draft-ietf-netconf-https-notif-06.txt.orig
> draft-ietf-netconf-https-notif-06.txt ***
> draft-ietf-netconf-https-notif-06.txt.orig  2021-01-27 10:06:29.000000000 -0500
> --- draft-ietf-netconf-https-notif-06.txt       2021-01-27 11:57:13.000000000
> -0500
> ***************
> *** 17,23 ****
>     This document defines a YANG data module for configuring HTTPS based
>     configured subscription, as defined in RFC 8639.  The use of HTTPS
>     maximizes transport-level interoperability, while allowing for
> !    encoding selection from text, e.g.  XML or JSON, to binary.
> 
>  Status of This Memo
> 
> --- 17,23 ----
>     This document defines a YANG data module for configuring HTTPS based
>     configured subscription, as defined in RFC 8639.  The use of HTTPS
>     maximizes transport-level interoperability, while allowing for
> !    encoding selection from text, e.g.,  XML or JSON, to binary.

The abstract section has been updated.

> 
>  Status of This Memo
> 
> ***************
> *** 103,109 ****
>     documents.  This document defines two YANG 1.1 [RFC7950] data
>     modules, one for augmenting the Subscription to YANG Notifications
>     [RFC8639] to add a transport type, and another for configuring and
> !    managing HTTPS based receivers for the notifications.
> 
> --- 103,109 ----
>     documents.  This document defines two YANG 1.1 [RFC7950] data
>     modules, one for augmenting the Subscription to YANG Notifications
>     [RFC8639] to add a transport type, and another for configuring and
> !    managing HTTPS-based receivers for the notifications.

Fixed.

> 
> ***************
> *** 118,124 ****
>     the same receiver instance.  The second module describes how to
>     enable the transmission of YANG modeled notifications, in the
>     configured encoding (i.e., XML, JSON) over HTTPS.  Notifications are
> !    delivered in the form of a HTTPS POST.  The use of HTTPS maximizes
>     transport-level interoperability, while the encoding selection pivots
>     between implementation simplicity (XML, JSON) and throughput (text
>     versus binary).
> --- 118,124 ----
>     the same receiver instance.  The second module describes how to
>     enable the transmission of YANG modeled notifications, in the
>     configured encoding (i.e., XML, JSON) over HTTPS.  Notifications are
> !    delivered in the form of an HTTPS POST.  The use of HTTPS maximizes
>     transport-level interoperability, while the encoding selection pivots
>     between implementation simplicity (XML, JSON) and throughput (text
>     versus binary).
> ***************

Fixed.

> *** 196,202 ****
> 
>     In the case of "pipelining", the flow of messages would look
>     something like this.  This example shows the flow assuming that
> !    Subscribed Notifications is used and therefore a <subscription-
>     started> notification is sent before sending the first notification.
>     The example would be the same for when Subscribed Notification is not
>     used by removing the first POST message for <susbscription-started>.
> --- 196,202 ----
> 
>     In the case of "pipelining", the flow of messages would look
>     something like this.  This example shows the flow assuming that
> !    Subscribed Notification is used and therefore a <subscription-
>     started> notification is sent before sending the first notification.
>     The example would be the same for when Subscribed Notification is not
>     used by removing the first POST message for <susbscription-started>.
> ***************

This section has been rewritten.

> *** 342,350 ****
> 
>  2.1.  Introduction
> 
> !    To learn the capabilities of the receiver, the publisher can issue a
>     HTTPS GET request with Accept-Type set to application/ietf-https-
> !    notif-cap+xml or application/ietf-https-notif-cap+json, with latter
>     as the mandatory to implement, and the default in case the type is
>     not specified.  If the receiver supports capabilities such as binary
>     encoding of data, it can return that as a capability in a response.
> --- 342,350 ----
> 
>  2.1.  Introduction
> 
> !    To learn the capabilities of the receiver, the publisher can issue an
>     HTTPS GET request with Accept-Type set to application/ietf-https-
> !    notif-cap+xml or application/ietf-https-notif-cap+json, with the latter
>     as the mandatory to implement, and the default in case the type is
>     not specified.  If the receiver supports capabilities such as binary
>     encoding of data, it can return that as a capability in a response.
> ***************

Fixed.

> *** 450,456 ****
>  Internet-Draft        HTTPS Configured Subscription        November 2020
> 
> !      Copyright (c) 2018 IETF Trust and the persons identified as
>       the document authors.  All rights reserved.
>       Redistribution and use in source and binary forms, with or
>       without modification, is permitted pursuant to, and subject
> --- 450,456 ----
>  Internet-Draft        HTTPS Configured Subscription        November 2020
> 
> !      Copyright (c) 2021 IETF Trust and the persons identified as
>       the document authors.  All rights reserved.
>       Redistribution and use in source and binary forms, with or
>       without modification, is permitted pursuant to, and subject
> ***************

Fixed.

> *** 536,545 ****
> 
>     This YANG module is a definition of a set of receivers that are
>     interested in the notifications published by the publisher.  The
> !    module contains the TCP, TLS and HTTPS parameters that are needed to
>     communicate with the receiver.  The module augments the ietf-sub-
>     notif-recv-list module to define a transport specific receiver.  As
> !    mentioned earlier, it uses POST method to deliver the notification.
>     The attribute 'path' defines the path for the resource on the
>     receiver, as defined by 'path-absolute' in URI Generic Syntax
>     [RFC3986].  The user-id used by Network Configuration Access Control
> --- 536,545 ----
> 
>     This YANG module is a definition of a set of receivers that are
>     interested in the notifications published by the publisher.  The
> !    module contains the TCP, TLS, and HTTPS parameters that are needed to
>     communicate with the receiver.  The module augments the ietf-sub-
>     notif-recv-list module to define a transport specific receiver.  As
> !    mentioned earlier, it uses the POST method to deliver the notification.
>     The attribute 'path' defines the path for the resource on the
>     receiver, as defined by 'path-absolute' in URI Generic Syntax
>     [RFC3986].  The user-id used by Network Configuration Access Control
> ***************

This section of the module has been rewritten.

> *** 639,645 ****
>       description
>         "YANG module for configuring HTTPS base configuration.
> 
> !         Copyright (c) 2018 IETF Trust and the persons identified as
>          the document authors.  All rights reserved.
>          Redistribution and use in source and binary forms, with or
>          without modification, is permitted pursuant to, and subject
> --- 639,645 ----
>       description
>         "YANG module for configuring HTTPS base configuration.
> 
> !         Copyright (c) 2021 IETF Trust and the persons identified as
>          the document authors.  All rights reserved.
>          Redistribution and use in source and binary forms, with or
>          without modification, is permitted pursuant to, and subject
> ***************

Fixed.

> *** 704,710 ****
> 
>             container receiver-identity {
>               description
> !                "Specifies mechanism for identifying the receiver.
>                  The publisher MUST NOT include any content in a
>                  notification that the user is not authorized to view.";
> 
> --- 704,710 ----
> 
>             container receiver-identity {
>               description
> !                "Specifies the mechanism for identifying the receiver.
>                  The publisher MUST NOT include any content in a
>                  notification that the user is not authorized to view.";
> 
> ***************

This description statement has been updated.

> *** 791,801 ****
> 
>  6.  Receiving Event Notifications
> 
> !    Encoding notifications for the HTTPS notifications is the same as the
>     encoding notifications as defined in RESTCONF [RFC8040] Section 6.4,
>     with the following changes.  Instead of saying that for JSON-encoding
>     purposes, the module name for "notification" element will be "ietf-
> !    restconf, it will say that for JSON-encoding purposes, the module
>     name for "notification" element will be "ietf-https-notif".
> 
>     With those changes, the SSE event notification encoded JSON example
> --- 791,801 ----
> 
>  6.  Receiving Event Notifications
> 
> !    Encoding notifications for the HTTPS notifications is the same as for
>     encoding notifications as defined in RESTCONF [RFC8040] Section 6.4,
>     with the following changes.  Instead of saying that for JSON-encoding
>     purposes, the module name for "notification" element will be "ietf-
> !    restconf", it will say that for JSON-encoding purposes, the module
>     name for "notification" element will be "ietf-https-notif".
> 
>     With those changes, the SSE event notification encoded JSON example
> ***************

This and all the following sections have been updated. 

Thanks.

> *** 815,826 ****
> 
>  7.  IANA Considerations
> 
> !    This document registers two URI, two YANG module and two Media Types.
> 
>  7.1.  URI Registration
> 
>     in the IETF XML registry [RFC3688].  Following the format in RFC
> !    3688, the following registration is requested to be made:
> 
>     URI: urn:ietf:params:xml:ns:yang:ietf-http-notif
>     URI: urn:ietf:params:xml:ns:yang:ietf-sub-notif-recv-list
> --- 815,826 ----
> 
>  7.  IANA Considerations
> 
> !    This document registers two URIs, two YANG modules, and two Media Types.
> 
>  7.1.  URI Registration
> 
>     in the IETF XML registry [RFC3688].  Following the format in RFC
> !    3688, the following registrations are requested to be made:
> 
>     URI: urn:ietf:params:xml:ns:yang:ietf-http-notif
>     URI: urn:ietf:params:xml:ns:yang:ietf-sub-notif-recv-list
> ***************
> *** 854,860 ****
> 
>  7.3.  Media Types
> 
> ! 7.3.1.  Media Type "application/ietf-https-notif-cap+xml
> 
>  Type name: application
> 
> --- 854,860 ----
> 
>  7.3.  Media Types
> 
> ! 7.3.1.  Media Type "application/ietf-https-notif-cap+xml"
> 
>  Type name: application
> 
> ***************
> *** 917,923 ****
> 
>  Provisional registration? (standards tree only): no
> 
> ! 7.3.2.  Media Type "application/ietf-https-notif-cap+json
> 
>  Type name: application
> 
> --- 917,923 ----
> 
>  Provisional registration? (standards tree only): no
> 
> ! 7.3.2.  Media Type "application/ietf-https-notif-cap+json"
> 
>  Type name: application
> 
> ***************
> *** 1106,1112 ****
>  </config>
> 
> ! 8.2.  Non Subscribed Notification based Configuration
> 
>     In the case that it is desired to use HTTPS notif outside of
>     Subscribed Notifications, there would have to be a module to define
> --- 1106,1112 ----
>  </config>
> 
> ! 8.2.  Non-Subscribed Notification based Configuration
> 
>     In the case that it is desired to use HTTPS notif outside of
>     Subscribed Notifications, there would have to be a module to define
> 
> Thanks,
> Acee
> 
> 

Mahesh Jethanandani
[email-masked]

---

From: "Acee Lindem (acee)" <[email-masked]>
Date: Wed, 10 Feb 2021 19:03:49 +0000

Hi Mahesh,

Thanks for the update. See some inlines.

From: Mahesh Jethanandani <[email-masked]>
Date: Monday, February 8, 2021 at 11:27 PM
To: Acee Lindem <[email-masked]>
Cc: YANG Doctors <[email-masked]>, "[email-masked]" <[email-masked]>, "[email-masked]" <[email-masked]>, "[email-masked]" <[email-masked]>
Subject: Re: Yangdoctors last call review of draft-ietf-netconf-https-notif-06

Hi Acee,

On Jan 27, 2021, at 9:01 AM, Acee Lindem via Datatracker <[email-masked]<mailto:[email-masked]>> wrote:

Reviewer: Acee Lindem

Well, right now, there is only one choice for transport.

That would be good although I understood the motivation. I guess this is one way to make it optional but currently the only option is both models or neither.

That is an improvement but since this augments a model with “snr” as the prefix, it seems that should be part of the prefix. If you didn’t have a separate model, it wouldn’t be an issue. ;^) However, I’m leave it to Tom (copied) for further debate.

Yes.

That’s better.

Thanks,
Acee

 Status of This Memo

--- 17,23 ----

 Status of This Memo

***************
*** 103,109 ****

--- 103,109 ----

Fixed.

***************
*** 118,124 ****

Fixed.

*** 196,202 ****

*** 342,350 ****

 2.1.  Introduction

 2.1.  Introduction

Fixed.

*** 450,456 ****

Fixed.

*** 536,545 ****

*** 639,645 ****
      description

Fixed.

*** 704,710 ****

--- 704,710 ----

***************

*** 791,801 ****

Thanks.

*** 815,826 ****

 7.  IANA Considerations

 7.1.  URI Registration

 7.  IANA Considerations

 7.1.  URI Registration

 7.3.  Media Types

 Type name: application

--- 854,860 ----

 7.3.  Media Types

 Type name: application

***************
*** 917,923 ****

 Type name: application

--- 917,923 ----

 Type name: application

***************
*** 1106,1112 ****
 </config>

Thanks,
Acee

Mahesh Jethanandani
[email-masked]<mailto:[email-masked]>

---

From: Mahesh Jethanandani <[email-masked]>
Date: Tue, 16 Feb 2021 10:30:16 -0800

Hi Acee,

See inline with [mj]

> On Feb 10, 2021, at 11:03 AM, Acee Lindem (acee) <[email-masked]> wrote:
> 
> Hi Mahesh, 
>  
> From: Mahesh Jethanandani <[email-masked] <mailto:[email-masked]>>
> To: Acee Lindem <[email-masked] <mailto:[email-masked]>>
> Cc: YANG Doctors <[email-masked] <mailto:[email-masked]>>, "[email-masked] <mailto:[email-masked]>" <[email-masked] <mailto:[email-masked]>>, "[email-masked] <mailto:[email-masked]>" <[email-masked] <mailto:[email-masked]>>, "[email-masked] <mailto:[email-masked]>" <[email-masked] <mailto:[email-masked]>>
>> On Jan 27, 2021, at 9:01 AM, Acee Lindem via Datatracker <[email-masked] <mailto:[email-masked]>> wrote:
>>  
>> Reviewer: Acee Lindem

[mj] True if you want to use https as the transport. There is another WG draft, the UDP transport draft that will use the ietf-sub-notif-recv-list module to add a case statement for udp transport. If this draft proposes one model, the UDP transport would have to import all the models https transport draft imports, just to resolve all the dependencies.

Ideally, this model should have been part of RFC 8639. But that train has already left the station. We were surprised that no one suggested that the model be spun into a draft of its own, although that draft would be very small.

Thanks.

> [email-masked] <mailto:[email-masked]>
>  
>  
>  
> 
>  

Mahesh Jethanandani
[email-masked]