Subscription to YANG Notifications for Datastore Updates
Extracted elements (28)
Dampening is needed for on-change subscriptions to prevent flooding receivers with rapid successive updates for fast-changing or oscillating objects. When a dampening period is active, only the value current at the end of the period is sent, not the entire interim history; objects that changed and reverted still appear to indicate churn.
Subscription negotiation is built into error responses to failed RPC requests so that random guessing of parameters by a subscriber is discouraged. Hints such as suggested periods, acceptable dampening periods, and object-count estimates are returned to increase the likelihood of subsequent success.
sync-on-start defaults to true so that an on-change subscription begins by sending a full push-update snapshot, establishing a reference frame for the receiver before subsequent incremental push-change-update notifications. Setting it to false restricts the subscription to change-only updates, which is appropriate when the receiver already has current state.
The YANG Patch patch-id is repurposed as a uint32 counter in YANG-Push to allow easy identification of lost or out-of-sequence update records. The RFC 8072 specification leaves patch-id as an arbitrary string, but YANG-Push assigns a specific counter semantic while remaining backward-compatible with the string type.
YANG-Push replaces polling-based management with a push model because polling incurs latency, cycles may be missed under network stress, interval fluctuations make data hard to calibrate, and polling for infrequent changes wastes resources on network, devices, and applications.
Before starting a subscription, the receiver is expected to know the publisher's YANG library information (schemas, modules, revisions, features, deviations) as defined in RFC 8525. If the YANG library changes at runtime, the yang-library-change notification informs the subscriber, and subscriptions may need to be updated accordingly.
Publishers SHOULD provide a mechanism to make discoverable which datastore objects support on-change notifications, because clients of implementations that lack this have no way to know whether their on-change subscription covers the objects they care about. Until a standardized solution (Yang-Push-Notif-Cap) is available, implementations SHOULD provide their own solution.
A dynamic subscription request SHOULD be declined if the publisher determines it may be unable to provide update records meeting the terms of an establish-subscription or modify-subscription RPC request.
A publisher MUST support at least one type of selection filter (subtree or XPath). Only a single selection filter can be applied to a subscription at a time; a new filter in an RPC request replaces any existing one.
For a periodic subscription, an empty push-update MUST be sent when, after access control, no objects remain in an update record, to prevent clients from thinking an update was lost. For an on-change subscription, a push-update MUST NOT be sent in the same situation, so clients remain unaware of changes to nodes they cannot read.
For on-change subscriptions, push-update MUST be used as the initial synchronization notification when sync-on-start is required. The publisher MAY also send a push-update later to resync the subscription.
For periodic subscriptions, if an anchor-time is not provided, the anchor-time MUST be set to the creation time of the initial update record. Subsequent update intervals are calculated as multiples of the period from this anchor-time.
The publisher MUST notify receivers immediately and reliably whenever it is unable to keep the terms of a subscription, including flagging incomplete updates and optionally suspending the subscription. A publisher SHOULD reject a subscription request if it is unlikely to be fulfilled, rather than accepting it and delivering degraded service.
The subscription id MUST be transported along with the subscribed contents in every push-update and push-change-update notification so that a receiver can determine which subscription resulted in a particular update record.
Update records for a single subscription MUST NOT be resequenced prior to transport. When a publisher cannot include the full set of desired objects, it MUST set the incomplete-update flag and MAY suspend the subscription; if no update record is created at all, the publisher MUST suspend the subscription.
Error hint structures establish-subscription-datastore-error-info and modify-subscription-datastore-error-info are yang-data containers returned in RPC error responses. They carry: reason (identityref), period-hint (centiseconds), filter-failure-hint (string), object-count-estimate and object-count-limit (uint32), kilobytes-estimate and kilobytes-limit (uint32).
On-change subscriptions include three additional parameters: dampening-period (minimum interval between successive updates for the same subscription), change-type (restricts which types of changes—create, delete, insert, move, replace—trigger updates), and sync-on-start (whether a full push-update is sent at subscription start to establish a reference frame).
The change-type enumeration defines five values used in on-change subscriptions and the excluded-change leaf-list: create, delete, insert, move, and replace. It is based on YANG Patch edit operations but extended to allow 'create' on an existing node and 'delete' on a missing node as valid operations indicating churn.
The incomplete-update leaf, when present in a push-update or push-change-update, indicates that not all changes since the last update are included and the publisher has failed to fulfill its full subscription obligations. On receipt, a receiver may wait, actively resync, or tear down the subscription.
The resync-subscription RPC, supported only for on-change dynamic subscriptions, instructs the publisher to send a fresh push-update snapshot. On receipt, the publisher must either quickly follow with a push-update or return an appropriate RPC error, optionally including hints in the resync-subscription-error yang-data structure.
Two notification types carry update records: push-update delivers a complete filtered snapshot of the datastore (used for periodic updates, initial on-change sync, and optional resync) and push-change-update delivers the set of changes since the last notification (used for ongoing on-change updates).
YANG-Push defines two subscription types distinguished by update trigger: periodic subscriptions (triggered at a configured time interval with an optional anchor-time) and on-change subscriptions (triggered whenever changes to subscribed datastore nodes are detected). Both types specify a selection filter and a target datastore.
RFC 8641 registers the YANG module ietf-yang-push (namespace urn:ietf:params:xml:ns:yang:ietf-yang-push) in the IANA 'YANG Module Names' registry, along with associated error-type identities and YANG-Push-specific XML namespace.
A receiver MUST only be sent updates for which it has proper authorization. The publisher MUST silently omit data nodes from results that a client is not authorized to see, applying access control per the NACM model (RFC 8341, Section 3.2.4) extended to notifications, equivalent to a regular 'get' operation.
If read access to previously accessible nodes is lost due to a receiver permissions change, this SHOULD be reported as a YANG Patch 'delete' operation for on-change subscriptions. If the publisher cannot handle this, it MUST force dynamic subscription re-establishment or configured subscription reinitialization.
On-change update records are encoded using YANG Patch operations (RFC 8072): 'create' for new objects, 'delete' for removed objects, 'replace' for changed values, 'insert' for new user-ordered list entries, and 'move' for reordering. Unlike RFC 8072, a 'create' on an already-existing node or a 'delete' of a missing node is valid in YANG-Push to signal churn.
The centiseconds typedef (type uint32) measures time periods in units of 0.01 seconds and is used for the period field in periodic subscriptions and the dampening-period field in on-change subscriptions throughout the ietf-yang-push YANG module.
The patch-id field in push-change-update SHOULD be a uint32 counter starting at 0 that increments with every push-change-update for a subscription. This counter MUST be reset to 0 on resynchronization (i.e., when a push-update is sent) and MUST wrap back to 0 after reaching the maximum value 4294967295, enabling detection of lost or out-of-sequence records.