> **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`](https://github.com/CosmoDTN/cosmocast-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
### macOS — Homebrew (recommended)
```bash
brew tap CosmoDTN/tap
brew install cosmosd
```
ffmpeg (required for `cosmosd ingest`):
```bash
brew install ffmpeg
```
---
### Ubuntu / Debian
Install system dependencies first:
```bash
sudo apt update
sudo apt install pkg-config libssl-dev ffmpeg
```
Install Rust (if not already installed):
```bash
```
Install cosmosd:
```bash
cargo install cosmosd
```
---
### Other Linux (Fedora, Arch, Alpine)
```bash
# Fedora / RHEL
sudo dnf install pkg-config openssl-devel ffmpeg
# Arch
sudo pacman -S pkg-config openssl ffmpeg
# Alpine
sudo apk add pkgconfig openssl-dev ffmpeg
```
Then:
```bash
cargo install cosmosd
```
---
### Windows
Install Rust from [rustup.rs](https://rustup.rs), then:
```bash
cargo install cosmosd
```
For `cosmosd ingest`, install [ffmpeg for Windows](https://ffmpeg.org/download.html) and add it to your PATH.
---
### From source
```bash
git clone https://github.com/CosmoDTN/cosmosd
cd cosmosd
cargo build --release
# Binary at: target/release/cosmosd
```
---
## Usage
```bash
# Start the daemon (defaults: HTTP on 7777, relay on 7778)
cosmosd serve
# Ingest a local video file (requires ffmpeg + daemon running)
cosmosd ingest /path/to/movie.mkv
cosmosd ingest /path/to/movie.mkv --title "Interstellar"
cosmosd ingest /path/to/movie.mkv --daemon http://10.2.0.119:7777
# Start daemon
# 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:
| `--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 |
| `--bind` | `127.0.0.1` | HTTP API bind address (`0.0.0.0` to expose on all interfaces) |
---
## HTTP API
The API binds to `127.0.0.1` only — it is local-only by design.
| `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
```bash
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`:
```bash
ffplay http://localhost:7777/play/my_show_ep1
```
---
## Bundle priorities
| `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`](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)](https://www.rfc-editor.org/rfc/rfc9171) extended with streaming-specific fields (sequence number, priority, HLS MIME type). Full BPv7 wire compatibility is a future goal.
---
## License
MIT