Documentation
¶
Overview ¶
Package node is the local execution environment of pi-durable: NodeExecutionEnv runs on the host file system and shell. It is a separate package, as upstream's env/node subpath, so the portable env package loads no host package.
Index ¶
- type NodeExecutionEnv
- func (env *NodeExecutionEnv) AbsolutePath(_ context.Context, path string) (string, error)
- func (env *NodeExecutionEnv) AppendFile(ctx context.Context, path string, content any) error
- func (env *NodeExecutionEnv) CanonicalPath(ctx context.Context, path string) (string, error)
- func (env *NodeExecutionEnv) Cleanup(context.Context) error
- func (env *NodeExecutionEnv) CreateDir(ctx context.Context, path string, options *durableenv.CreateDirOptions) error
- func (env *NodeExecutionEnv) CreateTempDir(ctx context.Context, prefix *string) (string, error)
- func (env *NodeExecutionEnv) CreateTempFile(ctx context.Context, options *durableenv.CreateTempFileOptions) (string, error)
- func (env *NodeExecutionEnv) Cwd() string
- func (env *NodeExecutionEnv) Exec(ctx context.Context, command any, options *durableenv.ShellExecOptions) (durableenv.ShellExecResult, error)
- func (env *NodeExecutionEnv) Exists(ctx context.Context, path string) (bool, error)
- func (env *NodeExecutionEnv) FileInfo(ctx context.Context, path string) (durableenv.FileInfo, error)
- func (env *NodeExecutionEnv) FlushFile(ctx context.Context, path string) error
- func (env *NodeExecutionEnv) Id() string
- func (env *NodeExecutionEnv) JoinPath(_ context.Context, parts []string) (string, error)
- func (env *NodeExecutionEnv) ListDir(ctx context.Context, path string) ([]durableenv.FileInfo, error)
- func (env *NodeExecutionEnv) ListFiles(ctx context.Context, path string, options *durableenv.ListFilesOptions) (durableenv.FileListing, error)
- func (env *NodeExecutionEnv) OpenBinaryReader(ctx context.Context, path string, options *durableenv.OpenBinaryReaderOptions) (durableenv.BinaryReader, error)
- func (env *NodeExecutionEnv) OpenDirReader(ctx context.Context, path string) (durableenv.DirReader, error)
- func (env *NodeExecutionEnv) OpenTextLineReader(ctx context.Context, path string) (durableenv.TextLineReader, error)
- func (env *NodeExecutionEnv) ReadBinaryFile(ctx context.Context, path string) ([]byte, error)
- func (env *NodeExecutionEnv) ReadTextFile(ctx context.Context, path string) (string, error)
- func (env *NodeExecutionEnv) ReadTextLines(ctx context.Context, path string, options *durableenv.ReadTextLinesOptions) ([]string, error)
- func (env *NodeExecutionEnv) Remove(ctx context.Context, path string, options *durableenv.RemoveOptions) error
- func (env *NodeExecutionEnv) RenameFile(ctx context.Context, sourcePath, destinationPath string) error
- func (env *NodeExecutionEnv) SetCwd(cwd string)
- func (env *NodeExecutionEnv) TruncateFile(ctx context.Context, path string, size int64) error
- func (env *NodeExecutionEnv) Watch(ctx context.Context, targets []durableenv.WatchTarget, ...) (durableenv.FileWatcher, error)
- func (env *NodeExecutionEnv) WriteFile(ctx context.Context, path string, content any) error
- type NodeExecutionEnvOptions
- type NodeWatchOptions
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type NodeExecutionEnv ¶
type NodeExecutionEnv struct {
// Self is the environment the methods of this one call for their own
// building blocks: Exec creates its spill file with Self.CreateTempFile,
// Exists calls Self.FileInfo, ReadTextLines calls Self.OpenTextLineReader,
// and CreateTempFile calls Self.CreateTempDir. A type that embeds
// NodeExecutionEnv and overrides one of those methods sets Self to itself,
// which is the dispatch a TypeScript subclass gets from this. It defaults to
// the NodeExecutionEnv.
Self durableenv.ExecutionEnv
// contains filtered or unexported fields
}
NodeExecutionEnv is the host-OS execution environment: filesystem access and bash command execution. Its name mirrors the upstream Node.js implementation.
func NewNodeExecutionEnv ¶
func NewNodeExecutionEnv(options NodeExecutionEnvOptions) *NodeExecutionEnv
NewNodeExecutionEnv constructs an environment rooted at options.Cwd.
func (*NodeExecutionEnv) AbsolutePath ¶
AbsolutePath resolves path without requiring it to exist.
func (*NodeExecutionEnv) AppendFile ¶
AppendFile creates or appends to path with content, a string or []byte, creating parent directories.
func (*NodeExecutionEnv) CanonicalPath ¶
CanonicalPath resolves every symlink in an existing path.
func (*NodeExecutionEnv) Cleanup ¶
func (env *NodeExecutionEnv) Cleanup(context.Context) error
Cleanup terminates every active command's process tree. It is best-effort and returns nil.
func (*NodeExecutionEnv) CreateDir ¶
func (env *NodeExecutionEnv) CreateDir(ctx context.Context, path string, options *durableenv.CreateDirOptions) error
CreateDir creates a directory; Recursive defaults to true.
func (*NodeExecutionEnv) CreateTempDir ¶
CreateTempDir creates a directory named prefix plus six random characters under the OS temp directory; prefix defaults to "tmp-".
func (*NodeExecutionEnv) CreateTempFile ¶
func (env *NodeExecutionEnv) CreateTempFile(ctx context.Context, options *durableenv.CreateTempFileOptions) (string, error)
CreateTempFile creates an empty file named prefix + UUID + suffix inside a fresh temporary directory.
func (*NodeExecutionEnv) Cwd ¶
func (env *NodeExecutionEnv) Cwd() string
Cwd is the directory relative paths resolve against.
func (*NodeExecutionEnv) Exec ¶
func (env *NodeExecutionEnv) Exec(ctx context.Context, command any, options *durableenv.ShellExecOptions) (durableenv.ShellExecResult, error)
Exec runs command in the environment's cwd (or options.Cwd). A string runs through bash; a []string runs its first element directly with the rest as its arguments, without a shell. Every decoded chunk of stdout and stderr goes to options.OnOutput as it arrives, with the stream it came from; options.Window is not used, so every chunk is delivered. A non-zero exit is a successful result. Cancellation of ctx, the timeout, a failing OnOutput, and a failed requested spill each kill the process tree of this command and fail the call.
func (*NodeExecutionEnv) Exists ¶
Exists reports false for missing paths and other failures as errors.
func (*NodeExecutionEnv) FileInfo ¶
func (env *NodeExecutionEnv) FileInfo(ctx context.Context, path string) (durableenv.FileInfo, error)
FileInfo returns metadata without following symlinks.
func (*NodeExecutionEnv) FlushFile ¶
func (env *NodeExecutionEnv) FlushFile(ctx context.Context, path string) error
FlushFile flushes the contents of path, and the metadata needed to retrieve them from an open file handle, to stable storage.
func (*NodeExecutionEnv) Id ¶
func (env *NodeExecutionEnv) Id() string
Id is the file namespace: every local environment sees the same files.
func (*NodeExecutionEnv) JoinPath ¶
JoinPath joins and normalizes path segments like Node's path.join.
func (*NodeExecutionEnv) ListDir ¶
func (env *NodeExecutionEnv) ListDir(ctx context.Context, path string) ([]durableenv.FileInfo, error)
ListDir lists direct children in directory order without following symlinks; unsupported file types are omitted.
func (*NodeExecutionEnv) ListFiles ¶
func (env *NodeExecutionEnv) ListFiles(ctx context.Context, path string, options *durableenv.ListFilesOptions) (durableenv.FileListing, error)
ListFiles fails with not_supported: upstream's NodeExecutionEnv leaves the optional listFiles undefined. LocalExecutionEnv in the env package adds it through a pi-env daemon.
func (*NodeExecutionEnv) OpenBinaryReader ¶
func (env *NodeExecutionEnv) OpenBinaryReader(ctx context.Context, path string, options *durableenv.OpenBinaryReaderOptions) (durableenv.BinaryReader, error)
OpenBinaryReader opens a regular file for bounded positional reads. A directory fails with is_directory, other non-regular files with invalid; with NoFollow a symbolic link as the final path component fails with invalid.
func (*NodeExecutionEnv) OpenDirReader ¶
func (env *NodeExecutionEnv) OpenDirReader(ctx context.Context, path string) (durableenv.DirReader, error)
OpenDirReader opens a directory for paged listing; metadata is read only for returned entries.
func (*NodeExecutionEnv) OpenTextLineReader ¶
func (env *NodeExecutionEnv) OpenTextLineReader(ctx context.Context, path string) (durableenv.TextLineReader, error)
OpenTextLineReader opens path for pull-based line reading.
func (*NodeExecutionEnv) ReadBinaryFile ¶
ReadBinaryFile reads path.
func (*NodeExecutionEnv) ReadTextFile ¶
ReadTextFile reads path as UTF-8, replacing invalid sequences.
func (*NodeExecutionEnv) ReadTextLines ¶
func (env *NodeExecutionEnv) ReadTextLines(ctx context.Context, path string, options *durableenv.ReadTextLinesOptions) ([]string, error)
ReadTextLines reads up to options.MaxLines lines; a non-positive limit returns no lines.
func (*NodeExecutionEnv) Remove ¶
func (env *NodeExecutionEnv) 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 (*NodeExecutionEnv) RenameFile ¶
func (env *NodeExecutionEnv) RenameFile(ctx context.Context, sourcePath, destinationPath string) error
RenameFile atomically renames sourcePath over destinationPath.
func (*NodeExecutionEnv) SetCwd ¶
func (env *NodeExecutionEnv) SetCwd(cwd string)
SetCwd changes the directory relative paths resolve against.
func (*NodeExecutionEnv) TruncateFile ¶
TruncateFile truncates or extends path to exactly size bytes; it never creates the file. A size that is negative or above JavaScript's largest safe integer is invalid.
func (*NodeExecutionEnv) Watch ¶
func (env *NodeExecutionEnv) Watch(ctx context.Context, targets []durableenv.WatchTarget, onChange func(durableenv.WatchChange)) (durableenv.FileWatcher, error)
Watch reports changes to the targets; see FileSystem.Watch. Coverage is established when it returns: the watchers come first, then the snapshot later changes are compared with.
type NodeExecutionEnvOptions ¶
type NodeExecutionEnvOptions struct {
Cwd string
// ShellPath is an explicit bash executable; empty selects the platform
// default.
ShellPath string
// ShellEnv is layered over the inherited process environment for every
// command.
ShellEnv map[string]string
// Watch configures FileSystem.Watch.
Watch NodeWatchOptions
}
NodeExecutionEnvOptions configure a NodeExecutionEnv.
type NodeWatchOptions ¶
type NodeWatchOptions struct {
// Mode forces a mode. By default polling is chosen on Windows, where native watchers keep directories open and so
// block renaming their parents, and for file systems that do not report remote changes.
Mode durableenv.WatchMode
// PollIntervalMs is the interval between snapshots in polling mode; nil is the default 2000 ms. Like a Node timer delay,
// a value below 1 or above 2^31-1 waits 1 ms.
PollIntervalMs *int
// MaxDirectories is the most directories one watcher covers; nil is the default 10,000. Any set value is the limit, so
// 0 refuses every directory.
MaxDirectories *int
}
NodeWatchOptions is how NodeExecutionEnv watches.