Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/svix/rust-ksuid
A pure-Rust KSUID implementation
https://github.com/svix/rust-ksuid
ksuid rust svix
Last synced: 6 days ago
JSON representation
A pure-Rust KSUID implementation
- Host: GitHub
- URL: https://github.com/svix/rust-ksuid
- Owner: svix
- License: mit
- Created: 2022-01-29T15:06:54.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2024-02-29T13:47:21.000Z (10 months ago)
- Last Synced: 2024-12-25T04:29:31.614Z (9 days ago)
- Topics: ksuid, rust, svix
- Language: Rust
- Homepage: https://www.svix.com
- Size: 91.8 KB
- Stars: 94
- Watchers: 3
- Forks: 12
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: ChangeLog.md
- License: LICENSE
Awesome Lists containing this project
README
Svix - Webhooks as a service
# Svix-KSUID (Rust)
A pure Rust and fully tested KSUID implementation
[](https://crates.io/crates/svix-ksuid)
[](https://github.com/svix/rust-ksuid/actions)
[](https://github.com/svix/rust-ksuid/actions/workflows/security.yml)
[](https://docs.rs/svix-ksuid/)
[](LICENSE)
[](https://www.svix.com/slack/)
This library is fully compatible with [Segment's KSUID](https://segment.com/blog/a-brief-history-of-the-uuid/) implementation:
https://github.com/segmentio/ksuid
For the Python version, please check out https://github.com/svix/python-ksuid
## What is a ksuid?
A ksuid is a K sorted UID. In other words, a KSUID also stores a date component, so that ksuids can be approximately
sorted based on the time they were created.
Read more [here](https://segment.com/blog/a-brief-history-of-the-uuid/).
## Usage
Add the dependency:
```toml
[dependencies]
svix-ksuid = "^0.6.0"
```
```rust
use svix_ksuid::*;
let ksuid = Ksuid::new(None, None);
println!("{}", ksuid.to_string());
// 1srOrx2ZWZBpBUvZwXKQmoEYga2
```
### Higher timestamp accuracy mode
Ksuids have a 1 second accuracy which is not sufficient for all use-cases. That's why this library exposes a higher accuracy mode which supports accuracy of up to 4ms.
It's fully compatible with normal ksuids, in fact, it outputs valid ksuids. The difference is that it sacrifices one byte of the random payload in favor of this accuracy.
The code too is fully compatible:
```rust
use svix_ksuid::*;
let ksuid = KsuidMs::new(None, None);
```
And they both implement the same `KsuidLike` trait.
### Opt-in features
* `serde` - adds the ability to serialize and deserialize `Ksuid` and `KsuidMs`
using serde.
Make sure to enable like this:
```toml
[dependencies]
svix-ksuid = { version = "^0.6.0", features = ["serde"] }
```
## Examples
### Converting Ksuids
```rust
use svix_ksuid::*;
let ksuid = Ksuid::new(None, None);
// Base62
println!("{}", ksuid.to_string()); // also: ksuid.to_base62()
// 1srOrx2ZWZBpBUvZwXKQmoEYga2
// Bytes (&[u8])
println!("{:?}", ksuid.bytes());
// [13, 53, 196, 51, 225, 147, 62, 55, 242, 117, 112, 135, 99, 173, 199, 116, 90, 245, 231, 242]
// Timestamp (time::OffsetDateTime)
println!("{:?}", ksuid.timestamp());
// 2021-05-21T20:04:03Z
// Timestamp (seconds)
println!("{}", ksuid.timestamp_seconds());
1621627443
// Payload (&[u8])
println!("{:?}", ksuid.bytes());
// [225, 147, 62, 55, 242, 117, 112, 135, 99, 173, 199, 116, 90, 245, 231, 242]
```
### Create Ksuids
```rust
use svix_ksuid::*;
// Timestamp is now, payload is randomly generated
let ksuid = Ksuid::new(None, None);
// Explicitly set either
let bytes = [12u8; Ksuid::PAYLOAD_BYTES];
let ksuid = Ksuid::new(Some(Utc::now()), Some(&bytes));
let ksuid = Ksuid::new(None, Some(&bytes));
let ksuid = Ksuid::new(Some(Utc::now()), None);
// From base62
let base62 = "1srOrx2ZWZBpBUvZwXKQmoEYga2";
let ksuid = Ksuid::from_base62(base62).unwrap();
let ksuid = Ksuid::from_str(base62).unwrap(); // Also implement FromStr
// From bytes
let bytes = [12u8; 20];
let ksuid = Ksuid::from_bytes(bytes.clone());
assert_eq!(&bytes, ksuid.bytes());
```
### Compare and order Ksuids
```rust
use svix_ksuid::*;
let ksuid1 = Ksuid::from_seconds(Some(1_555_555_555), None);
let ksuid2 = Ksuid::from_seconds(Some(1_777_777_777), None);
assert!(ksuid1 < ksuid2);
assert!(ksuid1 <= ksuid2);
assert!(ksuid1 == ksuid1);
assert!(ksuid2 > ksuid1);
assert!(ksuid2 >= ksuid1);
```
### License
ksuid source code is available under an MIT [License](./LICENSE).
All rights reserved to the [Svix webhooks service](https://www.svix.com).