env

package
v0.5.3 Latest Latest
Warning

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

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 8 Imported by: 0

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

Constants

This section is empty.

Variables

View Source
var ErrInvalidLineRange = errors.New("Invalid line range")

ErrInvalidLineRange is the error of a line range LineScanner refuses (upstream's RangeError).

Functions

func GetOrThrow

func GetOrThrow[TValue any, TError error](result Result[TValue, TError]) (TValue, error)

GetOrThrow returns the value, or the failure as a Go error.

func GetOrUndefined

func GetOrUndefined[TValue, TError any](result Result[*TValue, TError]) *TValue

GetOrUndefined returns the value, or nil for a failure.

func StartsWithBom

func StartsWithBom(firstBytes []byte) bool

StartsWithBom reports whether decoding the whole input drops its first three bytes as a byte-order mark.

func ToError

func ToError(value any) error

ToError converts a thrown value to an error: an error is kept, a string becomes its message, and any other value becomes its JSON text, or its default formatting when JSON fails.

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

type CreateTempFileOptions struct {
	Prefix string
	Suffix string
}

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

func (*ExecutionError) Name

func (*ExecutionError) Name() string

Name is the error class name, Pi's `name` property.

func (*ExecutionError) Unwrap

func (e *ExecutionError) Unwrap() error

Unwrap returns the cause.

type ExecutionErrorCode

type ExecutionErrorCode string

ExecutionErrorCode classifies an ExecutionError.

const (
	ExecutionErrorAborted          ExecutionErrorCode = "aborted"
	ExecutionErrorTimeout          ExecutionErrorCode = "timeout"
	ExecutionErrorShellUnavailable ExecutionErrorCode = "shell_unavailable"
	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.

func (*FileError) Error

func (e *FileError) Error() string

func (*FileError) Name

func (*FileError) Name() string

Name is the `name` property, "FileError".

func (*FileError) Unwrap

func (e *FileError) Unwrap() error

Unwrap returns the cause.

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 FileKind

type FileKind string

FileKind is "file", "directory", or "symlink".

const (
	FileKindFile      FileKind = "file"
	FileKindDirectory FileKind = "directory"
	FileKindSymlink   FileKind = "symlink"
)

type FileListEntry

type FileListEntry struct {
	// Path is relative to the listed directory, with `/` separators on every system.
	Path string
	// Kind is symlink for a symbolic link, which is listed as such and not followed.
	Kind FileKind
}

FileListEntry is one entry of a FileListing.

type FileListing

type FileListing struct {
	// Entries run depth first, parents before their entries, siblings in byte order of their names.
	Entries []FileListEntry
	// Truncated is whether a bound in ListFilesOptions ended the listing early.
	Truncated bool
}

FileListing is the result of FileSystem.ListFiles.

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)
	// ListFiles is upstream's optional `listFiles?`: the files, directories and symbolic links below a directory, at any
	// depth, for indexes such as file completion. Symbolic links are not followed; other kinds of files are not listed;
	// entries that cannot be read are skipped. It fails with a not_supported FileError when the environment cannot list
	// right now (an older remote daemon, or an environment without a lister, where upstream leaves the method undefined),
	// so callers fall back to their own walk. options may be nil.
	ListFiles(ctx context.Context, path string, options *ListFilesOptions) (FileListing, 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 ListFilesOptions

type ListFilesOptions struct {
	// Hidden includes names starting with `.` (on Windows also files with the hidden attribute); nil means true.
	// Entries named `.git` are never listed.
	Hidden *bool
	// Gitignore skips, inside a git work tree, what git ignores: the `.gitignore` files of the directory, its
	// subdirectories and its parents, `.git/info/exclude`, and the global excludes file; nil means true. Unlike
	// `git ls-files`, a tracked file that matches an ignore rule is skipped too. Outside work trees, `.gitignore` files
	// have no effect.
	Gitignore *bool
	// Exclude names entries to skip with everything below them, such as `node_modules`.
	Exclude []string
	// MaxEntries is the most entries to list; nil means 50 000.
	MaxEntries *float64
	// MaxBytes is the most bytes of the listing, each entry's UTF-8 path plus two; nil means 4 MiB, at most 15.9 MiB.
	MaxBytes *float64
	// TimeoutMs is the time after which the listing stops; nil means 10 000 ms.
	TimeoutMs *float64
}

ListFilesOptions configure FileSystem.ListFiles; a nil field takes its default.

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

type RemoveOptions struct {
	Recursive bool
	Force     bool
}

RemoveOptions configures FileSystem.Remove.

type Result

type Result[TValue, TError any] struct {
	Ok    bool
	Value TValue
	Error TError
}

Result is the value or the expected failure of a fallible operation.

func Err

func Err[TValue, TError any](err TError) Result[TValue, TError]

Err returns a failed result.

func Ok

func Ok[TValue, TError any](value TValue) Result[TValue, TError]

Ok returns a successful result.

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. It has the shape of output.OutputSkip from chord/output, which OutputBuffer.PushStringSkipping accepts.

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 TextLine

type TextLine struct {
	Text       string `json:"text"`
	Terminated bool   `json:"terminated"`
}

TextLine is one line read by a TextLineReader.

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

type WatchExclude struct {
	// Hidden excludes names starting with ".".
	Hidden bool
	Names  []string
}

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.

Directories

Path Synopsis
Package node is the local execution environment of pi-durable: NodeExecutionEnv runs on the host file system and shell.
Package node is the local execution environment of pi-durable: NodeExecutionEnv runs on the host file system and shell.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL