From fc226ab4af28b12421fa0b14f6ad7419c1780688 Mon Sep 17 00:00:00 2001
From: 4o1x5 <4o1x5@4o1x5.dev>
Date: Wed, 13 Nov 2024 19:57:46 +0100
Subject: [PATCH] readme: expanded a bit

---
 Cargo.toml |  3 ++-
 readme.md  | 55 ++++++++++++++++++++++++++++++++++++++++++------------
 src/lib.rs |  1 -
 3 files changed, 45 insertions(+), 14 deletions(-)

diff --git a/Cargo.toml b/Cargo.toml
index 8f23298..7b15569 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,10 +1,11 @@
 [package]
 name = "bunbun-worker"
 version = "0.1.0"
-description = "An rpc and non-rpc rabbitmq worker for Mediarose"
+description = "An rpc/non-rpc rabbitmq worker library"
 edition = "2021"
 license = "AGPL-3.0"
 authors = ["4o1x5 <4o1x5@4o1x5.dev>"]
+repository = "https://git.4o1x5.dev/4o1x5/bunbun-worker"
 
 
 [dependencies]
diff --git a/readme.md b/readme.md
index 9e33632..bfb43c6 100644
--- a/readme.md
+++ b/readme.md
@@ -1,30 +1,50 @@
 <center> <h1> BunBun-Worker </h1> </center>
 
-A multithreaded _panic-safe_ job runner built on the AMQP. Bunbun-worker features RPC and nonRPC calls, and can handle multiple types of messages at a time.
+`bunbun-worker` is a panic-safe multithreaded job-runner server/client library for rust. It supports [RPC](https://wikipedia.org/wiki/Remote_procedure_call) and regular (non-rpc) calls. As of right now only [rabbitmq](https://www.rabbitmq.com/) is supported but [gRPC](https://grpc.io/) will be added too.
 
 > ❗ Disclaimer  
 > This crate is still under development, meaning api's may change on every commit...
 
+# Introduction
+
+`bunbun-worker` was made to provide a way for microservices written in rust to communicate to each other by dispatching jobs that may return data and those who don't.
+
+### Rpc
+
+Remote procedure call, as it's name says is a message that can be sent to a remote microservice to be processed and the result to be returned. In `bunbun-worker` it's implemented by the following example:
+
+```mermaid
+sequenceDiagram
+    ServiceA->>+ServiceB: Hey, could you do this job for me?
+    Note right of ServiceB: ServiceB does the job
+    ServiceB->>+ServiceA: Sure, here is the data result
+```
+
+1. ServiceA creates a callback queue that the response shall be sent to.
+2. ServiceA sends a json job message to an **already declared** queue on a rabbitmq server.
+3. ServiceB is listening on that queue for messages and spawns a new thread for each received.
+4. Once ServiceB has finished the work, using the received messages header it responds to the callback queue with the correlation-id.
+
+### Non-rpc
+
+In `bunbun-worker` regular jobs are called _non-rpc_ jobs, indicating that the response is not awaited.
+
 ## Installation
 
-Since this package is not published to crates.io you will need to add it manually to `Cargo.toml`
+Get directly from crates.io
 
 ```toml
 [dependencies]
-bunbun-worker = { git = "https://git.4o1x5.dev/4o1x5/bunbun-worker", version = "0.12" }
+bunbun-worker = { version = "0.1.0" }
 ```
 
-or
+or get it directly from source
 
 ```toml
 [dependencies]
 bunbun-worker = { git = "https://git.4o1x5.dev/4o1x5/bunbun-worker", branch = "main" }
 ```
 
-## Motivation
-
-I have a project called _Mediarose_ in development and I needed a way to have efficient and simple communication between services to kill of circular dependencies.
-
 ## Usage
 
 Here is a basic implementation of an RPC job in bunbun-worker
@@ -64,7 +84,7 @@ impl RPCServerTask for EmailJob {
     type State = State;
     fn run(
         self,
-        state: Arc<Mutex<Self::State>>,
+        state: Self::State,
     ) -> futures::prelude::future::BoxFuture<'static, Result<Self::Result, Self::ErroredResult>>
     {
         Box::pin(async move {
@@ -87,9 +107,9 @@ async fn main(){
         .add_rpc_consumer::<EmailJob>(
             "email-emailjob-v1.0.0", // queue name
             "emailjob", // consumer tag
-            Arc::new(Mutex::new(State {
+            State {
                 something: "test".into(), // putting our state into a Arc<Mutex<S>> for thread safety
-            })),
+            },
         )
         .await;
     tracing::debug!("Starting listener");
@@ -142,13 +162,24 @@ async fn main(){
 }
 ```
 
+# Limitations
+
+1. Currently some `unwrap()`'s are called inside the code and may results in panics (not in the job-runner).
+2. No TLS support
+3. No settings, and very limited API
+4. The rabbitmq RPC logic is very basic with no message-versioning (aside using different queue names (see [usage](#usage)) )
+
+# Bugs department
+
+Since the code is hosted on a private git instance (as of right now) any bugs shall be discussed in [4o1x5's project room](https://matrix.to/#/#projects:4o1x5.dev).
+
 ## License
 
 Licensed under [GNU AFFERO GENERAL PUBLIC LICENSE](https://www.gnu.org/licenses/agpl-3.0.en.html)
 
 ### Contribution
 
-Currently this library does not accept any contributors, as it's hosted on a private registry and git server.
+Currently this library does not accept any contributors, as it's hosted on a private git server.
 
 # Credits
 
diff --git a/src/lib.rs b/src/lib.rs
index 2964dfc..dc12b11 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -184,7 +184,6 @@ impl BunBunWorker {
                     match outcome {
                         Err(error) => {
                             tracing::error!("Failed to start thread for worker {}", error);
-                            // TODO return erro
                             let headers = create_header(ResultHeader::Panic);
                             let _ = delivery.ack(BasicAckOptions::default()).await; // acking the delivery
                             respond_to_rpc_queue(