Open a byte-stream to a machine identified by its public key, wherever it is on the internet, across
NATs, without knowing its address. Identity is an ed25519 public key (a NodeId): you address who a
peer is, not where. bifrost gives you the connection and nothing more; what you send over it is up to
you.
It carries the connection over its own backends: iroh (QUIC with NAT hole-punching) and an in-process backend for tests.
The name. Bifröst is the burning rainbow bridge of Norse myth, the span that reaches from one world to any other. This crate is the bridge to a peer: name a public key and it carries a connection there.
Experimental. APIs will change and it is not ready for production use.
Git-only for now, not published to crates.io. Point at the repo:
[dependencies]
bifrost = { git = "https://github.com/theia-hq/bifrost" }
bifrost-iroh = { git = "https://github.com/theia-hq/bifrost" }Compose a transport with a discovery mechanism into a Node, then dial peers by identity:
use bifrost::{Node, NoDiscovery, Session};
use bifrost_iroh::Endpoint;
let node = Node::new(Endpoint::bind().await?, NoDiscovery);
let session = node.connect(peer_id).await?;
let (mut writer, mut reader) = session.open_bi().await?;Transport, Session, and Discovery are the pluggable interfaces. Implement Transport to add a
backend; it passes the conformance suite, so a dial written against these interfaces runs unchanged over
any of them. A shipping backend proves the peer's key in its handshake and protects its streams under
that handshake's keys; the in-process backend is for tests and proves nothing.
| crate | role |
|---|---|
bifrost |
facade: the connection API (Node, Transport, Session, Discovery) |
bifrost-core |
identity: NodeId, an ed25519 public key with a crypto-suite tag |
bifrost-transport |
the Transport and Session traits |
bifrost-iroh |
transport backend over iroh (QUIC with NAT hole-punching) |
bifrost-mem |
in-process transport backend for hermetic tests |
bifrost-mdns |
discovery over mDNS on the local network |
bifrost-conformance |
transport-agnostic test suite every backend must pass |
bifrost-wire |
one-shot blob transfer over a stream, BLAKE3-verified end to end |
This page describes the default branch.
- bifrost establishes the connection and hands you a byte-stream. It says nothing about what those bytes mean; that is the caller's protocol.
- Verified blob transfer lives in
bifrost-wire, a sibling crate the facade re-exports asbifrost::wire.
Licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.