ssh

package
v0.1.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 4, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Overview

Package ssh provides pinned-host connections to the runner's private management plane.

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalid        = errors.New("invalid_remote_connection")
	ErrConnection     = errors.New("remote_connection_failed")
	ErrAuthentication = errors.New("remote_authentication_failed")
	ErrHostUnverified = errors.New("remote_host_key_confirmation_required")
	ErrHostChanged    = errors.New("remote_host_key_changed")
	ErrTransfer       = errors.New("remote_file_transfer_failed")
	ErrIntegrity      = errors.New("remote_file_integrity_failed")
	ErrExists         = errors.New("remote_file_already_exists")
	ErrUnsupported    = errors.New("remote_operation_unsupported")
)
View Source 
var (
	ErrUpgradePending             = errors.New("remote_runner_upgrade_pending")
	ErrUpgradeArtifactUnavailable = errors.New("remote_runner_upgrade_artifact_unavailable")
)

Functions

func BootstrapDirectory 

func BootstrapDirectory(operationID string) string

BootstrapDirectory identifies the only staging path owned by an installation operation. Persist it before any remote mutation, including directory creation.

func UpgradeDirectory 

func UpgradeDirectory(operationID string) string

UpgradeDirectory is persisted by the caller before the first remote mutation.

func ValidBootstrapDirectory 

func ValidBootstrapDirectory(name string) bool

Types

type Artifact 

type Artifact struct {
	OS     string
	Arch   string
	Size   int64
	SHA256 string
	Source io.Reader
}

type Authentication 

type Authentication struct {
	// contains filtered or unexported fields
}

func PasswordAuthentication 

func PasswordAuthentication(password *credentials.Lease) Authentication

func PrivateKeyAuthentication 

func PrivateKeyAuthentication(key, passphrase *credentials.Lease) Authentication

func (Authentication) GoString 

func (Authentication) GoString() string

func (Authentication) MarshalJSON 

func (Authentication) MarshalJSON() ([]byte, error)

func (Authentication) String 

func (Authentication) String() string

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func Dial 

func Dial(ctx context.Context, endpoint Endpoint, authentication Authentication) (*Client, error)

Dial does not own the supplied leases. Empty pins return the observed key for explicit confirmation before authentication; changed pins always fail closed. The connection is independent of ctx once its handshake has completed.

func (*Client) CleanupBootstrap 

func (client *Client) CleanupBootstrap(ctx context.Context, directory string) error

CleanupBootstrap removes only a reported installer staging directory. An SSH loss may leave a partial upload; validate its entire bounded namespace before removing anything. The canonical installation and operation journal are kept.

func (*Client) Close 

func (client *Client) Close() error

func (*Client) ConnectBoundNode 

func (client *Client) ConnectBoundNode(
	ctx context.Context,
	identity runnerinstall.Identity,
	token *credentials.Lease,
) (*Node, jobcontract.RunnerInfo, error)

ConnectBoundNode uses the desktop's saved node-level authorization and exact installation identity. It never reads or silently replaces server pairing.

func (*Client) ConnectNode 

func (client *Client) ConnectNode(ctx context.Context) (*Node, jobcontract.RunnerInfo, error)

ConnectNode reuses the server's shared pairing without changing configuration, restarting its service, uploading an artifact, or comparing client builds.

func (*Client) GoString 

func (*Client) GoString() string

func (*Client) InstallationOperation 

func (client *Client) InstallationOperation(ctx context.Context, id string) (runnerinstall.Operation, error)

InstallationOperation resolves an uncertain SSH acknowledgment through the server's atomic journal. It does not restart or resubmit the operation.

func (*Client) Probe 

func (client *Client) Probe(ctx context.Context) (SystemInfo, error)

Probe executes a fixed read-only script; no endpoint or user-supplied text is interpolated into the remote command. Unsupported systems retain their facts.

func (*Client) Provision 

func (client *Client) Provision(
	ctx context.Context,
	request runnerinstall.Request,
	artifact Artifact,
	progress func(runnerinstall.Progress),
) (result runnerinstall.Result, runErr error)

Provision uploads a verified Linux program and invokes its fixed installer. Retries must retain request.OperationID and the original artifact. The durable receipt describes that operation; ConnectNode separately obtains live health.

func (*Client) ReadPrivate 

func (client *Client) ReadPrivate(ctx context.Context, name string, owner uint32) ([]byte, error)

ReadPrivate is used for the root-owned pairing secret, never for a general remote file browser. The caller must clear its returned bytes after use.

func (*Client) RecoverUpgrade 

func (client *Client) RecoverUpgrade(
	ctx context.Context,
	request runnerinstall.UpgradeRequest,
	artifact Artifact,
	progress func(runnerinstall.UpgradeProgress),
) (runnerinstall.UpgradeOperation, error)

RecoverUpgrade uses the durable operation's safety boundary. For explicit retry or recovery only, a nil artifact Source permits verified staged reuse; OS, Arch and SHA256 still identify the original release.

func (*Client) RetryUpgrade 

func (client *Client) RetryUpgrade(
	ctx context.Context,
	request runnerinstall.UpgradeRequest,
	artifact Artifact,
	progress func(runnerinstall.UpgradeProgress),
) (runnerinstall.UpgradeOperation, error)

func (*Client) RunnerHTTP 

func (client *Client) RunnerHTTP(port uint16) (*http.Client, error)

RunnerHTTP opens one endpoint owner, using SSH direct-tcpip to one loopback port. It creates no local listener and never uses a proxy or redirects.

func (*Client) String 

func (*Client) String() string

func (*Client) Upgrade 

func (client *Client) Upgrade(
	ctx context.Context,
	request runnerinstall.UpgradeRequest,
	artifact Artifact,
	progress func(runnerinstall.UpgradeProgress),
) (runnerinstall.UpgradeOperation, error)

Upgrade starts one explicit operation. An existing journal is returned without rerunning it; continuation and recovery require their separate explicit calls.

func (*Client) UpgradeOperation 

func (client *Client) UpgradeOperation(ctx context.Context, id string) (runnerinstall.UpgradeOperation, error)

UpgradeOperation reads only the fixed, root-owned atomic operation journal. In particular, a missing journal is not permission to launch another operation.

func (*Client) UploadNew 

func (client *Client) UploadNew(ctx context.Context, upload Upload) error

UploadNew validates both the transmitted bytes and a separate SFTP readback. It never overwrites a destination. The installer owns directory creation, installation locking, directory durability and activation of the uploaded file.

type Endpoint 

type Endpoint struct {
	Host        string
	Port        uint16
	User        string
	Fingerprint string
	HostKeyType string
}

func (Endpoint) Validate 

func (endpoint Endpoint) Validate() error

type HostKeyError 

type HostKeyError struct {
	Fingerprint string
	KeyType     string
	Changed     bool
}

func (*HostKeyError) Error 

func (err *HostKeyError) Error() string

func (*HostKeyError) Unwrap 

func (err *HostKeyError) Unwrap() error

type Node 

type Node struct {
	// contains filtered or unexported fields
}

Node owns a temporary node-token lease and an HTTP pool, not its parent SSH connection or accepted jobs. Close releases only these client-side resources.

func (*Node) Close 

func (node *Node) Close() error

func (*Node) Do 

func (node *Node) Do(ctx context.Context, input Request) (*http.Response, error)

Do sends only relative management routes through this node's pinned tunnel. Callers own request-body secret cleanup and response-body limits and Close.

func (*Node) GoString 

func (*Node) GoString() string

func (*Node) Identity 

func (node *Node) Identity() runnerinstall.Identity

func (*Node) Info 

func (node *Node) Info(ctx context.Context) (jobcontract.RunnerInfo, error)

func (*Node) MarshalJSON 

func (*Node) MarshalJSON() ([]byte, error)

func (*Node) PairingLease 

func (node *Node) PairingLease() (*credentials.Lease, error)

PairingLease copies the shared credential for the local OS Store. The caller owns this short-lived lease; closing either lease does not close the other.

func (*Node) String 

func (*Node) String() string

type ProvisionError 

type ProvisionError struct {
	OperationID        string
	TemporaryDirectory string
	CleanupPending     bool
	Cause              error
}

func (*ProvisionError) Error 

func (err *ProvisionError) Error() string

func (*ProvisionError) Unwrap 

func (err *ProvisionError) Unwrap() error

type Request 

type Request struct {
	Method     string
	Route      string
	Body       io.Reader
	Content    *jobcontract.ContentIdentity
	RangeStart *int64
	JSONGzip   bool
}

type SystemInfo 

type SystemInfo struct {
	UID            uint32 `json:"uid"`
	OS             string `json:"os"`
	Arch           string `json:"arch"`
	SystemdVersion uint32 `json:"systemd_version"`
	SystemdPID1    bool   `json:"systemd_pid1"`
	HasSHA256      bool   `json:"has_sha256"`
	HasRunuser     bool   `json:"has_runuser"`
	HasSudo        bool   `json:"has_sudo"`
}

type UpgradeError 

type UpgradeError struct {
	OperationID        string
	TemporaryDirectory string
	Pending            bool
	Cause              error
}

UpgradeError retains the operation's identity when the remote outcome cannot be observed. Its staging directory is retained; disconnecting never rolls back the installation or stops its detached service.

func (*UpgradeError) Error 

func (*UpgradeError) Error() string

func (*UpgradeError) GoString 

func (*UpgradeError) GoString() string

func (*UpgradeError) MarshalJSON 

func (*UpgradeError) MarshalJSON() ([]byte, error)

func (*UpgradeError) Unwrap 

func (err *UpgradeError) Unwrap() error

type Upload 

type Upload struct {
	Path   string
	Size   int64
	SHA256 string
	Mode   os.FileMode
	Source io.Reader
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.