mirror of
https://github.com/spacedriveapp/spacedrive.git
synced 2026-11-03 22:05:11 -05:00
Jamie Pine
2d380fd264
Replaces the Mintlify setup (mint.json, docs.json, snippets) with a standalone Fumadocs app in docs/: Next.js app router, meta.json nav per section, its own bun install. Run with `just dev-docs`. Content pass alongside the migration: core architecture, data model, CLI, and networking pages rewritten around the daemon/source-store/ library split, new product-direction.mdx defining the product boundary, new drive-catalog plan, and the physical-drives plan updated to reference it. Whitepaper page retired.
157 lines
5.0 KiB
Plaintext
157 lines
5.0 KiB
Plaintext
---
|
|
title: Networking
|
|
description: Direct encrypted transport for paired Spacedrive nodes
|
|
sidebarTitle: Networking
|
|
---
|
|
|
|
Spacedrive connects trusted devices through Iroh over QUIC. It attempts a
|
|
direct path first and uses a relay when network topology requires one. The
|
|
transport carries typed protocols for operations, source queries, byte ranges,
|
|
sync, and device presence.
|
|
|
|
A relay forwards encrypted traffic. It does not become a library authority or
|
|
receive permission to inspect a source.
|
|
|
|
## Network identity
|
|
|
|
Each daemon has a persistent cryptographic node identity. Pairing associates
|
|
that identity with a library device record and explicit grants.
|
|
|
|
Network discovery and authorization are separate:
|
|
|
|
- Discovery answers how to reach a node.
|
|
- Authentication proves which node connected.
|
|
- Authorization decides which libraries, sources, subtrees, and operations it
|
|
may use.
|
|
|
|
Seeing a node on the local network never grants file access.
|
|
|
|
## Reachability
|
|
|
|
Spacedrive combines:
|
|
|
|
- local network discovery for nearby nodes;
|
|
- direct QUIC connections when addresses permit them;
|
|
- internet discovery for a known node identity;
|
|
- relay fallback when NAT or firewalls block a direct path.
|
|
|
|
Connections can migrate between viable paths without changing device identity
|
|
or operation semantics.
|
|
|
|
## Protocol registry
|
|
|
|
Each protocol has a stable identifier, version, request limits, and
|
|
authorization rule. The network service routes an accepted stream to its
|
|
registered handler.
|
|
|
|
Core protocols include:
|
|
|
|
| Protocol | Purpose |
|
|
| --- | --- |
|
|
| Pairing | Establish and confirm device trust |
|
|
| Operations | Run scoped queries and actions |
|
|
| Source query | Browse or search a served source generation |
|
|
| Byte range | Stream original files and sidecars |
|
|
| Library sync | Exchange small shared state and assertions |
|
|
| Source sync | Replicate an authority-owned generation |
|
|
| Presence | Report device and source availability |
|
|
| Spacedrop | Offer an explicit file transfer |
|
|
|
|
Protocol versions are negotiated before application data is processed. An
|
|
unsupported version fails clearly instead of decoding with the wrong schema.
|
|
|
|
## Remote operations
|
|
|
|
Remote operation requests use the same registry as local clients. The serving
|
|
node creates a request context from the paired identity and grant, dispatches
|
|
the operation, and returns structured output or a typed error.
|
|
|
|
Long work remains a durable job on the executing node. The caller receives a
|
|
job ID and can query progress or logs later, including after reconnecting.
|
|
|
|
## Source queries
|
|
|
|
A node can serve one source without sending its entire library database. Query
|
|
responses name the source and generation that produced them.
|
|
|
|
Clients combine local, cached, and live remote results while preserving
|
|
completeness:
|
|
|
|
- complete means all required sources answered;
|
|
- partial means one or more sources were offline or denied;
|
|
- stale means a retained generation is older than the known authority.
|
|
|
|
## Byte streaming
|
|
|
|
The byte-range protocol reads local files, provider objects, caches, and
|
|
sidecars through one provider boundary. It supports:
|
|
|
|
- bounded ranges;
|
|
- backpressure;
|
|
- cancellation;
|
|
- content length and version evidence;
|
|
- resuming from verified offsets;
|
|
- authorization per request.
|
|
|
|
Control messages do not carry large file bodies. This keeps queries responsive
|
|
while previews, mounts, and transfers stream in parallel.
|
|
|
|
## Sync traffic
|
|
|
|
Library assertions and source generations use separate streams and watermarks.
|
|
Source generation follows one ingest authority. Multi-writer assertions merge
|
|
according to their type.
|
|
|
|
Backpressure prevents an initial source replication from starving interactive
|
|
queries. Peers can resume from acknowledged watermarks after a disconnect.
|
|
|
|
File bytes do not replicate merely because metadata synchronized. [File
|
|
Sync](/core/file-sync) controls durable byte placement.
|
|
|
|
## Security
|
|
|
|
The network boundary enforces:
|
|
|
|
- authenticated peer identity;
|
|
- protocol and message-size limits;
|
|
- library membership;
|
|
- source and subtree grants;
|
|
- query versus mutation permission;
|
|
- expiry and revocation;
|
|
- request timeouts and cancellation;
|
|
- audit context for durable actions.
|
|
|
|
Provider credentials, key material, and raw database handles never cross the
|
|
network protocol.
|
|
|
|
## Failure behavior
|
|
|
|
Network loss does not make a durable action silently succeed. The executing
|
|
node continues or stops according to the job contract. The caller observes an
|
|
unknown connection state until it can query the job again.
|
|
|
|
Remote reads fail with explicit availability. Cached metadata can remain
|
|
browsable, but the interface does not pretend that unavailable bytes are local.
|
|
|
|
## Observability
|
|
|
|
Status and logs expose:
|
|
|
|
- peer identity and connection state;
|
|
- direct or relayed path;
|
|
- protocol version;
|
|
- bytes and active streams;
|
|
- reconnect attempts;
|
|
- rejected authorization;
|
|
- source and job context.
|
|
|
|
Logs must not contain pairing secrets, bearer credentials, or signed provider
|
|
URLs.
|
|
|
|
## Related systems
|
|
|
|
- [Device Pairing](/core/pairing)
|
|
- [Library Sync](/core/library-sync)
|
|
- [API](/core/api)
|
|
- [Devices](/core/devices)
|