diff --git a/draft/draft-ietf-netconf-https-notif.xml b/draft/draft-ietf-netconf-https-notif.xml index 1591b08..c46e1ed 100755 --- a/draft/draft-ietf-netconf-https-notif.xml +++ b/draft/draft-ietf-netconf-https-notif.xml @@ -61,13 +61,20 @@ target="RFC9114"> HTTP/3, support for it is considered out of scope of this document at this time. - This document defines support for JSON and XML content; - future efforts may define support for other encodings (e.g., - binary). 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 document defines support for JSON and XML content, using + the media types defined in RESTCONF; future efforts may define + support for other encodings (e.g., CBOR). This document also + defines optional support for sending legacy notifications as + defined in NETCONF Event + Notifications using "application/xml" as the media + type. 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 document also defines two YANG 1.1 modules that extend the data model defined in To learn the capabilities of a receiver, a publisher can issue an HTTPS GET request to the "capabilities" resource - (see ) on the receiver with - "Accept" header set using the "application/xml" as defined - in XML Media Types, and/or - "application/json" as defined in JSON media-types. + (see ) on the receiver with the + "Accept" header set to "application/yang-data+xml" and/or + "application/yang-data+json", as defined in + RESTCONF.
The receiver responds with a "200 (OK)" message, having the - "Content-Type" header set to either "application/xml" or - "application/json" (which ever was selected), and containing + "Content-Type" header set to either "application/yang-data+xml" or + "application/yang-data+json" (whichever was selected), and containing in the response body a list of the receiver's capabilities encoded in the selected format. - Even though a YANG module is not defined for this interaction, - the response body MUST conform to the following YANG-modeled - format: + The response body MUST conform to the "receiver-capabilities" + structure defined in the "ietf-https-notif-transport" YANG module + (see YANG Data Structure Extensions):
- container receiver-capabilities { + structure receiver-capabilities { description - "A container for a list of capabilities supported by - the receiver."; + "A structure defining the response body for the capabilities + GET request."; leaf-list receiver-capability { - type "inet:uri"; + type inet:uri; description "A capability supported by the receiver. A partial list of capabilities is defined in the 'Capabilities for HTTPS @@ -280,11 +286,11 @@
+Accept: application/yang-data+xml, application/yang-data+json;q=0.5]]>
- If the receiver is able to reply using "application/xml", and - assuming it is able to receive JSON and XML encoded notifications, + If the receiver is able to reply using "application/yang-data+xml", + and assuming it is able to receive JSON and XML encoded notifications, and it is able to process the RFC 8639 state machine, the response might look like this: @@ -293,40 +299,41 @@ Accept: application/xml, application/json;q=0.5]]> Date: Wed, 26 Feb 2020 20:33:30 GMT Server: example-server Cache-Control: no-cache -Content-Type: application/xml +Content-Type: application/yang-data+xml - - \ - urn:ietf:capability:https-notif-receiver:encoding:json\ + + + urn:ietf:params:yang-notif:https-capability:encoding:json - \ - urn:ietf:capability:https-notif-receiver:encoding:xml\ + + urn:ietf:params:yang-notif:https-capability:encoding:xml - \ - urn:ietf:capability:https-notif-receiver:sub-notif\ + + urn:ietf:params:yang-notif:https-capability:sub-notif ]]>
- If the receiver is unable to reply using "application/xml", the - response might look like this: + If the receiver is unable to reply using "application/yang-data+xml", + the response might look like this:
@@ -339,9 +346,9 @@ Content-Length: nnn The publisher sends an HTTP POST request to the "relay-notification" resource (see ) on the receiver with the "Content-Type" header - set to either "application/json" or "application/xml" and a - body containing the notification encoded using the specified - format. + set to either "application/yang-data+json" or + "application/yang-data+xml" and a body containing the + notification encoded using the specified format. XML-encoded notifications are encoded using the format defined by NETCONF Event Notifications @@ -374,7 +381,7 @@ Content-Length: nnn
2019-03-22T12:35:00Z @@ -392,7 +399,7 @@ Content-Type: application/xml
+
+ + This document primarily defines a transport for YANG + notifications. However, implementations MAY also use this + HTTPS-based transport to send legacy event notifications as + defined in NETCONF Event + Notifications. This section defines how such legacy + notifications are sent and how a receiver advertises support + for them. + + +
+ + When sending legacy RFC 5277 notifications, the publisher + sends an HTTP POST request to the "relay-notification" + resource (see ) with the + "Content-Type" header set to "application/xml". The body + MUST contain the notification encoded as defined in NETCONF Event Notifications. + +
+ +
+ + A receiver that supports legacy RFC 5277 notifications MUST + advertise this capability by including the following URI in + its capabilities response (see ): + + +
+ urn:ietf:params:yang-notif:https-capability:rfc5277-notif +
+ + + + A publisher that intends to send legacy notifications SHOULD + query the receiver's capabilities first and MUST only send + RFC 5277 notifications when this capability URI is present. + + + A YANG-aware publisher SHOULD issue the capabilities request + with an "Accept" header set to "application/yang-data+xml" + and/or "application/yang-data+json", as described in . A legacy publisher that only understands + "application/xml" MAY instead set the "Accept" header to + "application/xml". In that case, the receiver SHOULD respond + with "Content-Type: application/xml" and the same + "receiver-capabilities" XML structure, allowing the legacy + publisher to parse the capability URIs without requiring + knowledge of YANG media types. + +
+ +
+ A legacy publisher that only understands "application/xml" + can discover receiver capabilities as follows: + +
+ +
+ + + The receiver, recognizing that the publisher sent + "Accept: application/xml", responds with the same + "receiver-capabilities" structure but using + "Content-Type: application/xml": + + +
+ + + urn:ietf:params:yang-notif:https-capability:encoding:json + + + urn:ietf:params:yang-notif:https-capability:encoding:xml + + + urn:ietf:params:yang-notif:https-capability:rfc5277-notif + +]]> +
+ + + Having confirmed the "rfc5277-notif" capability, the legacy + publisher then sends a notification as follows: + + +
+ + 2019-03-22T12:35:00Z + + fault + + Ethernet0 + + major + +]]> +
+ + And the response on success might be as follows: + +
+ +
+ +
+
+
This YANG module augments the "ietf-subscribed-notifications" module to @@ -474,11 +606,15 @@ INSERT_TEXT_FROM_FILE(../bin/ietf-https-notif-transport@YYYY-MM-DD-sub-tree.txt,
- The YANG module imports + The YANG module imports + Common YANG Data Types, A YANG Data Model for SNMP Configuration, Subscription to YANG Notifications, + YANG Data Structure Extensions, - and YANG Groupings for HTTP Clients and HTTP Servers. + and YANG Groupings for HTTP Clients and HTTP Servers. + It also defines the "receiver-capabilities" structure used as + the response body of the capabilities GET request. The YANG module is shown below. @@ -693,6 +829,12 @@ Record: Description: Identifies support for state machine described in RFC 8639, enabling the publisher to send, e.g., the "subscription-started" notification. +Record: + URN: urn:ietf:params:yang-notif:https-capability:rfc5277-notif + Reference: RFC XXXX:An HTTPS-based Transport for YANG Notifications + Description: Identifies support for receiving legacy RFC 5277 + XML notifications, transmitted using "application/xml" + as the Content-Type header value. @@ -710,24 +852,23 @@ Record: - - + + - diff --git a/src/yang/ietf-https-notif-transport.yang b/src/yang/ietf-https-notif-transport.yang index 233d8d3..32f6269 100644 --- a/src/yang/ietf-https-notif-transport.yang +++ b/src/yang/ietf-https-notif-transport.yang @@ -3,6 +3,12 @@ module ietf-https-notif-transport { namespace "urn:ietf:params:xml:ns:yang:ietf-https-notif-transport"; prefix "hnt"; + import ietf-inet-types { + prefix inet; + reference + "RFC 9911: Common YANG Data Types."; + } + import ietf-x509-cert-to-name { prefix x509c2n; reference @@ -20,7 +26,13 @@ module ietf-https-notif-transport { reference "RFC XXXX: An HTTPS-based Transport for YANG Notifications."; } - + + import ietf-yang-structure-ext { + prefix sx; + reference + "RFC 8791: YANG Data Structure Extensions."; + } + import ietf-http-client { prefix httpc; reference @@ -137,4 +149,22 @@ module ietf-https-notif-transport { "Augment the transport-type choice to include the 'https' transport."; } + + sx:structure receiver-capabilities { + description + "A structure defining the response body for the GET request + to the 'capabilities' resource. When encoded as + 'application/yang-data+xml', the root element is + 'receiver-capabilities' in the namespace of this module. + When encoded as 'application/yang-data+json', the top-level + key is 'ietf-https-notif-transport:receiver-capabilities'."; + leaf-list receiver-capability { + type inet:uri; + description + "A capability supported by the receiver. A partial list + of capabilities is defined in the 'Capabilities for HTTPS + Notification Receivers' registry (RFC XXXX). Additional + custom capabilities MAY be defined."; + } + } }