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
// Copyright (c) Subzero Labs, Inc.
// SPDX-License-Identifier: Apache-2.0
//! # Event Serialization
//!
//! This module provides serialization and deserialization capabilities for the event system.
//!
//! * **Bincode**: An extremely fast and compact binary serialization format optimized for Rust
//!
//! ## Format Overview
//!
//! The module currently supports Bincode serialization, which offers:
//!
//! - **Exceptional Performance**: One of the fastest serialization formats available
//! - **Compact Binary Format**: Significantly smaller than JSON (5-10x compression)
//! - **Type Safety**: Leverages Rust's type system for safe serialization
//! - **Zero-Copy Deserialization**: Minimal memory allocations during parsing
//! - **Cross-Platform Compatibility**: Consistent binary format across architectures
//!
//! ## Usage Examples
//!
//! ### Serializing an event to Bincode
//!
//! ```rust
//! use psmatcher::{event_types::{AttributeValue, DefaultEvent}, traits::BincodeSerializable};
//!
//! let event = DefaultEvent::new("user.login".to_string())
//! .with_attribute("user_id".to_string(), AttributeValue::String("12345".into()));
//!
//! let bincode_bytes = event.to_bincode().unwrap();
//! println!("Serialized {} bytes", bincode_bytes.len());
//! ```
//!
//! ### Deserializing an event from Bincode
//!
//! ```rust
//! use psmatcher::{event_types::DefaultEvent, traits::{BincodeDeserializable, BincodeSerializable}};
//!
//! // Serialize an event
//! let original_event = DefaultEvent::new("test.event".to_string());
//! let bincode_bytes = original_event.to_bincode().unwrap();
//!
//! // Deserialize it back
//! let deserialized_event = DefaultEvent::from_bincode(&bincode_bytes).unwrap();
//! assert_eq!(original_event, deserialized_event);
//! ```
//!
//! ### File I/O Operations
//!
//! ```rust
//! use psmatcher::{event_types::DefaultEvent, traits::{BincodeSerializable, BincodeDeserializable}};
//! use std::fs::File;
//! use std::io::{BufReader, BufWriter};
//!
//! let event = DefaultEvent::new("file.event".to_string());
//!
//! // Write to file
//! let file = File::create("event.bincode").unwrap();
//! let writer = BufWriter::new(file);
//! event.write_bincode(writer).unwrap();
//!
//! // Read from file
//! let file = File::open("event.bincode").unwrap();
//! let reader = BufReader::new(file);
//! let loaded_event = DefaultEvent::read_bincode(reader).unwrap();
//! ```
//!
//! ## Performance Characteristics
//!
//! Bincode provides excellent performance for event serialization:
//!
//! | Operation | Performance vs JSON |
//! |-----------|-------------------|
//! | Serialization | 10-50x faster |
//! | Deserialization | 5-20x faster |
//! | Size | 5-10x smaller |
//! | Memory Usage | Significantly lower |
//!
//! ## Design Considerations
//!
//! * **Bincode** is optimized for performance and size efficiency, making it ideal for:
//! - High-throughput event processing
//! - Storage-constrained environments
//! - Network transmission where bandwidth matters
//! - Applications requiring fast serialization/deserialization
//!
//! * **Trade-offs**:
//! - Rust-specific format (not human-readable)
//! - Requires matching Rust types for deserialization
//! - Less suitable for cross-language interoperability
//!
//! ## Future Considerations
//!
//! The module is designed to be extensible. Additional serialization formats can be added
//! in the future while maintaining the same trait-based interface:
//!
//! - JSON support for human-readable debugging
//! - MessagePack for cross-language compatibility
//! - Custom formats for specific use cases