Documentation
¶
Overview ¶
Package env is the remote execution environment of Pi Durable: an agent's tools run on another machine, usually over SSH, while the Durable worker, its storage and credentials stay local.
Ports packages/env/src/index.ts
Go mapping: upstream's Promise-returning methods are blocking calls that take a context.Context first, where upstream passes an AbortSignal. A request whose result is awaited later is a Call, started in call order (frames leave in the order the calls were started, which the daemon's write ordering needs) and awaited with Wait.
Index ¶
- func AcceptHostKey(target SshTarget, lines []string) error
- func ConnectSsh(ctx context.Context, options SshConnectOptions) (*Connection, RemotePlatform, error)
- func DeployDaemon(ctx context.Context, target SshTarget, remote RemotePlatform, ...) (string, error)
- func ForgetHostKey(target SshTarget) error
- func IsConnectionLost(err error) bool
- func LocalDaemon() (string, error)
- func PackagedDaemon(remote RemotePlatform) string
- func ScanHostKey(ctx context.Context, target SshTarget) (lines, fingerprints []string, err error)
- func SshArguments(target SshTarget, options ...SshArgumentsOptions) ([]string, error)
- func SshArgumentsWith(target SshTarget, strictHostKeys bool, knownHostsFile string) ([]string, error)
- type Call
- type Connection
- func (c *Connection) Close()
- func (c *Connection) Info(_ context.Context) (RemoteInfo, error)
- func (c *Connection) Kill(id uint32, sessionID int)
- func (c *Connection) Request(ctx context.Context, op string, request Json, options RequestOptions) (Reply, error)
- func (c *Connection) Session(_ context.Context) (int, error)
- func (c *Connection) Start(ctx context.Context, op string, request Json, options RequestOptions) *Call
- type ConnectionOptions
- type ErrorOptions
- type HostKeyChangedError
- type HostKeyUnknownError
- type Json
- type LocalExecutionEnv
- type LocalExecutionEnvOptions
- type NodeSystem
- type RemoteError
- type RemoteExecutionEnv
- func (e *RemoteExecutionEnv) AbsolutePath(ctx context.Context, path string) (string, error)
- func (e *RemoteExecutionEnv) AppendFile(ctx context.Context, path string, content any) error
- func (e *RemoteExecutionEnv) CanonicalPath(ctx context.Context, path string) (string, error)
- func (e *RemoteExecutionEnv) Cleanup(context.Context) error
- func (e *RemoteExecutionEnv) CreateDir(ctx context.Context, path string, options *durableenv.CreateDirOptions) error
- func (e *RemoteExecutionEnv) CreateTempDir(ctx context.Context, prefix *string) (string, error)
- func (e *RemoteExecutionEnv) CreateTempFile(ctx context.Context, options *durableenv.CreateTempFileOptions) (string, error)
- func (e *RemoteExecutionEnv) Cwd() string
- func (e *RemoteExecutionEnv) Exec(ctx context.Context, command any, options *durableenv.ShellExecOptions) (durableenv.ShellExecResult, error)
- func (e *RemoteExecutionEnv) Exists(ctx context.Context, path string) (bool, error)
- func (e *RemoteExecutionEnv) FileInfo(ctx context.Context, path string) (durableenv.FileInfo, error)
- func (e *RemoteExecutionEnv) FlushFile(ctx context.Context, path string) error
- func (e *RemoteExecutionEnv) Id() string
- func (e *RemoteExecutionEnv) JoinPath(ctx context.Context, parts []string) (string, error)
- func (e *RemoteExecutionEnv) ListDir(ctx context.Context, path string) ([]durableenv.FileInfo, error)
- func (e *RemoteExecutionEnv) ListFiles(ctx context.Context, path string, options *durableenv.ListFilesOptions) (durableenv.FileListing, error)
- func (e *RemoteExecutionEnv) OpenBinaryReader(ctx context.Context, path string, options *durableenv.OpenBinaryReaderOptions) (durableenv.BinaryReader, error)
- func (e *RemoteExecutionEnv) OpenDirReader(ctx context.Context, path string) (durableenv.DirReader, error)
- func (e *RemoteExecutionEnv) OpenTextLineReader(ctx context.Context, path string) (durableenv.TextLineReader, error)
- func (e *RemoteExecutionEnv) ReadBinaryFile(ctx context.Context, path string) ([]byte, error)
- func (e *RemoteExecutionEnv) ReadTextFile(ctx context.Context, path string) (string, error)
- func (e *RemoteExecutionEnv) ReadTextLines(ctx context.Context, path string, options *durableenv.ReadTextLinesOptions) ([]string, error)
- func (e *RemoteExecutionEnv) Remove(ctx context.Context, path string, options *durableenv.RemoveOptions) error
- func (e *RemoteExecutionEnv) RenameFile(ctx context.Context, sourcePath, destinationPath string) error
- func (e *RemoteExecutionEnv) SetCwd(cwd string)
- func (e *RemoteExecutionEnv) TruncateFile(ctx context.Context, path string, size int64) error
- func (e *RemoteExecutionEnv) Watch(ctx context.Context, targets []durableenv.WatchTarget, ...) (durableenv.FileWatcher, error)
- func (e *RemoteExecutionEnv) WriteFile(ctx context.Context, path string, content any) error
- type RemoteExecutionEnvOptions
- type RemoteInfo
- type RemotePlatform
- type RemoteTerminal
- type RemoteWatchOptions
- type RemoteWatcher
- type Reply
- type RequestOptions
- type SshArgumentsOptions
- type SshConnectOptions
- type SshConnected
- type SshError
- type SshTarget
- type TerminalExit
- type TerminalForeground
- type TerminalOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AcceptHostKey ¶
AcceptHostKey trusts host-key lines from ScanHostKey by adding them to the target's known-hosts file. Only plain lines for the target's alias are accepted. A key that differs from a trusted key of the same type is refused with HostKeyChangedError; ForgetHostKey must remove the old keys first.
func ConnectSsh ¶
func ConnectSsh(ctx context.Context, options SshConnectOptions) (*Connection, RemotePlatform, error)
ConnectSsh detects the remote system and deploys the daemon now, then returns a Connection that starts it over ssh, like SshConnection. Failures return here: host keys must already be trusted (ScanHostKey, AcceptHostKey), otherwise this fails with HostKeyUnknownError.
func DeployDaemon ¶
func DeployDaemon(ctx context.Context, target SshTarget, remote RemotePlatform, binaryOption *string) (string, error)
DeployDaemon makes sure the daemon is on the remote machine, verified by its SHA-256 before it ever runs, and removes daemons of other contents. The upload goes to a new temporary file and is renamed into place only once its hash matches. It returns the remote path of the binary. A nil binary is the packaged daemon for the system; a set path is used as given, so an empty one names no file.
func ForgetHostKey ¶
ForgetHostKey stops trusting every key stored for the target's alias, e.g. after the owner confirmed a changed host key.
func IsConnectionLost ¶
IsConnectionLost reports whether err means the connection was lost, not that the daemon refused the request.
func LocalDaemon ¶
LocalDaemon is the daemon this package ships for the machine it runs on, e.g. for terminals of local sessions.
func PackagedDaemon ¶
func PackagedDaemon(remote RemotePlatform) string
PackagedDaemon is the daemon binary shipped for a remote system.
func ScanHostKey ¶
ScanHostKey connects once with accept-new against a temporary known-hosts file to capture the key the host presents, through the same route (~/.ssh/config, jump hosts) as real connections. It returns its known-hosts lines and fingerprints. Showing a fingerprint is not authentication: compare it with one obtained out of band before accepting it.
func SshArguments ¶
func SshArguments(target SshTarget, options ...SshArgumentsOptions) ([]string, error)
SshArguments are the arguments for ssh up to the host: no prompts, no forwarding of any kind, no shared connections, no commands from the configuration, no locale forwarding (the remote uses its own), and host keys checked strictly against the application's own file under a fixed alias.
The optional options are upstream's trailing `strictHostKeys = true` and `knownHostsFile = target.knownHostsFile` parameters; a nil member is an absent argument.
func SshArgumentsWith ¶
func SshArgumentsWith(target SshTarget, strictHostKeys bool, knownHostsFile string) ([]string, error)
SshArgumentsWith is `sshArguments(target, strictHostKeys, knownHostsFile)` with every parameter given, in Pi's order (ssh.ts:77-81). Pi's defaults are `strictHostKeys = true` and `knownHostsFile = target.knownHostsFile`; SshArguments applies them.
Types ¶
type Call ¶
type Call struct {
// contains filtered or unexported fields
}
Call is a request that was sent and has not been awaited.
type Connection ¶
type Connection struct {
// contains filtered or unexported fields
}
Connection is one connection to a pi-env daemon: started lazily on the first request and started again after it is lost. Requests in flight when it is lost fail with code `unknown`; for mutations their outcome is then unknown.
func NewConnection ¶
func NewConnection(options ConnectionOptions) *Connection
NewConnection returns a connection that starts the daemon at its first request.
func (*Connection) Close ¶
func (c *Connection) Close()
Close stops the daemon; it kills everything it started.
func (*Connection) Info ¶
func (c *Connection) Info(_ context.Context) (RemoteInfo, error)
Info connects if needed and returns what the daemon reported about its machine. Connecting takes no cancellation, as upstream's info() takes no signal; the start ends at its own timeout or at Close.
func (*Connection) Kill ¶
func (c *Connection) Kill(id uint32, sessionID int)
Kill kills one `exec` without aborting it.
func (*Connection) Request ¶
func (c *Connection) Request(ctx context.Context, op string, request Json, options RequestOptions) (Reply, error)
Request sends one request and waits for its reply.
func (*Connection) Session ¶
func (c *Connection) Session(_ context.Context) (int, error)
Session connects if needed and returns the live session's id. Like Info, it does not cancel the connecting.
func (*Connection) Start ¶
func (c *Connection) Start(ctx context.Context, op string, request Json, options RequestOptions) *Call
Start sends one request and returns without waiting for its reply. Starting requests in a row sends them in that order. Cancelling ctx sends `cancel` after the request is written; a request cancelled while the daemon starts waits for the start and is then sent.
type ConnectionOptions ¶
type ConnectionOptions struct {
// Command starts the daemon, before its `serve --token <hex>` arguments, e.g. `ssh -T -- host
// ~/.pi/mobile/tools/pi-env`.
Command []string
// CommandFunc computes the command at each start instead (detecting and deploying first, for example); its failure
// fails that start, and the next request tries again. It takes precedence over Command.
CommandFunc func(ctx context.Context) ([]string, error)
// OnLog receives the daemon's and the transport's diagnostic output.
OnLog func(text string)
}
ConnectionOptions configure a Connection.
type ErrorOptions ¶
type ErrorOptions struct {
Cause error
}
ErrorOptions is the options argument the host-key errors inherit from the Error constructor; Cause becomes their `cause`.
type HostKeyChangedError ¶
type HostKeyChangedError struct {
Message string
// Cause is the `cause` a caller passes as the inherited Error constructor's ErrorOptions (`new HostKeyChangedError(message, { cause })`); ssh.go's own errors leave it nil, as ssh.ts does.
Cause error
}
HostKeyChangedError means the remote host's key differs from the one in KnownHostsFile; it is never accepted automatically.
func NewHostKeyChangedError ¶
func NewHostKeyChangedError(message string, options ...ErrorOptions) *HostKeyChangedError
NewHostKeyChangedError is `new HostKeyChangedError(message, options)`: the inherited Error constructor keeps options.Cause as `cause`.
func (*HostKeyChangedError) Error ¶
func (e *HostKeyChangedError) Error() string
func (*HostKeyChangedError) Name ¶
func (e *HostKeyChangedError) Name() string
Name is the `name` property. Upstream's class sets none, so it is the inherited "Error".
func (*HostKeyChangedError) Unwrap ¶
func (e *HostKeyChangedError) Unwrap() error
Unwrap returns Cause, the `cause` property.
type HostKeyUnknownError ¶
type HostKeyUnknownError struct {
Message string
// Cause is the `cause` a caller passes as the inherited Error constructor's ErrorOptions (`new HostKeyUnknownError(message, { cause })`); ssh.go's own errors leave it nil, as ssh.ts does.
Cause error
}
HostKeyUnknownError means the remote host's key is not in KnownHostsFile; ScanHostKey shows it so the owner can accept it.
func NewHostKeyUnknownError ¶
func NewHostKeyUnknownError(message string, options ...ErrorOptions) *HostKeyUnknownError
NewHostKeyUnknownError is `new HostKeyUnknownError(message, options)`: the inherited Error constructor keeps options.Cause as `cause`.
func (*HostKeyUnknownError) Error ¶
func (e *HostKeyUnknownError) Error() string
func (*HostKeyUnknownError) Name ¶
func (e *HostKeyUnknownError) Name() string
Name is the `name` property. Upstream's class sets none, so it is the inherited "Error".
func (*HostKeyUnknownError) Unwrap ¶
func (e *HostKeyUnknownError) Unwrap() error
Unwrap returns Cause, the `cause` property.
type LocalExecutionEnv ¶
type LocalExecutionEnv struct {
*node.NodeExecutionEnv
// contains filtered or unexported fields
}
LocalExecutionEnv is a NodeExecutionEnv with ListFiles through a pi-env daemon on the same machine, so local and remote environments list files with the same code. Everything else is NodeExecutionEnv's. The connection belongs to the caller, who closes it; several environments may share it.
func NewLocalExecutionEnv ¶
func NewLocalExecutionEnv(options LocalExecutionEnvOptions) *LocalExecutionEnv
NewLocalExecutionEnv returns the environment of options.
func (*LocalExecutionEnv) ListFiles ¶
func (e *LocalExecutionEnv) ListFiles(ctx context.Context, path string, options *durableenv.ListFilesOptions) (durableenv.FileListing, error)
ListFiles lists the files below path through the daemon.
type LocalExecutionEnvOptions ¶
type LocalExecutionEnvOptions struct {
node.NodeExecutionEnvOptions
// Connection is a connection to this machine's daemon, `NewConnection(ConnectionOptions{Command: []string{daemon}})` with
// LocalDaemon for `daemon`, for ListFiles.
Connection *Connection
}
LocalExecutionEnvOptions are the options of a LocalExecutionEnv: those of a NodeExecutionEnv and a connection.
type NodeSystem ¶
type NodeSystem struct{ Platform, Arch string }
NodeSystem is the daemon's system in Node's names, as process.platform and process.arch spell them.
func NodePlatform ¶
func NodePlatform(info RemoteInfo) NodeSystem
NodePlatform is `nodePlatform` of connection.ts: Node's names for the daemon's system and architecture, which `hello` reports in Rust's spelling: `windows` is `win32`, `macos` is `darwin`, `x86_64` is `x64`, `aarch64` is `arm64` and `x86` is `ia32`, so they compare with process.platform and process.arch. Other names are kept.
type RemoteError ¶
type RemoteError struct {
Code string
// Path is the optional `path` property: nil when the daemon reported no string path, so an empty reported path stays distinct from none.
Path *string
Message string
Fields Json
}
RemoteError is a failure reported by the daemon, with its Node-style code.
func NewRemoteError ¶
func NewRemoteError(fields Json) *RemoteError
NewRemoteError returns the error of the daemon's error fields.
func (*RemoteError) Error ¶
func (e *RemoteError) Error() string
func (*RemoteError) Name ¶
func (e *RemoteError) Name() string
Name is the `name` property, "RemoteError".
type RemoteExecutionEnv ¶
type RemoteExecutionEnv struct {
// Connection is the connection to the daemon.
Connection *Connection
// contains filtered or unexported fields
}
RemoteExecutionEnv is an ExecutionEnv on another machine, reached through a pi-env daemon. Results match NodeExecutionEnv running on that machine: the daemon performs the system calls, and this type applies Node's path, error, and result rules.
func NewRemoteExecutionEnv ¶
func NewRemoteExecutionEnv(options RemoteExecutionEnvOptions) *RemoteExecutionEnv
NewRemoteExecutionEnv returns an environment that works on the machine options.Connection reaches.
func (*RemoteExecutionEnv) AbsolutePath ¶
AbsolutePath resolves path without requiring it to exist.
func (*RemoteExecutionEnv) AppendFile ¶
AppendFile creates or appends to path with content, a string or []byte, creating parent directories.
func (*RemoteExecutionEnv) CanonicalPath ¶
CanonicalPath resolves every symlink in an existing path.
func (*RemoteExecutionEnv) Cleanup ¶
func (e *RemoteExecutionEnv) Cleanup(context.Context) error
Cleanup kills the commands this environment started without aborting them, so they settle with their killed status, as NodeExecutionEnv does.
func (*RemoteExecutionEnv) CreateDir ¶
func (e *RemoteExecutionEnv) CreateDir(ctx context.Context, path string, options *durableenv.CreateDirOptions) error
CreateDir creates a directory; Recursive defaults to true.
func (*RemoteExecutionEnv) CreateTempDir ¶
CreateTempDir creates a directory named prefix plus six random characters under the remote temporary directory; prefix defaults to "tmp-".
func (*RemoteExecutionEnv) CreateTempFile ¶
func (e *RemoteExecutionEnv) CreateTempFile(ctx context.Context, options *durableenv.CreateTempFileOptions) (string, error)
CreateTempFile creates an empty file named prefix + UUID + suffix inside a fresh temporary directory.
func (*RemoteExecutionEnv) Cwd ¶
func (e *RemoteExecutionEnv) Cwd() string
Cwd is the directory relative paths resolve against.
func (*RemoteExecutionEnv) Exec ¶
func (e *RemoteExecutionEnv) Exec(ctx context.Context, command any, options *durableenv.ShellExecOptions) (durableenv.ShellExecResult, error)
Exec runs a command on the remote machine. A string runs through its shell; a []string runs its first element directly with the rest as its arguments.
func (*RemoteExecutionEnv) Exists ¶
Exists reports false for missing paths and other failures as errors.
func (*RemoteExecutionEnv) FileInfo ¶
func (e *RemoteExecutionEnv) FileInfo(ctx context.Context, path string) (durableenv.FileInfo, error)
FileInfo returns metadata without following symlinks.
func (*RemoteExecutionEnv) FlushFile ¶
func (e *RemoteExecutionEnv) FlushFile(ctx context.Context, path string) error
FlushFile flushes the contents of path to stable storage.
func (*RemoteExecutionEnv) Id ¶
func (e *RemoteExecutionEnv) Id() string
Id is the file namespace: equal ids see the same files.
func (*RemoteExecutionEnv) JoinPath ¶
JoinPath joins and normalizes path segments like the remote system's path.join.
func (*RemoteExecutionEnv) ListDir ¶
func (e *RemoteExecutionEnv) ListDir(ctx context.Context, path string) ([]durableenv.FileInfo, error)
ListDir lists direct children without following symlinks; unsupported file types are omitted.
func (*RemoteExecutionEnv) ListFiles ¶
func (e *RemoteExecutionEnv) ListFiles(ctx context.Context, path string, options *durableenv.ListFilesOptions) (durableenv.FileListing, error)
ListFiles lists the files below path through the daemon; it fails with not_supported for a daemon released before `listFiles`.
func (*RemoteExecutionEnv) OpenBinaryReader ¶
func (e *RemoteExecutionEnv) OpenBinaryReader(ctx context.Context, path string, options *durableenv.OpenBinaryReaderOptions) (durableenv.BinaryReader, error)
OpenBinaryReader opens a regular file for bounded positional reads.
func (*RemoteExecutionEnv) OpenDirReader ¶
func (e *RemoteExecutionEnv) OpenDirReader(ctx context.Context, path string) (durableenv.DirReader, error)
OpenDirReader opens path for paged directory listings.
func (*RemoteExecutionEnv) OpenTextLineReader ¶
func (e *RemoteExecutionEnv) OpenTextLineReader(ctx context.Context, path string) (durableenv.TextLineReader, error)
OpenTextLineReader opens path for pull-based line reading.
func (*RemoteExecutionEnv) ReadBinaryFile ¶
ReadBinaryFile reads path as bytes.
func (*RemoteExecutionEnv) ReadTextFile ¶
ReadTextFile reads path as UTF-8 text.
func (*RemoteExecutionEnv) ReadTextLines ¶
func (e *RemoteExecutionEnv) ReadTextLines(ctx context.Context, path string, options *durableenv.ReadTextLinesOptions) ([]string, error)
ReadTextLines reads the first lines of path, or all of them.
func (*RemoteExecutionEnv) Remove ¶
func (e *RemoteExecutionEnv) Remove(ctx context.Context, path string, options *durableenv.RemoveOptions) error
Remove deletes a file or directory; a directory requires Recursive and a missing path requires Force.
func (*RemoteExecutionEnv) RenameFile ¶
func (e *RemoteExecutionEnv) RenameFile(ctx context.Context, sourcePath, destinationPath string) error
RenameFile atomically renames sourcePath over destinationPath.
func (*RemoteExecutionEnv) SetCwd ¶
func (e *RemoteExecutionEnv) SetCwd(cwd string)
SetCwd changes the directory relative paths resolve against.
func (*RemoteExecutionEnv) TruncateFile ¶
TruncateFile truncates or extends path to exactly size bytes.
func (*RemoteExecutionEnv) Watch ¶
func (e *RemoteExecutionEnv) Watch(ctx context.Context, targets []durableenv.WatchTarget, onChange func(durableenv.FileChange)) (durableenv.FileWatcher, error)
Watch reports changes to files and directories; the daemon watches next to the files.
type RemoteExecutionEnvOptions ¶
type RemoteExecutionEnvOptions struct {
Connection *Connection
// ID is the file namespace: equal ids see the same files (FileSystem.Id), e.g. `pi-env:<env name>`.
ID string
Cwd string
// ShellPath is an explicit shell on the remote machine.
ShellPath string
// ShellEnv is added to the remote environment of every command that inherits it, like NodeExecutionEnv's.
ShellEnv map[string]string
// Watch is how the daemon watches, like NodeExecutionEnv's watch option.
Watch RemoteWatchOptions
}
RemoteExecutionEnvOptions configure a RemoteExecutionEnv.
type RemoteInfo ¶
type RemoteInfo struct {
Protocol int
Version string
// OS is Rust's std::env::consts::OS spelling: linux, macos, android or windows.
OS string
Arch string
Home string
// Tmpdir follows the remote Node's os.tmpdir() rules.
Tmpdir string
// Separator is the path separator: `/`, or `\` on Windows.
Separator string
// Cwd is the daemon's working directory, where Node's path.resolve would fall back to process.cwd().
Cwd string
// DriveCwds are Windows' per-drive working directories (`C:` to `C:\work`) of the `=C:` variables.
DriveCwds map[string]string
Pid int
// Features are the operations added to protocol 1 that this daemon supports, such as `listFiles`; nil for older daemons, which omit the field.
Features []string
}
RemoteInfo is what `hello` reports about the remote machine.
type RemotePlatform ¶
type RemotePlatform struct {
// Platform is linux, android, darwin or windows.
Platform string
// Arch is x64 or arm64.
Arch string
// Home is the remote home directory, in the remote system's own spelling.
Home string
// Shell is, on Windows, the shell sshd runs commands with (DefaultShell): cmd or powershell.
Shell string
// Warnings are problems worth telling the owner about, such as Termux without termux-exec.
Warnings []string
}
RemotePlatform is a remote system the package ships a daemon for.
func DetectPlatform ¶
func DetectPlatform(ctx context.Context, target SshTarget) (RemotePlatform, error)
DetectPlatform finds which system the target runs: uname through the login shell, or PowerShell on Windows.
type RemoteTerminal ¶
type RemoteTerminal struct {
// Pid is the program's process id on the daemon's machine.
Pid int
// contains filtered or unexported fields
}
RemoteTerminal is a program running in a pseudo-terminal of a pi-env daemon. It ends when the program exits, Close kills it, or the connection is lost (the daemon then kills it).
func NewRemoteTerminal ¶
func NewRemoteTerminal(connection *Connection, id uint32, session, pid int, exited <-chan TerminalExit, abort context.CancelFunc) *RemoteTerminal
NewRemoteTerminal is the terminal of the running `pty` request id of a daemon session, as upstream's constructor takes it. exited delivers how the request settled, once; abort ends the request. OpenTerminal is how a terminal is started.
func OpenTerminal ¶
func OpenTerminal(ctx context.Context, connection *Connection, options TerminalOptions) (*RemoteTerminal, error)
OpenTerminal starts a program in a new pseudo-terminal of the daemon behind connection. It returns once the program runs; a failure before that, such as a missing directory, is the error. The terminal outlives ctx: cancelling ctx only abandons the open, and kills a program that was starting.
func (*RemoteTerminal) Close ¶
func (t *RemoteTerminal) Close()
Close kills the program and everything in its session.
func (*RemoteTerminal) Exited ¶
func (t *RemoteTerminal) Exited() (int, error)
Exited blocks until the terminal ended and returns the exit code. It is upstream's `exited` promise, which may be awaited any number of times. It fails with the daemon's error, with code `aborted` after Close.
func (*RemoteTerminal) Foreground ¶
func (t *RemoteTerminal) Foreground(ctx context.Context) (*TerminalForeground, error)
Foreground is the job in the terminal's foreground when it is not the program itself: what a shell runs, such as an editor. It is nil while the program is in front (a shell at its prompt), and fails once the terminal has ended.
func (*RemoteTerminal) Resize ¶
func (t *RemoteTerminal) Resize(cols, rows int)
Resize changes the size; the program receives SIGWINCH.
func (*RemoteTerminal) Write ¶
func (t *RemoteTerminal) Write(data any)
Write sends input, a string (sent as UTF-8) or []byte; once the terminal has ended, input is dropped. Any other value sends nothing, as upstream's `bytes.length` loop does for a value that has no length.
type RemoteWatchOptions ¶
type RemoteWatchOptions struct {
// Mode forces a mode; by default Windows and file systems that do not report remote changes poll.
Mode durableenv.WatchMode
// PollIntervalMs is the interval between snapshots in polling mode; nil is the daemon's default 2000 ms.
PollIntervalMs *int
// MaxDirectories is the most directories one watcher covers; nil is the daemon's default 10,000. A set value is sent
// as given, as Pi spreads its options into the watch request.
MaxDirectories *int
}
RemoteWatchOptions is how the daemon watches, like NodeExecutionEnv's NodeWatchOptions.
type RemoteWatcher ¶
type RemoteWatcher struct {
// contains filtered or unexported fields
}
RemoteWatcher is a watcher running in the daemon (Durable's NodeFileWatcher next to the files). When the connection is lost, it is opened again once the connection can be started again, and reports overflow: changes in between were not seen.
func OpenRemoteWatcher ¶
func OpenRemoteWatcher(ctx context.Context, connection *Connection, targets []durableenv.WatchTarget, onChange func(durableenv.FileChange), options RemoteWatchOptions) (*RemoteWatcher, error)
stubgen:omit NewRemoteWatcher stubgen:omit Open OpenRemoteWatcher is upstream's RemoteWatcher.open: the constructor is private upstream, and Go has no static methods. It watches targets (resolved paths); it fails like NodeFileWatcher.open if coverage cannot be established.
func (*RemoteWatcher) Mode ¶
func (w *RemoteWatcher) Mode() durableenv.WatchMode
Mode is how the watcher learns of changes.
type Reply ¶
type Reply struct {
JSON Json
Payload []byte
// Session is the daemon session that answered; handles from it are only valid while it lives.
Session int
}
Reply is a successful reply.
type RequestOptions ¶
type RequestOptions struct {
Payload []byte
// OnEvent receives progress events of the request, such as `exec` output, on the connection's reader.
OnEvent func(json Json, payload []byte)
// OnStart receives the request's id and session, for Kill, before the request is sent.
OnStart func(id uint32, session int)
// Session, when not 0, only runs the request in that daemon session, for requests on handles it opened. After the
// connection was lost and started again, such requests fail instead of reaching a daemon that never opened the
// handle.
Session int
}
RequestOptions configure one request.
type SshArgumentsOptions ¶
SshArgumentsOptions are the optional trailing parameters of SshArguments: whether host keys are checked strictly, and the known hosts file.
type SshConnectOptions ¶
type SshConnectOptions struct {
SshTarget
// Binary is the daemon to deploy; nil is the packaged one.
Binary *string
// LoginShell starts the daemon through the user's login shell (`$SHELL -l`) on POSIX, so commands see the
// environment of ~/.profile and similar files. Off by default: ssh runs commands without a login shell.
LoginShell bool
OnLog func(text string)
}
SshConnectOptions are the options of SshConnection and ConnectSsh: the target, plus the binary to deploy (default: the one shipped for the remote system).
type SshConnected ¶
type SshConnected struct {
// Connection starts the daemon over ssh on its first request.
Connection *Connection
// Remote is the detected system, or nil until a start detected it.
Remote func() *RemotePlatform
}
SshConnected is what SshConnection returns, upstream's `{ connection, remote() }`.
func SshConnection ¶
func SshConnection(options SshConnectOptions) SshConnected
SshConnection is a Connection to the target that does nothing until its first request. Each start detects the remote system (the first time), verifies the daemon and deploys it if it is missing or changed, then starts it over ssh. A failure (no network, an untrusted or changed host key) fails the requests waiting for that start with code spawn_error and the ssh diagnostics as message; the next request tries again. remote returns the detected system, once known.
type SshError ¶
type SshError struct {
Message string
// ExitCode is nil when ssh did not exit with a code (it was killed, or could not start).
ExitCode *int
Stderr string
}
SshError is an ssh invocation that failed for another reason, with its exit code and diagnostics.
func NewSshError ¶
NewSshError builds an SshError. Ports packages/env/src/ssh.ts SshError constructor(message, exitCode, stderr); a nil exitCode is upstream's null.
type SshTarget ¶
type SshTarget struct {
// Host is a host name or ~/.ssh/config alias.
Host string
User *string
Port *int
IdentityFile *string
// KnownHostsFile holds the host keys this application trusts; AcceptHostKey adds to it.
KnownHostsFile string
// HostKeyAlias is the name keys are stored under, independent of aliases, ports and jump hosts, e.g.
// `pi-env-<env name>`.
HostKeyAlias string
// Ssh is the ssh program; default ssh.
Ssh *string
// ConfigFile is an ssh configuration file instead of ~/.ssh/config (-F).
ConfigFile *string
}
SshTarget is how to reach a machine with the system ssh.
A nil User, Port, IdentityFile, Ssh or ConfigFile is unset, as `undefined` is in Pi; a set value is used as given, so SshArguments rejects an explicitly empty user or identity file and port 0 with Pi's messages.
type TerminalExit ¶
TerminalExit is how a terminal ended: its exit code, or the daemon's error, a RemoteError with code `aborted` after Close.
type TerminalForeground ¶
TerminalForeground is the foreground job of a terminal: its process group id, and its leader's name if the system tells ("" otherwise).
type TerminalOptions ¶
type TerminalOptions struct {
// Cwd is the working directory of the program; it must exist.
Cwd string
// Argv is the program and its arguments. Nil is the user's shell (`SHELL` in Env or the daemon's environment) as a
// login shell.
Argv []string
// Env is added to the daemon's environment, or is the whole environment with InheritEnv false. Set `TERM` here.
Env map[string]string
InheritEnv *bool
Cols, Rows int
// OnData receives the terminal's raw output, in order, on the connection's reader.
OnData func(bytes []byte)
}
TerminalOptions configure OpenTerminal.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
pi-env
command
Command pi-env is the remote execution environment daemon of Pi Durable: it serves the pi-env protocol on stdin and stdout.
|
Command pi-env is the remote execution environment daemon of Pi Durable: it serves the pi-env protocol on stdin and stdout. |
|
Package daemon is pi-env's daemon: it gives a Pi Durable host an execution environment on this machine over a framed protocol on stdin and stdout, usually started through ssh as `pi-env serve --token <hex>`.
|
Package daemon is pi-env's daemon: it gives a Pi Durable host an execution environment on this machine over a framed protocol on stdin and stdout, usually started through ssh as `pi-env serve --token <hex>`. |