mikrotik_proto/
lib.rs

1#![cfg_attr(not(feature = "std"), no_std)]
2#![warn(missing_docs)]
3//! # mikrotik-proto
4//!
5//! Sans-IO protocol implementation for the `MikroTik` `RouterOS` API.
6//!
7//! This crate provides a runtime-agnostic, `no_std`-compatible implementation
8//! of the `MikroTik` `RouterOS` API wire protocol. It handles:
9//!
10//! - **Wire-format encoding/decoding** — variable-length prefix codec for words and sentences
11//! - **Command building** — typestate builder pattern with compile-time validation
12//! - **Response parsing** — zero-copy sentence parsing into typed responses
13//! - **Connection state machine** — multiplexed command/response correlation
14//! - **Login handshake** — typestate-enforced authentication flow
15//!
16//! This crate performs **no I/O**. It accepts byte slices as input and produces
17//! byte buffers and events as output. A runtime adapter (e.g., `mikrotik-tokio`)
18//! is responsible for actual network communication.
19//!
20//! # Feature flags
21//!
22//! | Feature | Default | Description |
23//! |---------|---------|-------------|
24//! | `std`   | no      | Uses `std::collections::HashMap` in public types. When disabled (default), falls back to `hashbrown::HashMap` for `no_std` compatibility. |
25//!
26//! # Architecture
27//!
28//! ```text
29//! ┌─────────────────────────────────────────────────────┐
30//! │  mikrotik-proto (this crate)                        │
31//! │                                                     │
32//! │  codec (RawSentence) ──▶ response                    │
33//! │                           ▲                         │
34//! │  command ─────────────────┘                         │
35//! │                                                     │
36//! │  connection (state machine, multiplexing)            │
37//! │  handshake  (typestate login flow)                   │
38//! └─────────────────────────────────────────────────────┘
39//!          ▲ receive(&[u8])    │ poll_transmit()
40//!          │                  │ poll_event()
41//!          │                  ▼
42//! ┌─────────────────────────────────────────────────────┐
43//! │  Runtime adapter (e.g., mikrotik-tokio)             │
44//! │  Thin async glue: TcpStream ↔ Connection            │
45//! └─────────────────────────────────────────────────────┘
46//! ```
47
48extern crate alloc;
49
50// Re-export the appropriate HashMap type based on feature flags.
51//
52// When the `std` feature is enabled (default), public types use
53// `std::collections::HashMap`. When disabled (for `no_std` environments),
54// they fall back to `hashbrown::HashMap`.
55#[cfg(not(feature = "std"))]
56pub use hashbrown::HashMap;
57#[cfg(feature = "std")]
58pub use std::collections::HashMap;
59
60/// Wire-format codec for MikroTik API length-prefixed words and sentences.
61pub mod codec;
62/// Command builder with typestate pattern and compile-time validation.
63pub mod command;
64/// Sans-IO connection state machine with multiplexed command/response correlation.
65pub mod connection;
66/// Error types for the protocol implementation.
67pub mod error;
68/// Typestate-enforced login handshake.
69pub mod handshake;
70/// Compile-time command path validation and `command!` macro.
71pub mod macros;
72/// Response types for parsed command responses.
73pub mod response;
74/// Command tag — a unique identifier for correlating commands with responses.
75pub mod tag;
76/// Word types: the fundamental unit of the MikroTik API protocol.
77pub mod word;
78
79// Re-export key types at crate root for convenience
80pub use command::{Command, CommandBuilder};
81pub use connection::{Connection, Event, State, Transmit};
82pub use handshake::{Authenticated, Handshaking, LoginProgress};
83pub use response::CommandResponse;
84pub use tag::Tag;
mikrotik_proto/lib.rs

mikrotik_proto/
lib.rs
