<p align="center"> <img src="img/oxedyne_logo_white_text_below_opt.svg" width="150"/> </p>

<p align="center"> <img src="img/fe2o3_display_white_opt.svg" width="200"/> </p>

Oxedyne Hematite (fe2o3)

Hematite is a collection of Rust crates that grew from an exploration into database design and key data structures. The project includes several innovative components:

• O3db: A log-structured key-value database inspired by BitCask, designed for high throughput.
• JDAT: A superset of JSON adding types, combining human-readable and binary formats.
• Shield: A secure peer-to-peer protocol and app built on UDP.
• Namex: A distributed universal name codex for schemes and specifications.

Oxedyne is my Rust/Web development shop.

Status

This solo project has been in progress on a part time basis for several years, and I estimate completion of the initial 0.9.0 release is at around 50% overall. I'm now doing this in public in the hope of soliciting ideas and suggestions, with a view to publishing a developer guide and accepting contributions some time in the next 12 months.

Feel free to:

• Star/watch the repository if interested,
• Open issues for bugs or feature suggestions,
• Fork and experiment with the code,
• Provide feedback through discussions,
• Contribute through GitHub Sponsors if you want faster development or wider adoption, and
• Make pull requests once the contribution window opens.

See the detailed project progress for recently completed and upcoming features.

Project Philosophy

Hematite started as a Rust learning experience, and one of my objectives has been to minimise third-party dependencies. However, despite every effort to reinvent lots of wheels, it still depends on many crates directly and indirectly. So I am very grateful to all their authors and contributors.

The code aims mostly to be correct, readable, and maintainable rather than super-fast or clever. While I have always strived for economy and efficiency, I'm looking forward to community contributions that help make better use of Rust features, and lead to more aggressive optimisation.

One of the initial motivations for the library was to improve my personal developer experience, which has involved a range of experiments particularly around error handling and logging. The code avoids the use of unsafe and unwrap. The ? propogator is avoided in favour of macros that are more explicitly function-like such as the directly replacement ok!, the match-based res! and the closure catch! which tries to capture unwind panics. Eventually any impacts on performance will be properly assessed. Tags were built into the fe2o3_core::error::Error type which offers a foundation for theoretical benefits but the practical value remains to be seen.

Components

The crates can be organised by their level of internal cross-dependencies, currently the most notable being:

Foundational (no internal cross-dependencies)

• fe2o3_core: Core traits, utilities, logging, and fundamental types, typically small and relatively simple.
• fe2o3_stds: A place for existing public standards.

Fundamental (1-3 internal cross-dependencies)

• fe2o3_bot: Thread worker library, for bot-like worker threads with common termination semantics.
• fe2o3_data: Specialised data structures such as ring buffers, stacks, trees and timestamped types.
• fe2o3_iop_hash: Interoperability layer for hashing, including SHA3-256 and Seahash.
• fe2o3_net: Network utilities with support for DNS, HTTP, WebSocket, and SMTP.
• fe2o3_num: Numerical type utilities, big integer, decimal types, and number strings.
• fe2o3_text: String manipulation and formatting, with text processing tools, base2x encoding and a REPL-friendly Stringer.

Functional (4-7 internal cross-dependencies)

• fe2o3_crypto: Cryptography library including post-quantum implementations such as SABER and Dilithium.
• fe2o3_hash: Generic hashing and key derivation utilities.
• fe2o3_iop_crypto: Interoperability layer for cryptography, including AES-GCM, and Ed25519.
• fe2o3_iop_db: Interoperability layer for databases.
• fe2o3_jdat: A user-level type layer including JDAT format implementation.
• fe2o3_namex: A distributed, general purpose, universal name codex with utilities.
• fe2o3_syntax: A command parsing library for defining custom protocols.

Application Level (8+ internal cross-dependencies)

• fe2o3_o3db: The Ozone database.
• fe2o3_shield: Shield protocol implementation for secure peer-to-peer networking.
• fe2o3_steel: A web server implementation with developer mode, HTTPS, WebSocket, and SMTPS support.
• fe2o3_tui: A terminal user interface library, including the Ironic TUI.

Getting Started

Hematite is currently available via GitHub and version 0.9.0 will be available on crates.io. You can use it in several ways:

Installation

Note that Hematite is developed on linux. Compilation of C static libraries for the post quantum cryptography scheme SABRE reference implementation (for testing) requires OpenSSL. On ubuntu:

sudo apt-get install libssl-dev

From GitHub

For the latest development version, use git dependencies:

[dependencies]
oxedyne_fe2o3 = { git = "https://github.com/oxedyne-io/fe2o3" }

Local Development

To explore or contribute:

1. Clone the repository:

git clone https://github.com/oxedyne-io/fe2o3.git
cd fe2o3

1. Build the project:

cargo build

1. Run the tests:

cargo test

Tests are grouped inside files within a tests directory for each crate, and run via the tests/main.rs file, e.g.:

cd fe2o3_core
cargo test main -- --nocapture

From crates.io

When it becomes available, you can access specific crates directly :

[dependencies]
oxedyne_fe2o3_core = "0.5.0"
oxedyne_fe2o3_jdat = "0.5.0"

Or use the workspace crate to access everything:

[dependencies]
oxedyne_fe2o3 = { version = "0.5.0", features = ["all"] }

Or just the components you need:

[dependencies]
oxedyne_fe2o3 = { version = "0.5.0", features = ["core", "jdat", "o3db"] }

Usage Examples

Check the test files in each crate's tests directory for detailed usage examples. Here's a quick start:

// Using the workspace crate
use oxedyne_fe2o3::core::prelude::*;
use oxedyne_fe2o3::jdat;

// Or individual crates
use oxedyne_fe2o3_core::prelude::*;
use oxedyne_fe2o3_jdat;

Highlights

Ozone Database

O3db aims to:

• Write data quickly to log-structured files,
• Offer a high degree of parallalism using operating system threads,
• Keep as much data in a fast volatile cache as possible,
• Provide automatic file garbage collection, and a
• Simple, familiar key-value interface.

JDAT

JDAT extends JSON to support:

• Type annotations including multiple number formats,
• Binary encoding and decoding,
• Comment support, and
• Any type as map keys.

Shield Protocol

Shield stands for Signed Hash In Every Little Datagram and provides:

• UDP-based messaging,
• Secure and authenticated peer-to-peer communication,
• Post-quantum cryptography options, and
• Mitigates DOS attacks through use of proof of work in all packets.

Namex

Namex aims to enable:

• A decentralised, versionless database for mapping 32-byte identifiers to entities
• Support for over 4 billion identifier families, each with over 65,000 variants
• JDAT-based storage format with human-readable export options
• Rich entity metadata including names, descriptions, timestamps, and cross-references
• Language-aware naming with alternative name support
• Hierarchical tagging system for flexible categorisation

Steel Web Server

Steel includes:

• A robust HTTPS server with WebSocket upgrade support
• Development mode with hot reloading and self-signed certificates
• Production mode with Let's Encrypt certificate automation
• Built-in static file serving and route configuration
• Clean separation between server and application layers
• JavaScript/TypeScript bundling and SASS compilation in development mode

Iron Interactive Console

Ironic aims to offer:

• Modal editing inspired by Vi/Vim
• Windowing system with draggable/resizable windows
• Tab-based interface for organizing content
• Customisable styles and colours
• Scrollbars and status indicators
• File tree navigation
• Support for both static and editable text views

License

See the LICENSE file for license rights and limitations.

Future Plans

• Complete initial implementation of all components,
• Stabilise APIs,
• Expand documentation,
• Open for community contributions,
• Publish to crates.io.

Contact

<hello@oxedyne.io>