o192 0.2.2

ORION-192: ordered, resilient, independent, URL-safe 192-bit IDs for distributed systems.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

# o192 — Rust

[![Crates.io](https://img.shields.io/crates/v/o192.svg)](https://crates.io/crates/o192)
[![docs.rs](https://docs.rs/o192/badge.svg)](https://docs.rs/o192)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
[![MSRV](https://img.shields.io/badge/MSRV-1.74-informational.svg)](#minimum-supported-rust-version)
[![Spec: v0](https://img.shields.io/badge/spec-v0-orange.svg)](https://github.com/lh0x00/orion-192/blob/main/SPEC.md)

Rust reference implementation of [**ORION-192**](https://github.com/lh0x00/orion-192) — **O**rdered, **R**esilient, **I**ndependent, **O**paque-ish, **N**on-coordinated 192-bit identifiers for distributed systems.

ORION-192 produces fixed-width, URL-safe, lexicographically sortable IDs without a central coordinator, worker ID, or machine identity in the wire format. This crate is byte-compatible with the [JavaScript](../javascript) and [Python](../python) reference implementations.

## Highlights

- **Single small dependency** (`getrandom`) for OS CSPRNG access; no transitive bloat.
- `#![forbid(unsafe_code)]` and `#![warn(missing_docs)]` enforced crate-wide.
- **Optional `serde` feature** for `Serialize` / `Deserialize` on `ParsedOrionId`.
- **Strictly monotonic** within a generator instance, including across clock rollback.
- **Wire-compatible** with the JavaScript and Python packages — same 24-byte layout, same 32-character canonical form.

## Install

```bash
cargo add o192
```

With the optional `serde` feature:

```bash
cargo add o192 --features serde
```

## Quick start

```rust
use o192::OrionIdGenerator;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Long-lived generator (recommended for sustained throughput)
    let mut gen = OrionIdGenerator::new();
    let a = gen.next()?;
    let b = gen.next()?;
    assert!(a < b); // strictly monotonic per generator

    println!("{a}");
    Ok(())
}
```

### Private epoch

```rust
use o192::OrionIdGenerator;

let mut gen = OrionIdGenerator::with_epoch_ms(1_735_689_600_000)?; // 2025-01-01 UTC
let id = gen.next()?;
```

### Parsing

```rust
use o192::{is_valid, parse};

let id = "0Pu_iDKVO9012BwIEM28oFojPMWLWeLU";
assert!(is_valid(id));

let view = parse(id, 0)?;
println!("{} {}", view.relative_ms, view.counter);
```

## API

| Item | Purpose |
|---|---|
| `OrionIdGenerator` | Stateful generator with strict local monotonicity. |
| `encode_sortable64` / `decode_sortable64` | Wire-format codec. |
| `parse` / `is_valid` | Structured view and syntactic validation. |
| `ParsedOrionId` | Field-level view of a parsed ID. |
| `OrionIdError` | Single error enum covering every failure mode. |

Every public item is documented; run `cargo doc --open` for the full reference, or browse it on [docs.rs](https://docs.rs/o192).

## Cargo features

| Feature | Default | Effect |
|---|:-:|---|
| `serde` | off | Implements `serde::{Serialize, Deserialize}` for `ParsedOrionId`. |

## Minimum Supported Rust Version

This crate supports **Rust 1.74 and newer**. MSRV bumps are treated as minor-version releases and noted in the changelog.

## Performance

A single `OrionIdGenerator` produces roughly **2–6 M IDs/second** on a modern laptop. Numbers are indicative — run the bundled example on your target hardware:

```bash
cargo run --release --example bench
```

## Status

ORION-192 is at **spec `v0`** — implementation-complete, cross-language conformant, and **wire-frozen**. See the [project status](https://github.com/lh0x00/orion-192#status) for the full stability statement.

## Specification & related

- [Specification (`SPEC.md`)](https://github.com/lh0x00/orion-192/blob/main/SPEC.md) — normative wire format and algorithm.
- [Design rationale (`docs/RATIONALE.md`)](https://github.com/lh0x00/orion-192/blob/main/docs/RATIONALE.md) — why 192 bits, why this layout.
- [Storage guide (`docs/DATABASE.md`)](https://github.com/lh0x00/orion-192/blob/main/docs/DATABASE.md) — column types, collation, indexing.
- [Security policy (`SECURITY.md`)](https://github.com/lh0x00/orion-192/blob/main/SECURITY.md) — threat model and disclosure process.
- Sibling implementations: [JavaScript](https://www.npmjs.com/package/orion-192) · [Python](https://pypi.org/project/o192/).

## License

Licensed under the [MIT License](./LICENSE) — Copyright © 2026 Lam Hieu and contributors.