node

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: 29 Imported by: 0

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

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

func (env *NodeExecutionEnv) AbsolutePath(_ context.Context, path string) (string, error)

AbsolutePath resolves path without requiring it to exist.

func (*NodeExecutionEnv) AppendFile

func (env *NodeExecutionEnv) AppendFile(ctx context.Context, path string, content any) error

AppendFile creates or appends to path with content, a string or []byte, creating parent directories.

func (*NodeExecutionEnv) CanonicalPath

func (env *NodeExecutionEnv) CanonicalPath(ctx context.Context, path string) (string, error)

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

func (env *NodeExecutionEnv) CreateTempDir(ctx context.Context, prefix *string) (string, error)

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

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

func (env *NodeExecutionEnv) Exists(ctx context.Context, path string) (bool, error)

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

func (env *NodeExecutionEnv) JoinPath(_ context.Context, parts []string) (string, error)

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

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

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

func (env *NodeExecutionEnv) ReadBinaryFile(ctx context.Context, path string) ([]byte, error)

ReadBinaryFile reads path.

func (*NodeExecutionEnv) ReadTextFile

func (env *NodeExecutionEnv) ReadTextFile(ctx context.Context, path string) (string, error)

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

func (env *NodeExecutionEnv) TruncateFile(ctx context.Context, path string, size int64) error

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

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.

func (*NodeExecutionEnv) WriteFile

func (env *NodeExecutionEnv) WriteFile(ctx context.Context, path string, content any) error

WriteFile creates or overwrites path with content, a string or []byte, creating parent directories.

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.

Jump to

Keyboard shortcuts

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