mirror of
https://github.com/spacedriveapp/spacedrive.git
synced 2026-11-02 05:20:29 -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.
129 lines
3.6 KiB
Plaintext
129 lines
3.6 KiB
Plaintext
---
|
|
title: Unified Addressing
|
|
description: Locators for physical paths, providers, content, and sidecars
|
|
sidebarTitle: Addressing
|
|
---
|
|
|
|
Spacedrive operations accept a common path value for local files, cloud
|
|
objects, content identity, and derived sidecars. An address tells an operation
|
|
what to resolve now. Durable source and record identity remain separate.
|
|
|
|
## Address forms
|
|
|
|
### Physical
|
|
|
|
~~~text
|
|
local://jamies-macbook/Users/james/Documents/report.pdf
|
|
~~~
|
|
|
|
A physical address names a device and operating-system path. It is useful for a
|
|
direct local or remote operation, but mount paths can change.
|
|
|
|
### Cloud
|
|
|
|
~~~text
|
|
s3://my-bucket/photos/2026/vacation.jpg
|
|
~~~
|
|
|
|
A cloud address names a provider scheme, provider identifier, and native path.
|
|
Credentials and account selection come from the authorized source, not from the
|
|
URI.
|
|
|
|
### Content
|
|
|
|
~~~text
|
|
content://550e8400-e29b-41d4-a716-446655440000
|
|
~~~
|
|
|
|
A content address asks Spacedrive to resolve an instance of known bytes. The
|
|
resolver considers confirmation strength, availability, permissions, and
|
|
policy. It does not promise which physical copy will answer.
|
|
|
|
### Sidecar
|
|
|
|
~~~text
|
|
sidecar://550e8400-e29b-41d4-a716-446655440000/thumbs/grid@2x.webp
|
|
~~~
|
|
|
|
A sidecar address names a deterministic derivative by content, kind, variant,
|
|
and format.
|
|
|
|
## SdPath
|
|
|
|
The Rust wire type represents these forms:
|
|
|
|
~~~rust
|
|
pub enum SdPath {
|
|
Physical { device_slug: String, path: PathBuf },
|
|
Cloud { service: CloudServiceType, identifier: String, path: String },
|
|
Content { content_id: Uuid },
|
|
Sidecar {
|
|
content_id: Uuid,
|
|
kind: SidecarKind,
|
|
variant: SidecarVariant,
|
|
format: SidecarFormat,
|
|
},
|
|
}
|
|
~~~
|
|
|
|
Plain operating-system paths parse as physical paths on the current device.
|
|
Clients should preserve the structured value when possible instead of
|
|
round-tripping through display text.
|
|
|
|
## Durable references
|
|
|
|
A path is not durable identity. Persisted relationships use:
|
|
|
|
- source UUID;
|
|
- record UUID;
|
|
- source-relative path as a resolvable hint;
|
|
- content UUID for byte equality;
|
|
- sidecar key for a derivative.
|
|
|
|
This distinction lets a drive remount elsewhere, a file move, or a source
|
|
authority transfer without breaking tags and provenance.
|
|
|
|
## Resolution
|
|
|
|
Resolution is explicit and fallible:
|
|
|
|
1. Authenticate the request context.
|
|
2. Resolve device, source, provider, or content identity.
|
|
3. Check current availability and granted scope.
|
|
4. Validate version evidence where a mutation is planned.
|
|
5. Select a byte provider or writable origin.
|
|
|
|
An address can therefore be valid but unavailable. Clients should distinguish
|
|
not found, offline, denied, stale, and ambiguous.
|
|
|
|
## Content selection
|
|
|
|
Several records can share one content identity. A content-addressed read chooses
|
|
an instance that:
|
|
|
|
- has confirmed evidence when policy requires it;
|
|
- is online or cached;
|
|
- is permitted for the caller;
|
|
- satisfies requested range and format capabilities;
|
|
- avoids unnecessary network or provider cost.
|
|
|
|
Destructive operations still target exact source records. A content URI alone
|
|
is too broad for deletion.
|
|
|
|
## Batches
|
|
|
|
File actions accept batches of addresses for copy, move, delete, and share
|
|
workflows. Validation reports errors per item so one unavailable path does not
|
|
hide the rest of the plan.
|
|
|
|
## Display
|
|
|
|
The interface may show a friendly path, source name, or device label. Copying an
|
|
address should retain an unambiguous machine-readable form.
|
|
|
|
Never expose provider credentials, bearer tokens, or signed download URLs as
|
|
durable Spacedrive addresses.
|
|
|
|
See [Data Model](/core/data-model) for identity and [File Copy
|
|
Operations](/core/file-copy-operations) for resolution during mutation.
|