httlib_protos/
lib.rs

1//! This crate implements [Protocol Buffers] binary protocol `v3` (`proto3`),
2//! for encoding and decoding typed messages to and from the wire format. The
3//! protocol deals in-depth with optimizing the representation of data types on
4//! the wire so that as little data as possible is transmitted between the client
5//! and server.
6//! 
7//! [![Documentation](https://img.shields.io/badge/-Documentation-blue?style=for-the-badge&logo=Rust)](https://docs.rs/httlib-protos)
8//! [![Source](https://img.shields.io/badge/-Source-lightgrey?style=for-the-badge&logo=GitHub)](https://github.com/xpepermint/httlib-rs/tree/main/protos)
9//! 
10//! ## About
11//! 
12//! Protocol Buffers, also know as `protos` or `protobufs`, is an open-source
13//! interface description language originally developed by Google and a library
14//! that allows JSON-like data messages to be transmitted over the wire without
15//! unnecessary ballast. Today, it is most relevant in the context of [gRPC],
16//! where [RPC] server and client code for arbitrary programming languages is
17//! generated based on Protocol Buffers descriptions.
18//!  
19//! Protocol Buffers were developed primarily with the goal of speeding up the
20//! transmission of strongly typed key-value message objects over the network,
21//! which in turn means reducing the amount of data that needs to be transmitted
22//! over the wire from A to B.
23//! 
24//! [REST] and [RPC] are two concepts that are now considered a kind of de facto
25//! way of developing APIs in web development. Communication between the client
26//! and the server is mostly about transferring data in [JSON] format. This is
27//! user-friendly, but highly suboptimal at the network level. 
28//! 
29//! Protocol Buffers addresses this issue and is one of the most optimized
30//! protocols which is also growing in popularity.
31//! 
32//! This library is not meant for generating code for the client and the server.
33//! The crate focuses on the low-level data compression and decompression for
34//! transmitting typed objects over the wire. It offers the full implementation
35//! of the Protocol Buffer's binary protocol.
36//! 
37//! ## Usage
38//!
39//! **Encoding example:**
40//! 
41//! ```rust
42//! use httlib_protos::{Encoder, EncoderLit};
43//! 
44//! let encoder = Encoder::default();
45//! 
46//! let mut dst = Vec::new();
47//! encoder.encode((&1, &150i32), &mut dst).unwrap(); // common type
48//! encoder.encode((&2, EncoderLit::SInt32(&-150i32)), &mut dst).unwrap(); // specific type
49//! ```
50//! 
51//! **Decoding example:**
52//! 
53//! ```rust
54//! use httlib_protos::{Decoder, DecoderLit};
55//! 
56//! let mut decoder = Decoder::default();
57//! 
58//! let mut buf = vec![0x85, 0x35, 0x85];
59//! 
60//! let mut dst = vec![];
61//! let size = decoder.decode(&mut buf, &mut dst).unwrap();
62//! 
63//! for (tag, typ, byt) in dst.drain(..) {
64//!     if tag == 1 {
65//!         i32::from(DecoderLit::Int32(byt));
66//!     }
67//! }
68//! ```
69//! 
70//! ## Articles
71//! 
72//! * [Deep dive into the binary algorithm of Protocol Buffers](https://dev.to/xpepermint/deep-dive-into-the-binary-algorithm-of-protocol-buffers-7j2)
73//! 
74//! [Protocol Buffers]: https://en.wikipedia.org/wiki/Protocol_Buffers
75//! [gRPC]: https://grpc.io/
76//! [REST]: https://en.wikipedia.org/wiki/Representational_state_transfer
77//! [RPC]: https://en.wikipedia.org/wiki/Remote_procedure_call
78//! [JSON]: https://en.wikipedia.org/wiki/JSON
79
80pub mod decoder;
81pub mod encoder;
82mod typ;
83
84pub use decoder::*;
85pub use encoder::*;
86pub use typ::*;
httlib_protos/lib.rs

httlib_protos/
lib.rs
