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 ¶
- func GetOrThrow[TValue any, TError error](result Result[TValue, TError]) (TValue, error)
- func GetOrUndefined[TValue, TError any](result Result[*TValue, TError]) *TValue
- func ToError(value any) error
- type CreateDirOptions
- type CreateTempFileOptions
- type ExecutionEnv
- type ExecutionError
- type ExecutionErrorCode
- type FileError
- type FileErrorCode
- type FileInfo
- type FileKind
- type FileSystem
- type ReadTextLinesOptions
- type RemoveOptions
- type Result
- type Shell
- type ShellExecOptions
- type ShellExecResult
- type ShellSpillOptions
- type TextLine
- type TextLineReader
Constants ¶
This section is empty.
Variables ¶
This section is empty.
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.
Types ¶
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 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)
// 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)
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 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 Shell ¶
type Shell interface {
Exec(ctx context.Context, command string, options *ShellExecOptions) (ShellExecResult, error)
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 combined stdout and stderr as it arrives: raw, unbounded, and
// unthrottled.
OnOutput func(ctx context.Context, text string)
Spill *ShellSpillOptions
}
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 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.