Merge pull request #47 from chainbound/feat/book

feat: mdbook

.github/workflows/book.yml

@@ -0,0 +1,38 @@
+name: Book Deployment
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      deployments: write
+    name: Publish to GitHub Pages
+    steps:
+      - name: Checkout sources
+        uses: actions/checkout@v4
+      - name: Setup mdbook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: "latest"
+      - name: Setup mdbook-mermaid
+        uses: magicgh/mdbook-mermaid-action@v1
+        with:
+          version: "latest"
+      - name: Install mdbook-template
+        run: |
+          mkdir mdbook-template
+          curl -sSL https://github.com/sgoudham/mdbook-template/releases/latest/download/mdbook-template-x86_64-unknown-linux-gnu.tar.gz | tar -xz --directory=./mdbook-template
+          echo `pwd`/mdbook-template >> $GITHUB_PATH
+      - name: Build book
+        working-directory: ./book
+        run: mdbook build
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.ref == 'refs/heads/main' }}
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./book/book

.gitignore

@@ -3,3 +3,4 @@
 .helix/
 *.svg
 *.log
+.DS_Store

CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contribution guidelines
+
+Thanks for your interest in contributing to making MSG better!
+
+## How to contribute
+
+### Getting started
+
+To get started with MSG, you will need the Rust toolchain installed on your machine.
+You can find the installation instructions [here](https://www.rust-lang.org/tools/install).
+
+Once you have the necessary tools installed, you can clone the repository and run the tests:
+
+```shell
+git clone git@github.com:chainbound/msg-rs.git
+cd msg-rs
+
+cargo test --all
+```
+
+### Development workflow
+
+We use Github for all our development workflow. If you are not familiar with Github, you can find
+a great guide [here](https://guides.github.com/activities/hello-world/).
+
+We use Github issues to track all our work. If you want to contribute, you can find a list of
+open issues [here](https://github.com/chainbound/msg-rs/issues). If you want to work on an issue,
+please leave a comment on the specific issue so that we it can be assigned to you.
+
+When testing your changes, please use the following commands and make sure that they all pass:
+
+```
+cargo check --all
+cargo test --all
+cargo +nightly fmt -- --check
+cargo +nightly clippy --all --all-features -- -D warnings
+```
+
+Once you are done with your changes, you can open a pull request. We will review your changes
+and provide feedback. Once the changes are approved, your pull request will be merged.
+
+### Asking for help
+
+If you have any questions, you can open a [new issue](https://github.com/chainbound/msg-rs/issues/new)
+or join our [Discord server](https://discord.gg/nhWcSWYpm9).
+
+### Code of conduct
+
+MSG adheres to the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct).
+This document describes the minimum behavior expected from all contributors.
+
+### License
+
+By contributing to MSG, you agree that your contributions will be licensed under its
+[MIT license](https://github.com/chainbound/msg-rs/blob/main/LICENSE).

README.md

@@ -3,18 +3,14 @@
 [![CI](https://github.com/chainbound/msg-rs/actions/workflows/ci.yml/badge.svg)][gh-ci]
 [![License](https://img.shields.io/badge/License-MIT-orange.svg)][mit-license]
 
-[gh-ci]: https://github.com/chainbound/msg-rs/actions/workflows/ci.yml
-[mit-license]: https://github.com/chainbound/msg-rs/blob/main/LICENSE
-
 **A flexible and lightweight messaging library for distributed systems built with Rust and Tokio.**
 
 ## Overview
 
 `msg-rs` is a messaging library that was inspired by projects like [ZeroMQ](https://zeromq.org/) and [Nanomsg](https://nanomsg.org/).
 It was built because we needed a Rust-native messaging library like those above.
 
-> **Warning**
-> This project is still in early development and is not ready for production use.
+> MSG is still in ALPHA and is not ready for production use.
 
 ## Features
 
@@ -25,7 +21,7 @@ It was built because we needed a Rust-native messaging library like those above.
   - [ ] Push/Pull
   - [ ] Survey/Respond
 - [ ] Stats (RTT, throughput, packet drops etc.)
- - [x] Request/Reply basic stats
+- [x] Request/Reply basic stats
 - [ ] Queuing
 - [ ] Pluggable transport layer
   - [x] TCP
@@ -73,6 +69,7 @@ async fn main() {
 ```
 
 ### Publish/Subscribe
+
 ```rust
 use bytes::Bytes;
 use tokio_stream::StreamExt;
@@ -105,14 +102,24 @@ async fn main() {
 ```
 
 ## MSRV
+
 The minimum supported Rust version is 1.70.
 
 ## Contributions & Bug Reports
 
-Please report any bugs or issues you encounter by [opening a github issue](https://github.com/chainbound/msg-rs/issues/new).
+If you are interested in contributing or have found a bug, please check out the [contributing guide][contributing].
+Please report any bugs or doubts you encounter by [opening a Github issue][new-issue].
 
-Pull requests are welcome! If you would like to contribute, please open an issue first to discuss the change you would like to make.
+Additionally, you can reach out to us on [Discord][discord] if you have any questions or just want to chat.
 
 ## License
 
-This project is licensed under the [MIT license](https://github.com/chainbound/msg-rs/blob/main/LICENSE).
+This project is licensed under the [MIT license][mit-license].
+
+<!-- Links -->
+
+[gh-ci]: https://github.com/chainbound/msg-rs/actions/workflows/ci.yml
+[discord]: https://discord.gg/nhWcSWYpm9
+[new-issue]: https://github.com/chainbound/msg-rs/issues/new
+[mit-license]: https://github.com/chainbound/msg-rs/blob/main/LICENSE
+[contributing]: https://github.com/chainbound/msg-rs/blob/main/CONTRIBUTING.md

book/.gitignore

@@ -0,0 +1,2 @@
+book
+.DS_Store

book/README.md

@@ -0,0 +1,13 @@
+# msg-rs book
+
+To build the book locally, you need to install the following tools:
+
+```shell
+cargo install mdbook mdbook-mermaid mdbook-template
+```
+
+Then, to run the book locally:
+
+```shell
+mdbook serve
+```

book/book.toml

@@ -0,0 +1,14 @@
+[book]
+authors = ["Nicolas Racchi"]
+language = "en"
+multilingual = false
+src = "src"
+title = "The MSG-RS Book"
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[preprocessor.template]
+
+[output.html]
+additional-js = ["mermaid.min.js", "mermaid-init.js"]

book/mermaid-init.js

@@ -0,0 +1 @@
+mermaid.initialize({ startOnLoad: true, theme: "dark" });

book/src/SUMMARY.md

@@ -0,0 +1,13 @@
+# Summary
+
+- [Introduction](./intro.md)
+- [Usage](./usage/intro.md)
+  - [Getting started](./usage/getting-started.md)
+  - [Socket Types](./usage/socket-types.md)
+  - [Transport Layers](./usage/transport-layers.md)
+  - [Authentication](./usage/authentication.md)
+  - [Compression](./usage/compression.md)
+  - [Encryption](./usage/encryption.md)
+  - [Logging](./usage/logging.md)
+  - [FAQ](./usage/faq.md)
+- [Contributing](./contributing.md)

book/src/contributing.md

@@ -0,0 +1,55 @@
+# Contribution guidelines
+
+Thanks for your interest in contributing to making MSG better!
+
+## How to contribute
+
+### Getting started
+
+To get started with MSG, you will need the Rust toolchain installed on your machine.
+You can find the installation instructions [here](https://www.rust-lang.org/tools/install).
+
+Once you have the necessary tools installed, you can clone the repository and run the tests:
+
+```shell
+git clone git@github.com:chainbound/msg-rs.git
+cd msg-rs
+
+cargo test --all
+```
+
+### Development workflow
+
+We use Github for all our development workflow. If you are not familiar with Github, you can find
+a great guide [here](https://guides.github.com/activities/hello-world/).
+
+We use Github issues to track all our work. If you want to contribute, you can find a list of
+open issues [here](https://github.com/chainbound/msg-rs/issues). If you want to work on an issue,
+please leave a comment on the specific issue so that we it can be assigned to you.
+
+When testing your changes, please use the following commands and make sure that they all pass:
+
+```
+cargo check --all
+cargo test --all
+cargo +nightly fmt -- --check
+cargo +nightly clippy --all --all-features -- -D warnings
+```
+
+Once you are done with your changes, you can open a pull request. We will review your changes
+and provide feedback. Once the changes are approved, your pull request will be merged.
+
+### Asking for help
+
+If you have any questions, you can open a [new issue](https://github.com/chainbound/msg-rs/issues/new)
+or join our [Discord server](https://discord.gg/nhWcSWYpm9).
+
+### Code of conduct
+
+MSG adheres to the [Rust Code of Conduct](https://www.rust-lang.org/policies/code-of-conduct).
+This document describes the minimum behavior expected from all contributors.
+
+### License
+
+By contributing to MSG, you agree that your contributions will be licensed under its
+[MIT license](https://github.com/chainbound/msg-rs/blob/main/LICENSE).

book/src/intro.md

@@ -0,0 +1,54 @@
+# MSG-RS
+
+<a href="https://github.com/chainbound/msg-rs"><img src="https://img.shields.io/badge/GitHub%20Repo-msg-green?logo=github"></a>
+<a href="https://discord.gg/nhWcSWYpm9"><img src="https://img.shields.io/badge/Discord-x?logo=discord&label=chainbound"></a>
+
+## Introduction
+
+> 📖 [MSG-RS][msg] is a flexible and lightweight messaging library for distributed
+> systems built with Rust and Tokio, designed for performance and reliability.
+
+This library is built and maintained by [Chainbound][chainbound], and is licensed
+under the [MIT License][license].
+
+## Overview
+
+MSG-RS is inspired by projects like [ZeroMQ][zeromq] and [Nanomsg][nanomsg].
+It was built because at Chainbound we needed a Rust-native messaging library
+that was flexible and customizable enough without relying on C bindings or
+external dependencies.
+
+Another reason for building this library was to modularize the messaging
+components of our [Fiber][fiber] project. Lastly, this was also used as
+an opportunity to dive deeper into some async rust patterns to measure
+optimizations in isolation from other distributed system components.
+
+## Features
+
+**1. Flexible and modular**
+
+MSG-RS is designed to be modular by leveraging Rust's traits and generics. This
+modularity can be seen in all aspects, from the transport layer to the socket patterns.
+
+**2. Durable**
+
+Durability is a critical aspect in distributed systems. By using smart abstractions
+like the ones from [StubbornIO][stubborn-io], MSG is able to provide reliable
+reconnections and retries out of the box.
+
+**3. Extensible**
+
+Even though MSG comes with different socket patterns and transport layers, it is also
+designed to be easily extensible if you want to bring your own options like
+authentication, encryption, and compression to the table.
+
+## Development Status
+
+**MSG is currently in ALPHA, and is not yet recommended for use in production.**
+
+## Contributing
+
+Contributors are welcome! Please see the [contributing guide][contributing] for
+more information.
+
+{{#include ./links.md}}

book/src/links.md

@@ -0,0 +1,21 @@
+<!-- External -->
+
+[zeromq]: https://zeromq.org/
+[nanomsg]: https://nanomsg.org/
+[turmoil]: https://github.com/tokio-rs/turmoil
+[stubborn-io]: https://github.com/craftytrickster/stubborn-io
+
+<!-- MSG links -->
+
+[msg]: https://github.com/chainbound/msg-rs
+[book]: https://msg.chainbound.io/book
+[issues]: https://github.com/chainbound/msg-rs/issues
+[new-issue]: https://github.com/chainbound/msg-rs/issues/new
+[license]: https://github.com/chainbound/msg-rs/blob/main/LICENSE
+[contributing]: https://github.com/chainbound/msg-rs/tree/main/CONTRIBUTING.md
+
+<!-- Chainbound links -->
+
+[chainbound]: https://chainbound.io/
+[discord]: https://discord.gg/nhWcSWYpm9
+[fiber]: https://fiber.chainbound.io/