Documentation
¶
Index ¶
- Variables
- func NativeLocalPath(p string) string
- type Client
- func (s *Client) ChmodFile(remotePath string, mode os.FileMode) error
- func (s *Client) ChownFile(remotePath string, uid, gid int) error
- func (s *Client) ChtimesFile(remotePath string, atime, mtime time.Time) error
- func (s *Client) Close() error
- func (s *Client) Getwd() (string, error)
- func (s *Client) LinkFile(existing, newPath string) error
- func (s *Client) MakeDir(remotePath string) error
- func (s *Client) ReadFile(remotePath string, offset, length int64, mode string, ...) (*FileResult, error)
- func (s *Client) ReadLink(path string) (string, error)
- func (s *Client) ReadToLocalProgress(ctx context.Context, remotePath, localPath string, offset, length int64, ...) (int64, error)
- func (s *Client) RealPath(path string) (string, error)
- func (s *Client) RemoveFile(remotePath string) error
- func (s *Client) RenameFile(oldPath, newPath string) error
- func (s *Client) ReplaceInFile(remotePath, oldText, newText string) (int64, error)
- func (s *Client) StatFile(remotePath string) (*FileStatResult, error)
- func (s *Client) StatVFS(path string) (*FsStatResult, error)
- func (s *Client) StreamReadTo(w io.Writer, remotePath string, offset, length int64) (int64, error)
- func (s *Client) StreamWriteFrom(r io.Reader, remotePath string, offset *int64) (int64, error)
- func (s *Client) SymlinkFile(target, linkPath string) error
- func (s *Client) TruncateFile(path string, size int64) error
- func (s *Client) WriteFile(remotePath string, offset *int64, data string, mode string, localPath string, ...) (int64, error)
- func (s *Client) WriteFromLocalProgress(ctx context.Context, remotePath string, offset *int64, localPath string, ...) (int64, error)
- type FileResult
- type FileStatResult
- type FsStatResult
- type ProgressFunc
Constants ¶
This section is empty.
Variables ¶
var ( ErrPatternNotFound = errors.New("pattern not found in file") ErrPatternAmbiguous = errors.New("pattern matched more than once; must match uniquely") )
ReplaceInFile errors: exact matching only.
var ErrBinaryFile = errors.New("binary file cannot be read as text")
ErrBinaryFile reports that a text read found a NUL byte, so the content is not text. Classified as a 400 like ErrIsDirectory: the caller asked for a rendering these bytes do not have, and the message names the two modes that do.
var ErrIsDirectory = errors.New("is a directory")
ErrIsDirectory reports that a read named a directory.
A sentinel rather than a formatted string because the MCP layer classifies it: a directory is what the caller asked for and cannot use, which is a 400, while an SSH_FX_FAILURE from the same reader is a genuine fault and stays a 500.
Functions ¶
func NativeLocalPath ¶ added in v0.2.8
NativeLocalPath rewrites a POSIX-shell path into the spelling this host's file system API understands.
The daemon is usually driven from a shell, and a shell reports paths in its own dialect: Git Bash hands out `/d/home/x` for `D:\home\x`, and os.Open on Windows has no idea what that is — it answers "The system cannot find the path specified", which names neither the path nor the problem (found by driving a real Windows daemon from Git Bash). Only a leading `/<letter>/` is rewritten: on Windows that spelling is never a native path, so nothing that used to work changes meaning.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
sftpClient abstracts SFTP operations.
func NewClient ¶
OpenSFTPOverSSH opens an SFTP connection over an existing SSH client (for regular SSH).
func Shared ¶ added in v0.2.9
Shared wraps an existing engine as a Client whose Close does nothing.
WHY A VIEW RATHER THAN A REFERENCE COUNT: the engine's lifetime is its session's, and a caller cannot know when the last of several concurrent calls finishes. Handing out an owned-looking Client would invite `defer Close()`, which would leave every later call holding a dead engine — the bug this type exists to make impossible to write.
func (*Client) ChtimesFile ¶ added in v0.1.2
ChtimesFile changes the access and modification times of a remote file.
func (*Client) ReadFile ¶
func (s *Client) ReadFile(remotePath string, offset, length int64, mode string, localPath, charset string, raw, numbered bool) (*FileResult, error)
ReadFile reads a segment of a remote file and renders it for a reply.
charset is the caller's --encoding: the bytes are decoded from it to UTF-8 BEFORE the text rendering, because rendering first is what turned a PowerShell log into `\xff\xfeP\x00S\x00...` — true, and unreadable (issue #177). Empty means UTF-8, which is what this file read assumed everywhere until the flag existed.
raw skips the ESCAPE RENDERING and hands back the text as it is (issue #248). EncodeText turns every newline into the two characters `\n`, which is the right contract for a value a caller will feed back to `write --data` — and the wrong one for reading a config file to review it, where 946 bytes of nginx.conf arrived as one line and a missed line was a missed setting. Escaping exists so a reply can be a single-line value; raw says this reply is text, not a value.
numbered prefixes each line with the line's position IN THE FILE, which needs newlines preserved too, so it implies raw. The number is counted, not assumed: a read that starts at an offset is not reading line 1 first.
func (*Client) ReadToLocalProgress ¶ added in v0.2.8
func (s *Client) ReadToLocalProgress(ctx context.Context, remotePath, localPath string, offset, length int64, onProgress ProgressFunc) (int64, error)
ReadToLocalProgress streams remotePath into a local file, reporting progress.
THE LOCAL SIDE IS THE ONE THAT MUST NOT BE LEFT HALF-WRITTEN, for the same reason a remote target must not: whoever consumes the download — a build, a checksum, an installer — reads the name it asked for. So the bytes go to `<local>.part` and the rename happens on a clean exit; an interrupted download deletes the part file.
func (*Client) RealPath ¶ added in v0.1.2
RealPath returns the canonical absolute path of a remote file or directory.
func (*Client) RemoveFile ¶
RemoveFile deletes a remote file.
func (*Client) RenameFile ¶
RenameFile moves or renames a remote file/directory (same filesystem).
func (*Client) ReplaceInFile ¶ added in v0.2.8
ReplaceInFile replaces exactly one occurrence of oldText with newText.
THE UNIQUENESS CONSTRAINT IS THE FEATURE. A replace that "just replaces" is how an edit lands in the wrong place: an agent asked to change `timeout = 5` in a config with three such lines would silently pick the first, and the mistake is invisible until the wrong service misbehaves. Matching zero or several times is an error that names the count, so the caller narrows the pattern instead of guessing which one it got.
ATOMIC ON POSIX: the result is written to a temporary file in the SAME directory and renamed over the original. rename(2) within a filesystem is atomic, so a reader either sees the old file or the new one — never a half-written one, which is what an in-place write produces if the process dies mid-way.
Returns the number of bytes written (the new file's size).
func (*Client) StatFile ¶
func (s *Client) StatFile(remotePath string) (*FileStatResult, error)
StatFile returns file/directory info.
func (*Client) StatVFS ¶ added in v0.1.2
func (s *Client) StatVFS(path string) (*FsStatResult, error)
StatVFS returns filesystem statistics for the given remote path.
func (*Client) StreamReadTo ¶
StreamReadTo reads from remotePath (optionally at offset for length bytes) and streams raw bytes into w. Uses io.CopyN for zero-buffer streaming — never loads the whole file into memory. For large files use offset=0, length<=0 to stream the entire file.
func (*Client) StreamWriteFrom ¶
StreamWriteFrom reads raw bytes from r and writes them to remotePath at the given offset. A nil offset truncates the file; a pointer to 0 overwrites from the first byte without truncating. Uses io.Copy to stream without buffering in memory.
A WHOLE-FILE WRITE GOES THROUGH A TEMPORARY SIBLING, the same rule WriteFromLocalProgress follows and for the same reason (#158): a stream that dies partway — the reader errored, the caller cancelled, the link dropped — must not leave a truncated file where the real one goes. This path had no such protection, so `read <a> file <x> | write <b> file <y>` where x could not be opened left an empty <y> behind: a copy that failed, reported failed, and destroyed the destination anyway.
An explicit offset still patches in place: a patch cannot be assembled in a sibling without copying the rest of the file first.
func (*Client) SymlinkFile ¶ added in v0.1.2
SymlinkFile creates a symbolic link on the remote. target is the existing path, linkPath is the new symlink to create.
func (*Client) TruncateFile ¶ added in v0.1.2
TruncateFile truncates a remote file to the given size.
func (*Client) WriteFile ¶
func (s *Client) WriteFile(remotePath string, offset *int64, data string, mode string, localPath string, localOffset, length int64) (int64, error)
WriteFile writes data to a remote file, either inline or from a local file.
func (*Client) WriteFromLocalProgress ¶ added in v0.2.8
func (s *Client) WriteFromLocalProgress(ctx context.Context, remotePath string, offset *int64, localPath string, localOffset, length int64, onProgress ProgressFunc) (int64, error)
WriteFromLocalProgress streams a local file to remotePath, reporting progress.
ATOMIC ON A FULL REWRITE. When offset == nil the caller is replacing the file, and a sync copy that gets interrupted (host watchdog, link reset) leaves a half-written file on the far side — which docker or a service then fails to run (#158). So a whole-file write streams to a temporary sibling (`.termcp-part-…`) and renames it over the target only on a clean exit. An aborted transfer deletes the part file: no half-written binaries are ever left behind.
An explicit offset patches the target in place, because a patch cannot be assembled in a sibling without copying the rest of the file first.
type FileResult ¶
type FileResult struct {
// Data is a POINTER so "the inline body is empty" and "this read has no inline
// body" stay distinguishable.
//
// mode=file streams to a local path and never fills Data; mode=text/hex always
// does, even when the window is empty. A plain string with no omitempty made the
// first case report `data: ""` — a body that looks truncated rather than absent —
// while keeping omitempty made the second case drop the field on a zero-length
// read, which is the one read where seeing a zero matters.
//
// Length and BytesRead keep no omitempty for the same reason they always needed
// it: 0 is a fact about the window, not a missing value.
Data *string `json:"data,omitempty"`
Mode string `json:"mode"` // "text" | "hex" | "file"
Encoding string `json:"encoding,omitempty"`
TotalSize int64 `json:"total_size"`
HasMore bool `json:"has_more,omitempty"`
Offset int64 `json:"offset,omitempty"`
Length int64 `json:"length"`
BytesRead int64 `json:"bytes_read"`
LocalPath string `json:"local_path,omitempty"`
}
FileResult holds the result of a file_read operation.
type FileStatResult ¶
type FileStatResult struct {
Name string `json:"name"`
Size int64 `json:"size"`
IsDir bool `json:"is_dir"`
ModTime int64 `json:"mod_time,omitempty"` // Unix ms; 0 = unknown
// Mode is the permission bits as a caller would chmod them ("0664").
//
// IT IS HERE BECAUSE "IS THIS EXECUTABLE" WAS UNANSWERABLE (issue #191). A
// script that a caller had just written failed `open --argv` with "permission
// denied", and every surface that could have said "mode 664" instead reported
// size and mtime: the caller went looking at mounts, users and paths while the
// fact sat in the stat response nobody had asked for.
Mode string `json:"mode,omitempty"`
// Uid and Gid name the owner, which is the second half of "why can this not be
// run/read": a 755 file owned by someone else is still not yours to write.
Uid string `json:"uid,omitempty"`
Gid string `json:"gid,omitempty"`
Children []FileStatResult `json:"children,omitempty"`
}
FileStatResult holds the result of a file_stat operation.
type FsStatResult ¶ added in v0.1.2
type FsStatResult struct {
TotalSpace uint64 `json:"total_space"`
FreeSpace uint64 `json:"free_space"`
AvailSpace uint64 `json:"avail_space"`
TotalINodes uint64 `json:"total_inodes"`
FreeINodes uint64 `json:"free_inodes"`
AvailINodes uint64 `json:"avail_inodes"`
BlockSize uint64 `json:"block_size"`
}
FsStatResult holds the result of a file_statvfs operation.
type ProgressFunc ¶ added in v0.2.8
type ProgressFunc func(n int64)
ProgressFunc receives incremental byte counts during a transfer.