Skip to content

Commit

Permalink
docs: Update readme (#55)
Browse files Browse the repository at this point in the history
## Description

- remove mention of using raw quinn, since that is no longer possible
- consistently use upper case for QUIC and BLAKE3
- eliminate mention of collections. Collections are just one of many
special cases of hash sequences.
- remove mention of reexport that does not exist anymore

## Breaking Changes

None

## Notes & open questions

Note: the readme is also used from the iroh docs page. That is why I
have a link to "this repository".

## Change checklist

- [ ] Self-review.
- [ ] Documentation updates following the [style
guide](https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html#appendix-a-full-conventions-text),
if relevant.
- [ ] Tests if relevant.
- [ ] All breaking changes documented.

---------

Co-authored-by: Philipp Krüger <[email protected]>
  • Loading branch information
rklaehn and matheus23 authored Feb 21, 2025
1 parent 57cb626 commit d8d2b48
Show file tree
Hide file tree
Showing 3 changed files with 11 additions and 10 deletions.
14 changes: 6 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,18 @@
# iroh-blobs

This crate provides blob and collection transfer support for iroh. It implements a simple request-response protocol based on blake3 verified streaming.
This crate provides blob and blob sequence transfer support for iroh. It implements a simple request-response protocol based on BLAKE3 verified streaming.

A request describes data in terms of blake3 hashes and byte ranges. It is possible to
request blobs or ranges of blobs, as well as collections.
A request describes data in terms of BLAKE3 hashes and byte ranges. It is possible to request blobs or ranges of blobs, as well as entire sequences of blobs in one request.

The requester opens a quic stream to the provider and sends the request. The provider answers with the requested data, encoded as [blake3](https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf) verified streams, on the same quic stream.
The requester opens a QUIC stream to the provider and sends the request. The provider answers with the requested data, encoded as [BLAKE3](https://github.com/BLAKE3-team/BLAKE3-specs/blob/master/blake3.pdf) verified streams, on the same QUIC stream.

This crate is usually used together with [iroh](https://crates.io/crates/iroh), but can also be used with normal [quinn](https://crates.io/crates/quinn) connections. Connection establishment is left up to the user or a higher level APIs such as the iroh CLI.
This crate is used together with [iroh](https://crates.io/crates/iroh). Connection establishment is left up to the user or higher level APIs.

## Concepts

- **Blob:** a sequence of bytes of arbitrary size, without any metadata.

- **Link:** a 32 byte blake3 hash of a blob.
- **Link:** a 32 byte BLAKE3 hash of a blob.

- **HashSeq:** a blob that contains a sequence of links. Its size is a multiple of 32.

Expand Down Expand Up @@ -64,8 +63,7 @@ async fn main() -> anyhow::Result<()> {

## Examples

Examples that use `iroh-blobs` can be found in the `iroh` crate. the iroh crate publishes `iroh_blobs` as `iroh::bytes`.

Examples that use `iroh-blobs` can be found in [this repo](https://github.com/n0-computer/iroh-blobs/tree/main/examples).

# License

Expand Down
5 changes: 4 additions & 1 deletion deny.toml
Original file line number Diff line number Diff line change
Expand Up @@ -37,4 +37,7 @@ ignore = [
]

[sources]
allow-git = []
allow-git = [
"https://github.com/n0-computer/iroh.git",
"https://github.com/n0-computer/quic-rpc.git",
]
2 changes: 1 addition & 1 deletion src/store/fs.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1247,7 +1247,7 @@ impl super::Map for Store {
type Entry = Entry;

async fn get(&self, hash: &Hash) -> io::Result<Option<Self::Entry>> {
Ok(self.0.get(*hash).await?.map(From::from))
Ok(self.0.get(*hash).await?)
}
}

Expand Down

0 comments on commit d8d2b48

Please sign in to comment.