mise_server/

lib.rs

//! # `mise-server`
//!
//! mise (MIcro SErvice) also pronounced as 'mice' is a web stack for the
//! specific use in micro services.
//!
//! See [prelude::Mise].
//!
//! ## Server
//!
//! The micro service environment is the kind of setup where each service is
//! relatively small and with minimal overheads since they have to talk to each
//! other a lot. A micro service is not directly exposed to the public.
//! A typical setup would be pods in kubernetes or a similar infrastructure.
//!
//! The typical use of micro services are for RPC, where a user is not involved
//! and every request is seen as an api call.
//!
//! Since this implementation uses no async, the microservice being built would
//! be of a particular kind, usually without any IO wait on the downstream or
//! coded with that in mind to be non blocking by the user of this stack.
//!
//! Since the environment is meant to be also micro, the requests are handled
//! in a monothreaded way, and so enqueued as soon as a request object is
//! available, a call for a response is made. There will be a second thread for
//! piping the channels in and out of the IO.
//!
//! ## Routing
//!
//! Basic routing is available.
//!
//! - static routes `/route`
//! - query params `/route?id=X`
//! - last path item wildcard `/route/*` for `/route/X`
//!
//! ## Metrics
//!
//! Metrics are being measured with [metrics](https://docs.rs/metrics) but the
//! registry is not initialized by default, that will have to be done by the
//! user of the library by setting up the crate that will implement the
//! metric endpoint (Eg
//! [metrics-exporter-prometheus](https://docs.rs/metrics-exporter-prometheus))
//! before starting the server.
//!
//! ## Tracing
//!
//! Logs are done through the [tracing](https://docs.rs/tracing) crate, and can
//! be setup by the user through calling the
//! [tracing_subscriber](https://docs.rs/tracing_subscriber) crate.
//!
//! ## Limitations
//!
//! - HTTP 1 only: http2 has the issue of sticky sessions for its nature of
//!   keeping the connection open. Http 1 is easier to distribute across more
//!   nodes because connections are usually created in a pool from the point of
//!   view of the clients. Uses [http](https://docs.rs/http) for basic types.
//!
//! - No TLS: it is assumed the local network where microservices are running
//!   to be already protected. TLS would be an unnecessary complexity for
//!   internal use, add too many dependencies, and too hard to setup for non
//!   blocking sockets.
//!
//! - No async: non-blocking IO is managed through this library APIs directly
//!   and the use of channels. Uses [mio](https://docs.rs/mio)
//!
//! - JSON only: common support is JSON only in microservices. Uses
//!   [serde_json](https://docs.rs/serde_json)
//!
//! - No compression: intented to be in a local network where speeds of
//!   transfer do not significantly require compression and the waste of cpu
//!   that implies. If the response is wihtin MTU, there is even less sense to
//!   compress, and this library is not meant to respond with files or
//!   attachments, but a RPC JSON response.
//!
//! - No 3xx redirects: the server is meant to respond directly to a RPC and
//!   does not forward the request anywhere else.
//!
//! - Auth optional: Authentication header is optionally implemented but it is
//!   going to be handled by the user on the server side.
//!
//! - No relative URI: No '..' interpreted. This is an RPC stack and requires
//!   specific paths. No file system path is mapped through URIs.

mod connection;
mod mise;
mod routes;
mod server;

pub mod prelude {
    pub use super::mise::{
        Deserializable, Mise, Request, Response, Route, Serializable, TextRoute,
    };
    pub use http::StatusCode;
}