Expand description
Gearbox is a versatile library that encompasses a wide array of functionalities, including networking, logging, railway-oriented programming extensions, and time management. Initially designed as a collection of utilities, the ultimate vision for Gearbox is to evolve into a highly optimized, standalone toolkit. The goal is to minimize external dependencies progressively, leading to a library that is lightweight and efficient. By doing so, Gearbox aims to be universally compatible, from embedded systems to WebAssembly (WASM) environments, all while maintaining simplicity and minimizing the need for boilerplate code. This development strategy positions Gearbox as a comprehensive solution for developers seeking to build efficient, scalable applications across a broad spectrum of platforms.
§Features
| Category | Feature | use | Description | Status |
|---|---|---|---|---|
| Common | TryDefault | gearbox::common::TryDefault | This is a trait used internally in Gearbox defining a TryDefault trait that returns a Result<T,Self::Error>. It can also be used in other systems. | ✅ |
| BoxedFuture | gearbox::common::BoxedFuture | Type alias for a pinned boxed future. Used for returning dynamically dispatched futures. | ✅ | |
| Error | ErrorTracer | gearbox::error::tracer::* | An error structure that builds a traceable stack of errors. It allows breaking down the error into a TypeId to define the encapsulated error for further operations. Contains information about file, line, module path, and optional error_code with display and debug. This also comes with the macro Error!() which sets up the ErrorTracerExtInfo with all the needed information (file, line, module). | ⚠️ |
| Rail ErrorTracer | gearbox::rails::ext::map_err_tracer | Simplification for map_err for operating with the ErrorTracer, allowing for passing an Error!() or an ErrorTracerExtInfo for collecting all the information. | ✅ | |
| Logging | Tracing Log Formatter | gearbox::log::fmt::* | Custom subscriber for formatting logs when using the rust Tracing library. | ⚠️ |
| Networking | hostname | gearbox::net::hostname | Get the hostname of the local machine. | ✅ |
| HTTP Request | gearbox::net::http::request | Send an HTTP request. This is an extension on top of Reqwest that simplifies the implementation of mTLS and payload signing. | ⚠️ | |
| HTTP Request Chaining | gearbox::net::http::request_chain | Chaining system for HTTP requests, allowing for chaining requests and responses for more advanced request/response handling. | ❌ | |
| Paths | Common Paths | gearbox::path::* | Common paths under Windows, Linux, and more. For example, under Linux, the config path is usually ~/.config/. | ✅ |
| Rails | Common Extensions | gearbox::rails::ext::* | Various extension traits for operating on Result, Option, and other standard types, providing additional methods for error handling, merging results, and tapping into values. | ⚠️ |
| Future Extensions | gearbox::rails::ext::future::* | Extensions for working with Future types, providing methods for mapping, chaining, and merging futures. | ✅ | |
| serde | Dynamic Serialization | gearbox::serde::dynamic::* | Dynamic serialization system that allows for encoding and decoding of multiple formats. This is a simplified version of the serde library. | ⚠️ |
| Wasm Bindgen Ser/de | gearbox::serde::wasm_bindgen::* | Implementation for WASM Bind Generator that allows for serialization/deserialization of JsValue. | ✅ | |
| Storage | Web Storage | gearbox::storage::web::local_storage::* | Interface for interacting with local storage in a web environment, including features for setting, getting, and deleting data with JSON serialization/deserialization support. | 🚧 |
| File Storage | gearbox::storage::io::file::* | Interface for interacting with file storage, including features for setting, getting, and deleting data with JSON and YAML serialization/deserialization support. | 🧪 | |
| Selective Storage | gearbox::storage::selective_storage | Trait for selective storage operations, providing methods for creating, setting, getting, and deleting storage entries. | 🚧 | |
| Time | Time Stamps and more | gearbox::time::* | Timestamp system similar to Chrono, handling times and time calculations. Used throughout Gearbox instead of Chrono. | ⚠️ |
| Template | Template Engine | gearbox::template::* | Template engine responsible for rendering templates using context data and applying pipelines for data transformations. It supports pipelines for operations like date formatting and string prefixing. | ⚠️ |
§Status Icons Explanation
- ✅ Completed: The feature is fully implemented and tested.
- ❌ Not Completed: The feature is not implemented.
- ⚠️ Partially: The feature is partially implemented.
- 🚧 In Development: The feature is currently being developed.
- 🧪 Missing Testing: The feature is implemented but lacks testing.
§Test Status
§Http Request (gearbox::net::http::request)
§Complete architectural overview:
classDiagram
%% Package: request
namespace request {
class Client {
+client: reqwest::Client
+new()
+with_client(reqwest::Client)
+set_global_signing(Signature)
}
class Error {
+UrlParser(ParseError)
+Request(reqwest::Error)
+NoUrl
+HeaderValue(reqwest::header::InvalidHeaderValue)
+DeserializeContentType(String)
+DeserializeJson(serde_json::Error)
+BodyError(TracerError)
}
class Method {
<<enumeration>>
Get
Post
Put
Delete
Patch
Head
Options
Connect
Trace
None
}
class RequestBuilder {
+client: Option<Arc<Client>>
+method: Method
+uri: Option<Url>
+headers: HeaderMap
+body: Body
+content_type: String
+signature: Option<Signature>
+new_with_client(client: Option<Client>, method: Method, uri: Url)
+method(T: Into<Method>)
+uri(uri: &str)
+header(H: Into<Header>)
+headers(H: Into<HeaderMap>)
+body(B: Into<Body>)
+content_type(content_type: &str)
+with_signing_default()
+with_signing(signature: Signature)
+send()
}
class Response {
+status: StatusCode
+headers: HeaderMap
+content_length: Option<u64>
+url: Url
+body: BodyOwned
+status()
+to(T: DeserializeOwned)
}
class StatusCode {
+code: u16
+reason: &'static str
+as_u16()
+as_str()
}
class Url {
+Simple(url: String)
}
class Body {
+Empty
}
class BodyOwned {
+from(box_raw: Box<reqwest::Response>)
}
}
%% Relationships
Client --> RequestBuilder
RequestBuilder --> Response
RequestBuilder --> Error
Response --> StatusCode
Response --> HeaderMap
Response --> Url
Response --> BodyOwned
HeaderMap --> Header
Header --> Name
Header --> Values
Values --> Value§Http Request Chaining (gearbox::net::http::request_chaining)
§Complete architectural overview:
classDiagram
%% Package: request
namespace request {
class Client {
+client: reqwest::Client
+new()
+with_client(reqwest::Client)
+set_global_signing(Signature)
}
class Error {
+UrlParser(ParseError)
+Request(reqwest::Error)
+NoUrl
+HeaderValue(reqwest::header::InvalidHeaderValue)
+DeserializeContentType(String)
+DeserializeJson(serde_json::Error)
+BodyError(TracerError)
}
class Method {
<<enumeration>>
Get
Post
Put
Delete
Patch
Head
Options
Connect
Trace
None
}
class RequestBuilder {
+client: Option<Arc<Client>>
+method: Method
+uri: Option<Url>
+headers: HeaderMap
+body: Body
+content_type: String
+signature: Option<Signature>
+new_with_client(client: Option<Client>, method: Method, uri: Url)
+method(T: Into<Method>)
+uri(uri: &str)
+header(H: Into<Header>)
+headers(H: Into<HeaderMap>)
+body(B: Into<Body>)
+content_type(content_type: &str)
+with_signing_default()
+with_signing(signature: Signature)
+send()
}
class Response {
+status: StatusCode
+headers: HeaderMap
+content_length: Option<u64>
+url: Url
+body: BodyOwned
+status()
+to(T: DeserializeOwned)
}
class StatusCode {
+code: u16
+reason: &'static str
+as_u16()
+as_str()
}
class Url {
+Simple(url: String)
}
class Body {
+Empty
}
class BodyOwned {
+from(box_raw: Box<reqwest::Response>)
}
}
%% Package: request_chaining
namespace request_chaining {
class Header {
+name: Name
+values: Values
}
class HeaderMap {
+inner: HashMap<Name, Values>
+get(K: Into<Name>)
+insert(header: Header)
+extend(headers: HeaderMap)
}
class Name {
+String name
}
class Values {
+Vec<Value> values
+iter()
}
class Value {
+Vec<u8> value
+as_bytes()
+to_vec()
}
class TracerError
class Signature
class ParseError
}
%% Relationships
Client --> RequestBuilder
RequestBuilder --> Response
RequestBuilder --> Error
Response --> StatusCode
Response --> HeaderMap
Response --> Url
Response --> BodyOwned
HeaderMap --> Header
Header --> Name
Header --> Values
Values --> Value§Signature (gearbox::net::signature)
(docs: gearbox::net::signature)
§Railway Future extension (gearbox::rails::ext::future)
(docs: gearbox::serde::dynamic)
§Dynamic Serialization/Deserialization (gearbox::serde::dynamic)
(docs: gearbox::serde::dynamic)
§RwArc (gearbox::sync::rw_arc)
§RwArc (gearbox::template)
§TODO
- ( gearbox::log::* ) Clean up Log fmt/syslog, some of the code can be combined and cleaned up a bit better, also the formatter supports syslog, and bunyan, this should probably be cleared up a bit more, and separated better.
- ( gearbox::path::* ) current this system is mainly just exposing the dirs::* library, this should be removed.
- ( gearbox::* ) Remove usage for Vec or move usage of std::vec::Vec to another no-std library
Re-exports§
pub extern crate alloc;pub extern crate base64;pub extern crate bs58;pub extern crate bytes;pub extern crate core;pub extern crate serde as crate_serde; pub extern crate derive_more;pub extern crate erased_serde;pub extern crate futures;pub extern crate gearbox_macros;pub extern crate hashbrown;pub extern crate hex;pub extern crate hmac;pub extern crate reqwest;pub extern crate semver;pub extern crate serde_derive;pub extern crate serde_json;pub extern crate serde_qs;pub extern crate serde_yaml;pub extern crate sha2;pub extern crate spin;pub extern crate std;pub extern crate tokio;pub extern crate tracing;pub extern crate uniffi;pub extern crate uniffi_macros;pub use crate::log::syslog::macros::*;pub use crate::error::tracer::error_macro::*;