Transactions
On a server with a candidate datastore, a safe change takes several steps, and so does the cleanup when one of them fails. withCandidate() does all of them in the order RFC 6241 Appendix E.1 gives:
- lock running, then lock the candidate
<discard-changes>, to drop stale edits someone left in the candidate- your edits
<validate>, if the server supports it<commit>- unlock the candidate, then running
import { withCandidate, x } from '@node-net/netconf';
const SYS = 'urn:ietf:params:xml:ns:yang:ietf-system';
await withCandidate(client, async (txn) => {
const config = x('system', { xmlns: SYS }, x('hostname', 'router1'));
await txn.editConfig({ config });
// reads the candidate
const current = await txn.getConfig();
});
// committed: { 'ietf-system:hostname': 'router1' }
await client.content.read('/ietf-system:system/hostname');txn.editConfig({ config }) and txn.getConfig({ filter }) also take RFC 7951 JSON, converted with the candidate's YANG schema (JSON and YANG), when withCandidate() is given the client (or an extension context) rather than a bare session.
If anything fails after the locks are taken, the candidate is discarded and the locks released. Cleanup still runs if your AbortSignal fires, and is skipped only if the session has closed.
The Content layer's configure(), set() and remove() use withCandidate() whenever the device's workflow edits the candidate and commits, so everything on this page applies to them too.
Seeing the changes before you commit
txn.getCandidateChanges() lists what the commit will apply: how the candidate now differs from running. Both datastores are locked, so nobody else can change them before the commit. To back out, throw: the candidate is discarded and nothing is committed.
import { withCandidate } from '@node-net/netconf';
const config = { 'ietf-system:system': { location: 'rack 9' } };
await withCandidate(client, async (txn) => {
await txn.editConfig({ config });
const changes = await txn.getCandidateChanges();
for (const c of changes) {
console.log(c.operation, c.path, c.previous, '→', c.value);
}
// create /ietf-system:system/location undefined → rack 9
// to back out, throw: nothing is committed
if (changes.some((c) => c.operation === 'delete')) {
throw new Error('not approved: this change deletes something');
}
});Each change has an operation (create, delete, replace or move), the node's RFC 7951 data path, and its value in the candidate and previous value in running. Comparing datastores describes them, and how list entries are matched.
The comparison is made by the client with the server's YANG schema, so it works on any server with a candidate. txn.getCandidateChanges() needs withCandidate() to be given the client, not a bare session.
Outside a transaction, without the locks, client.content.getCandidateChanges() and client.content.compareDatastores() make the same comparison: see Comparing datastores.
Options
| Option | |
|---|---|
validate | true or false overrides whether <validate> is sent (default: if :validate is advertised) |
lockRunning: false | lock only the candidate |
lock: false | lock nothing |
confirmed | make a confirmed commit (below) |
onStep | called as each request succeeds, cleanup included |
A server without :candidate is refused with a CapabilityError before anything is sent. There is no fallback to running.
Failures
Every failure rejects with a TransactionError:
phase: where it failed:lock,discard,edit,validate,commit,confirmorcancelcause: the original error, such as anRpcErrorcleanupErrors: anything that went wrong while discarding or unlocking. These never replace the original error.
If another session holds a lock, the error is a LockDeniedError (a kind of TransactionError). It has the datastore and the holder's session-id, where 0 means something other than a NETCONF session holds it.
Confirmed commits
A confirmed commit is rolled back by the server unless you confirm it in time. This is useful when a change might cut you off from the device:
import { withCandidate } from '@node-net/netconf';
const config = { 'ietf-system:system': { location: 'rack 9' } };
const { pending } = await withCandidate(
client,
(txn) => txn.editConfig({ config }),
// timeout in seconds
{ confirmed: { timeout: 120 } },
);
// Can we still read from the device?
const reachable = await client.content
.read('/ietf-system:system/hostname')
.then(() => true, () => false);
if (reachable) {
await pending.confirm();
} else {
// roll back now
await pending.cancel();
}
// 'confirmed'
pending.state;With the path API:
const pending = await client.content.set(
'/ietf-system:system/location',
'rack 3',
{ confirmed: { timeout: 120 } },
);
await pending?.confirm();PendingCommit has confirm(), cancel(), state, persistId and expires. With await using, a commit that is still pending is cancelled when the scope ends.
- Running is unlocked as soon as the confirmed commit succeeds, so the server is free to roll back. The candidate stays locked until the commit is confirmed or cancelled.
confirm()is refused from 2 seconds beforeexpires. A confirm that reached the server after it had rolled back would commit the candidate again.cancel()needs:confirmed-commit:1.1.confirmed: { timeout, persist: 'token' }makes the commit survive the session closing, so another session can confirm it withcommit({ persistId: 'token' }).