remote

Documentation

Overview

Package remote abstracts the cloud object store a volume syncs through. beardrive is provider-agnostic: any backend that can put/get/list immutable objects works. Built-in schemes:

file:///abs/path      local or network-drive directory (also used in tests)
s3://bucket/prefix    Amazon S3 (or S3-compatible via AWS_ENDPOINT_URL)
gs://bucket/prefix    Google Cloud Storage
https://host:4173     a bdrive web server brokering one of the above —
                      the device needs no storage credentials at all

Remote layout: blobs/<sha256> for content, journal/<device>.jsonl for op logs. Each device writes only its own journal, so there are no concurrent writers per object and no server-side coordination is needed.

Index

• type Backend
  • func Open(ctx context.Context, raw string) (Backend, error)
  • func Prefixed(be Backend, prefix string) Backend
• type Object
• type PutSigner
• type ReadEvent
• type ReadReporter
• type SignedPut

Types

type Backend

type Backend interface {
	Put(ctx context.Context, key string, r io.Reader, size int64) error
	Get(ctx context.Context, key string) (io.ReadCloser, error)
	List(ctx context.Context, prefix string) ([]Object, error)
	Exists(ctx context.Context, key string) (bool, error)
	Close() error
}

func Open

func Open(ctx context.Context, raw string) (Backend, error)

Open creates a backend from a remote URL.

func Prefixed

func Prefixed(be Backend, prefix string) Backend

Prefixed namespaces a backend under prefix: every key is stored at <prefix>/<key>. Used by the web server to host many projects in one storage root. Closing the returned backend does not close the underlying one (it is shared across prefixes).

type Object

type Object struct {
	Key  string
	Size int64
}

type PutSigner

type PutSigner interface {
	SignPut(ctx context.Context, key string, size int64, ttl time.Duration) (*SignedPut, error)
}

PutSigner is implemented by backends that can mint presigned upload URLs so clients write to storage directly. Backends without that capability (file://) simply don't implement it, and callers fall back to uploading through the server.

type ReadEvent

type ReadEvent struct {
	Path string    `json:"path"`
	Time time.Time `json:"time,omitzero"`
}

ReadEvent is one agent file read reported to the hub for its read heatmap.

type ReadReporter

type ReadReporter interface {
	ReportReads(ctx context.Context, reads []ReadEvent) error
}

ReadReporter is the optional read-telemetry capability, in the PutSigner mold: backends that sync through a hub report the device's agent reads so the heat view can split human from agent traffic. Object-store backends simply don't implement it — there is no hub to tell.

type SignedPut

type SignedPut struct {
	URL     string            // upload here
	Method  string            // always "PUT"
	Headers map[string]string // headers that must be sent verbatim (they are signed)
	Expires time.Time
}

SignedPut is a presigned direct-upload request: whoever holds the URL can PUT that one object until Expires, without ever seeing storage credentials.