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 ¶
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 ¶
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 ¶
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 ¶
InstallLoop is Install on a loop of package eventloop.
func (*API) Close ¶
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.
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.
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. 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.