Skip to content

Notifications and subscriptions ​

A subscription is an async iterable. Read it with for await, and close it by leaving an await using scope:

ts
await using sub = await client.ops.notifications.createSubscription({
  stream: 'NETCONF',
});
for await (const n of sub) console.log(n.eventTime, n.event?.name);

It holds notifications in a bounded queue until you read them, so a slow reader gets backpressure, not lost notifications.

To ask for notifications, use one of two extensions:

RFC 5277 notificationsRFC 8639/8641 subscriptions
Event streams✔ one per session✔ one per session
Datastore updates (YANG-Push)✔ periodic or on change, any number
Modify or cancel✘ lasts until stop-time or session end✔ modify(), delete()
Supported bymost serversnewer servers

A session can use one or the other, not both.

RFC 5277 event notifications ​

ts
import { connect } from '@node-net/netconf';
import { notifications } from '@node-net/netconf/operations/notifications';

const client = await connect({ transport, extensions: [notifications] });

await using sub = await client.ops.notifications.createSubscription({
  stream: 'NETCONF',
});
for await (const n of sub) console.log(n.eventTime, n.event?.name);

Options: stream, filter, startTime and stopTime (to replay logged notifications), and queueSize. client.content.notifications.streams() lists the server's streams.

  • Backpressure: notifications wait in a bounded queue (1000 by default) until you read them. If you fall behind, the subscription ends with a SubscriptionOverflowError that says how many were dropped. Nothing is dropped silently.
  • One per session, and permanent. RFC 5277 has no way to cancel a subscription. Disposing it only stops delivery to you.
  • Interleave: without the :interleave capability, the server accepts nothing except <close-session> on a subscribed session, so the client refuses other operations with a CapabilityError. Use a separate session for notifications.

Base notifications (RFC 6470) ​

The NETCONF stream carries events about the server itself. decodeBaseNotification() turns them into typed objects:

ts
import {
  decodeBaseNotification,
} from '@node-net/netconf/operations/base-notifications';

const moduleOf = (ns: string) => client.content.moduleOf(ns);
for await (const n of sub) {
  const event = decodeBaseNotification(n, { moduleOf });
  switch (event?.type) {
    case 'netconf-config-change':
      // "/ietf-interfaces:interfaces/interface[name='eth0']", …
      const paths = event.edits.map((e) => e.target);
      console.log(event.changedBy, event.datastore, paths);
      break;
    case 'netconf-session-start':
    case 'netconf-session-end':
    case 'netconf-capability-change':
    case 'netconf-confirmed-commit':
      console.log(event);
  }
}

These are plain functions, so nothing goes in extensions. Any other event decodes to undefined. An edit's target is an RFC 7951 path with module names in place of the server's prefixes; moduleOf lets it name modules the session knows, rather than only the well-known IETF ones.

RFC 8639 subscriptions and YANG-Push ​

ts
import { connect, subtree, x } from '@node-net/netconf';
import { subscriptions } from '@node-net/netconf/operations/subscriptions';

const client = await connect({ transport, extensions: [subscriptions] });
const subs = client.ops.subscriptions;

// An event stream
await using events = await subs.establish({ stream: 'NETCONF' });

// The interfaces in operational, every 10 seconds (periods are in centiseconds)
await using telemetry = await subs.establish({
  datastore: 'operational',
  filter: subtree(x('interfaces', { xmlns: IF })),
  periodic: { period: 1000 },
});

// Changes only, as they happen
await using changes = await subs.establish({
  datastore: 'running',
  onChange: { dampeningPeriod: 0, syncOnStart: true },
});

for await (const update of telemetry) {
  if (update.type === 'push-update') console.log(update.contents);
}

Updates are typed by type: event, push-update (with contents), push-change-update (with a decoded YANG Patch), and suspended and resumed.

A subscription has an id, modify(), delete() and resync(), and replayComplete and ended promises. ended tells you why it ended: deleted, terminated (with the server's reason), completed, closed or overflow. Leaving an await using scope, or breaking out of for await, deletes it.

client.ops.subscriptions also has modify(id), delete(id), resync(id), kill(id) and active. client.content.subscriptions has streams(), list() (with receiver counters), and support(), which reports what the server supports. The subscription YANG modules are YANG 1.1, so the hello doesn't list them. Support is read from the YANG library the first time it's needed, and each request is checked against it.

A session can hold any number of datastore subscriptions, but only one stream subscription, because stream events don't carry a subscription id.

What the server can push ​

A server that implements RFC 9196 says what it can push before you subscribe: whether on-change updates are supported, for which datastores and nodes, and the shortest periodic period. client.content.subscriptions.capabilities() reads it:

Other device
const caps = await client.content.subscriptions.capabilities();
if (caps === undefined) {
  // The server doesn't implement ietf-system-capabilities
} else {
  // { minimumUpdatePeriod: 500, onChange: { config: true, state: true }, ... }
  caps.system;
  // [{ datastore: 'ietf-datastores:operational',
  //    nodes: [{ selector: '/', onChange: { config: false, state: true } }] }]
  caps.datastores;
}

system holds the values that apply everywhere unless a datastore's node entries say otherwise. Each datastore entry lists its nodes in the server's order, which is their precedence: the first entry whose selector covers a node applies to it, and / is the whole datastore. Each level can report maxNodesPerUpdate, periodic and onChange support (each as { config, state }: whether changes to configuration and to state data are supported), minimumUpdatePeriod or supportedUpdatePeriods, minimumDampeningPeriod (all in centiseconds, like period), and excludedChangeTypes. A value the server doesn't report is left out.

It resolves with undefined, after at most a YANG library read, when the server doesn't implement ietf-system-capabilities. That module is YANG 1.1, so the hello doesn't list it; the YANG library does. establish() doesn't check these capabilities for you: matching per-node selectors against a subscription's filter is the server's job, and it answers with an error such as ietf-yang-push:on-change-unsupported.

Every notification on a session ​

For logging or debugging, the session's 'notification' event fires for every <notification> it receives, whatever subscription it belongs to:

ts
client.session.on('notification', (n) => {
  console.log(n.eventTime, n.event?.name);
});

The event has no queue or backpressure. It also doesn't keep notifications coming: it fires only while a subscription is open, so you still need one. For anything else, read the subscription.

Using with RxJS ​

Subscriptions are async iterables, so RxJS's from() turns one into an Observable without an adapter:

ts
import { from, bufferTime, filter } from 'rxjs';

const sub = await client.ops.notifications.createSubscription({
  stream: 'NETCONF',
});

const batches = from(sub)
  .pipe(bufferTime(5000), filter((batch) => batch.length > 0))
  .subscribe((batch) => console.log(`${batch.length} events in the last 5s`));

// Later
batches.unsubscribe();
await sub[Symbol.asyncDispose]();

Unsubscribing from the Observable alone doesn't end the subscription until the next notification arrives, so dispose of it yourself. fromEvent(client.session, 'notification') works too, with the limits of the session event above.

Released under the MIT Licence.