@zenfs/core 2.7.1 → 2.7.2

package/README.md

@@ -43,6 +43,9 @@ Your financial support would go a long way toward improving ZenFS and its commun
 
 ## Usage
 
+> [!IMPORTANT]
+> **[Check out the ZenFS docs!](https://zenfs.dev/start/usage/)**
+
 ```js
 import { fs } from '@zenfs/core'; // You can also use the default export
 
@@ -52,15 +55,9 @@ const contents = fs.readFileSync('/test.txt', 'utf-8');
 console.log(contents);
 ```
 
-#### Using different and/or multiple backends
-
-A single `InMemory` backend is created by default, mounted on `/`.
-
-You can configure ZenFS to use a different backend and mount multiple backends. It is strongly recommended to do so using the `configure` function.
-
-You can use multiple backends by passing an object to `configure` which maps paths to file systems.
-
-The following example mounts a zip file to `/zip`, in-memory storage to `/tmp`, and IndexedDB to `/home`. Note that `/` has the default in-memory backend.
+A single `InMemory` backend is created by default, mounted on `/`. To use different backends, and to
+mount more than one, configure ZenFS with `configure`. This mounts a zip file to `/mnt/zip`,
+in-memory storage to `/tmp`, and IndexedDB to `/home`:
 
 ```js
 import { configure, InMemory } from '@zenfs/core';
@@ -78,110 +75,16 @@ await configure({
 });
 ```
 
-Note that while you aren't required to use absolute paths for the keys of `mounts`, it is a good practice to do so.
-
-> [!TIP]
-> When configuring a mount point, you can pass in
->
-> 1. A `Backend` object, if the backend has no required options
-> 2. An object that has the options accepted by the backend and a `backend` property which is a `Backend` object
-> 3. A `FileSystem` instance
-
-Here is an example that mounts the `WebStorage` backend from `@zenfs/dom` on `/`:
-
-```js
-import { configureSingle, fs } from '@zenfs/core';
-import { WebStorage } from '@zenfs/dom';
-
-await configureSingle({ backend: WebStorage });
-
-if (!fs.existsSync('/test.txt')) {
-	fs.writeFileSync('/test.txt', 'This will persist across reloads!');
-}
-
-const contents = fs.readFileSync('/test.txt', 'utf-8');
-console.log(contents);
-```
-
-#### FS Promises
-
-The FS promises API is exposed as `promises`.
-
-```js
-import { configureSingle } from '@zenfs/core';
-import { exists, writeFile } from '@zenfs/core/promises';
-import { IndexedDB } from '@zenfs/dom';
-
-await configureSingle({ backend: IndexedDB });
-
-const exists = await exists('/myfile.txt');
-if (!exists) {
-	await writeFile('/myfile.txt', 'Lots of persistent data');
-}
-```
-
-> [!NOTE]
-> You can import the promises API using:
->
-> 1. Exports from `@zenfs/core/promises`
-> 2. The `promises` export from `@zenfs/core`
-> 3. `fs.promises` on the exported `fs` from `@zenfs/core`.
+The `fs/promises` API is available from `@zenfs/core/promises`, as the `promises` export, or as
+`fs.promises`.
 
-#### Mounting and unmounting, creating backends
-
-If you would like to create backends without configure (e.g. to do something dynamic at runtime), you may do so by importing the backend and calling `resolveMountConfig` with it.
-
-You can then mount and unmount the backend instance by using `mount` and `umount`.
-
-```js
-import { configure, resolveMountConfig, InMemory } from '@zenfs/core';
-import { IndexedDB } from '@zenfs/dom';
-import { Zip } from '@zenfs/archives';
-
-await configure({
-	mounts: {
-		'/tmp': InMemory,
-		'/home': IndexedDB,
-	},
-});
-
-fs.mkdirSync('/mnt/zip', { recursive: true });
-
-const res = await fetch('mydata.zip');
-const zipfs = await resolveMountConfig({ backend: Zip, data: await res.arrayBuffer() });
-fs.mount('/mnt/zip', zipfs);
-
-// do stuff with the mounted zip
-
-fs.umount('/mnt/zip'); // finished using the zip
-```
-
-> [!CAUTION]
-> Instances of backends follow the _internal_ API. You should never use a backend's methods unless you are extending a backend.
-
-### Devices and device files
-
-ZenFS includes support for device files. These are designed to follow Linux's device file behavior, for consistency and ease of use. Check out the [Devices and Device Drivers](https://zenfs.dev/core/documents/Devices_and_Device_Drivers) documentation for more information.
-
-## `node:*` emulation
-
-ZenFS also includes emulation of some other `node:` modules for various reasons, importable from `@zenfs/core/<name>`:
-
-- `node:path`
-- `node:readline`
-
-For example:
-
-```ts
-import * as path from '@zenfs/core/path';
-```
+For the full usage guide, see **[the documentation](https://zenfs.dev/start/usage/)**.
+This includes mounting at runtime, contexts and permissions, devices, and the `node:*`module emulation.
 
 ## Bundling
 
 ZenFS exports a drop-in for Node's `fs` module, so you can use it for your bundler of preference using the default export.
-
-> [!IMPORTANT]
-> See [COPYING.md](./COPYING.md)
+See [COPYING.md](./COPYING.md) for more info.
 
 ## Sponsors
 

package/dist/config.d.ts

@@ -56,6 +56,8 @@ export interface Configuration<T extends ConfigMounts> extends SharedConfig {
     /**
      * Whether to automatically add normal Linux devices
      * @default false
+     * @deprecated Use `@zenfs/linux`!
+     * @todo [breaking] remove
      */
     addDevices: boolean;
     /**
@@ -97,6 +99,8 @@ export declare function configureSingle<T extends Backend>(configuration: MountC
 export declare function configureSingleSync<T extends Backend>(configuration: MountConfiguration<T>): void;
 /**
  * @category Backends and Configuration
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare function addDevice(driver: DeviceDriver, options?: object): Device;
 /**

package/dist/config.js

@@ -189,6 +189,8 @@ function mountWithMkdirSync(path, fs) {
 }
 /**
  * @category Backends and Configuration
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export function addDevice(driver, options) {
     const devfs = defaultContext.mounts.get('/dev');

package/dist/context.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
 import { UV } from 'kerium';
 import { bindFunctions } from 'utilium';
-import { contextOf, createChildContext } from './internal/contexts.js';
+import { contextOf, createChildContext, defaultContext } from './internal/contexts.js';
 import * as fs from './node/index.js';
 import * as path from './path.js';
 import * as xattr from './vfs/xattr.js';
@@ -17,9 +17,9 @@ export const boundContexts = new Map();
  * @category Contexts
  */
 export function bindContext(init = {}) {
-    const $ = contextOf(this);
-    if (!fs.statSync.call(this, $.root).isDirectory())
-        throw UV('ENOTDIR', { syscall: 'chroot', path: $.root });
+    const $ = contextOf(this), parent = $.parent || defaultContext;
+    if (!fs.statSync.call(parent, parent.root).isDirectory())
+        throw UV('ENOTDIR', { syscall: 'chroot', path: parent.root });
     const ctx = createChildContext($, init);
     const bound = Object.assign(ctx, {
         fs: {

package/dist/internal/contexts.js

@@ -46,7 +46,7 @@ let _nextId = 2;
  */
 export function createChildContext(parent, init = {}) {
     assertContext(parent);
-    const { root = parent.root, pwd = parent.pwd, credentials = structuredClone(parent.credentials), mounts = Object.fromEntries(parent.mounts), } = init;
+    const { root = parent.root, pwd = parent.pwd, credentials = structuredClone(parent.credentials), mounts } = init;
     const ctx = {
         [kIsContext]: true,
         id: _nextId++,
@@ -56,7 +56,7 @@ export function createChildContext(parent, init = {}) {
         descriptors: new Map(),
         parent: parent,
         children: [],
-        mounts: new Map(Object.entries(mounts)),
+        mounts: mounts ? new Map(Object.entries(mounts)) : parent.mounts,
     };
     Object.defineProperties(ctx, {
         id: { configurable: false, writable: false },

package/dist/internal/devices.d.ts

@@ -4,10 +4,11 @@ import type { CreationOptions } from './filesystem.js';
 import { Inode, type InodeLike } from './inode.js';
 /**
  * A device
- * @todo Maybe add some other device information, like a UUID?
  * @category Internals
  * @privateRemarks
  * UUIDs were considered, however they don't make sense without an easy mechanism for persistence
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export interface Device<TData = any> {
     /**
@@ -34,6 +35,8 @@ export interface Device<TData = any> {
 }
 /**
  * @category Internals
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export interface DeviceInit<TData = any> {
     data?: TData;
@@ -45,6 +48,8 @@ export interface DeviceInit<TData = any> {
 /**
  * A device driver
  * @category Internals
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export interface DeviceDriver<TData = any> {
     /**
@@ -88,6 +93,8 @@ export interface DeviceDriver<TData = any> {
 /**
  * A temporary file system that manages and interfaces with devices
  * @category Internals
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare class DeviceFS extends StoreFS<InMemoryStore> {
     protected readonly devices: Map<string, Device<any>>;
@@ -132,6 +139,8 @@ export declare class DeviceFS extends StoreFS<InMemoryStore> {
  * - Writes discard data, advancing the file position.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const nullDevice: DeviceDriver;
 /**
@@ -144,6 +153,8 @@ export declare const nullDevice: DeviceDriver;
  * - Provides basic file metadata, treating it as a character device.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const zeroDevice: DeviceDriver;
 /**
@@ -152,6 +163,8 @@ export declare const zeroDevice: DeviceDriver;
  * - Writes always fail with ENOSPC (no space left on device).
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const fullDevice: DeviceDriver;
 /**
@@ -160,12 +173,16 @@ export declare const fullDevice: DeviceDriver;
  * - Writes discard data, advancing the file position.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const randomDevice: DeviceDriver;
 /**
  * Shortcuts for importing.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export declare const devices: {
     null: DeviceDriver<any>;

package/dist/internal/devices.js

@@ -13,6 +13,8 @@ import { Inode } from './inode.js';
 /**
  * A temporary file system that manages and interfaces with devices
  * @category Internals
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export class DeviceFS extends StoreFS {
     devices = new Map();
@@ -231,6 +233,8 @@ const emptyBuffer = new Uint8Array();
  * - Writes discard data, advancing the file position.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const nullDevice = {
     name: 'null',
@@ -255,6 +259,8 @@ export const nullDevice = {
  * - Provides basic file metadata, treating it as a character device.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const zeroDevice = {
     name: 'zero',
@@ -275,6 +281,8 @@ export const zeroDevice = {
  * - Writes always fail with ENOSPC (no space left on device).
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const fullDevice = {
     name: 'full',
@@ -295,6 +303,8 @@ export const fullDevice = {
  * - Writes discard data, advancing the file position.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const randomDevice = {
     name: 'random',
@@ -315,6 +325,8 @@ export const randomDevice = {
  * Simulates the `/dev/console` device.
  * @category Internals
  * @experimental @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 const consoleDevice = {
     name: 'console',
@@ -334,6 +346,8 @@ const consoleDevice = {
  * Shortcuts for importing.
  * @category Internals
  * @internal
+ * @deprecated Use `@zenfs/linux`!
+ * @todo [breaking] remove
  */
 export const devices = {
     null: nullDevice,

package/dist/vfs/shared.js

@@ -128,7 +128,7 @@ export function chroot(path) {
             throw UV('EBUSY', 'chroot', handle.path);
         handle.path = handle.path.slice($.root.length);
     }
-    if (newRoot.length > $.root.length)
+    if (newRoot.length < $.root.length)
         throw withErrno('EPERM', 'Can not chroot() outside of current root');
     $.root = newRoot;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zenfs/core",
-	"version": "2.7.1",
+	"version": "2.7.2",
 	"description": "A filesystem, anywhere",
 	"funding": {
 		"type": "individual",

package/tests/common/context.test.ts

@@ -1,5 +1,5 @@
 // SPDX-License-Identifier: LGPL-3.0-or-later
-import { bindContext, configure, fs, InMemory } from '@zenfs/core';
+import { bindContext, configure, fs, InMemory, type BoundContext } from '@zenfs/core';
 import assert from 'node:assert/strict';
 import { suite, test } from 'node:test';
 import { canary } from 'utilium';
@@ -124,4 +124,14 @@ suite('Context', () => {
 		assert.equal(ctx.readFileSync('/copy.txt', 'utf-8'), 'not in real root!');
 		assert(fs.readdirSync('/ctx').includes('copy.txt'));
 	});
+
+	test('bindContext should resolve root relative to the parent context', () => {
+		fs.mkdirSync('/secure');
+		const ctx = bindContext({ root: '/secure', credentials: { uid: 333, gid: 333 } });
+
+		const plain = bindContext({ credentials: { uid: 1, gid: 1 } });
+		console.log('child of / context: ok, root =', plain.root);
+
+		assert.doesNotThrow(() => ctx.bind({ credentials: { uid: 500, gid: 500 } }));
+	});
 });