1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625
/* =================================================================================
File: fbp_iidmessage.rs
Description: This file contains message struct and behavior for a Flow Based
Programming system
History: RustDev 03/31/2021 Code ported from original rustfbp crate
Copyright © 2021 Pesa Switching Systems Inc. All rights reserved.
================================================================================== */
//! # FBP Message Struct
//!
//! A Flow based programming system is at its heart a message passing system. The
//! IIDMessage struct represents a message that is sent between FBP nodes.
//!
//! The IIDMessage struct has a type and a subtype along with a payload. The payload
//! can be any String, but it typically is a JSON string of a serialized struct.
//!
use serde::{Deserialize, Serialize};
use uuid::Uuid;
/// Defines the type of an IIDMessage
///
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
pub enum MessageType {
/// A 'normal' data message to be processed by an FBP Node.
Data,
/// The configuration message is used to modify an FBP Node.
Config,
/// The process message is used to control the running of an FBP Node.
Process,
/// The invalid message is used to stop message propagation.
Invalid,
}
/// Defines the sub-types of an IIDMessage
///
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
pub enum SubMessageType {
/// A 'normal' message. One that need to be processed
Normal,
/// This sub-message type specifies that this message is a reply to a previously sent messages.
/// It is mostly used by the TCP system
Reply,
}
/// Defines the types of Config messages that are the payload of an IIDMessage
///
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
pub enum ConfigMessageType {
/// This specifies that the payload of this Config message is connection information to connect
/// one nodes output to the input to another node
Connect,
/// This specifies that the payload of this Config message is the node to disconnect from the
/// output of the receiving node
Disconnect,
/// This specifies that the payload of this Config message is a JSON string that sets the value
/// of a field in the FBP node
Field,
}
/// Defines the types of Process messages for an FBP node
///
#[derive(Serialize, Deserialize, Debug, Clone, Copy, PartialEq, Eq)]
pub enum ProcessMessageType {
/// The Stop type tells the node to stop processing and quit its input thread
Stop,
/// The Suspend type tells the node to suspend processing message and just pass them through to
/// any nodes that are to receive the output of this node.
Suspend,
/// The Restart type tells the node to re-start processing messages. If the node was not
/// previously suspended this will no nothing.
Restart,
}
/// The MessageSerializer trait is used to serialize and deserialize structs so
/// that they may become the payload of an IIDMessage
///
///
/// # Example
/// ```
/// use fbp::fbp_iidmessage::*;
///
/// // config_data is a JSON string to set a path to a log file
/// let config_data = "{\"log_file_path\":\"Log_file.txt\"}".to_string();
///
/// // This creates the new ConfigMessage with the config data
/// let config_msg = ConfigMessage::new(ConfigMessageType::Field, Some(config_data.clone()) );
///
/// // This will create a new IIDMessage with the serialized Config message as its payload
/// let a_msg = config_msg.make_message(MessageType::Config);
///
/// // This trait can also be used to deserialize the payload of an IIDMessage
///
/// // When an config message is received it can use this trait to deserialize the payload
/// if a_msg.msg_type() == MessageType::Config {
/// let a_config_msg: ConfigMessage = ConfigMessage::make_self_from_string(
/// a_msg
/// .payload()
/// .as_ref()
/// .unwrap()
/// .as_str());
///
/// // Process the config message.
/// }
///
/// ```
pub trait MessageSerializer {
/// This will deserialize a JSON string that is a serialized Rust struct back into the original struct
///
fn make_self_from_string<'a, T>(json_string: &'a str) -> T
where
T: std::marker::Sized + serde::Deserialize<'a>,
{
serde_json::from_str(json_string).unwrap()
}
/// This will take a struct and serialize that struct into a JSON string that will then become the
/// payload of an IIDMesssage
///
fn make_message(&self, msg_type: MessageType) -> IIDMessage
where
Self: std::marker::Sized + serde::Serialize,
{
let struct_string = serde_json::to_string(&self).unwrap();
IIDMessage::new(msg_type, Some(struct_string))
}
}
/// Provides the structure of a message that is sent between FBP nodes.
///
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct IIDMessage {
msg_type: MessageType,
sub_msg_type: SubMessageType,
payload: Option<String>,
}
impl IIDMessage {
/// Creates a new IIDMessage with a specific type and optional payload
///
/// An IIDMesage may or may not have a payload. If no payload is required then
/// None can be passed as the payload.
/// # Example
///
/// Basic usage:
/// ```
/// use fbp::fbp_iidmessage::*;
///
/// let a_msg = IIDMessage::new(MessageType::Data, Some("This is a payload".to_string()));
///
/// ```
pub fn new(msg_type: MessageType, payload: Option<String>) -> Self {
IIDMessage {
msg_type,
sub_msg_type: SubMessageType::Normal,
payload,
}
}
/// Retrieves a message's msg_type
///
/// # Example
///
/// Basic usage:
/// ```
/// use fbp::fbp_iidmessage::*;
///
/// let a_msg = IIDMessage::new(MessageType::Data, Some("This is a payload".to_string()));
///
/// match a_msg.msg_type() {
/// MessageType::Data => { /* Deal with a Data Message */ },
/// MessageType::Config => { /* Deal with a Config Message */ },
/// MessageType::Process => { /* Deal with a Process Message */ },
/// _ => { /* Invalid or unknown message type */ },
/// };
///
/// ```
///
pub fn msg_type(&self) -> MessageType {
self.msg_type
}
/// Retrieves a messages's subtype
///
/// # Example
///
/// Basic usage:
/// ```
/// use fbp::fbp_iidmessage::*;
///
/// pub fn deal_with_msg(a_msg: IIDMessage) {
/// if a_msg.sub_msg_type() == SubMessageType::Reply {
/// // ignore the message
/// }
/// }
///
/// ```
///
pub fn sub_msg_type(&self) -> SubMessageType {
self.sub_msg_type
}
/// Retrieves a messages's payload
///
///
/// # Example
///
/// Basic usage:
/// ```
/// use fbp::fbp_iidmessage::*;
///
/// pub fn process_msg(a_msg: IIDMessage) {
/// let msg_payload = a_msg.payload();
/// if msg_payload.is_some() {
/// // do something with the payload
/// }
/// }
///
///
/// ```
///
pub fn payload(&self) -> &Option<String> {
&self.payload
}
/// Returns a mutable reference to the messages's submesssage type so that it maybe changed.
///
/// # Example
///
/// Basic usage:
/// ```
/// use fbp::fbp_iidmessage::*;
///
/// pub fn set_msg_reply(a_msg: &mut IIDMessage) {
/// *a_msg.sub_msg_type_mut() = SubMessageType::Reply;
/// }
///
/// ```
///
pub fn sub_msg_type_mut(&mut self) -> &mut SubMessageType {
&mut self.sub_msg_type
}
}
/// Supports the ConfigMessageType::Field ConfigMessage for more complex
/// configurations.
///
/// Suppose that a field for a node needs to be generated from *base data*.
/// For example, suppose that a TCP FBP node that uses TLS needs a PKCS12
/// so that the certificate and private key can be used to secure the TCP
/// connection. A PKCS12 file also will need a password. Beyond that, one
/// might want to specify if the connection will use mutual authentification
/// or not and what specific cipher list should be used. A struct with this
/// information could be used to create the neccessary security information
/// for a TLS connection, but is NOT the data that is directly used for the
/// necessary fields of a TCP FBP node that uses TLS. This is an example
/// of what the FieldConfiguration struct could be used for.
///
/// ## Example
/// ```
/// use serde::{Deserialize, Serialize};
///
/// use fbp::fbp_iidmessage::*;
/// // This struct holds the information for creating the necessary data
/// // to use a secure TLS connection with TCP.
/// // file_path: This is a file path to a PKCS12 file
/// // password: This is the password for the PKCS12 file
/// // if there is no password then this will be None
/// // require_mutual_authentication:
/// // This signifies if the TLS connect needs to be
/// // mutually authenticated (Has both a server and
/// // a client certificate)
/// // cipher_list The specific cipher list to use. None means to
/// // use the default cipher list.
/// //
/// #[derive(Serialize, Deserialize, Debug, Clone, PartialEq, Eq)]
/// pub struct SecurityData {
/// pub file_path: String,
/// pub password: Option<String>,
/// pub require_mutual_authentication: bool,
/// pub cipher_list: Option<String>,
/// }
///
/// impl SecurityData {
/// pub fn new(file_path: String,
/// require_mutual_authentication: bool,
/// password: Option<String>,
/// cipher_list: Option<String>) -> Self {
/// SecurityData {
/// file_path,
/// password,
/// require_mutual_authentication,
/// cipher_list
/// }
/// }
/// }
///
/// // Typically configuration JSON data will be stored either in a file or
/// // sent from another node. This function shows how the FieldConfiguration
/// // struct can be used to create complex configuration data.
/// pub fn make_config_msg() -> IIDMessage {
/// let sd = SecurityData::new("secureData.p12".to_string(),
/// true, Some("password".to_string()), None);
///
/// let sd_string = serde_json::to_string(&sd).unwrap();
///
/// let fc = FieldConfiguration::new("tcp_stream_handler".to_string(),
/// sd_string);
///
/// let fc_string = serde_json::to_string(&fc).unwrap();
///
/// let cm = ConfigMessage::new(ConfigMessageType::Field, Some(fc_string));
///
/// cm.make_message(MessageType::Config)
/// }
///
/// // The make_config_msg will return a IIDMessage that can be sent to a FBP
/// // node to configure that node. The deal_with_config_message assumes that
/// // it will be called from the fn process_config(self: &mut Self, msg: IIDMessage)
/// // trait message when a FBP node is being configured
/// pub fn deal_with_config_message(msg: IIDMessage) {
///
/// if msg.msg_type() != MessageType::Config {
/// return;
/// }
///
/// let payload = msg.payload().as_ref().unwrap();
/// let config_message: ConfigMessage = serde_json::from_str(&payload)
/// .expect("Failed to deserialize the config message");
///
/// let tcp_stream_handler_string = "tcp_stream_handler".to_string();
///
/// if config_message.data().as_ref().is_some() {
/// let fc: FieldConfiguration = serde_json::from_str(config_message.data().as_ref().unwrap()).unwrap();
/// match fc.get_field_name() {
/// tcp_stream_handler_string => {
/// let _sd: SecurityData = serde_json::from_str(fc.get_config_string().as_str()).unwrap();
/// // Now the SecurityData can be used to configure the TCP FBP Node.
/// },
/// _ => {
/// // Invalid field
/// }
/// };
/// }
/// }
///
/// ```
///
#[derive(Clone, Serialize, Deserialize)]
pub struct FieldConfiguration {
field_name: String,
config_string: String,
}
impl FieldConfiguration {
pub fn new(field_name: String, config_string: String) -> Self {
FieldConfiguration {
field_name,
config_string,
}
}
pub fn get_field_name(&self) -> String {
self.field_name.clone()
}
pub fn set_field_name(&mut self, new_field: String) {
self.field_name = new_field.clone();
}
pub fn get_config_string(&self) -> String {
self.config_string.clone()
}
pub fn set_config_string(&mut self, new_config: String) {
self.config_string = new_config.clone();
}
}
/// Provides the structure of the payload of an IIDMessage when the IIDMessage has a type
/// of MessageType::Config
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ConfigMessage {
msg_type: ConfigMessageType,
data: Option<String>,
}
impl ConfigMessage {
/// Creates a new ConfigMessage with a specific type and optional payload
///
/// A ConfigMessage may or may not have a payload. If no payload is required then
/// None can be passed as the payload.
/// # Example
///
/// Basic usage:
/// ```
/// use fbp::fbp_iidmessage::*;
///
/// // Assuming that an FBP node has a field called log_file_path, set its value to be Log_file.txt.
/// // This is done with a JSON string.
/// let json_config_string = "{\"log_file_path\":\"Log_file.txt\"}".to_string();
/// let a_msg = ConfigMessage::new(ConfigMessageType::Field, Some(json_config_string));
///
/// ```
pub fn new(msg_type: ConfigMessageType, data: Option<String>) -> Self {
ConfigMessage { msg_type, data }
}
/// Retrieves an ConfigMessage's msg_type
///
/// # Example
///
/// Basic usage:
/// ```
/// use fbp::fbp_iidmessage::*;
///
/// let json_config_string = "{\"log_file_path\":\"Log_file.txt\"}".to_string();
/// let c_msg = ConfigMessage::new(ConfigMessageType::Field, Some(json_config_string));
/// let a_msg = c_msg.make_message(MessageType::Config);
///
/// match a_msg.msg_type() {
/// MessageType::Data => { /* Deal with a Data Message */ },
/// MessageType::Config => {
/// if a_msg.payload().is_some() {
/// let a_config_msg: ConfigMessage =
/// ConfigMessage::make_self_from_string(a_msg.payload().clone().unwrap().as_str());
/// match a_config_msg.msg_type() {
/// ConfigMessageType::Connect => {
/// // Deal with a Connect
/// },
/// ConfigMessageType::Disconnect => {
/// // Deal with a Disconnect
/// },
/// ConfigMessageType::Field => {
/// // Deal with setting a field in an FBP node
/// }
/// };
/// }
/// },
/// MessageType::Process => {
/// // Deal with a process message
/// },
/// _ => {
/// // Deal with an invalid or unknown message
/// },
/// };
///
///
/// ```
///
pub fn msg_type(&self) -> ConfigMessageType {
self.msg_type
}
/// Retrieves a Config messages's data
///
///
/// # Example
///
/// Basic usage:
/// ```
/// use fbp::fbp_iidmessage::*;
///
/// pub fn process_config_msg(a_msg: ConfigMessage) {
/// let data = a_msg.data();
/// if data.is_some() {
/// // do something with the data
/// }
/// }
///
///
/// ```
///
pub fn data(&self) -> &Option<String> {
&self.data
}
}
impl MessageSerializer for ConfigMessage {}
/// Provides the structure of payload of an IIDMessage when the IIDMessage has a type
/// of MessageType::Process
#[derive(Serialize, Deserialize, Debug, Clone)]
pub struct ProcessMessage {
msg: ProcessMessageType,
propagate: bool,
pub message_node: Option<Uuid>,
}
impl ProcessMessage {
/// Creates a new ProcessMessage with a specific type and a flag to signal if the message
/// shold be propagated
///
/// # Example
///
/// Basic usage:
/// ```
/// use fbp::fbp_iidmessage::*;
///
/// let p_msg = ProcessMessage::new(ProcessMessageType::Stop, true);
///
/// ```
pub fn new(msg: ProcessMessageType, propagate: bool) -> Self {
ProcessMessage {
msg,
propagate,
message_node: None,
}
}
/// Retrieves a Process message's type
///
/// # Example
///
/// Basic usage:
/// ```
/// use fbp::fbp_iidmessage::*;
///
/// pub fn deal_with_process_msg(p_msg: ProcessMessage) {
/// if p_msg.msg() == ProcessMessageType::Stop {
/// // Time to stop!
/// }
/// }
///
/// ```
///
pub fn msg(&self) -> ProcessMessageType {
self.msg
}
/// Retrieves a Process message propagate flag
///
/// # Example
///
/// Basic usage:
/// ```
/// use fbp::fbp_iidmessage::*;
///
/// pub fn should_propagate_process_msg(p_msg: ProcessMessage) -> bool {
/// p_msg.propagate()
/// }
///
/// ```
///
pub fn propagate(&self) -> bool {
self.propagate
}
pub fn message_node(&self) -> &Option<Uuid> {
&self.message_node
}
}
impl MessageSerializer for ProcessMessage {}
/* --------------------------------------------------------------------------
Unit Tests
------------------------------------------------------------------------- */
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn test_iidmessage() {
let msg_string = "foo".to_string();
let mut msg = IIDMessage::new(MessageType::Data, Some(msg_string.clone()));
assert_eq!(msg.msg_type(), MessageType::Data);
assert_eq!(msg.payload().is_none(), false);
assert_eq!(*msg.payload().as_ref().unwrap(), msg_string);
assert_eq!(msg.sub_msg_type(), SubMessageType::Normal);
*msg.sub_msg_type_mut() = SubMessageType::Reply;
assert_eq!(msg.sub_msg_type(), SubMessageType::Reply);
}
#[test]
fn test_config_message() {
let config_data = "{\"log_file_path\":\"Log_file.txt\"}".to_string();
let config_msg = ConfigMessage::new(ConfigMessageType::Field, Some(config_data.clone()));
assert_eq!(config_msg.msg_type(), ConfigMessageType::Field);
assert!(config_msg.data().is_some());
assert_eq!(*config_msg.data().as_ref().unwrap(), config_data);
// serialize the config message into a IIDMessage
let a_msg = config_msg.make_message(MessageType::Config);
assert_eq!(a_msg.msg_type(), MessageType::Config);
assert!(a_msg.payload().is_some());
let a_config_msg: ConfigMessage =
ConfigMessage::make_self_from_string(a_msg.payload().as_ref().unwrap().as_str());
assert_eq!(a_config_msg.msg_type(), ConfigMessageType::Field);
assert!(a_config_msg.data().is_some());
assert_eq!(*a_config_msg.data().as_ref().unwrap(), config_data);
}
#[test]
fn test_process_message() {
let prop_msg = ProcessMessage::new(ProcessMessageType::Stop, true);
assert_eq!(prop_msg.msg(), ProcessMessageType::Stop);
assert!(prop_msg.propagate());
// serialize the process message into a IIDMessage
let a_msg = prop_msg.make_message(MessageType::Process);
assert_eq!(a_msg.msg_type(), MessageType::Process);
assert!(a_msg.payload().is_some());
let a_prop_msg: ProcessMessage =
ProcessMessage::make_self_from_string(a_msg.payload().as_ref().unwrap().as_str());
assert_eq!(a_prop_msg.msg(), ProcessMessageType::Stop);
assert!(a_prop_msg.propagate());
}
}