cosmosd 0.1.0

Delay-tolerant streaming daemon — stream across the void
cosmosd-0.1.0 is not a library.

Disclaimer: This project was largely written with AI assistance. Most of the code has not been formally reviewed, tested in production, or audited for correctness. Use at your own risk. Contributions, reviews, and bug reports are very welcome.

cosmosd

Delay-tolerant streaming daemon — stream across the void.

cosmosd is the core relay node for the CosmoDTN framework. It stores HLS video segments as BPv7-inspired bundles, forwards them hop-by-hop to peers over any available link, and serves them to local players via a standard HTTP/HLS API.

Designed for networks where internet connectivity is absent, intermittent, or extremely high-latency: space stations, aircraft, submarines, remote villages, disaster zones.

How it works

Content is chunked into 10-second HLS segments by cosmoscast-ingest. Each segment is wrapped in a bundle — a self-describing unit with a content ID, sequence number, priority, TTL, and a BLAKE3 integrity hash.

cosmosd uses epidemic routing: when two nodes connect, they exchange bundle manifests and transfer what the other is missing. Bundles propagate through the network hop-by-hop until they reach every reachable node.

Viewers watch via any HLS player pointed at http://localhost:7777/play/{content_id}. Playback is time-shifted, not buffered — cosmosd pre-positions chunks ahead of the playhead so there is no spinner.

[Ingest node]          [Relay node]          [Viewer node]
cosmoscast-ingest  →   cosmosd stores    →   cosmosd serves
POST /ingest           epidemic sync         GET /play/...
                        TCP / BLE / LoRa      HLS player

Install

Homebrew (recommended)

brew tap CosmoDTN/tap
brew install cosmosd

From source

Prerequisites: Rust 1.78+

git clone https://github.com/CosmoDTN/cosmosd
cd cosmosd
cargo build --release
# Binary at: target/release/cosmosd

Usage

# Start the daemon (defaults: HTTP on 7777, relay on 7778)
cosmosd serve

# Custom ports
cosmosd serve --port 8888 --relay-port 8889

# Connect to known peers at startup
cosmosd serve --peer 192.168.1.5:7778 --peer 192.168.1.6:7778

# Custom store path and node ID
cosmosd serve --store /data/cosmosd --node-id iss-node-1

# Require a shared secret for relay connections
cosmosd serve --relay-token my-secret

# Disable mDNS auto-discovery (for controlled environments)
cosmosd serve --no-discovery

All options:

Flag Default Description
--port 7777 HTTP API port (SDK and ingest connect here)
--relay-port 7778 TCP relay port (peer-to-peer bundle sync)
--peer — Known peer relay address; pass multiple times
--store .cosmosd/store Bundle store directory
--node-id hostname Human-readable node identifier
--relay-token — Shared secret; peers must supply the same token
--no-discovery false Disable mDNS auto-discovery

HTTP API

The API binds to 127.0.0.1 only — it is local-only by design.

Method Path Description
GET /health Node status, version
GET /catalog List all stored content
GET /play/:content_id HLS M3U8 playlist
GET /segment/:content_id/:sequence Raw .ts segment bytes
POST /ingest Add a bundle (used by cosmoscast-ingest)
GET /peers Connected peers and sync status
POST /peers Add a peer at runtime

Example: ingest a segment

PAYLOAD_B64=$(base64 -i segment_00001.ts)

curl -s -X POST http://localhost:7777/ingest \
  -H "Content-Type: application/json" \
  -d "{
    \"content_id\": \"my_show_ep1\",
    \"content_title\": \"My Show — Episode 1\",
    \"sequence\": 1,
    \"mime_type\": \"video/mp2t\",
    \"priority\": \"vod\",
    \"payload_b64\": \"$PAYLOAD_B64\"
  }"

Example: play content

Point any HLS player at:

http://localhost:7777/play/my_show_ep1

Or with ffplay:

ffplay http://localhost:7777/play/my_show_ep1

Bundle priorities

Priority TTL Routing
live 30 minutes Aggressive — any available link
near_live 6 hours Best-effort
vod 30 days Carry indefinitely

Expired bundles are reaped automatically every 5 minutes.

Architecture

cosmosd
├── src/
│   ├── main.rs          — CLI, startup, background task wiring
│   ├── bundle/          — BPv7-inspired bundle format, BLAKE3 integrity
│   ├── store/           — Content-addressed bundle store (sled)
│   ├── router/          — Epidemic routing logic
│   ├── peer/            — Peer manager: outgoing sync + relay listener
│   ├── transport/       — Convergence layer trait + TCP implementation
│   ├── discovery/       — mDNS peer auto-discovery
│   ├── auth/            — Optional relay token authentication
│   └── api/             — Local HTTP API (axum)

Transport plugins (convergence layers)

cosmosd ships with TCP. Any transport medium can be added by implementing three traits: ConvergenceLayer, BundleListener, and BundleStream.

See TRANSPORT.md for the interface, bundle framing spec, and bandwidth guidance per medium (TCP, Bluetooth, LoRa, ham radio, USB sneakernet).

Community transports:

  • [cosmodtn/transport-reticulum] (planned)
  • [cosmodtn/transport-lora] (planned)

Protocol

The bundle format is a working subset of IETF BPv7 (RFC 9171) extended with streaming-specific fields (sequence number, priority, HLS MIME type). Full BPv7 wire compatibility is a future goal.

License

MIT