@struktoai/mirage-node 0.0.8-alpha.1 → 0.0.8

package/dist/mount/core.d.ts

@@ -1,313 +0,0 @@
-import { type Files } from '@struktoai/mirage-core/workspace/files';
-import { FileTable } from '@struktoai/mirage-core/runtime/handles/index';
-import { FileStat } from '@struktoai/mirage-core/types';
-import type { SessionState } from '@struktoai/mirage-core/workspace/session/session';
-import type { MountAttrs, Handle } from './types.ts';
-export interface MountCoreOptions {
-    rootPrefix?: string;
-    /**
-     * Bind every op to this session's mount grants. The kernel-tier
-     * primitive: bind-mount the tree into a container and the narrowing
-     * travels with it. Enforcement happens inside dispatch/Files via the
-     * session context, so binding at the op entry point is sufficient.
-     */
-    session?: SessionState;
-}
-/**
- * Protocol-neutral mount logic shared by every kernel adapter.
- *
- * Everything here is expressed in POSIX terms (attribute records, ordinary
- * thrown errors) and imports nothing from `@zkochan/fuse-native`, so it is
- * reusable by a non-FUSE adapter and unit-testable without a kernel.
- *
- * The division of labour: this class decides *what* the filesystem
- * contains, an adapter decides *how* to say it to a particular kernel
- * interface. Adapters translate the errors thrown here into their own
- * error codes with `classifyErrno`. Mirrors Python's `MountCore`.
- *
- * Every op goes through `ws.vfs`, which delegates to the dispatcher, so
- * a mount walks the same dispatcher as a shell line (mount modes, policies,
- * cache, invalidation) and every op it runs lands on the `ws.vfs.records`
- * ledger. Reaching `ws.dispatch` from here instead would skip the record;
- * reaching a backend directly would skip the dispatcher.
- */
-export declare class MountCore {
-    readonly files: Files;
-    readonly session: SessionState | null;
-    private readonly now;
-    private readonly root;
-    readonly handles: FileTable<Handle>;
-    private readonly hydrations;
-    private readonly hydrationGen;
-    private readonly pending;
-    private readonly removals;
-    private readonly opening;
-    private readonly uid;
-    private readonly gid;
-    constructor(files: Files, options?: MountCoreOptions);
-    /**
-     * Run one op under the bound session's mount grants and profile, as the
-     * Python MountCore binds each op: dispatch reads the session from
-     * context, so binding at the op entry point is what scopes a kernel or
-     * SFTP mount to it. Unbound, an op runs as whatever session is current.
-     */
-    private op;
-    resolve(path: string): string;
-    dirStat(): MountAttrs;
-    /**
-     * The attrs for one stat row, the way a guest's stat reads it. The row
-     * carries the namespace overlay (chmod bits, chown ids, a touched mtime),
-     * so what a metadata op stored is what the mount shows, and a device
-     * keeps its type and numbers. String uid/gid (names) fall back to the
-     * mounting user: the kernel wants numbers and there is no user db to map
-     * against. A missing stamp falls back to the mount's start time; epoch
-     * zero is a real time and lands. `size` replaces the row's, from an open
-     * handle or a link's shown target. Mirrors Python's `MountCore.attrs`.
-     */
-    attrs(s: FileStat, size?: number | null): MountAttrs;
-    /**
-     * The target to present for a link at a mount path. Relative targets are
-     * stored verbatim and returned as-is. Absolute targets name virtual
-     * paths, so they are rewritten relative to the link's directory: returned
-     * raw, the kernel would resolve them against the host root and escape
-     * the mountpoint.
-     */
-    shownTarget(path: string, target: string): string;
-    /**
-     * The length of the bytes an open handle on the file holds. A size-unknown
-     * file is read whole when it opens, so while a handle is open its length
-     * answers a stat by path too (`ls -l` beside a `cat`). Once every handle
-     * is released, the dispatcher answers from the workspace cache instead.
-     * Mirrors Python's `held_size`.
-     */
-    heldSize(path: string): number | null;
-    /**
-     * Read a size-unknown file whole for the handle opening it, through the
-     * dispatcher, so a caching mount keeps the bytes for the next open and for
-     * a stat once this one closes. Undefined when the read fails: open() stays
-     * permissive and the read() that follows surfaces the error. Mirrors
-     * Python's `_hydrate`.
-     */
-    private hydrate;
-    /**
-     * Run one mutation of a file after every mutation already queued for
-     * it, and let the next one wait for it. Serialization is per identity,
-     * so a flush through a link and a truncate through its target queue
-     * behind each other, and a flush still landing cannot be overtaken by a
-     * truncate that would then be undone when the flush completes.
-     */
-    private mutate;
-    /**
-     * Run `fn` holding the chain of every key, taken in sorted order so two
-     * callers that hold the same pair never wait on each other. Mirrors
-     * Python's `_queue_all`.
-     */
-    private queueAll;
-    /**
-     * Run `fn`, which removes, replaces or moves the files at `paths`, after
-     * the opens of those names already out, with later ones held back until
-     * it is done, as the kernel orders an open and an unlink or a rename of
-     * one name. `hold` reads the rest for the handles open before; an open
-     * that slipped in while that read was out would get a chunked handle onto
-     * bytes about to go. Chains of their own, taken before any `pending` one,
-     * rather than `pending` itself: an open they wait for may be truncating
-     * there.
-     */
-    private removing;
-    /**
-     * Run `fn` after every call already queued under `key` in `queues`, and
-     * let the next one wait for it, whether it resolves or throws.
-     */
-    private queue;
-    /**
-     * Land write runs on the mount, one pwrite each, in order. A pwrite keeps
-     * every stored byte the handle did not write, so nothing is read through
-     * the dispatcher first: a session that may write a file and not read it writes
-     * through FUSE, as through a write-only descriptor. The runs that landed
-     * leave `runs` in one step, so after a failure `runs` holds only what did
-     * not land and a retry never replays a run over bytes another writer has
-     * since put there. A run that fails still invalidates what the core holds,
-     * since the runs before it have landed.
-     */
-    private applyWrites;
-    /**
-     * POSIX attributes for a path. One stat through the dispatcher answers: a
-     * link the session cannot see is absent, as it is to the shell, and a
-     * visible one reports its own row with its target read through the
-     * dispatcher too. `follow` reports a trailing link's target rather than
-     * the link (stat rather than lstat).
-     */
-    getattr(path: string, follow?: boolean, ctx?: Handle | null): Promise<MountAttrs>;
-    /**
-     * Attributes through an open handle: the path's row, with the size the
-     * handle holds, what it wrote and has not flushed included.
-     */
-    fgetattr(path: string, fd: number): Promise<MountAttrs>;
-    /**
-     * The mount root's attrs: its own row through the dispatcher, so a chmod
-     * made on it shows, or a plain directory when nothing answers for it (a
-     * workspace with no mount at `/`). Mirrors Python's `root_attrs`.
-     */
-    rootAttrs(): Promise<MountAttrs>;
-    readdir(path: string): Promise<string[]>;
-    read(path: string, fd: number, pos: number, len: number): Promise<Uint8Array>;
-    /** Buffer a write on its handle, or apply it directly when there is none. */
-    write(path: string, fd: number, data: Uint8Array, pos: number): Promise<void>;
-    /**
-     * Cut a new write's range out of what the file's other handles hold:
-     * their bytes there are older, and the new write replaces them. No two
-     * handles on a file then hold the same bytes, so whichever flush, release
-     * or sync lands first, the file ends as its writes were made. Nothing
-     * lands here, so a write never waits on one.
-     */
-    private supersede;
-    /**
-     * Create an empty file and return a fresh handle. `mode` is what the
-     * creator asked for, umask applied; null takes the mount's default.
-     */
-    create(path: string, mode?: number | null): Promise<number>;
-    /** Create a directory, keeping the mode it was asked for. */
-    mkdir(path: string, mode?: number | null): Promise<void>;
-    /**
-     * Store the mode a create asked for, when it is not the one the backend
-     * made the entry with (a disk mount applies the daemon's umask), so
-     * `open(O_CREAT, 0600)` and `mkdir -m` read back as asked without a
-     * write per ordinary create. Mirrors Python's `_keep_mode`.
-     */
-    private keepMode;
-    /** The target of a namespace link, read through the dispatcher; EINVAL when not a link. */
-    readlink(path: string): Promise<string>;
-    /**
-     * Create namespace link `dest -> src` (ln -s src dest; libfuse passes
-     * the pointee first). Relative sources are stored verbatim (resolved
-     * at follow time, exactly like the shell `ln -s`); absolute sources
-     * are mapped into virtual space so a scoped mount stores the path it
-     * will later follow.
-     */
-    symlink(src: string, dest: string): Promise<void>;
-    /**
-     * Remove the entry at `path`, a link entry like any other.
-     *
-     * A link routes through the dispatcher rather than straight to the node
-     * table: `unlink` is a LINK_ENTRY_OPS member, so the dispatcher answers a
-     * link path itself, gated by session grants and admission policies
-     * and recorded on the ledger. Writing the table here instead let a
-     * session-scoped kernel mount delete a link on a mount its profile
-     * hides. Mirrors Python's MountCore.unlink.
-     */
-    unlink(path: string): Promise<void>;
-    /**
-     * The one function every mutation of a file's bytes goes through. The
-     * open handles on a file are matched by its identity (the mount path with
-     * namespace links followed), and this is the only place their bytes are
-     * refreshed, so a new mutating op cannot forget one of them and a link
-     * alias cannot slip past. A hydration still in flight is outdated so it
-     * re-reads instead of handing over what it fetched, and hydrated handles
-     * on the file are refreshed in one read through the dispatcher, so fstat
-     * and read through any of them, including the handle that wrote, see the
-     * new bytes. A removal or rename passes `rehydrate = false`: POSIX keeps
-     * an open descriptor on the bytes it had, and the name, not what it
-     * points at, is what changed. A refresh that fails is logged
-     * and leaves the handles unhydrated rather than failing the committed
-     * mutation. Mirrors Python's `_changed`.
-     */
-    private changed;
-    rename(src: string, dst: string): Promise<void>;
-    rmdir(path: string): Promise<void>;
-    /**
-     * Where a mount path really points: the mount-resolved path with every
-     * namespace link followed, so two handles opened through a link and
-     * its target are recognised as the same file.
-     */
-    identity(path: string, follow?: boolean): string;
-    /**
-     * Persist a handle's buffered writes. The buffer is detached before the
-     * await so a write arriving meanwhile is not lost to the clear, and the
-     * runs that did not land are restored ahead of those later writes when
-     * persistence fails, so the acknowledged bytes stay for the handle's own
-     * flush to retry.
-     */
-    private settle;
-    /** The handles open on the entry at `path` itself. */
-    private named;
-    /**
-     * The handles open on the file `key` names. A detached handle is on a file
-     * with no name left, whatever its key says.
-     */
-    private openOn;
-    /** Land the buffered writes of every handle open on `key`. */
-    private landBuffered;
-    private persistBuffered;
-    truncate(path: string, size: number): Promise<void>;
-    statfs(): Record<string, number>;
-    /**
-     * Store metadata through the dispatcher. The backend keeps what it can and
-     * the namespace overlay the rest, so a chmod, chown or `touch -d` through
-     * the mount is what `stat` in a shell reads back, on a backend with no
-     * permission bits or settable times of its own too. A null field is left
-     * as it is. Mirrors Python's `MountCore.setattr`.
-     */
-    setattr(path: string, mode: number | null, uid?: number | null, gid?: number | null, atime?: Date | null, mtime?: Date | null, follow?: boolean): Promise<void>;
-    /**
-     * Store an extended attribute through the dispatcher, which keeps
-     * it on the path's namespace node: it outlives the mount, moves with a
-     * rename, and is the attribute every other surface (the shell's
-     * getfattr, a guest's os.getxattr) reads. Tools that set xattrs as a
-     * matter of course (rsync -aX, tar --xattrs, cp -p, Finder writing
-     * com.apple.*) succeed on a backend with no attribute slot of its own.
-     * Mirrors the python MountCore.
-     */
-    setxattr(path: string, name: string, value: Uint8Array, opts?: {
-        create?: boolean;
-        replace?: boolean;
-    }): Promise<void>;
-    /** One attribute, the backend's own facts included; ENODATA when unset. */
-    getxattr(path: string, name: string): Promise<Uint8Array>;
-    listxattr(path: string): Promise<string[]>;
-    removexattr(path: string, name: string): Promise<void>;
-    open(path: string, flags?: number): Promise<number>;
-    /** The open itself, which a removal of its name waits for. */
-    private openPath;
-    /**
-     * A removal of `path` still running. One is keyed by the name it takes, so
-     * an open through a link meets the link's removal and then its target's.
-     */
-    private removalOf;
-    /**
-     * Keep what the handles open on `path` need once it goes, and return the
-     * row they stat by from then on. POSIX keeps an open descriptor on the
-     * file it had, so an unlink or a rename onto it must not leave a handle
-     * reading or stat'ing the file at that name next. A handle holding no
-     * bytes yet (never read, or chunked and holding one chunk) gets them all
-     * from one read every such handle shares; it runs under `removing` and
-     * the file's `pending` chain, so no handle opens on the file and no write
-     * lands on it meanwhile. The handles are matched by the
-     * entry itself, so removing a link holds nothing: it takes the link,
-     * never its target's bytes. A stat or a read that fails (a policy may
-     * allow the removal and refuse either) leaves a bare row or the handles
-     * as they are, each on its own, rather than refusing a mutation the
-     * caller is allowed. Mirrors Python's `MountCore._hold`.
-     */
-    private hold;
-    /**
-     * Wait for a flush or truncation of the handle's file still landing, into
-     * the queue a rename moved the handle to. Mirrors Python's `_settled`.
-     */
-    private settled;
-    /**
-     * Land a handle's buffered writes and let it go. The handle goes even
-     * when the landing fails, as close(2) releases its descriptor: no
-     * adapter retries a release, so a kept handle would never close. The
-     * failure still reaches the caller.
-     */
-    release(fd: number): Promise<void>;
-    flush(_path: string, fd: number): Promise<void>;
-    /**
-     * Land what every open handle holds, as sync(2) does, for a client whose
-     * close(2) returns before it releases the handle (sshfs). A landing that
-     * fails is logged, and its bytes stay on the handle for its own flush to
-     * retry and report.
-     */
-    sync(): Promise<void>;
-}
-//# sourceMappingURL=core.d.ts.map

package/dist/mount/core.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/mount/core.ts"],"names":[],"mappings":"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"}