connection

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Jan 5, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Overview

Package connection provides an abstraction for local and remote operations. This allows Gas Town to manage rigs on remote machines via SSH using the same interface as local operations.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Address 

type Address struct {
	Machine string // Machine name (empty = local)
	Rig     string // Rig name (required)
	Polecat string // Polecat name (empty = broadcast to rig)
}

Address represents a parsed agent or rig address. Format: [machine:]rig[/polecat]

Examples:

  • "gastown/rictus" -> local machine, gastown rig, rictus polecat
  • "vm:gastown/rictus" -> vm machine, gastown rig, rictus polecat
  • "gastown/" -> local machine, gastown rig, broadcast
  • "vm:gastown/" -> vm machine, gastown rig, broadcast

func MustParseAddress 

func MustParseAddress(s string) *Address

MustParseAddress parses an address and panics on error. Only use for known-good addresses (e.g., constants).

func ParseAddress 

func ParseAddress(s string) (*Address, error)

ParseAddress parses an address string into its components. Valid formats:

  • rig/polecat
  • rig/
  • machine:rig/polecat
  • machine:rig/

func (*Address) Equal 

func (a *Address) Equal(other *Address) bool

Equal returns true if two addresses are equivalent.

func (*Address) IsBroadcast 

func (a *Address) IsBroadcast() bool

IsBroadcast returns true if the address targets a rig (no specific polecat).

func (*Address) IsLocal 

func (a *Address) IsLocal() bool

IsLocal returns true if the address targets the local machine.

func (*Address) RigPath 

func (a *Address) RigPath() string

RigPath returns the rig/polecat portion without machine prefix.

func (*Address) String 

func (a *Address) String() string

String returns the address in canonical form.

func (*Address) Validate 

func (a *Address) Validate(registry *MachineRegistry) error

Validate checks if the address is valid against the registry. Returns nil if valid, otherwise an error describing the issue.

type BasicFileInfo 

type BasicFileInfo struct {
	FileName    string      `json:"name"`
	FileSize    int64       `json:"size"`
	FileMode    fs.FileMode `json:"mode"`
	FileModTime time.Time   `json:"mod_time"`
	FileIsDir   bool        `json:"is_dir"`
}

BasicFileInfo is a simple implementation of FileInfo.

func FromOSFileInfo 

func FromOSFileInfo(fi fs.FileInfo) BasicFileInfo

FromOSFileInfo creates a BasicFileInfo from an os.FileInfo.

func (BasicFileInfo) IsDir 

func (f BasicFileInfo) IsDir() bool

IsDir implements FileInfo.

func (BasicFileInfo) ModTime 

func (f BasicFileInfo) ModTime() time.Time

ModTime implements FileInfo.

func (BasicFileInfo) Mode 

func (f BasicFileInfo) Mode() fs.FileMode

Mode implements FileInfo.

func (BasicFileInfo) Name 

func (f BasicFileInfo) Name() string

Name implements FileInfo.

func (BasicFileInfo) Size 

func (f BasicFileInfo) Size() int64

Size implements FileInfo.

type Connection 

type Connection interface {

	// Name returns a human-readable name for this connection.
	Name() string

	// IsLocal returns true if this is a local connection.
	IsLocal() bool

	// ReadFile reads the named file and returns its contents.
	ReadFile(path string) ([]byte, error)

	// WriteFile writes data to the named file with the given permissions.
	WriteFile(path string, data []byte, perm fs.FileMode) error

	// MkdirAll creates a directory and all parent directories.
	MkdirAll(path string, perm fs.FileMode) error

	// Remove removes the named file or empty directory.
	Remove(path string) error

	// RemoveAll removes the named file or directory and any children.
	RemoveAll(path string) error

	// Stat returns file info for the named file.
	Stat(path string) (FileInfo, error)

	// Glob returns the names of all files matching the pattern.
	Glob(pattern string) ([]string, error)

	// Exists returns true if the path exists.
	Exists(path string) (bool, error)

	// Exec runs a command and returns its combined output.
	Exec(cmd string, args ...string) ([]byte, error)

	// ExecDir runs a command in the specified directory.
	ExecDir(dir, cmd string, args ...string) ([]byte, error)

	// ExecEnv runs a command with additional environment variables.
	ExecEnv(env map[string]string, cmd string, args ...string) ([]byte, error)

	// TmuxNewSession creates a new tmux session with the given name.
	TmuxNewSession(name, dir string) error

	// TmuxKillSession terminates the named tmux session.
	TmuxKillSession(name string) error

	// TmuxSendKeys sends keys to the named tmux session.
	TmuxSendKeys(session, keys string) error

	// TmuxCapturePane captures the last N lines from a tmux pane.
	TmuxCapturePane(session string, lines int) (string, error)

	// TmuxHasSession returns true if the named tmux session exists.
	TmuxHasSession(name string) (bool, error)

	// TmuxListSessions returns a list of all tmux session names.
	TmuxListSessions() ([]string, error)
}

Connection abstracts file operations, command execution, and tmux management for both local and remote (SSH) execution contexts.

type ConnectionError 

type ConnectionError struct {
	Op      string // Operation that failed (e.g., "connect", "exec")
	Machine string // Machine name or address
	Err     error  // Underlying error
}

ConnectionError indicates a connection-level failure.

func (*ConnectionError) Error 

func (e *ConnectionError) Error() string

func (*ConnectionError) Unwrap 

func (e *ConnectionError) Unwrap() error

type FileInfo 

type FileInfo interface {
	// Name returns the base name of the file.
	Name() string

	// Size returns the length in bytes.
	Size() int64

	// Mode returns the file mode bits.
	Mode() fs.FileMode

	// ModTime returns the modification time.
	ModTime() time.Time

	// IsDir returns true if this is a directory.
	IsDir() bool
}

FileInfo abstracts fs.FileInfo for use over remote connections. This is needed because fs.FileInfo contains methods that can't be easily serialized over SSH.

type LocalConnection 

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

LocalConnection implements Connection for local file and command operations.

func NewLocalConnection 

func NewLocalConnection() *LocalConnection

NewLocalConnection creates a new local connection.

func (*LocalConnection) Exec 

func (c *LocalConnection) Exec(cmd string, args ...string) ([]byte, error)

Exec runs a command and returns its combined output.

func (*LocalConnection) ExecDir 

func (c *LocalConnection) ExecDir(dir, cmd string, args ...string) ([]byte, error)

ExecDir runs a command in the specified directory.

func (*LocalConnection) ExecEnv 

func (c *LocalConnection) ExecEnv(env map[string]string, cmd string, args ...string) ([]byte, error)

ExecEnv runs a command with additional environment variables.

func (*LocalConnection) Exists 

func (c *LocalConnection) Exists(path string) (bool, error)

Exists returns true if the path exists.

func (*LocalConnection) Glob 

func (c *LocalConnection) Glob(pattern string) ([]string, error)

Glob returns the names of all files matching the pattern.

func (*LocalConnection) IsLocal 

func (c *LocalConnection) IsLocal() bool

IsLocal returns true for local connections.

func (*LocalConnection) MkdirAll 

func (c *LocalConnection) MkdirAll(path string, perm fs.FileMode) error

MkdirAll creates a directory and all parent directories.

func (*LocalConnection) Name 

func (c *LocalConnection) Name() string

Name returns "local" for local connections.

func (*LocalConnection) ReadFile 

func (c *LocalConnection) ReadFile(path string) ([]byte, error)

ReadFile reads the named file.

func (*LocalConnection) Remove 

func (c *LocalConnection) Remove(path string) error

Remove removes the named file or empty directory.

func (*LocalConnection) RemoveAll 

func (c *LocalConnection) RemoveAll(path string) error

RemoveAll removes the named file or directory and any children.

func (*LocalConnection) Stat 

func (c *LocalConnection) Stat(path string) (FileInfo, error)

Stat returns file info for the named file.

func (*LocalConnection) TmuxCapturePane 

func (c *LocalConnection) TmuxCapturePane(session string, lines int) (string, error)

TmuxCapturePane captures the last N lines from a tmux pane.

func (*LocalConnection) TmuxHasSession 

func (c *LocalConnection) TmuxHasSession(name string) (bool, error)

TmuxHasSession returns true if the session exists.

func (*LocalConnection) TmuxKillSession 

func (c *LocalConnection) TmuxKillSession(name string) error

TmuxKillSession terminates a tmux session.

func (*LocalConnection) TmuxListSessions 

func (c *LocalConnection) TmuxListSessions() ([]string, error)

TmuxListSessions returns all tmux session names.

func (*LocalConnection) TmuxNewSession 

func (c *LocalConnection) TmuxNewSession(name, dir string) error

TmuxNewSession creates a new tmux session.

func (*LocalConnection) TmuxSendKeys 

func (c *LocalConnection) TmuxSendKeys(session, keys string) error

TmuxSendKeys sends keys to a tmux session.

func (*LocalConnection) WriteFile 

func (c *LocalConnection) WriteFile(path string, data []byte, perm fs.FileMode) error

WriteFile writes data to the named file.

type Machine 

type Machine struct {
	Name     string `json:"name"`
	Type     string `json:"type"`      // "local", "ssh"
	Host     string `json:"host"`      // for ssh: user@host
	KeyPath  string `json:"key_path"`  // SSH private key path
	TownPath string `json:"town_path"` // Path to town root on remote
}

Machine represents a managed machine in the federation.

type MachineRegistry 

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

MachineRegistry manages machine configurations and provides Connection instances.

func NewMachineRegistry 

func NewMachineRegistry(configPath string) (*MachineRegistry, error)

NewMachineRegistry creates a registry from the given config file path. If the file doesn't exist, an empty registry is created.

func (*MachineRegistry) Add 

func (r *MachineRegistry) Add(m *Machine) error

Add adds or updates a machine in the registry.

func (*MachineRegistry) Connection 

func (r *MachineRegistry) Connection(name string) (Connection, error)

Connection returns a Connection for the named machine.

func (*MachineRegistry) Get 

func (r *MachineRegistry) Get(name string) (*Machine, error)

Get returns a machine by name.

func (*MachineRegistry) List 

func (r *MachineRegistry) List() []*Machine

List returns all machines in the registry.

func (*MachineRegistry) LocalConnection 

func (r *MachineRegistry) LocalConnection() *LocalConnection

LocalConnection returns the local connection. This is a convenience method for the common case.

func (*MachineRegistry) Remove 

func (r *MachineRegistry) Remove(name string) error

Remove removes a machine from the registry.

type NotFoundError 

type NotFoundError struct {
	Path string
}

NotFoundError indicates a file or resource was not found.

func (*NotFoundError) Error 

func (e *NotFoundError) Error() string

type PermissionError 

type PermissionError struct {
	Path string
	Op   string
}

PermissionError indicates an access permission failure.

func (*PermissionError) Error 

func (e *PermissionError) Error() string

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.