Documentation
¶
Overview ¶
Package remote is a Runtime backend for a harness somebody else is already running.
Every other backend provisions the compute it hands back: runtime/local starts the harness in process, runtime/substrate creates an actor. That makes a harness a build-time decision, because the binary has to import it. This one provisions nothing. It is given an address where a harness is already listening and returns an incarnation pointing at it, so a harness can be registered by configuration instead of by recompiling the server.
The harness self-describes: Describe dials it and asks, so placement gates on the tier the harness actually declares rather than on anything configured here. The answer is live, not pinned: if a different harness starts answering at the address, the next Exec, Resume or Fork sees it. Because an address can front more than one process (replicas behind a load balancer, or a harness restarted between two calls), the backend implements placement.LiveDescriber: the Placer asks again on the connection that runs the turn and refuses it there, before journaling, if that harness cannot be placed. That check is not bound to the turn's Connect stream, so a harness that takes over the address between the two calls is not detected (see placement's recheck). Describe itself is bounded by the Placer, so a harness that accepts the connection and never answers is reported as unavailable rather than holding the call.
Capabilities report MemorySnapshot=false, and that is not a limitation to be lifted later. This backend does not own the process it points at, so it cannot capture its memory. A harness that declares REQUIRES_MEMORY_SNAPSHOT is therefore refused by the Placer's CanPlace gate on Exec, Resume and Fork before any compute is touched or anything is journaled, which is the correct answer rather than a degraded one: run that harness on a backend that owns the sandbox.
Addresses are host:port (dialed over cleartext h2c) or a unix socket. unix:///abs/path and unix://rel/path are dialed the same way placement's default dialer does, so the address that passes Describe is the address the Placer runs turns on; any other form, such as unix:path or a dns:/// target, is handed to gRPC's resolver unchanged.
Index ¶
- type Backend
- func (b *Backend) Capabilities() api.RuntimeCapabilities
- func (b *Backend) Close() error
- func (b *Backend) Create(ctx context.Context, s *api.SessionSpec) (inc api.Incarnation, err error)
- func (b *Backend) Describe(ctx context.Context) (desc api.Descriptor, err error)
- func (b *Backend) DescribesLiveHarness() bool
- func (b *Backend) Fork(ctx context.Context, ref api.SnapshotRef, opts api.ForkOpts) (inc api.Incarnation, err error)
- func (b *Backend) Restore(ctx context.Context, ref api.SnapshotRef) (inc api.Incarnation, err error)
- func (b *Backend) Snapshot(ctx context.Context, in api.Incarnation, kind api.SnapshotKind) (ref api.SnapshotRef, err error)
- func (b *Backend) Status(ctx context.Context, in api.Incarnation) (api.ComputeState, error)
- func (b *Backend) Stop(ctx context.Context, in api.Incarnation) error
- type Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Backend ¶
type Backend struct {
// contains filtered or unexported fields
}
Backend attaches sessions to a harness reachable at a fixed address.
func (*Backend) Capabilities ¶
func (b *Backend) Capabilities() api.RuntimeCapabilities
Capabilities reports a backend that owns no sandbox: no memory snapshot, CoW fork, attestation, or GPU state. See the package comment for why MemorySnapshot=false is structural here.
func (*Backend) Close ¶
Close releases the connection to the harness. The harness itself is not ours to stop. A closed backend stays closed: a later Describe fails rather than opening a connection nobody will close.
func (*Backend) Create ¶
func (b *Backend) Create(ctx context.Context, s *api.SessionSpec) (inc api.Incarnation, err error)
Create hands back an incarnation pointing at the configured address. Nothing is provisioned: the harness is already running, which is the whole point of this backend.
func (*Backend) Describe ¶
Describe asks the harness what it is, so placement gates on the harness's own declaration rather than on a tier assumed by configuration.
func (*Backend) DescribesLiveHarness ¶
DescribesLiveHarness reports that Describe asks whichever harness answers at the address, so the Placer re-checks the harness on the connection that runs each turn (placement.LiveDescriber).
func (*Backend) Fork ¶
func (b *Backend) Fork(ctx context.Context, ref api.SnapshotRef, opts api.ForkOpts) (inc api.Incarnation, err error)
Fork is a replay-fork: the child attaches to the same harness and its copied log prefix is replayed into it. There is no clone-from-memory path without owning the sandbox.
func (*Backend) Restore ¶
func (b *Backend) Restore(ctx context.Context, ref api.SnapshotRef) (inc api.Incarnation, err error)
Restore re-attaches to the same harness. Harness-visible state is reconstructed by the host replaying the journal, which is what STATELESS_REPLAY means.
func (*Backend) Snapshot ¶
func (b *Backend) Snapshot(ctx context.Context, in api.Incarnation, kind api.SnapshotKind) (ref api.SnapshotRef, err error)
Snapshot names the session so Restore can re-attach. Memory=false: this backend does not own the harness process and cannot capture its memory.
func (*Backend) Status ¶
func (b *Backend) Status(ctx context.Context, in api.Incarnation) (api.ComputeState, error)
Status reports the compute-lifecycle state. The log and the placement layer are the lifecycle authority, so a known incarnation is LIVE.
Source Files