bootstrap

Documentation

Overview

Package bootstrap installs the ptyrelay-agent binary on the remote.

The flow is:

1. Detect the remote OS + architecture via `uname -sm` over a ShellBackend.
2. Look up the matching agent binary from a Provider.
3. Choose an install path (XDG-aware, $HOME-rooted by default).
4. ShellBackend.Write the binary atomically (tempfile + sha256 + rename) with mode 0755.
5. Probe the freshly-installed agent to confirm it answers.

On success, Bootstrap returns the install path; AgentBackend.New can then be called against that path.

Index

• Variables
• func Bootstrap(ctx context.Context, sb *shell.Backend, opts Options) (string, error)
• func VerifyInstall(ctx context.Context, sb *shell.Backend, agentPath string) error
• type EmbedProvider
  • func (p *EmbedProvider) Get(osName, arch string) ([]byte, error)
• type FileProvider
  • func (p *FileProvider) Get(osName, arch string) ([]byte, error)
• type Options
• type Provider

Variables

var ErrUnsupportedTarget = errors.New("bootstrap: unsupported target")

ErrUnsupportedTarget is returned by Provider.Get when no binary is available for the requested platform.

Functions

func Bootstrap

func Bootstrap(ctx context.Context, sb *shell.Backend, opts Options) (string, error)

Bootstrap installs the agent and returns the absolute path it was written to.

Path selection:

• opts.FromURL != nil → remote curl/wget directly to the install path. Best when the remote has outbound network.
• opts.Provider != nil → local bytes uploaded via ShellBackend.Write. Best when the remote is air-gapped.

func VerifyInstall

func VerifyInstall(ctx context.Context, sb *shell.Backend, agentPath string) error

VerifyInstall calls ping on a freshly-installed agent to confirm the binary actually works on the remote (right architecture, executable, not silently truncated).

Types

type EmbedProvider

type EmbedProvider struct {
	FS   embed.FS
	Root string // subdir within FS, e.g. "agents"
}

EmbedProvider reads agent binaries out of an embed.FS rooted at `agents/<os>-<arch>`. Production CLIs declare:

//go:embed agents/*
var agents embed.FS
provider := &bootstrap.EmbedProvider{FS: agents, Root: "agents"}

func (*EmbedProvider) Get

func (p *EmbedProvider) Get(osName, arch string) ([]byte, error)

Get implements Provider.

type FileProvider

type FileProvider struct {
	Dir string
}

FileProvider reads agent binaries from a local directory laid out as `<dir>/<os>-<arch>` (e.g. `agents/linux-amd64`).

It is the form tests use; production builds prefer EmbedProvider.

func (*FileProvider) Get

func (p *FileProvider) Get(osName, arch string) ([]byte, error)

Get implements Provider.

type Options

type Options struct {
	// Provider supplies the agent binary as bytes the local side then
	// uploads to the remote via ShellBackend.Write. Required when
	// FromURL is nil.
	Provider Provider

	// FromURL, when non-nil, takes precedence over Provider: the
	// remote fetches the binary directly via curl/wget, skipping the
	// (slow) multi-MB local→remote upload. The callback receives the
	// detected (osName, arch) and returns a download URL plus an
	// optional sha256 hex (empty string disables verification).
	//
	// URLs ending in ".gz" are gunzipped on the remote. Requires the
	// remote to have either curl or wget on PATH.
	FromURL func(osName, arch string) (url, sha256 string)

	// InstallPath is the absolute path where the binary should land on
	// the remote. Empty means "$HOME/.local/bin/ptyrelay-agent" — the
	// $HOME is resolved at runtime by the remote shell.
	InstallPath string
}

Options configures Bootstrap.

type Provider

type Provider interface {
	// Get returns the agent bytes for the given GOOS/GOARCH names
	// (e.g. "linux", "amd64"). Returns ErrUnsupportedTarget when the
	// provider has no binary for that combination.
	Get(osName, arch string) ([]byte, error)
}

Provider supplies an agent binary for a target (os, arch) tuple.

Production builds use EmbedProvider over a `//go:embed agents/*` directory; tests inject a FileProvider that reads from disk.