Documentation
¶
Overview ¶
Package env declares the portable execution environment of pi-durable: a file system and a shell that tools and prompt sections use through a conversation's environment.
Ports packages/durable/src/env/index.ts
Go mapping: upstream operations return `Result<T, E>` instead of throwing. Each Go method returns `(T, error)`; an expected failure is a *FileError or *ExecutionError and never a panic. The Result helpers stay for callers that hold a value-or-failure pair.
Index ¶
- Variables
- func GetOrThrow[TValue any, TError error](result Result[TValue, TError]) (TValue, error)
- func GetOrUndefined[TValue, TError any](result Result[*TValue, TError]) *TValue
- func StartsWithBom(firstBytes []byte) bool
- func ToError(value any) error
- type BinaryReader
- type CreateDirOptions
- type CreateTempFileOptions
- type DirPage
- type DirReader
- type ExecutionEnv
- type ExecutionError
- type ExecutionErrorCode
- type FileError
- type FileErrorCode
- type FileInfo
- type FileKind
- type FileSystem
- type FileWatcher
- type LineScan
- type LineScanner
- type OpenBinaryReaderOptions
- type RangeDecoder
- type ReadTextLinesOptions
- type RemoveOptions
- type Result
- type ScanLinesOptions
- type Shell
- type ShellExecOptions
- type ShellExecResult
- type ShellOutputInfo
- type ShellOutputSkip
- type ShellOutputWindow
- type ShellSpillOptions
- type ShellStream
- type StreamDecoder
- type TextLine
- type TextLineReader
- type WatchChange
- type WatchChangeError
- type WatchChangeOverflow
- type WatchChangePaths
- type WatchExclude
- type WatchMode
- type WatchTarget
Constants ¶
This section is empty.
Variables ¶
var ErrInvalidLineRange = errors.New("Invalid line range")
ErrInvalidLineRange is the error of a line range LineScanner refuses (upstream's RangeError).
Functions ¶
func GetOrThrow ¶
GetOrThrow returns the value, or the failure as a Go error.
func GetOrUndefined ¶
GetOrUndefined returns the value, or nil for a failure.
func StartsWithBom ¶
StartsWithBom reports whether decoding the whole input drops its first three bytes as a byte-order mark.
Types ¶
type BinaryReader ¶
type BinaryReader interface {
// Info is the metadata of the opened file, not of whatever its path names now.
Info(ctx context.Context) (FileInfo, error)
// Read returns up to length bytes at offset, fewer only at the end of the file. A negative offset or length, or
// one above JavaScript's largest safe integer, is invalid.
Read(ctx context.Context, offset, length int64) ([]byte, error)
// ScanLines is one pass over the file that locates lines [StartLine, EndLine) (EndLine nil: to the end), 0-based,
// where line k starts after the k-th newline byte. Decoded sizes are those of the text a TextDecoder would produce
// for that range, so a byte-order mark at the start of the file is not counted.
ScanLines(ctx context.Context, options ScanLinesOptions) (LineScan, error)
Close(ctx context.Context) error
}
BinaryReader makes positional reads from one opened regular file; all calls see the same file even if its path is renamed. Close is idempotent and every other call fails with an invalid FileError after it.
type CreateDirOptions ¶
type CreateDirOptions struct {
// Recursive creates missing parents; nil means true, as upstream's options?.recursive ?? true.
Recursive *bool
}
CreateDirOptions configures FileSystem.CreateDir.
type CreateTempFileOptions ¶
CreateTempFileOptions configures FileSystem.CreateTempFile.
type DirPage ¶
type DirPage struct {
Entries []FileInfo
// Done marks the end; it may come with the last entries or with an empty page.
Done bool
}
DirPage is one page of a DirReader.
type DirReader ¶
type DirReader interface {
// Next returns up to maxEntries entries in the order the file system returns them, continuing where the previous
// call stopped. An entry that disappears before its metadata is read is skipped, as are entries of unsupported
// kinds. After a failed or aborted call, close the reader.
Next(ctx context.Context, maxEntries int) (DirPage, error)
Close(ctx context.Context) error
}
DirReader pages the entries of one directory.
type ExecutionEnv ¶
type ExecutionEnv interface {
FileSystem
Shell
}
ExecutionEnv is a file system and a shell.
type ExecutionError ¶
type ExecutionError struct {
Code ExecutionErrorCode
Message string
// SpillPath is the spill file of a command that timed out or was aborted after its output crossed the spill
// thresholds; empty otherwise.
SpillPath string
Cause error
}
ExecutionError is the expected failure of a Shell command.
func NewExecutionError ¶
func NewExecutionError(code ExecutionErrorCode, message string, cause error) *ExecutionError
NewExecutionError returns an ExecutionError; cause may be nil.
func (*ExecutionError) Error ¶
func (e *ExecutionError) Error() string
type ExecutionErrorCode ¶
type ExecutionErrorCode string
ExecutionErrorCode classifies an ExecutionError.
const ( ExecutionErrorAborted ExecutionErrorCode = "aborted" ExecutionErrorTimeout ExecutionErrorCode = "timeout" ExecutionErrorSpawnError ExecutionErrorCode = "spawn_error" ExecutionErrorCallbackError ExecutionErrorCode = "callback_error" ExecutionErrorUnknown ExecutionErrorCode = "unknown" )
type FileError ¶
type FileError struct {
Code FileErrorCode
Message string
// Path is empty when the failure has no path.
Path string
Cause error
}
FileError is the expected failure of a FileSystem operation.
func NewFileError ¶
func NewFileError(code FileErrorCode, message, path string, cause error) *FileError
NewFileError returns a FileError; path and cause may be empty.
type FileErrorCode ¶
type FileErrorCode string
FileErrorCode classifies a FileError.
const ( FileErrorAborted FileErrorCode = "aborted" FileErrorNotFound FileErrorCode = "not_found" FileErrorPermissionDenied FileErrorCode = "permission_denied" FileErrorNotDirectory FileErrorCode = "not_directory" FileErrorIsDirectory FileErrorCode = "is_directory" FileErrorInvalid FileErrorCode = "invalid" FileErrorNotSupported FileErrorCode = "not_supported" FileErrorUnknown FileErrorCode = "unknown" )
type FileInfo ¶
type FileInfo struct {
Name string `json:"name"`
Path string `json:"path"`
Kind FileKind `json:"kind"`
Size int64 `json:"size"`
MtimeMs float64 `json:"mtimeMs"`
}
FileInfo describes one file system entry.
type FileSystem ¶
type FileSystem interface {
// Id names the file namespace: equal ids see the same files at the same paths, whatever their cwd. Every local
// environment shares one id; each container or remote host has its own.
Id() string
Cwd() string
SetCwd(cwd string)
AbsolutePath(ctx context.Context, path string) (string, error)
JoinPath(ctx context.Context, parts []string) (string, error)
ReadTextFile(ctx context.Context, path string) (string, error)
OpenTextLineReader(ctx context.Context, path string) (TextLineReader, error)
ReadTextLines(ctx context.Context, path string, options *ReadTextLinesOptions) ([]string, error)
ReadBinaryFile(ctx context.Context, path string) ([]byte, error)
// OpenBinaryReader opens a regular file for bounded positional reads. A directory fails with is_directory, other
// non-regular files with invalid. options may be nil.
OpenBinaryReader(ctx context.Context, path string, options *OpenBinaryReaderOptions) (BinaryReader, error)
// WriteFile writes content, a string or []byte.
WriteFile(ctx context.Context, path string, content any) error
// AppendFile appends content, a string or []byte.
AppendFile(ctx context.Context, path string, content any) error
// TruncateFile truncates or extends a file to exactly size bytes.
TruncateFile(ctx context.Context, path string, size int64) error
// FlushFile flushes file contents and the metadata needed to retrieve them from an open file handle.
FlushFile(ctx context.Context, path string) error
RenameFile(ctx context.Context, sourcePath, destinationPath string) error
FileInfo(ctx context.Context, path string) (FileInfo, error)
ListDir(ctx context.Context, path string) ([]FileInfo, error)
OpenDirReader(ctx context.Context, path string) (DirReader, error)
// Watch reports changes to files and directories, for hosts that load resources from the environment. When it
// returns a watcher, coverage is established: a host that watches before it loads cannot miss a change made during
// the load. See WatchChange for what is reported and FileWatcher.Mode for how reliably.
Watch(ctx context.Context, targets []WatchTarget, onChange func(WatchChange)) (FileWatcher, error)
CanonicalPath(ctx context.Context, path string) (string, error)
Exists(ctx context.Context, path string) (bool, error)
CreateDir(ctx context.Context, path string, options *CreateDirOptions) error
Remove(ctx context.Context, path string, options *RemoveOptions) error
CreateTempDir(ctx context.Context, prefix *string) (string, error)
CreateTempFile(ctx context.Context, options *CreateTempFileOptions) (string, error)
Cleanup(ctx context.Context) error
}
FileSystem is the portable file system capability. Operations return failures rather than panicking. Context comes first, as Go convention, where upstream passes it last.
type FileWatcher ¶
type FileWatcher interface {
Mode() WatchMode
// Close stops watching; no onChange call starts after it returns. It is idempotent.
Close(ctx context.Context) error
}
FileWatcher is a running watch.
type LineScan ¶
type LineScan struct {
// Newlines is the number of newline bytes in the whole file; it has Newlines + 1 lines.
Newlines int64
// Start and End are the byte range of the selected lines: from the start of the first to the end of the last,
// without the newline that ends it. A selection past the last line is empty at the end of the file.
Start, End int64
// FirstLineEnd is where the first selected line ends: its newline, or the end of the file.
FirstLineEnd int64
// LastLineStart is where the last selected line starts.
LastLineStart int64
// SelectedBytes and FirstLineBytes are the UTF-8 byte lengths of the decoded selection and of its first line.
SelectedBytes, FirstLineBytes int64
}
LineScan is where the lines of a file are, as BinaryReader.ScanLines found them.
type LineScanner ¶
type LineScanner struct {
// contains filtered or unexported fields
}
LineScanner computes a LineScan from a file's bytes fed in order, so an environment can scan any size in bounded memory. Decoded sizes use the same streaming WHATWG decoder as decoding the whole file at once.
func NewLineScanner ¶
func NewLineScanner(startLine int64, endLine *int64) (*LineScanner, error)
NewLineScanner returns a scanner for lines [startLine, endLine), 0-based. startLine must be a non-negative safe integer and endLine, when not nil, a safe integer above startLine.
func (*LineScanner) Finish ¶
func (scanner *LineScanner) Finish() LineScan
Finish returns the scan of the bytes pushed so far, taking them as the whole file.
func (*LineScanner) Push ¶
func (scanner *LineScanner) Push(chunk []byte)
Push feeds the next bytes of the file.
type OpenBinaryReaderOptions ¶
type OpenBinaryReaderOptions struct {
// NoFollow refuses a symbolic link as the final path component with an invalid FileError instead of following it;
// earlier components are still resolved.
NoFollow bool
}
OpenBinaryReaderOptions configures FileSystem.OpenBinaryReader.
type RangeDecoder ¶
type RangeDecoder struct {
// contains filtered or unexported fields
}
RangeDecoder is a streaming UTF-8 decoder for a byte range, like a TextDecoder with ignoreBOM: a character split across two chunks is held back until its remaining bytes arrive, each maximal invalid subpart becomes one U+FFFD, and no byte-order mark is dropped. Callers that start at the beginning of a file skip a leading mark themselves.
func NewRangeDecoder ¶
func NewRangeDecoder() *RangeDecoder
NewRangeDecoder returns a decoder for a byte range (upstream rangeDecoder).
func (*RangeDecoder) Decode ¶
func (decoder *RangeDecoder) Decode(chunk []byte) string
Decode returns the text of the complete characters in the held bytes plus chunk.
func (*RangeDecoder) Flush ¶
func (decoder *RangeDecoder) Flush() string
Flush returns the replacement character for a character the stream ended in the middle of, or "".
type ReadTextLinesOptions ¶
type ReadTextLinesOptions struct {
MaxLines *int
}
ReadTextLinesOptions bounds FileSystem.ReadTextLines; nil MaxLines reads every line.
type RemoveOptions ¶
RemoveOptions configures FileSystem.Remove.
type Result ¶
Result is the value or the expected failure of a fallible operation.
type ScanLinesOptions ¶
type ScanLinesOptions struct {
StartLine int64
// EndLine is nil to scan to the end of the file.
EndLine *int64
}
ScanLinesOptions selects the lines BinaryReader.ScanLines measures.
type Shell ¶
type Shell interface {
// Exec runs a command. A string runs through the environment's shell. A []string runs its first element directly
// with the rest as its arguments, without a shell, so they reach the program unparsed; an empty one is a
// spawn_error. Aborting ctx or a timeout kills only this command's processes.
Exec(ctx context.Context, command any, options *ShellExecOptions) (ShellExecResult, error)
// Cleanup kills every command this environment still runs; for its owner's shutdown, never for one request.
Cleanup(ctx context.Context) error
}
Shell runs commands.
type ShellExecOptions ¶
type ShellExecOptions struct {
Cwd string
Env map[string]string
InheritEnv *bool
// Timeout is in seconds; nil has no timeout.
Timeout *float64
// OnOutput receives every decoded chunk of stdout and stderr as it arrives, in arrival order, with the stream it
// came from: raw, unbounded, and unthrottled. Each stream is decoded separately, so a character split across
// chunks survives.
OnOutput func(ctx context.Context, text string, info ShellOutputInfo)
Spill *ShellSpillOptions
// Window is the tail the caller keeps, so the environment may omit output outside it and report the omission as
// ShellOutputInfo.Skipped. Without it, every chunk is delivered.
Window *ShellOutputWindow
}
ShellExecOptions configures Shell.Exec.
type ShellExecResult ¶
type ShellExecResult struct {
ExitCode int
// SpillPath is the temporary file holding the complete raw output when the spill thresholds were exceeded.
SpillPath string
}
ShellExecResult is the result of a completed command.
type ShellOutputInfo ¶
type ShellOutputInfo struct {
Stream ShellStream
// Skipped is output omitted immediately before this chunk, only with ShellExecOptions.Window. The chunk then holds
// all output after the omission up to its end, and that is more than the window by at least one byte or one line:
// more than Window.MaxBytes bytes or more than Window.MaxLines newlines. So the omitted text can never be in the
// kept tail. The omission and such a chunk may span both streams in arrival order; Stream then names the chunk's
// last stream. Callers that need the streams apart do not pass Window.
Skipped *ShellOutputSkip
}
ShellOutputInfo describes one output chunk.
type ShellOutputSkip ¶
type ShellOutputSkip struct {
// Bytes is the UTF-8 byte length of the omitted text.
Bytes int
// Newlines is the number of newlines (U+000A) in the omitted text.
Newlines int
// EndsWithNewline reports whether the omitted text ends with a newline.
EndsWithNewline bool
}
ShellOutputSkip is output an environment omitted, measured on the decoded text OnOutput would have received: every U+FFFD counts as three bytes, and no sanitizing is applied.
type ShellOutputWindow ¶
type ShellOutputWindow struct {
// MaxBytes is the UTF-8 bytes of decoded text kept at the end of the output.
MaxBytes int
// MaxLines is the lines kept at the end of the output.
MaxLines int
// MinIntervalMs is the minimum pause between the caller's samples of the output.
MinIntervalMs float64
// BytesPerSecond: each sample also pauses the caller in proportion to its size at this rate.
BytesPerSecond float64
}
ShellOutputWindow is the tail of the combined output a caller keeps, and how often it samples it. An environment that transfers output over a slow link uses it to omit what the caller would drop anyway and to send no faster than the caller commits.
type ShellSpillOptions ¶
type ShellSpillOptions struct {
AfterBytes int64
// AfterLines counts complete or partial lines.
AfterLines int64
}
ShellSpillOptions spills the complete output to a temporary file once it exceeds either threshold.
type ShellStream ¶
type ShellStream string
ShellStream names the stream an output chunk came from.
const ( ShellStdout ShellStream = "stdout" ShellStderr ShellStream = "stderr" )
type StreamDecoder ¶
type StreamDecoder struct {
// contains filtered or unexported fields
}
StreamDecoder decodes one stream chunk by chunk exactly like decoding all of it at once.
func NewStreamDecoder ¶
func NewStreamDecoder() *StreamDecoder
NewStreamDecoder returns a decoder for one stream.
func (*StreamDecoder) Decode ¶
func (decoder *StreamDecoder) Decode(chunk []byte) string
Decode returns the text for chunk, holding back an incomplete character.
func (*StreamDecoder) End ¶
func (decoder *StreamDecoder) End() string
End returns the text the end of the stream completes: a replacement character for an incomplete character. This is upstream's decode() without bytes.
type TextLineReader ¶
type TextLineReader interface {
// ReadLine returns nil at the end of the file.
ReadLine(ctx context.Context) (*TextLine, error)
Close(ctx context.Context) error
}
TextLineReader reads a text file line by line.
type WatchChange ¶
type WatchChange interface {
// contains filtered or unexported methods
}
WatchChange is what changed. It is WatchChangePaths, WatchChangeOverflow, or WatchChangeError.
type WatchChangeError ¶
type WatchChangeError struct{ Error *FileError }
WatchChangeError reports that the watcher stopped, for example because the watched tree grew past the environment's limit; no calls follow.
type WatchChangeOverflow ¶
type WatchChangeOverflow struct{}
WatchChangeOverflow reports that coverage was uncertain for a while (lost events, reconnect): rescan everything that is watched.
type WatchChangePaths ¶
type WatchChangePaths struct{ Paths []string }
WatchChangePaths reports that something at or below each path may have changed (a directory path covers its whole subtree). Calls may be spurious; a change is never missed while the watcher is healthy.
type WatchExclude ¶
WatchExclude names the entries below a watched path that are neither watched nor reported.
type WatchMode ¶
type WatchMode string
WatchMode is how a FileWatcher learns of changes.
const ( // WatchNative: changes are reported within about two seconds. WatchNative WatchMode = "native" // WatchPolling: the environment compares snapshots, because the file system does not report changes reliably // (network and FUSE file systems); a change undone between two snapshots can be missed. WatchPolling WatchMode = "polling" )
type WatchTarget ¶
type WatchTarget struct {
Path string
// Recursive watches everything below a directory, not only its entries. Symbolic links below it are not followed.
Recursive bool
Exclude *WatchExclude
}
WatchTarget is a file or directory to watch. It may be missing; creating it is a change.