@jsonjoy.com/json-pack 1.21.0 → 17.59.0

package/lib/nfs/v4/server/operations/OpenFileState.js

@@ -1,8 +1,59 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenFileState = void 0;
+/**
+ * Open file state record for NFSv4 OPEN operations.
+ * Tracks state for an individual file that has been opened by a client,
+ * including the stateid, file descriptor, share reservations, and confirmation status.
+ */
 class OpenFileState {
-    constructor(stateid, path, fd, shareAccess, shareDeny, openOwnerKey, seqid, confirmed) {
+    constructor(
+    /**
+     * Stateid assigned to this open file.
+     * Used by client to identify this particular open in subsequent operations
+     * (CLOSE, OPEN_DOWNGRADE, READ, WRITE, etc.).
+     */
+    stateid, 
+    /**
+     * Absolute file system path of the opened file.
+     * Used to identify the file and check for share reservation conflicts.
+     */
+    path, 
+    /**
+     * Node.js file descriptor/handle for the opened file.
+     * Used to perform I/O operations and must be closed when the file is closed.
+     */
+    fd, 
+    /**
+     * Share access mode - which operations this open allows.
+     * Bitwise OR of OPEN4_SHARE_ACCESS_READ, OPEN4_SHARE_ACCESS_WRITE.
+     * Controls what the opener can do with the file.
+     */
+    shareAccess, 
+    /**
+     * Share deny mode - which operations this open denies to others.
+     * Bitwise OR of OPEN4_SHARE_DENY_READ, OPEN4_SHARE_DENY_WRITE, or OPEN4_SHARE_DENY_NONE.
+     * Controls what conflicting operations are blocked for other opens.
+     */
+    shareDeny, 
+    /**
+     * Key identifying the open-owner that opened this file.
+     * Format: `${clientid}:${base64(owner)}`.
+     * Links this open back to the owner for sequence number management.
+     */
+    openOwnerKey, 
+    /**
+     * Sequence number for this open.
+     * Used to detect replayed or out-of-order operations.
+     * Incremented on OPEN_CONFIRM and OPEN_DOWNGRADE.
+     */
+    seqid, 
+    /**
+     * Whether this open has been confirmed via OPEN_CONFIRM.
+     * NFSv4.0 requires new opens from new open-owners to be confirmed.
+     * Once confirmed, the open can be used for READ/WRITE operations.
+     */
+    confirmed) {
         this.stateid = stateid;
         this.path = path;
         this.fd = fd;

package/lib/nfs/v4/server/operations/OpenFileState.js.map

@@ -1 +1 @@
-{"version":3,"file":"OpenFileState.js","sourceRoot":"","sources":["../../../../../src/nfs/v4/server/operations/OpenFileState.ts"],"names":[],"mappings":";;;AAQA,MAAa,aAAa;IACxB,YAMkB,OAA4B,EAM5B,IAAY,EAMZ,EAAc,EAOvB,WAAmB,EAOnB,SAAiB,EAOR,YAAoB,EAO7B,KAAa,EAOb,SAAkB;QA/CT,YAAO,GAAP,OAAO,CAAqB;QAM5B,SAAI,GAAJ,IAAI,CAAQ;QAMZ,OAAE,GAAF,EAAE,CAAY;QAOvB,gBAAW,GAAX,WAAW,CAAQ;QAOnB,cAAS,GAAT,SAAS,CAAQ;QAOR,iBAAY,GAAZ,YAAY,CAAQ;QAO7B,UAAK,GAAL,KAAK,CAAQ;QAOb,cAAS,GAAT,SAAS,CAAS;IACxB,CAAC;CACL;AAxDD,sCAwDC"}
+{"version":3,"file":"OpenFileState.js","sourceRoot":"","sources":["../../../../../src/nfs/v4/server/operations/OpenFileState.ts"],"names":[],"mappings":";;;AAGA;;;;GAIG;AACH,MAAa,aAAa;IACxB;IACE;;;;OAIG;IACa,OAA4B;IAE5C;;;OAGG;IACa,IAAY;IAE5B;;;OAGG;IACa,EAAc;IAE9B;;;;OAIG;IACI,WAAmB;IAE1B;;;;OAIG;IACI,SAAiB;IAExB;;;;OAIG;IACa,YAAoB;IAEpC;;;;OAIG;IACI,KAAa;IAEpB;;;;OAIG;IACI,SAAkB;QA/CT,YAAO,GAAP,OAAO,CAAqB;QAM5B,SAAI,GAAJ,IAAI,CAAQ;QAMZ,OAAE,GAAF,EAAE,CAAY;QAOvB,gBAAW,GAAX,WAAW,CAAQ;QAOnB,cAAS,GAAT,SAAS,CAAQ;QAOR,iBAAY,GAAZ,YAAY,CAAQ;QAO7B,UAAK,GAAL,KAAK,CAAQ;QAOb,cAAS,GAAT,SAAS,CAAS;IACxB,CAAC;CACL;AAxDD,sCAwDC"}

package/lib/nfs/v4/server/operations/OpenOwnerState.d.ts

@@ -1,9 +1,83 @@
+/**
+ * Open-owner state record for NFSv4 OPEN operations.
+ * An open-owner represents a single entity (process, thread) on a client
+ * that can open files. Tracks all opens made by this owner and manages
+ * sequence numbers for serialization.
+ */
 export declare class OpenOwnerState {
+    /**
+     * Client ID that owns this open-owner.
+     * Links the owner back to the specific NFS client that created it.
+     */
     readonly clientid: bigint;
+    /**
+     * Opaque owner identifier provided by the client.
+     * Typically represents a process or thread ID on the client.
+     * Combined with clientid, uniquely identifies this open-owner.
+     */
     readonly owner: Uint8Array;
+    /**
+     * Sequence number for operations from this open-owner.
+     * Used to serialize OPEN/CLOSE/OPEN_CONFIRM/OPEN_DOWNGRADE operations.
+     * Incremented after each successful stateful operation.
+     * Server rejects operations with incorrect sequence numbers to prevent replays.
+     */
     seqid: number;
+    /**
+     * Set of stateid keys for all files currently opened by this owner.
+     * Format: stateid keys are `${seqid}:${base64(other)}`.
+     * Used to track all active opens and clean them up if the owner goes away.
+     */
     readonly opens: Set<string>;
-    lastResponse?: any;
+    /**
+     * Cached response from the last successful operation.
+     * Per RFC 7530 §9.1.7, when a client retries with the same seqid (replay),
+     * the server must return the cached response instead of re-executing the operation.
+     * This ensures idempotency for operations like OPEN, OPEN_CONFIRM, OPEN_DOWNGRADE, CLOSE.
+     */
+    lastResponse?: any | undefined;
+    /**
+     * Signature of the last OPEN request. Used to distinguish true replays
+     * (identical requests) from clients that reuse seqids with different
+     * parameters, which must be rejected with BAD_SEQID.
+     */
     lastRequestKey?: string | undefined;
-    constructor(clientid: bigint, owner: Uint8Array, seqid: number, opens?: Set<string>, lastResponse?: any, lastRequestKey?: string | undefined);
+    constructor(
+    /**
+     * Client ID that owns this open-owner.
+     * Links the owner back to the specific NFS client that created it.
+     */
+    clientid: bigint, 
+    /**
+     * Opaque owner identifier provided by the client.
+     * Typically represents a process or thread ID on the client.
+     * Combined with clientid, uniquely identifies this open-owner.
+     */
+    owner: Uint8Array, 
+    /**
+     * Sequence number for operations from this open-owner.
+     * Used to serialize OPEN/CLOSE/OPEN_CONFIRM/OPEN_DOWNGRADE operations.
+     * Incremented after each successful stateful operation.
+     * Server rejects operations with incorrect sequence numbers to prevent replays.
+     */
+    seqid: number, 
+    /**
+     * Set of stateid keys for all files currently opened by this owner.
+     * Format: stateid keys are `${seqid}:${base64(other)}`.
+     * Used to track all active opens and clean them up if the owner goes away.
+     */
+    opens?: Set<string>, 
+    /**
+     * Cached response from the last successful operation.
+     * Per RFC 7530 §9.1.7, when a client retries with the same seqid (replay),
+     * the server must return the cached response instead of re-executing the operation.
+     * This ensures idempotency for operations like OPEN, OPEN_CONFIRM, OPEN_DOWNGRADE, CLOSE.
+     */
+    lastResponse?: any | undefined, 
+    /**
+     * Signature of the last OPEN request. Used to distinguish true replays
+     * (identical requests) from clients that reuse seqids with different
+     * parameters, which must be rejected with BAD_SEQID.
+     */
+    lastRequestKey?: string | undefined);
 }

package/lib/nfs/v4/server/operations/OpenOwnerState.js

@@ -1,8 +1,51 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenOwnerState = void 0;
+/**
+ * Open-owner state record for NFSv4 OPEN operations.
+ * An open-owner represents a single entity (process, thread) on a client
+ * that can open files. Tracks all opens made by this owner and manages
+ * sequence numbers for serialization.
+ */
 class OpenOwnerState {
-    constructor(clientid, owner, seqid, opens = new Set(), lastResponse, lastRequestKey) {
+    constructor(
+    /**
+     * Client ID that owns this open-owner.
+     * Links the owner back to the specific NFS client that created it.
+     */
+    clientid, 
+    /**
+     * Opaque owner identifier provided by the client.
+     * Typically represents a process or thread ID on the client.
+     * Combined with clientid, uniquely identifies this open-owner.
+     */
+    owner, 
+    /**
+     * Sequence number for operations from this open-owner.
+     * Used to serialize OPEN/CLOSE/OPEN_CONFIRM/OPEN_DOWNGRADE operations.
+     * Incremented after each successful stateful operation.
+     * Server rejects operations with incorrect sequence numbers to prevent replays.
+     */
+    seqid, 
+    /**
+     * Set of stateid keys for all files currently opened by this owner.
+     * Format: stateid keys are `${seqid}:${base64(other)}`.
+     * Used to track all active opens and clean them up if the owner goes away.
+     */
+    opens = new Set(), 
+    /**
+     * Cached response from the last successful operation.
+     * Per RFC 7530 §9.1.7, when a client retries with the same seqid (replay),
+     * the server must return the cached response instead of re-executing the operation.
+     * This ensures idempotency for operations like OPEN, OPEN_CONFIRM, OPEN_DOWNGRADE, CLOSE.
+     */
+    lastResponse, 
+    /**
+     * Signature of the last OPEN request. Used to distinguish true replays
+     * (identical requests) from clients that reuse seqids with different
+     * parameters, which must be rejected with BAD_SEQID.
+     */
+    lastRequestKey) {
         this.clientid = clientid;
         this.owner = owner;
         this.seqid = seqid;

package/lib/nfs/v4/server/operations/OpenOwnerState.js.map

@@ -1 +1 @@
-{"version":3,"file":"OpenOwnerState.js","sourceRoot":"","sources":["../../../../../src/nfs/v4/server/operations/OpenOwnerState.ts"],"names":[],"mappings":";;;AAMA,MAAa,cAAc;IACzB,YAKkB,QAAgB,EAOhB,KAAiB,EAQ1B,KAAa,EAOJ,QAAqB,IAAI,GAAG,EAAE,EAQvC,YAAkB,EAOlB,cAAuB;QArCd,aAAQ,GAAR,QAAQ,CAAQ;QAOhB,UAAK,GAAL,KAAK,CAAY;QAQ1B,UAAK,GAAL,KAAK,CAAQ;QAOJ,UAAK,GAAL,KAAK,CAAyB;QAQvC,iBAAY,GAAZ,YAAY,CAAM;QAOlB,mBAAc,GAAd,cAAc,CAAS;IAC7B,CAAC;CACL;AA7CD,wCA6CC"}
+{"version":3,"file":"OpenOwnerState.js","sourceRoot":"","sources":["../../../../../src/nfs/v4/server/operations/OpenOwnerState.ts"],"names":[],"mappings":";;;AAAA;;;;;GAKG;AACH,MAAa,cAAc;IACzB;IACE;;;OAGG;IACa,QAAgB;IAEhC;;;;OAIG;IACa,KAAiB;IAEjC;;;;;OAKG;IACI,KAAa;IAEpB;;;;OAIG;IACa,QAAqB,IAAI,GAAG,EAAE;IAE9C;;;;;OAKG;IACI,YAAkB;IAEzB;;;;OAIG;IACI,cAAuB;QArCd,aAAQ,GAAR,QAAQ,CAAQ;QAOhB,UAAK,GAAL,KAAK,CAAY;QAQ1B,UAAK,GAAL,KAAK,CAAQ;QAOJ,UAAK,GAAL,KAAK,CAAyB;QAQvC,iBAAY,GAAZ,YAAY,CAAM;QAOlB,mBAAc,GAAd,cAAc,CAAS;IAC7B,CAAC;CACL;AA7CD,wCA6CC"}

package/lib/nfs/v4/server/operations/node/Nfsv4OperationsNode.d.ts

@@ -1,5 +1,4 @@
-/// <reference types="node" />
-import { Nfsv4OperationCtx, Nfsv4Operations } from '../Nfsv4Operations';
+import type { Nfsv4OperationCtx, Nfsv4Operations } from '../Nfsv4Operations';
 import * as msg from '../../../messages';
 import * as struct from '../../../structs';
 import { ClientRecord } from '../ClientRecord';
@@ -11,39 +10,102 @@ import { LockStateid } from '../LockStateid';
 import { FilesystemStats } from '../FilesystemStats';
 import { FileHandleMapper } from './fh';
 export interface Nfsv4OperationsNodeOpts {
+    /** Node.js `fs` module. */
     fs: typeof import('node:fs');
+    /**
+     * Absolute path to the root directory to serve. This is some directory on the
+     * host filesystem that the NFS server will use as its root.
+     */
     dir: string;
+    /**
+     * Maximum number of confirmed clients to allow.
+     * @default 1000
+     */
     maxClients?: number;
+    /**
+     * Maximum number of pending clients to allow.
+     * @default 1000
+     */
     maxPendingClients?: number;
+    /**
+     * Optional function to provide filesystem statistics.
+     * If not provided, defaults to 2TB available space and 2M available inodes.
+     */
     fsStats?: () => Promise<FilesystemStats>;
 }
+/**
+ * NFS v4 Operations implementation for Node.js `fs` filesystem.
+ */
 export declare class Nfsv4OperationsNode implements Nfsv4Operations {
     protected readonly fs: typeof import('node:fs');
-    protected readonly promises: (typeof import('node:fs'))['promises'];
+    protected readonly promises: typeof import('node:fs')['promises'];
     protected dir: string;
+    /**
+     * Lease time in seconds.
+     * Per RFC 7530 §9.5, this is the time a client has to renew its lease
+     * before the server may reclaim its state. Default is 90 seconds.
+     */
     protected readonly leaseTime: number;
+    /** Confirmed clients. */
     protected clients: Map<bigint, ClientRecord>;
+    /** Clients pending SETCLIENTID_CONFIRM confirmation. */
     protected pendingClients: Map<bigint, ClientRecord>;
+    /** Maximum number of client records to keep. */
     protected maxClients: number;
+    /** Maximum number of pending client records to keep. */
     protected maxPendingClients: number;
+    /** Next client ID to assign. */
     protected nextClientId: bigint;
+    /** Boot stamp, identifies server instance, 16 bits. */
     protected bootStamp: number;
     protected readonly fh: FileHandleMapper;
+    /** Next stateid sequence number. */
     protected nextStateidSeqid: number;
+    /** Map from stateid (as string key) to open file state. */
     protected openFiles: Map<string, OpenFileState>;
+    /** Map from open-owner key to owner state. */
     protected openOwners: Map<string, OpenOwnerState>;
+    /** Map from lock key to byte-range lock. */
     protected locks: Map<string, ByteRangeLock>;
+    /** Map from lock-owner key to lock-owner state. */
     protected lockOwners: Map<string, LockOwnerState>;
+    /** Map from lock stateid 'other' field to lock stateid state. Per RFC 7530, one stateid per lock-owner per file. */
     protected lockStateids: Map<string, LockStateid>;
+    /**
+     * Server-wide monotonic change counter for directory change_info.
+     * Incremented on every mutating operation (RENAME, REMOVE, CREATE, etc.).
+     * Used to populate change_info4 before/after values for client cache validation.
+     */
     protected changeCounter: bigint;
+    /**
+     * Function to retrieve filesystem statistics.
+     */
     protected fsStats: () => Promise<FilesystemStats>;
     constructor(opts: Nfsv4OperationsNodeOpts);
+    /**
+     * Default filesystem statistics: 2TB available space, 2M available inodes.
+     */
     protected defaultFsStats: () => Promise<FilesystemStats>;
     protected findClientByIdString(map: Map<bigint, ClientRecord>, clientIdString: Uint8Array): [bigint, ClientRecord] | undefined;
     protected enforceClientLimit(): void;
     protected enforcePendingClientLimit(): void;
     protected makeOpenOwnerKey(clientid: bigint, owner: Uint8Array): string;
+    /**
+     * Validates a seqid from a client request against the owner's current seqid.
+     * Per RFC 7530 §9.1.7, the server expects seqid = last_seqid + 1 for new operations,
+     * or seqid = last_seqid for replayed requests (idempotent retry).
+     *
+     * @param requestSeqid - seqid from the client request
+     * @param ownerSeqid - current seqid stored for the owner
+     * @returns 'valid' if seqid matches expected next value, 'replay' if it matches last value, 'invalid' otherwise
+     */
     protected validateSeqid(requestSeqid: number, ownerSeqid: number): 'valid' | 'replay' | 'invalid';
+    /**
+     * Renews the lease for a client.
+     * Per RFC 7530 §9.5, any stateful operation renews the client's lease.
+     *
+     * @param clientid - The client ID whose lease should be renewed
+     */
     protected renewClientLease(clientid: bigint): void;
     protected makeStateidKey(stateid: struct.Nfsv4Stateid): string;
     protected createStateid(): struct.Nfsv4Stateid;
@@ -57,7 +119,15 @@ export declare class Nfsv4OperationsNode implements Nfsv4Operations {
     protected getOrCreateLockStateid(lockOwnerKey: string, path: string): LockStateid;
     protected findLockStateidByOther(other: Uint8Array): LockStateid | undefined;
     protected hasConflictingLock(path: string, locktype: number, offset: bigint, length: bigint, ownerKey: string): boolean;
+    /**
+     * Establishes client ID or updates callback information.
+     * Returns a client ID and confirmation verifier for SETCLIENTID_CONFIRM.
+     */
     SETCLIENTID(request: msg.Nfsv4SetclientidRequest, ctx: Nfsv4OperationCtx): Promise<msg.Nfsv4SetclientidResponse>;
+    /**
+     * Confirms a client ID established by SETCLIENTID.
+     * Transitions unconfirmed client record to confirmed state.
+     */
     SETCLIENTID_CONFIRM(request: msg.Nfsv4SetclientidConfirmRequest, ctx: Nfsv4OperationCtx): Promise<msg.Nfsv4SetclientidConfirmResponse>;
     ILLEGAL(request: msg.Nfsv4IllegalRequest, ctx: Nfsv4OperationCtx): Promise<msg.Nfsv4IllegalResponse>;
     PUTROOTFH(request: msg.Nfsv4PutrootfhRequest, ctx: Nfsv4OperationCtx): Promise<msg.Nfsv4PutrootfhResponse>;