mikrotik-proto 0.2.0

Sans-IO protocol implementation for MikroTik RouterOS API
Documentation 
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

#![cfg_attr(not(feature = "std"), no_std)]
#![warn(missing_docs)]
//! # mikrotik-proto
//!
//! Sans-IO protocol implementation for the `MikroTik` `RouterOS` API.
//!
//! This crate provides a runtime-agnostic, `no_std`-compatible implementation
//! of the `MikroTik` `RouterOS` API wire protocol. It handles:
//!
//! - **Wire-format encoding/decoding** — variable-length prefix codec for words and sentences
//! - **Command building** — typestate builder pattern with compile-time validation
//! - **Response parsing** — zero-copy sentence parsing into typed responses
//! - **Connection state machine** — multiplexed command/response correlation
//! - **Login handshake** — typestate-enforced authentication flow
//!
//! This crate performs **no I/O**. It accepts byte slices as input and produces
//! byte buffers and events as output. A runtime adapter (e.g., `mikrotik-tokio`)
//! is responsible for actual network communication.
//!
//! # Feature flags
//!
//! | Feature | Default | Description |
//! |---------|---------|-------------|
//! | `std`   | no      | Uses `std::collections::HashMap` in public types. When disabled (default), falls back to `hashbrown::HashMap` for `no_std` compatibility. |
//!
//! # Architecture
//!
//! ```text
//! ┌─────────────────────────────────────────────────────┐
//! │  mikrotik-proto (this crate)                        │
//! │                                                     │
//! │  codec (RawSentence) ──▶ response                    │
//! │                           ▲                         │
//! │  command ─────────────────┘                         │
//! │                                                     │
//! │  connection (state machine, multiplexing)            │
//! │  handshake  (typestate login flow)                   │
//! └─────────────────────────────────────────────────────┘
//!          ▲ receive(&[u8])    │ poll_transmit()
//!          │                  │ poll_event()
//!          │                  ▼
//! ┌─────────────────────────────────────────────────────┐
//! │  Runtime adapter (e.g., mikrotik-tokio)             │
//! │  Thin async glue: TcpStream ↔ Connection            │
//! └─────────────────────────────────────────────────────┘
//! ```

extern crate alloc;

// Re-export the appropriate HashMap type based on feature flags.
//
// When the `std` feature is enabled (default), public types use
// `std::collections::HashMap`. When disabled (for `no_std` environments),
// they fall back to `hashbrown::HashMap`.
#[cfg(not(feature = "std"))]
pub use hashbrown::HashMap;
#[cfg(feature = "std")]
pub use std::collections::HashMap;

/// Wire-format codec for MikroTik API length-prefixed words and sentences.
pub mod codec;
/// Command builder with typestate pattern and compile-time validation.
pub mod command;
/// Sans-IO connection state machine with multiplexed command/response correlation.
pub mod connection;
/// Error types for the protocol implementation.
pub mod error;
/// Typestate-enforced login handshake.
pub mod handshake;
/// Compile-time command path validation and `command!` macro.
pub mod macros;
/// Response types for parsed command responses.
pub mod response;
/// Command tag — a unique identifier for correlating commands with responses.
pub mod tag;
/// Word types: the fundamental unit of the MikroTik API protocol.
pub mod word;

// Re-export key types at crate root for convenience
pub use command::{Command, CommandBuilder};
pub use connection::{Connection, Event, State, Transmit};
pub use handshake::{Authenticated, Handshaking, LoginProgress};
pub use response::CommandResponse;
pub use tag::Tag;