2 unstable releases
0.2.0 | Dec 26, 2022 |
---|---|
0.1.0 | Dec 26, 2022 |
#7 in #cid
22KB
388 lines
Ceramic StreamID
This package contains Ceramic StreamID and CommitID implementation.
Implements Ceramic streamIDs as defined in ceramic spec and
CIP,
represented as StreamId
and StreamId
for API clarity.
StreamId
represents a reference to a stream as a whole, thus does not
contain commit information.
CommitId
represents a reference to a particular commit in the stream
evolution.
<streamid> ::= <multibase-prefix><multicodec-streamid><type><genesis-cid-bytes>
or including StreamId
commit
<streamid> ::= <multibase-prefix><multicodec-streamid><type><genesis-cid-bytes><commit-cid-bytes>
Getting started
Installation
$ cargo add streamid
Usage
See the ceramic developer site for more details about how to use this package.
To reference a stream as a whole, use StreamId
. You can create an instance
from the parts. stream type string or integer and CID instance or string are
required.
use std::str::FromStr;
use cid::Cid;
use streamid::*;
const CID_STRING: &str = "bagcqcerakszw2vsovxznyp5gfnpdj4cqm2xiv76yd24wkjewhhykovorwo6a";
const STREAM_ID_STRING: &str = "kjzl6cwe1jw147dvq16zluojmraqvwdmbh61dx9e0c59i344lcrsgqfohexp60s";
let stream_id = StreamId::from_str(STREAM_ID_STRING).unwrap();
assert_eq!(stream_id.stream_type(), StreamType::Tile);
assert_eq!(stream_id.stream_type().to_string(), "tile");
assert_eq!(stream_id.cid().to_string(), CID_STRING);
assert_eq!(stream_id.to_string(), STREAM_ID_STRING);
assert_eq!(stream_id.to_url(), format!("ceramic://{STREAM_ID_STRING}"));
You can also create StreamId
instance from StreamId
string or bytes.
use std::str::FromStr;
use streamid::*;
const STREAM_ID_STRING: &str = "kjzl6cwe1jw147dvq16zluojmraqvwdmbh61dx9e0c59i344lcrsgqfohexp60s";
let stream_id = StreamId::from_str(STREAM_ID_STRING).unwrap();
use streamid::*;
let stream_id = StreamId::from_slice(vec![]).unwrap();
To reference particular point in a stream evolution, use CommitId
. In
addition to stream type (StreamType
) and genesis reference ([Cid
]), one is
expected to provide a reference to commit ([Cid
]). If you pass None
, this
would reference a genesis commit.
use std::str::FromStr;
use streamid::*;
const BASE_CID_STRING: &str = "bagcqcerakszw2vsovxznyp5gfnpdj4cqm2xiv76yd24wkjewhhykovorwo6a";
const COMMIT_CID_STRING: &str = "bagjqcgzaday6dzalvmy5ady2m5a5legq5zrbsnlxfc2bfxej532ds7htpova";
const COMMIT_ID_STRING: &str =
"k1dpgaqe3i64kjqcp801r3sn7ysi5i0k7nxvs7j351s7kewfzr3l7mdxnj7szwo4kr9mn2qki5nnj0cv836ythy1t1gya9s25cn1nexst3jxi5o3h6qprfyju";
let commit_id = CommitId::from_str(COMMIT_ID_STRING).unwrap();
assert_eq!(commit_id.stream_type(), StreamType::Tile);
assert_eq!(commit_id.stream_type().to_string(), "tile");
assert_eq!(commit_id.cid().to_string(), BASE_CID_STRING);
assert_eq!(commit_id.commit().to_string(), COMMIT_CID_STRING);
assert_eq!(commit_id.to_string(), COMMIT_ID_STRING);
assert_eq!(commit_id.to_url(), format!("ceramic://{COMMIT_ID_STRING}"));
To reference specific CID from StreamId
or to change commit reference in
CommitId
, use StreamRefExt::at_commit
method:
use streamid::StreamRefExt;
commit_id.at_commit("bagcqcerakszw2vsov..."); // #=> new CommitId for the same stream
stream_id.at_commit("bagcqcerakszw2vsov..."); // #=> new CommitId for the same stream
CommitId
(StreamId
for compatibility also) can get you base StreamId
via StreamRefExt::to_base_id
:
use streamid::StreamRefExt;
commit_id.to_base_id(); // #=> StreamID reference to the stream
stream_id.to_base_id(); // #=> new StreamID reference to the same stream, effectively a shallow clone.
To parse an unknown input into proper CommitId
or StreamId
, you could
use StreamRef::from_str
:
use std::str::FromStr;
use streamid::StreamRef;
let input = "bagcqcerakszw2vsov...";
let stream_id_or_commit_id = StreamRef::from_str(input).unwrap();
Development
Run tests:
cargo test
Run linter:
cargo clippy
cargo fmt
Contributing
We are happy to accept small and large contributions. Make sure to check out the Ceramic specifications for details of how the protocol works.
License
MIT or Apache-2.0
Dependencies
~4.5–6MB
~112K SLoC