remote

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(ctx context.Context, raw string) (Backend, error)

func Prefixed(be Backend, prefix string) Backend

type ConditionalPutter ¶ added in v0.16.1

type ConditionalPutter interface {
	// GetVersioned reads an object and reports the version it was at, so a
	// later PutIf can say "only if this has not moved".
	GetVersioned(ctx context.Context, key string) (io.ReadCloser, Version, error)
	// PutIf writes only if the object is still at expect, and reports the
	// version it wrote. ErrVersionMismatch means somebody else got there.
	PutIf(ctx context.Context, key string, r io.Reader, size int64, expect Version) (Version, error)
}

ConditionalPutter is the optional compare-and-swap capability, in the

PutSigner and Watcher mold: a backend that cannot do it simply does not
implement it, and callers keep exactly the behaviour they had.

It exists because a journal append is a READ-MODIFY-WRITE of one object,
and Put is last-writer-wins. Inside one process a mutex is enough and that
is what the hub has always used. Across two it is not: both read the same
journal, both append their own ops, and whichever writes second silently
erases the other's — no error anywhere, because both writes succeeded. That
is the lost update the "each device writes only its own journal" invariant
has always prevented BETWEEN devices, reappearing inside one device id the
moment the hub runs more than once (docs/hub-load-prd.md Stage 10).

Implemented for GCS, which is what the managed hub stores in. Not for S3
(conditional PutObject is recent and unevenly supported), not for file://
(a rename is atomic but a compare-and-swap across processes is not, and
inventing one would be a worse lie than not offering the capability), and
not for the https:// client — that one talks to a hub, and the hub is the
process doing the conditional write.

type Object ¶

type Object struct {
	Key  string
	Size int64
	// Modified is when the store last wrote this object, when the backend
	// reports it (S3, GCS) and the zero time when it does not. It is how the
	// hub decides an object can no longer change — see RemoteSource.verify.
	Modified time.Time
}

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 ¶ added in v0.4.0

type ReadEvent struct {
	Path string `json:"path"`
	// Session is the agent session the read happened in, so the hub can join
	// a run's reads to the writes journal.Op.Session carries. A client string
	// — the hub pins each recorded row to the device it validated, never to
	// anything in this body (see handleReadReport).
	Session string    `json:"session,omitempty"`
	Time    time.Time `json:"time,omitzero"`
}

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

type ReadReporter ¶ added in v0.4.0

type ReadReporter interface {
	// ReportReads sends queued reads. kind is "" or "agent" for device
	// traffic (the actor is this device) and "human" for a person reading in
	// a viewer (the actor is the signed-in account, resolved by the hub).
	ReportReads(ctx context.Context, kind string, reads []ReadEvent) error
}

type Scope ¶ added in v0.16.0

type Scope struct {
	// Tag identifies this account's current visibility. It changes whenever
	// what this account can see does, and only then.
	Tag string `json:"scope"`
	// ReadOnly are slash-terminated prefixes this device may sync down but
	// must never journal a change to.
	ReadOnly []string `json:"readonly"`
	// Deny are slash-terminated prefixes this account may not read at all.
	// The hub sends no ops for them, so nothing materializes there; this list
	// exists so the device also never JOURNALS anything a local file at such a
	// path would otherwise produce — which the hub would refuse, wedging the
	// device's whole journal. See the note on handleProjectScope for the
	// disclosure this represents and why there is no alternative.
	Deny []string `json:"deny"`
}

Scope is what one account may do inside one project, as the hub sees it. Only ReadOnly is carried: a prefix the caller may not READ at all is deliberately not reported, because naming it would hand every member of a project the name of every hidden folder. See docs/folder-permissions-prd.md.

type Scoper ¶ added in v0.16.0

type Scoper interface {
	Scope(ctx context.Context) (Scope, error)
}

Scoper is the optional "what may I write here?" capability, in the PutSigner mold. A hub knows about folder permissions; a raw object store has no account to answer for, so the object-store backends simply do not implement it and nothing is restricted — which is right, since a device talking straight to a bucket already holds credentials for all of it.

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.

type Version ¶ added in v0.16.1

type Version string

Version identifies one stored revision of an object.

Opaque on purpose: a GCS generation, an S3 ETag and a file backend's
fingerprint have nothing in common but equality, and the moment anything
parses one it has made a promise the next backend cannot keep. Only ever
compared, never inspected.

const VersionAbsent Version = ""

type Watcher ¶ added in v0.16.0

type Watcher interface {
	Watch(ctx context.Context) (<-chan struct{}, error)
}

Watcher is the optional change-notification capability, in the PutSigner mold: a hub can tell a device that a peer pushed, so the daemon syncs on the news instead of waiting out its remote interval. Object-store backends simply don't implement it — a bucket has nobody to do the telling, and the daemon keeps polling exactly as it does today.

The channel carries no payload on purpose. The only question the daemon asks is "is it worth talking to the remote now", and the answer to a burst of changes is one cycle, not one per change — so an implementation coalesces and the daemon can never fall behind the stream. A closed channel means the notification path is gone (hub down, connection dropped, an older hub with no such route): callers fall back to polling and may re-dial. It is an accelerator, never a correctness input — nothing may depend on a signal arriving, because for most backends none ever will.