node

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Nov 15, 2026 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Overview

Package node installs a part of Node.js's built-in modules into a moejs runtime that runs on an event loop: node:fs and node:fs/promises over one directory of the host, and node:buffer with its Buffer class. It is meant for sandboxes, where a program reads and perhaps writes the files of a workspace and nothing else.

imp := node.Importer(hostImporter) // serves node:fs, node:fs/promises, node:buffer
rt := moejs.NewRuntime(moejs.Options{Importer: imp})
loop, err := eventloop.New(rt, eventloop.Options{})
api, err := node.InstallLoop(loop, node.Options{
	FS:     &node.FSOptions{Root: "/srv/ws/123", Mount: "/workspace"},
	Buffer: true, // the global Buffer
})
defer api.Close()
err = loop.Run(func(rt *moejs.Runtime) error { ... })

The modules are small ES modules, compiled once per process, that Importer and Resolver return for the specifiers "node:fs", "node:fs/promises" and "node:buffer" and their bare forms "fs", "fs/promises" and "buffer". Each reads what it exports from its import.meta, which Install fills for its own runtime: a runtime without Install, or one whose Options have no FS for node:fs, fails the import with an Error that says so.

Sandbox

Every path is resolved inside FSOptions.Root through an os.Root, so neither ".." nor a symbolic link leaves it. JavaScript sees Root at FSOptions.Mount, and relative paths resolve against FSOptions.Cwd. A path outside the mount, and one that a link or ".." takes out of the root, fails with EACCES. Writes fail with EROFS unless FSOptions.Write is set, and FSOptions.Allow sees every access first. See the package's documentation in docs/guide.md for the whole contract and the deviations from Node.js.

Event loop and resources

The loop is package eventloop's (InstallLoop) or the host's own, which gives the package what Loop names: a way to run a task on the runtime's goroutine and a hold that keeps it alive. The synchronous functions run on the loop, as in Node.js. The promise and callback forms run their file system work on a bounded pool of goroutines (FSOptions.Workers) and settle on the loop, in a task of its tasks phase; an operation in flight keeps Run alive. What they hand to JavaScript, file contents, listings and names, is charged to the runtime's memory limit (moejs.Options.MemoryLimit) on the loop, and a file larger than the limit is refused before it is read.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Importer

func Importer(next *moejs.Importer) *moejs.Importer

Importer returns an Importer whose Resolve is Resolver(next.Resolve) and whose Meta is next's: the host's Importer with the package's modules added. next may be nil. Like any Importer, the result may serve any number of runtimes.

func Resolver

func Resolver(next moejs.Resolver) moejs.Resolver

Resolver returns a Resolver that resolves the specifiers of the package, "node:fs", "node:fs/promises", "node:buffer", "fs", "fs/promises" and "buffer", to its modules, and passes every other to next. A nil next resolves no other specifier: a "node:" one fails with Node's message, "No such built-in module: node:path", any other with "Cannot find module". The modules are compiled once per process; each exports what Install put in its runtime.

Types

type API

type API struct {
	// contains filtered or unexported fields
}

API is the modules installed in one runtime.

func Install

func Install(loop Loop, opts Options) (*API, error)

Install installs the package into the loop's runtime: the bindings that the modules of Importer and Resolver export in it, and the global Buffer when opts.Buffer is set. It is called once per runtime, while the loop does not run or on the loop. It wraps the import.meta hook of the runtime's Importer, so the runtime keeps the Importer it was created with.

func InstallLoop

func InstallLoop(loop *eventloop.Loop, opts Options) (*API, error)

InstallLoop is Install on a loop of package eventloop.

func (*API) Close

func (a *API) Close() error

Close closes the root directory and ends the operations that wait for a worker: their promises reject, and their callbacks are called, with an EBADF error the next time the loop runs. Operations that a worker runs finish first. A file system function called after Close fails with EBADF. Close may be called from any goroutine, and more than once.

type FSOptions

type FSOptions struct {
	// Root is the directory of the host that the file system is: every
	// path resolves inside it. It must exist. Install opens it, and the
	// directory stays the same one if it is renamed later.
	Root string
	// Mount is the absolute path at which JavaScript sees Root, such as
	// "/workspace". An absolute path JavaScript gives must lie under it,
	// and realpath and glob return paths under it. Empty means Root
	// itself. On Windows it may also have a drive ("C:\work", "c:/work")
	// or be a share ("\\server\share\work"); without either, as
	// "/workspace", it has no volume, and a rooted path (\x) is on the
	// volume of Cwd. Paths are read as Node.js reads them there: either
	// separator, "." and ".." cleaned before the check against Mount,
	// which ignores case, and the paths the package makes have
	// backslashes and Mount's own spelling.
	Mount string
	// Cwd is the directory relative paths resolve against, as
	// process.cwd() is in Node.js: an absolute path under Mount, or a
	// path relative to Mount. Empty means Mount. On Windows it takes the
	// forms of Mount, and a drive-relative path (C:x) resolves against it
	// on its drive.
	Cwd string
	// Write allows the functions that change the file system: writeFile,
	// appendFile, mkdir, rm, rmdir, unlink, rename, copyFile and cp.
	// Without it they fail with EROFS.
	Write bool
	// Allow, when not nil, approves each access before it is made. op is
	// "read" for one that reads (contents, listings, metadata) and "write"
	// for one that changes the file system, as in Node.js's permission
	// model. path is the absolute path in JavaScript's view (under Mount)
	// with every symbolic link resolved, so that a link cannot dodge the
	// policy; a path that does not exist yet has its existing part
	// resolved. On Windows it has backslashes, and Mount's spelling of
	// the part that is Mount. An error fails the operation: one that
	// errors.Is finds fs.ErrNotExist fails it with ENOENT, a syscall.Errno
	// with that
	// errno, any other with EACCES. It is called on the loop for the
	// synchronous functions and on a worker goroutine for the others, so
	// concurrently.
	Allow func(op, path string) error
	// Workers bounds how many promise and callback operations do their
	// file system work at once; the others wait in a queue. 0 means 4,
	// the size of libuv's pool.
	Workers int
	// NoDescriptorCache turns off, on Linux, the cache of the descriptors
	// of the directories an operation looked in within the last
	// millisecond, which makes a stat or an open of a name in one a
	// single system call. A cached descriptor follows its directory if
	// another process renames it, out of the root too, for up to that
	// millisecond: set this when other processes may rearrange the tree
	// while the program runs. See docs/guide.md.
	NoDescriptorCache bool
}

FSOptions configures node:fs.

type Loop

type Loop interface {
	// Runtime returns the loop's runtime.
	Runtime() *moejs.Runtime
	// Post queues task to run on the runtime's goroutine, outside any
	// JavaScript call, as the loop runs a callback, and reports whether
	// it took it: false once the loop is over, and the task is dropped.
	// It is called from any goroutine. The loop handles the task's error
	// as a callback's: an *moejs.InterruptedError, such as the memory
	// limit's, stops the program, and so does an exception, which a
	// callback of the callback form throws as an uncaught exception does
	// in Node.js. The task runs the promise jobs it queues before it
	// returns.
	Post(task func(*moejs.Runtime) error) bool
	// Hold keeps the loop alive until release is called: a loop with no
	// other work waits for the tasks that a held operation posts rather
	// than end. Hold is called on the runtime's goroutine, release from
	// any goroutine, once, after the operation's Post.
	Hold() (release func())
}

Loop is what the package needs of the event loop its runtime runs on: a way to run a task on the runtime's goroutine, and a hold that keeps the loop alive while work is in flight. A promise or callback operation takes a hold when it starts, on the runtime's goroutine, and when its work is done posts the task that settles it and then releases the hold. InstallLoop adapts package eventloop's loop; a host that drives its own loop implements Loop.

type Options

type Options struct {
	// FS gives the runtime node:fs and node:fs/promises over a directory
	// of the host. Nil means no file system: importing them fails.
	FS *FSOptions
	// Buffer defines the global Buffer, as Node.js has it. node:buffer
	// can be imported either way.
	Buffer bool
}

Options configures Install.

Jump to

Keyboard shortcuts

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