Re: [Netconf] yang-push issue: error handling

[Andy Bierman <[e-mail]>]

On Wed, Jan 10, 2018 at 11:50 AM, Eric Voit (evoit) <[e-mail]> wrote:

> I have placed the error mechanism described in the thread below into the
> YANG models.   These can be seen at:
>
>
>
> https://github.com/netconf-wg/rfc5277bis/blob/master/ietf-
> subscribed-notifications%402018-01-10.yang
>
>
>
> https://github.com/netconf-wg/yang-push/blob/master/ietf-
> yang-push%402018-01-10.yang
>
>
>
> Aspects worth noting:
>
>
>
> (a) Error “reason” is included as an identityref rather than an
> enumeration.  Using an identityref here provides several benefits:
>
> - each type of error need be defined only once
>
> - new error identities can be added in yang-push, and then are
> automatically usable with subscribed-notification RPCs/Notifications
>
> - vendor specific error reason identities can be added to model importing
> yang-push, and still used with existing subscribed-notification
> RPCs/Notifications
>
>
>
> (b) Individual error identities can have multiple base identities.
>
>
>
> E.g.:
>
>   identity no-such-subscription {
>
>        base modify-subscription-error;
>
>        base delete-subscription-error;
>
>        base subscription-terminated-reason;
>
>     description
>
>      "Referenced subscription doesn't exist. This may be as a result of
>
>       a non-existent subscription ID, an ID which belongs to another
>
>       subscriber, or an ID for configured subscription.";
>
>   }
>
>
>
> This multi-base definition provides guidance/enforcement of what errors
> are valid with which RPCs/Notifications.  If people want, this information
> now embedded in the YANG model can also be summarized for easier reference
> in a non-normative appendix.
>
>
>
> (c) For RPCs, there is no need to populate more error-app-tag or
> error-message (as these are optional in RFC6241).  Instead, a simple
> “subscription-error” could be used as the error-app-tag.   The error-info
> would provide all additional details.
>
>
>
> Thoughts?   If nothing, I will update the draft text to match these YANG
> models.
>


I do not really like all the special error condition indications, some for
just 1 operation.
There are already requirements for error handling that clients and servers
already have to support

Using just 'no-such-subscription' as an example...
RFC 7950 sec 15.5 already says how to handle a 'require-instance' error for
a leafref:

  error-tag: data-missing
     error-app-tag:  instance-required
     error-path:     Path to the instance-identifier or leafref leaf.

Individual NETCONF and RESTCONF operations have their own error handling
requirements.

I prefer a new error-app-tag for each separate "error-info" block modeled
in rc:yang-data.
E.g.,

    error-tag: resource-denied
    error-app-tag: subscription-not-supported
    error-info: rc:data struct describing sub-resources not supported with
given params



Eric
>

Andy



>
>
>
>
> Hi Andy,
>
>
>
> *From:* Andy Bierman, January 8, 2018 8:19 PM
>
> On Mon, Jan 8, 2018 at 4:38 PM, Eric Voit (evoit) <[e-mail]> wrote:
>
> Hi Martin,
>
> Moving error information to yang-data instead of within descriptions has
> some good points.  But we shouldn't be dependent on yd:augment-yang-data.
>     1) there is no mechanism to insert additional error types into the
> leaf reason enum set.
>
>
>
>
>
> There has NEVER been any mechanism to add your own error-tag values.
>
> This is by design. This set is fixed by the NETCONF protocol.
>
> The error-app-tag is available for this purpose.
>
> The description-stmt has to be used to define error-app-tag and other
> <rpc-error>
>
> requirements for individual RPC operations.
>
>
>
> <Eric>  There is no intent to add error-tag values.   What I was referring
> to was the types of errors which would be sent back as error-app-tags.
> (e.g., stream-unavailable, insufficient-resources...)  With Martin’s
> original proposal, new enums would have needed to be augmented in to leaf
> ‘reason’.
>
>
>
> Martin is ok with the alternative I proposed below using independent
> yang-data constructs for the different error responses for both stream and
> datastore.  These independent constructs eliminates the need for such enum
> or yang-data augmentation.    As the shift in the draft to use error
> constructs was intended to help backwards compatibility for existing
> implementations, are you also ok with such an approach?
>
>
>
> Eric
>
>
>
>
>
> Andy
>
>
>
>
>
>     2) draft-bierman-netmod-yang-data-ext is not yet adopted
> So it is not a full or near-term answer.  If we do go down the yang-data
> path, instead I believe we should use RFC8040's rc:yang-data extension.
>
> If we do go with rc:yang-data, perhaps we could have independent ones for
> establish-subscription for the different datastore targets  (i.e., one
> rc:yang-data for streams and one for datastores).  This would seem
> reasonable as the error info returned for streams isn't the same as for
> datastores.  Such an approach would look something like:
>   rc:yang-data establish-subscription-stream-error-info
>   rc:yang-data establish-subscription-datastore-error-info
> Either of these two could then be inserted as within the error-info in the
> response.
>
> However that would also mean that the establish-subscription error
> response would have to handle several different yang-data containers.  Are
> people ok with this?   If not, we likely should either stay with error
> information in descriptions, or go back to hints returned as in the earlier
> yang-push drafts.
>
> Eric
>
> > From: Martin Bjorklund, January 8, 2018 6:59 AM
> >
> > Hi,
> >
> > I think that in the base document, you can do:
> >
> >   yd:yang-data establish-subscription-error-info {
> >     description
> >       "Nodes to put into 'error-info' on error....";
> >
> >     leaf reason {
> >       type enumeration { // instead of listing strings for
> >                          // error-app-tag in the description
> >         enum stream-unavailable { ... }
> >         enum "encoding-not-supported { ... }
> >         ...
> >       }
> >     }
> >     uses hints;
> >     leaf replay-start-time-hint {
> >       type yang:date-and-time;
> >       ...
> >     }
> >   }
> >
> > Then in establish-subscription, you can describe that this structure is
> used in
> > 'error-info' upon error.
> >
> > In YANG push you can then do:
> >
> >   yd:augment-yang-data {
> >     // push-specific extra params here
> >   }
> >
> >
> >
> > /martin
> >
> >
> >
> > "Alexander Clemm" <[e-mail]> wrote:
> > > Hi all,
> > >
> > > Getting back to the thread on error handling in YANG-Push.
> > >
> > > In updating the module to move the negotiation hints into <rpc-error>
> > > and error-info etc, I have come across another issue for which it is
> > > not clear what is the best way to address it in YANG.  It would be
> > > great to get some guidance here from some of the resident YANG
> > > experts:-)
> > >
> > > The problem comes when augmenting the RPCs defined in
> > > subscribed-notifications for YANG-Push. As discussed earlier in the
> > > thread, the negotiation hints and application-specific error
> > > conditions have now been moved into <rpc-error>, specifically
> > > error-info (as well as the app-error-tag).  The information to include
> > > is defined as part of the description clause pasted below.
> > >
> > > In YANG-Push, we want to add additional information to return as part
> > > of error-info.  For this, we would ideally want to augment the
> > > description clause of the RPC (previously we had augmented the RPC
> > > output parameters, but now this is moving into error-info).  How do we
> > > do that?  Clearly, we cannot augment just the description clause.
> > > Given that we are still augmenting the input parameters of the RPC,
> > > one possibility would be to use the description clause of that.  This
> > > does not seem the ideal place to put it, but what are the
> > > alternatives?  Another option would be to not augment the RPC, but
> > > define an entirely new RPC (e.g. "establish-datastore-subscription" in
> > > addition to "establish-subscription").  This is not preferred (as it
> > > would run somehow counter to why we introduced the
> > > subscribed-notification mechanism as generalization of YANG-push, as
> > > opposed to making them orthogonal) .  Or perhaps there is a third
> > > option that we haven't yet thought of?
> > >
> > > Here is the description of establish-subscription in subscribed
> > > notifications that we want to augment.
> > >
> > >   rpc establish-subscription {
> > >     description
> > >       "This RPC allows a subscriber to create (and possibly negotiate)
> > >        a subscription on its own behalf.  If successful, the
> > >        subscription remains in effect for the duration of the
> > >        subscriber's association with the publisher, or until the
> > >        subscription is terminated.
> > >
> > >        In case an error is returned, the subscription is not created.
> > >        In that case, the RPC error response SHOULD include an
> > >        error-app-tag that indicates the reason why the subscription
> > >        was not created.  Depending on the reason, one of the
> > >        following strings SHOULD be returned:
> > >        &quot;stream unavailable&quot;
> > >        &quot;encoding not supported&quot;
> > >        &quot;replay not supported&quot;
> > >        &quot;filter unavailable&quot; // referenced filter does not
> exist
> > >        &quot;filter type unsupported&quot;
> > >        &quot;filter unsupported&quot; // example: filter too complex
> > >        &quot;namespace unavailable&quot;
> > >        &quot;insufficient resources&quot;
> > >        &quot;unsupportable volume&quot; // requested data volume too
> large
> > >        &quot;no such option&quot; // requested parameter setting not
> > >        supported
> > >        &quot;DSCP unavailable&quot; // requested DSCP marking not
> > allocatable
> > >        &quot;QoS unsupported&quot; // requested QoS parameter not
> > > supported
> > >
> > >        In addition, the RPC error response SHOULD include error-info
> > >        with a set of suggested parameter settings that would have a
> > >        higher likelihood of succeeding in a subsequent
> > >        establish-subscription request.  The error-info should include
> > >        the following YANG data:
> > >        // begin error-info
> > >        uses hints;
> > >        leaf replay-start-time-hint {
> > >          type yang:date-and-time;
> > >            description
> > >              "If a replay has been requested, but the requested replay
> > >              time cannot be honored, this may provide a hint at an
> > >              alternate time which may be supportable.";
> > >          }
> > >        // end error-info
> > >        ";
> > > ...
> > >
> > > For the datastore subscription in YANG-push, we would like to augment
> > > that YANG-data that the error-info should include.  We also want to
> > > add additional app-error tags.
> > >
> > > Thoughts?
> > > --- Alex
> > >
> > > -----Original Message-----
> > > From: Netconf [mailto:[e-mail]] On Behalf Of Alexander
> > > Clemm
> > > Sent: Tuesday, December 5, 2017 12:35 PM
> > > To: Martin Bjorklund <[e-mail]>; [e-mail]
> > > Cc: [e-mail]
> > > Subject: Re: [Netconf] yang-push issue: error handling
> > >
> > > Hi Martin,
> > >
> > > Sure, the eventual solution may make use of rpc-error again.  But
> > > until we get there, the currently proposed solution seems to make
> > > sense to me.  I don't think we have an issue today with lots of RPCs
> > > each defining their own way of dealing with corner conditions -
> > > definition of RPCs is something that has so far only rarely been
> > > exercised with YANG models.  Once this becomes more common, I am sure
> > > we will find a more general solution, but I don't think we are at that
> > > point.
> > >
> > > --- Alex
> > >
> > > > -----Original Message-----
> > > > From: Martin Bjorklund [mailto:[e-mail]]
> > > > Sent: Tuesday, December 05, 2017 12:25 PM
> > > > To: [e-mail]
> > > > Cc: Alexander Clemm <[e-mail]>; [e-mail]
> > > > Subject: Re: [Netconf] yang-push issue: error handling
> > > >
> > > > Andy Bierman <[e-mail]> wrote:
> > > > > Hi,
> > > > >
> > > > > The protocol defines how error handling is done, not the
> > > > > individual operations.
> > > > > If the request fails, then clients expect an <rpc-error> and
> > > > > servers are designed to send an <rpc-error> when a client request
> fails.
> > > >
> > > > Agreed, and for RESTCONF, the HTTP error codes are used.  An HTTP
> > > > request that fails does not return 200 ok with a body that explains
> > > > that it actually was an error.
> > > >
> > > > > IMO, a separate error handling procedure for each RPC is more
> > > > > clunky than error-info.
> > > >
> > > > +1
> > > >
> > > > Some additional comments inline.
> > > >
> > > >
> > > > > > While possible, the solution of having to return rpc-error etc
> > > > > > does strike me as somewhat clunky.  While it is possible to add
> > > > > > an error-app-tag, and negotiation stuff as error-info (and I
> > > > > > appreciate the suggestion), that solution would need to be
> > > > > > described using a lot of prose in description statements a la
> > > > > > SMIv2 (presumably as part of the RPC description, not as part of
> > > > > > e.g. the identities, which might be used in a number of places,
> > > > > > not just the error-app-tag).
> > > >
> > > > If both the error code and hint is defined in a yang-data (i.e., not
> > > > using the error-app-tag), you would do:
> > > >
> > > >   yx:yang-data subscription-error {
> > > >     container subscription-error {
> > > >       leaf error-code {
> > > >         type identity {
> > > >           base error;
> > > >         }
> > > >       }
> > > >       container hints { ... }
> > > >     }
> > > >   }
> > > >
> > > > Then you are right, you have to describe in prose that this
> > > > yang-data structure can be sent as error-info.
> > > >
> > > >
> > > > > > I am not sure why that would make an RPC any easier to implement.
> > > > > > The same checks still have to be made.
> > > >
> > > > Agreed.
> > > >
> > > > > > Why would the proposed solution not acceptable?   Ideally YANG
> would
> > > > > > provide better support to formally define
> > > > > > application/RPC-specific return codes and corner conditions etc.
> > > >
> > > > Also agreed.  But once we have that, such a solution would make use
> > > > of the rpc-error we have (for both NETCONF and RESTCONF).
> > > >
> > > >
> > > > /martin
> > > >
> > > >
> > > > > > Short of that, the proposed solution of adding RPC output
> > > > > > parameters that are used for the purpose of indicating what is
> > > > > > going on at the application level simply makes them part of the
> > > > > > semantics of the specific RPC itself.  It is not Netconf’s role
> > > > > > to define what an RPC can or cannot do, just like it cannot
> > > > > > define what a particular leaf may or may not represent.  That is
> > > > > > part of the RPC definition.
> > > > > >
> > > > > >
> > > > > >
> > > > > > Basically, what we are discussing here is behavior of
> > > > > > subscription configuration under corner conditions.  The fact
> > > > > > that no subscription is created because it would result in an
> > > > > > unacceptable volume of updates for a specific implementation is
> > > > > > different from an error condition such as a malformed message
> > > > > > that is missing a required message-id, or where a value violates
> > > > > > a constraint specified in a MUST-condition.  In our case, what
> > > > > > is being described are
> > > > specific conditions at the application layer, above the
> > > > > > Netconf/Restconf generic validation infrastructure.  The
> > > > > > operation does not “work” in the sense that it does not result
> > > > > > in an active subscription, but it does work in the sense that
> > > > > > the behavior is very well defined in terms of the effect that
> > > > > > the RPC has (i.e.
> > > > > > the effect is that it result in creation of a subscription, if
> > > > > > certain conditions are met, and it does not result in creation
> > > > > > of a subscription in case certain conditions are not met).  Why
> > > > > > should Netconf restrict what an RPC can or cannot do?  This is
> > > > > > all
> > > > > > application-
> > > > specific.
> > > > > >
> > > > > >
> > > > > >
> > > > > > --- Alex
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > *From:* Netconf [mailto:[e-mail]] *On Behalf Of
> > > > > > *Andy Bierman
> > > > > > *Sent:* Monday, December 04, 2017 9:15 AM
> > > > > > *To:* Martin Bjorklund <[e-mail]>
> > > > > > *Cc:* Netconf <[e-mail]>
> > > > > > *Subject:* Re: [Netconf] yang-push issue: error handling
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > On Mon, Dec 4, 2017 at 4:55 AM, Martin Bjorklund
> > > > > > <[e-mail]>
> > > > wrote:
> > > > > >
> > > > > > Andy Bierman <[e-mail]> wrote:
> > > > > > > Hi,
> > > > > > >
> > > > > > > IMO the special error handling in YANG Push is not acceptable
> > > > > > > because it violates NETCONF and RESTCONF error handling
> > procedures.
> > > > > > > NETCONF says if the operation does not work for any reason an
> > > > > > > <rpc-error> element SHOULD be returned.
> > > > > >
> > > > > > I fully agree, and I have pointed this out several times in my
> > > > > > reviews.  The problem is actually in subscribed notifications,
> > > > > > and I think Eric is tracking that issue.
> > > > > >
> > > > > > Trying to be constructive, I think that the existing mechanisms
> > > > > > in YANG can be used to achieve the same functionality that these
> > > > > > drafts try to achieve.  Specifically:
> > > > > >
> > > > > >   1. Use identities just like the ones you have
> > > > > >      ("unsupportable-volume", "filter-unavailable" etc), but add
> text
> > > > > >      that explains that these identities are sent as
> "error-app-tag"
> > > > > >      in "rpc-error", encoded to a string as
> <module>:<identity>.  This
> > > > > >      works for both NETCONF and RESTCONF.
> > > > > >
> > > > > >   2. For the "hints" extra info that you return, define a
> "yang-data"
> > > > > >      structure with the hints, and explain in text that this
> structure
> > > > > >      is returned in "error-info".  This works for both NETCONF
> and
> > > > > >      RESTCONF.
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > +1
> > > > > >
> > > > > >
> > > > > >
> > > > > > If the error handling was done correctly then the same
> > > > > > procedures could be
> > > > > >
> > > > > > applied to <edit-config> failures for configured subscriptions.
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > As an alternative to 1, you can put the error identitiyref in
> > > > > > the "yang-data" structure, and send both the identitiyref and
> > > > > > hints in "error-info".
> > > > > >
> > > > > >
> > > > > > /martin
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > Andy
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > >
> > > > > > > The <establish-subscription> returns data even on error.
> > > > > > > Instead of the common error-tag, error-info, and other fields,
> > > > > > > there is a subscription-result leaf.
> > > > > > >
> > > > > > > If any client (or even server) functionality uses the NETCONF
> > > > > > > and RESTCONF standard error handling, then subscription-result
> > > > > > > will not be sent or expected as an error response. Depending
> > > > > > > on the server implementation, the code that knows about
> > > > > > > establish-subscription may not get called because common error
> > > > > > > handling code has already determined there is an <rpc-error>
> > > > > > > to send instead of a data response.
> > > > > > >
> > > > > > > Expect that some servers are never going to send data on an
> > > > > > > operation failure, and will only send <rpc-error> instead.
> > > > > > >
> > > > > > >
> > > > > > > >From sec. 3.8:
> > > > > > >
> > > > > > >    For instance, for the following request:
> > > > > > >
> > > > > > > <netconf:rpc message-id="101"
> > > > > > >    xmlns:netconf="urn:ietf:params:xml:ns:netconf:base:1.0">
> > > > > > >    <establish-subscription
> > > > > > >        xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-
> notifications"
> > > > > > >        xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
> > > > > > >       <yp:datastore>
> > > > > > >         <yp:source
> > > > > > >         xmlns="urn:ietf:params:xml:ns:yang:ietf-datastores">
> > > > > > >           operational
> > > > > > >         </yp:source>
> > > > > > >         <yp:subtree-filter netconf:type="xpath"
> > > > > > >             xmlns:ex="http://example.com/sample-data/1.0"
> > > > > > >             select="/ex:foo"/>
> > > > > > >       </yp:datastore>
> > > > > > >       <yp:period>500</yp:period>
> > > > > > >    </establish-subscription>
> > > > > > > </netconf:rpc>
> > > > > > >
> > > > > > >                  Figure 3: Establish-Subscription example
> > > > > > >
> > > > > > >    the publisher might return:
> > > > > > >
> > > > > > >
> > > > > > > <rpc-reply message-id="101"
> > > > > > >      xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
> > > > > > >    <subscription-result
> > > > > > >        xmlns="urn:ietf:params:xml:ns:yang:ietf-subscribed-
> notifications"
> > > > > > >        xmlns:yp="urn:ietf:params:xml:ns:yang:ietf-yang-push">
> > > > > > >      yp:period-unsupported
> > > > > > >    </subscription-result>
> > > > > > >    <period-hint xmlns:"urn:ietf:params:xml:ns:
> yang:ietf-yang-push">
> > > > > > >       2000
> > > > > > >    </period-hint>
> > > > > > > </rpc-reply>
> > > > > > >
> > > > > > >                      Figure 4: Error response example
> > > > > > >
> > > > > > >
> > > > > > >
> > > > > > > BTW, all the filter examples seem to be wrong, including the
> > > > > > > one above
> > > > > > >
> > > > > > >
> > > > > > > OLD:
> > > > > > >
> > > > > > >         <yp:subtree-filter netconf:type="xpath"
> > > > > > >             xmlns:ex="http://example.com/sample-data/1.0"
> > > > > > >             select="/ex:foo"/>
> > > > > > >
> > > > > > >
> > > > > > > NEW:
> > > > > > >
> > > > > > >
> > > > > > >         <yp:subtree-filter>
> > > > > > >            <ex:foo xmlns:ex="http://example.com/
> sample-data/1.0"
> > > > > > > />
> > > > > > >
> > > > > > >         </yp:subtree-filter>
> > > > > > >
> > > > > > >
> > > > > > > Andy
> > > > > >
> > > > > >
> > > > > >
> > > _______________________________________________
> > > Netconf mailing list
> > > [e-mail]
> > > https://www.ietf.org/mailman/listinfo/netconf
> > >
>
>
>