lib.rs

//! A minimal (i.e. very incomplete) implementation of a MTProto server and
//! client.
//!
//! The purpose of this project is to provide a larger example of an
//! asynchronous Rust project built with Tokio. Do not attempt to run this in
//! production... seriously.
//!
//! # Layout
//!
//! The library is structured such that it can be used with guides. There are
//! modules that are public that probably would not be public in a "real" MTProto
//! client library.
//!
//! The major components are:
//!
//! * `server`: MTProto server implementation. Includes a single `run` function
//!   that takes a `TcpListener` and starts accepting MTProto client connections.
//!
//! * `client`: an asynchronous MTProto client implementation.
//!
//! * `cmd`: implementations of the supported MTProto commands(APIs).
//!
//! * `frame`: represents a single MTProto protocol frame. A frame is used as an
//!   intermediate representation between a "command" and the byte
//!   representation.

#![feature(test)]
#![feature(cursor_remaining)]
#![feature(assert_matches)]

pub mod blocking_client;
pub mod client;

pub mod cmd;
pub use cmd::Command;

mod connection;
pub use connection::Connection;

pub mod frame;
pub use frame::Frame;

mod db;
use db::Db;
use db::DbDropGuard;

mod parse;
use parse::{Parse, ParseError};

pub mod server;

mod buffer;
pub use buffer::{buffer, Buffer};

mod shutdown;
use shutdown::Shutdown;

/// Default port that a MTProto server listens on.
///
/// Used if no port is specified.
pub const DEFAULT_PORT: &str = "6379";

/// Error returned by most functions.
///
/// When writing a real application, one might want to consider a specialized
/// error handling crate or defining an error type as an `enum` of causes.
/// However, for our example, using a boxed `std::error::Error` is sufficient.
///
/// For performance reasons, boxing is avoided in any hot path. For example, in
/// `parse`, a custom error `enum` is defined. This is because the error is hit
/// and handled during normal execution when a partial frame is received on a
/// socket. `std::error::Error` is implemented for `parse::Error` which allows
/// it to be converted to `Box<dyn std::error::Error>`.
pub type Error = Box<dyn std::error::Error + Send + Sync>;

/// A specialized `Result` type for mini-telegram operations.
///
/// This is defined as a convenience.
pub type Result<T> = std::result::Result<T, Error>;