use crate::error::{NetconfClientError, NetconfClientResult};
use crate::message::{
CopySource, Datastore, DefaultOperation, EditContent, ErrorOption, Filter, Hello, Rpc,
RpcOperation, RpcReply, Source, TestOption, WithDefaultsValue, capability_id, from_xml,
};
use crate::transport::Transport;
use crate::{INTERLEAVE_CAP, NETCONF_BASE_11_CAP, NETCONF_URN, NOTIFICATION_CAP};
use core::fmt;
#[cfg(feature = "tokio")]
use core::time::Duration;
use log::{debug, trace, warn};
use std::collections::VecDeque;
#[cfg(feature = "tokio")]
use tokio::sync::mpsc::Sender;
const MAX_NOTIFICATION_BUFFER: usize = 256;
pub struct Connection {
pub(crate) transport: Box<dyn Transport + Send + 'static>,
session_id: Option<u64>,
capabilities: Vec<String>,
parse_replies: bool,
warnings_as_errors: bool,
next_message_id: u64,
is_closed: bool,
desynchronized: bool,
notification_buffer: VecDeque<String>,
#[cfg(feature = "tokio")]
timeout: Option<Duration>,
}
impl fmt::Debug for Connection {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let mut dbg = f.debug_struct("Connection");
dbg.field("session_id", &self.session_id)
.field("capabilities", &self.capabilities)
.field("parse_replies", &self.parse_replies)
.field("warnings_as_errors", &self.warnings_as_errors)
.field("is_closed", &self.is_closed)
.field("desynchronized", &self.desynchronized)
.field("notification_buffer", &self.notification_buffer.len());
#[cfg(feature = "tokio")]
dbg.field("timeout", &self.timeout);
dbg.finish_non_exhaustive()
}
}
impl Connection {
pub async fn new<T>(transport: T) -> NetconfClientResult<Connection>
where
T: Transport + 'static,
{
let mut conn = Connection {
transport: Box::from(transport),
session_id: None,
capabilities: Vec::new(),
parse_replies: true,
warnings_as_errors: false,
next_message_id: 1,
is_closed: false,
desynchronized: false,
notification_buffer: VecDeque::new(),
#[cfg(feature = "tokio")]
timeout: None,
};
conn.session_id = conn.hello().await?;
Ok(conn)
}
pub fn set_parse_replies(&mut self, parse_replies: bool) {
self.parse_replies = parse_replies;
}
pub fn parse_replies(&self) -> bool {
self.parse_replies
}
pub fn set_warnings_as_errors(&mut self, warnings_as_errors: bool) {
self.warnings_as_errors = warnings_as_errors;
}
pub fn warnings_as_errors(&self) -> bool {
self.warnings_as_errors
}
#[cfg(feature = "tokio")]
#[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
pub fn set_timeout(&mut self, timeout: Option<Duration>) {
self.timeout = timeout;
}
pub fn session_id(&self) -> Option<u64> {
self.session_id
}
pub fn capabilities(&self) -> &[String] {
&self.capabilities
}
pub fn has_capability(&self, capability: &str) -> bool {
self.capabilities
.iter()
.any(|cap| capability_id(cap) == capability)
}
async fn hello(&mut self) -> NetconfClientResult<Option<u64>> {
let hello = Hello::new();
let response = self.write_and_receive(&hello.to_string(), false).await?;
trace!("hello:\n{}", response);
let hello: Hello = from_xml(&response)?;
self.capabilities = hello.capabilities();
if hello.has_capability(NETCONF_BASE_11_CAP) {
debug!("server advertised :base:1.1; switching to chunked framing");
self.transport.upgrade().await;
} else {
debug!("server did not advertise :base:1.1; staying on 1.0 framing");
}
Ok(hello.session_id())
}
pub async fn get_config(
&mut self,
datastore: Datastore,
filter: Option<Filter>,
defaults: Option<WithDefaultsValue>,
) -> NetconfClientResult<String> {
let get_config =
Rpc::new_with_operation(RpcOperation::new_get_config(datastore, filter, defaults));
self.run_rpc(get_config).await
}
pub async fn get(
&mut self,
filter: Option<Filter>,
defaults: Option<WithDefaultsValue>,
) -> NetconfClientResult<String> {
let get = Rpc::new_with_operation(RpcOperation::new_get(filter, defaults));
self.run_rpc(get).await
}
pub async fn validate(&mut self, datastore: Datastore) -> NetconfClientResult<String> {
let validate = Rpc::new_with_operation(RpcOperation::Validate {
source: Source { datastore },
});
self.run_rpc(validate).await
}
pub async fn edit_config(
&mut self,
target: Datastore,
content: EditContent,
default_operation: Option<DefaultOperation>,
test_option: Option<TestOption>,
error_option: Option<ErrorOption>,
) -> NetconfClientResult<String> {
let rpc = Rpc::new_with_operation(RpcOperation::new_edit_config(
target,
content,
default_operation,
test_option,
error_option,
));
self.run_rpc(rpc).await
}
pub async fn copy_config(
&mut self,
source: CopySource,
target: Datastore,
) -> NetconfClientResult<String> {
let rpc = Rpc::new_with_operation(RpcOperation::new_copy_config(source, target));
self.run_rpc(rpc).await
}
pub async fn delete_config(&mut self, target: Datastore) -> NetconfClientResult<String> {
let rpc = Rpc::new_with_operation(RpcOperation::new_delete_config(target));
self.run_rpc(rpc).await
}
pub async fn lock(&mut self, target: Datastore) -> NetconfClientResult<String> {
let rpc = Rpc::new_with_operation(RpcOperation::new_lock(target));
self.run_rpc(rpc).await
}
pub async fn unlock(&mut self, target: Datastore) -> NetconfClientResult<String> {
let rpc = Rpc::new_with_operation(RpcOperation::new_unlock(target));
self.run_rpc(rpc).await
}
pub async fn commit(&mut self) -> NetconfClientResult<String> {
let commit = Rpc::new_with_operation(RpcOperation::new_commit(None, None, None, None));
self.run_rpc(commit).await
}
pub async fn confirmed_commit(
&mut self,
confirm_timeout: Option<i32>,
persist: Option<String>,
persist_id: Option<String>,
) -> NetconfClientResult<String> {
let commit = Rpc::new_with_operation(RpcOperation::new_commit(
Some(()),
confirm_timeout,
persist,
persist_id,
));
self.run_rpc(commit).await
}
pub async fn confirm_commit(&mut self, persist_id: String) -> NetconfClientResult<String> {
let commit =
Rpc::new_with_operation(RpcOperation::new_commit(None, None, None, Some(persist_id)));
self.run_rpc(commit).await
}
pub async fn cancel_commit(
&mut self,
persist_id: Option<String>,
) -> NetconfClientResult<String> {
let rpc = Rpc::new_with_operation(RpcOperation::new_cancel_commit(persist_id));
self.run_rpc(rpc).await
}
pub async fn discard_changes(&mut self) -> NetconfClientResult<String> {
let rpc = Rpc::new_with_operation(RpcOperation::new_discard_changes());
self.run_rpc(rpc).await
}
pub async fn close_session(&mut self) -> NetconfClientResult<String> {
let close_session = Rpc::new_with_operation(RpcOperation::CloseSession);
self.is_closed = true;
let reply = self.run_rpc(close_session).await;
if let Err(err) = self.transport.close().await {
debug!("transport close after <close-session> failed: {}", err);
}
reply
}
pub async fn kill_session(&mut self, session_id: u64) -> NetconfClientResult<String> {
let kill_session = Rpc::new_with_operation(RpcOperation::KillSession { session_id });
self.run_rpc(kill_session).await
}
pub async fn raw_rpc(&mut self, xml: &str) -> NetconfClientResult<String> {
let xml = self.ensure_rpc_envelope(xml);
self.exchange(
&xml,
request_message_id(&xml).as_deref(),
request_is_commit(&xml),
self.warnings_as_errors,
&request_operation(&xml),
)
.await
}
pub async fn raw_rpc_with_warnings(
&mut self,
xml: &str,
) -> NetconfClientResult<(String, Vec<crate::message::Error>)> {
let xml = self.ensure_rpc_envelope(xml);
let response = self
.exchange(
&xml,
request_message_id(&xml).as_deref(),
request_is_commit(&xml),
false,
&request_operation(&xml),
)
.await?;
let warnings = match from_xml::<RpcReply>(&response) {
Ok(reply) => reply.warnings().into_iter().cloned().collect(),
Err(_) => Vec::new(),
};
Ok((response, warnings))
}
pub async fn create_subscription(
&mut self,
stream: Option<&str>,
filter: Option<Filter>,
start_time: Option<&str>,
stop_time: Option<&str>,
) -> NetconfClientResult<String> {
if !self.has_capability(NOTIFICATION_CAP) {
debug!("server did not advertise :notification; create-subscription may fail");
}
if !self.has_capability(INTERLEAVE_CAP) {
debug!("server did not advertise :interleave; RPCs during this subscription may fail");
}
let rpc = Rpc::new_with_operation(RpcOperation::new_create_subscription(
stream, filter, start_time, stop_time,
)?);
self.run_rpc(rpc).await
}
pub fn drain_notifications(&mut self) -> Vec<String> {
self.notification_buffer.drain(..).collect()
}
pub fn has_notifications(&self) -> bool {
!self.notification_buffer.is_empty()
}
pub async fn recv_notification(&mut self) -> NetconfClientResult<String> {
if let Some(notification) = self.notification_buffer.pop_front() {
return Ok(notification);
}
if self.desynchronized {
return Err(NetconfClientError::SessionDesynchronized);
}
loop {
let message = self.transport.receive().await?;
if classify_incoming(&message) == Incoming::Notification {
return Ok(message);
}
warn!("Discarding unexpected message while waiting for notification");
}
}
#[cfg(feature = "tokio")]
#[cfg_attr(docsrs, doc(cfg(feature = "tokio")))]
pub async fn notification(
&mut self,
sender: Sender<String>,
stream: Option<&str>,
filter: Option<Filter>,
start_time: Option<&str>,
stop_time: Option<&str>,
) -> NetconfClientResult<()> {
self.create_subscription(stream, filter, start_time, stop_time)
.await?;
self.run_notification_loop(sender).await
}
#[cfg(feature = "tokio")]
async fn run_notification_loop(&mut self, sender: Sender<String>) -> NetconfClientResult<()> {
loop {
let notification = self.recv_notification().await?;
if sender.send(notification).await.is_err() {
return Ok(());
}
}
}
fn buffer_notification(&mut self, notification: String) {
if self.notification_buffer.len() >= MAX_NOTIFICATION_BUFFER {
warn!("Notification buffer full ({MAX_NOTIFICATION_BUFFER}); dropping oldest");
self.notification_buffer.pop_front();
}
self.notification_buffer.push_back(notification);
}
async fn run_rpc(&mut self, mut rpc: Rpc) -> NetconfClientResult<String> {
let is_commit = rpc.is_commit();
let message_id = self.allocate_message_id();
rpc.set_message_id(&message_id);
self.exchange(
&rpc.to_string(),
Some(&message_id),
is_commit,
self.warnings_as_errors,
rpc.operation_name(),
)
.await
}
fn allocate_message_id(&mut self) -> String {
let id = self.next_message_id;
self.next_message_id += 1;
id.to_string()
}
fn ensure_rpc_envelope(&mut self, xml: &str) -> String {
if root_is_rpc(xml) {
xml.to_string()
} else {
wrap_in_rpc(xml, &self.allocate_message_id())
}
}
async fn exchange(
&mut self,
request: &str,
expected_message_id: Option<&str>,
is_commit: bool,
warnings_as_errors: bool,
operation: &str,
) -> NetconfClientResult<String> {
if self.desynchronized {
return Err(NetconfClientError::SessionDesynchronized);
}
let response = self.write_and_receive(request, is_commit).await?;
trace!("rpc:\n{response}");
let reply = match from_xml::<RpcReply>(&response) {
Ok(reply) => reply,
Err(err) if self.parse_replies => return Err(err),
Err(_) => return Ok(response),
};
if let Some(expected) = expected_message_id
&& let Some(actual) = reply.message_id()
&& actual != expected
{
self.desynchronized = true;
return Err(NetconfClientError::MessageIdMismatch {
expected: expected.to_string(),
actual: actual.to_string(),
});
}
if self.parse_replies && reply_is_failure(&reply, warnings_as_errors) {
return Err(NetconfClientError::Netconf {
operation: operation.to_string(),
reply,
});
}
Ok(response)
}
#[cfg(feature = "tokio")]
async fn write_and_receive(
&mut self,
request: &str,
is_commit: bool,
) -> NetconfClientResult<String> {
let result = if let Some(timeout) = self.timeout {
match tokio::time::timeout(timeout, self.write_and_read_reply(request)).await {
Ok(result) => result,
Err(_) => {
self.desynchronized = true;
return Err(NetconfClientError::Timeout { timeout });
}
}
} else {
self.write_and_read_reply(request).await
};
map_commit_eof(result, is_commit)
}
#[cfg(not(feature = "tokio"))]
async fn write_and_receive(
&mut self,
request: &str,
is_commit: bool,
) -> NetconfClientResult<String> {
map_commit_eof(self.write_and_read_reply(request).await, is_commit)
}
async fn write_and_read_reply(&mut self, request: &str) -> NetconfClientResult<String> {
if let Err(err) = self.transport.write(request).await {
return Err(self.invalidate_on_eof(err));
}
loop {
let response = match self.transport.receive().await {
Ok(response) => response,
Err(err) => return Err(self.invalidate_on_eof(err)),
};
if classify_incoming(&response) == Incoming::Notification {
debug!("buffered notification during rpc");
self.buffer_notification(response);
continue;
}
return Ok(response);
}
}
fn invalidate_on_eof(&mut self, err: NetconfClientError) -> NetconfClientError {
if err.is_unexpected_eof() {
self.desynchronized = true;
}
err
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Incoming {
Notification,
Other,
}
fn classify_incoming(xml: &str) -> Incoming {
match first_element_local_name(xml) {
Some("notification") => Incoming::Notification,
_ => Incoming::Other,
}
}
fn first_element_local_name(xml: &str) -> Option<&str> {
let mut rest = xml;
while let Some(idx) = rest.find('<') {
rest = &rest[idx + 1..];
if rest.starts_with('!') || rest.starts_with('?') || rest.starts_with('/') {
continue;
}
let name_end = rest
.find(|c: char| c.is_whitespace() || c == '>' || c == '/')
.unwrap_or(rest.len());
let name = &rest[..name_end];
let local = name.rsplit(':').next().unwrap_or(name);
if !local.is_empty() {
return Some(local);
}
}
None
}
fn reply_is_failure(reply: &RpcReply, warnings_as_errors: bool) -> bool {
reply.has_errors() || (warnings_as_errors && reply.has_warnings())
}
fn map_commit_eof(
result: NetconfClientResult<String>,
is_commit: bool,
) -> NetconfClientResult<String> {
match result {
Err(err) if is_commit && err.is_unexpected_eof() => Err(NetconfClientError::CommitUnknown),
other => other,
}
}
fn root_local_name(xml: &str) -> Option<&str> {
let mut rest = xml;
while let Some(idx) = rest.find('<') {
rest = &rest[idx + 1..];
if rest.starts_with('!') || rest.starts_with('?') || rest.starts_with('/') {
continue;
}
let name_end = rest
.find(|c: char| c.is_whitespace() || c == '>' || c == '/')
.unwrap_or(rest.len());
let name = &rest[..name_end];
let local = name.rsplit(':').next().unwrap_or(name);
if !local.is_empty() {
return Some(local);
}
}
None
}
fn root_is_rpc(xml: &str) -> bool {
root_local_name(xml) == Some("rpc")
}
fn xml_body_start(xml: &str) -> usize {
if let Some(decl) = xml.find("<?xml")
&& let Some(end) = xml[decl..].find("?>")
{
return decl + end + 2;
}
0
}
fn wrap_in_rpc(xml: &str, message_id: &str) -> String {
let (prolog, body) = xml.split_at(xml_body_start(xml));
format!("{prolog}<rpc xmlns=\"{NETCONF_URN}\" message-id=\"{message_id}\">{body}</rpc>")
}
fn request_message_id(xml: &str) -> Option<String> {
for key in ["message-id=\"", "message-id='"] {
if let Some(start) = xml.find(key) {
let rest = &xml[start + key.len()..];
let quote = key.chars().next_back()?;
if let Some(end) = rest.find(quote) {
let id = &rest[..end];
if !id.is_empty() {
return Some(id.to_string());
}
}
}
}
None
}
fn request_operation(xml: &str) -> String {
let mut rest = xml;
let mut seen_rpc = false;
while let Some(idx) = rest.find('<') {
rest = &rest[idx + 1..];
if rest.starts_with('!') || rest.starts_with('?') || rest.starts_with('/') {
continue;
}
let name_end = rest
.find(|c: char| c.is_whitespace() || c == '>' || c == '/')
.unwrap_or(rest.len());
let name = &rest[..name_end];
let local = name.rsplit(':').next().unwrap_or(name);
if !seen_rpc {
if local == "rpc" {
seen_rpc = true;
}
continue;
}
if !local.is_empty() {
return local.to_string();
}
}
"rpc".to_string()
}
fn request_is_commit(xml: &str) -> bool {
let mut rest = xml;
while let Some(idx) = rest.find('<') {
rest = &rest[idx + 1..];
if rest.starts_with('!') || rest.starts_with('?') || rest.starts_with('/') {
continue;
}
let name_end = rest
.find(|c: char| c.is_whitespace() || c == '>' || c == '/')
.unwrap_or(rest.len());
let name = &rest[..name_end];
let local = name.rsplit(':').next().unwrap_or(name);
if local == "commit" || local == "commit-configuration" {
return true;
}
}
false
}
impl Drop for Connection {
fn drop(&mut self) {
if !self.is_closed {
warn!("NETCONF session dropped without close_session; the device may hold it open");
}
}
}
#[cfg(test)]
mod tests {
use super::{
Incoming, classify_incoming, request_is_commit, request_message_id, request_operation,
root_is_rpc, wrap_in_rpc,
};
use crate::message::capability_id;
use crate::{CANDIDATE_CAP, URL_CAP};
#[test]
fn capability_id_strips_query() {
assert_eq!(capability_id(CANDIDATE_CAP), CANDIDATE_CAP);
assert_eq!(
capability_id(&format!("{URL_CAP}?scheme=http,ftp,file")),
URL_CAP
);
}
#[test]
fn request_message_id_reads_double_and_single_quotes() {
assert_eq!(
request_message_id(r#"<rpc message-id="abc-123"><get/></rpc>"#).as_deref(),
Some("abc-123")
);
assert_eq!(
request_message_id("<rpc message-id='x'><get/></rpc>").as_deref(),
Some("x")
);
assert_eq!(request_message_id("<rpc><get/></rpc>"), None);
}
#[test]
fn request_is_commit_matches_commit_and_junos_not_cancel() {
assert!(request_is_commit("<rpc><commit/></rpc>"));
assert!(request_is_commit(
r#"<rpc><nc:commit xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"/></rpc>"#
));
assert!(request_is_commit("<rpc><commit-configuration/></rpc>"));
assert!(request_is_commit("<rpc><commit confirmed/></rpc>"));
assert!(!request_is_commit("<rpc><cancel-commit/></rpc>"));
assert!(!request_is_commit(
"<rpc><get><commit-id>1</commit-id></get></rpc>"
));
assert!(!request_is_commit("<rpc><get/></rpc>"));
}
#[test]
fn wrap_in_rpc_adds_envelope_and_keeps_existing_rpc() {
assert!(root_is_rpc("<rpc><get/></rpc>"));
assert!(root_is_rpc(
r#"<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"><nc:get/></nc:rpc>"#
));
assert!(!root_is_rpc("<get-interface-information/>"));
let wrapped = wrap_in_rpc("<get-interface-information/>", "3");
assert_eq!(
wrapped,
concat!(
"<rpc xmlns=\"urn:ietf:params:xml:ns:netconf:base:1.0\" message-id=\"3\">",
"<get-interface-information/>",
"</rpc>",
)
);
assert_eq!(request_operation(&wrapped), "get-interface-information");
assert_eq!(request_message_id(&wrapped).as_deref(), Some("3"));
let with_decl = wrap_in_rpc("<?xml version=\"1.0\"?>\n<get-interface-information/>", "1");
assert!(with_decl.starts_with("<?xml version=\"1.0\"?>"));
assert!(root_is_rpc(&with_decl));
assert_eq!(request_operation(&with_decl), "get-interface-information");
}
#[test]
fn request_operation_reads_first_child_of_rpc() {
assert_eq!(request_operation("<rpc><get-config/></rpc>"), "get-config");
assert_eq!(
request_operation(
r#"<nc:rpc xmlns:nc="urn:ietf:params:xml:ns:netconf:base:1.0"><nc:edit-config/></nc:rpc>"#
),
"edit-config"
);
assert_eq!(
request_operation("<rpc message-id='1'><lock/></rpc>"),
"lock"
);
assert_eq!(request_operation("<rpc/>"), "rpc");
assert_eq!(request_operation("<hello/>"), "rpc");
}
#[test]
fn classify_incoming_uses_root_local_name() {
assert_eq!(
classify_incoming(
r#"<notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"/>"#
),
Incoming::Notification
);
assert_eq!(
classify_incoming(
r#"<nc:notification xmlns:nc="urn:ietf:params:xml:ns:netconf:notification:1.0"><eventTime>t</eventTime></nc:notification>"#
),
Incoming::Notification
);
assert_eq!(
classify_incoming(r#"<?xml version="1.0"?><notification/>"#),
Incoming::Notification
);
assert_eq!(
classify_incoming(r#"<rpc-reply message-id="1"><ok/></rpc-reply>"#),
Incoming::Other
);
assert_eq!(
classify_incoming(
r#"<rpc-reply><notification xmlns="urn:ietf:params:xml:ns:netconf:notification:1.0"/></rpc-reply>"#
),
Incoming::Other
);
}
}