@effect-vfs/nfs 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2023 Effectful Technologies Inc
4
+ Copyright (c) 2026 Lloyd Richards
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,93 @@
1
+ # @effect-vfs/nfs
2
+
3
+ Read-only NFSv4.1 export for exposing one live Effect VFS volume to native tools. The package is an experimental beta. Its local read-only profile has `preview` evidence; its trusted-network profile remains `experimental`.
4
+
5
+ This package runs a scoped socket server over TCP or a UNIX-domain socket and implements the bounded NFSv4.1 session, metadata, directory, symlink, and regular-file read path. It is not a conformant NFSv4.1 server and no future profile will claim to be one: RFC 8881 requires RPCSEC_GSS with Kerberos, which this package permanently excludes because no viable server-side implementation exists in the JavaScript ecosystem. It also omits delegations, write locks, layouts, migration, and recovery. Backchannels and connection trunking are implemented, but nothing is ever recalled over a backchannel because no delegation or layout is ever granted. Mutating filesystem operations return `NFS4ERR_ROFS`.
6
+
7
+ ## Supported profile and maturity
8
+
9
+ The package describes what it does with a capability profile and how well that is evidenced with a maturity label. The two are tracked separately; see the [NFS profile ladder](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.okf/decisions/nfs/nfs-profile-ladder.md) for definitions and the evidence each maturity level requires.
10
+
11
+ | Profile | What it adds | Maturity |
12
+ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
13
+ | `read-only-local` | complete read path, `NFS4ERR_ROFS` on mutation, loopback binding, `AUTH_SYS` accepted as untrusted, backchannel and connection binding | preview |
14
+ | `read-only-networked` | `AUTH_SYS` identity mapped to VFS callers by application policy, non-loopback binding behind that policy and an explicit opt-in | experimental |
15
+ | `writable` | create, write, rename, remove, durable `WRITE` and `COMMIT`, share reservations, and advisory byte-range locks | not public |
16
+ | `stateful` | grace and reclaim, restart recovery, persistent filehandles | not public |
17
+
18
+ The current read-only export tracks advisory byte-range read locks between NFS clients. `LOCK` requires an open stateid; `LOCKU` releases an exact range. Write locks still return `NFS4ERR_ROFS`. `maxLockOwners` and `maxLocks` bound the in-memory state, which is removed on lease expiry or client revocation. Direct VFS callers do not participate in NFS locks.
19
+
20
+ `read-only-local` is currently `preview`: the protocol test suites pass, scripted macOS 26.6.2 and Linux kernel-client mounts each pass every read-side check, and a pinned pynfs run with every failure classified is recorded in the preview app's [conformance baseline](https://github.com/lloydrichards/effect-virtual-fs/blob/main/apps/nfs-preview/CONFORMANCE.md). The Linux mount is a repeatable opt-in CI gate rather than a manual run. Per-requirement status against RFC 8881 lives in the [operations](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.okf/research/nfs/nfs-operations-ledger.md), [attributes](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.okf/research/nfs/nfs-attributes-ledger.md), and [protocol rules](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.okf/research/nfs/nfs-protocol-rules-ledger.md) ledgers. NFSv4.0 and NFSv4.2 are out of scope; mount with `vers=4.1` explicitly.
21
+
22
+ `NfsServer.make` and `NfsServer.layer` accept local `{ volume, caller }` or networked `{ volume, policy, peer }` options. Both require an Effect `SocketServer`; the application chooses and binds its platform implementation. Local mode accepts only loopback TCP or a UNIX-domain socket. Networked mode can bind elsewhere only with `allowNonLoopback: true`. The server defaults to a 30-second lease, a 30-second callback timeout, and finite resource limits. RPCSEC_GSS credentials are refused with `AUTH_TOOWEAK`.
23
+
24
+ In local mode, one application-supplied caller performs every read. Decoded `AUTH_SYS` fields never grant VFS authority, and ACCESS answers derived from them are advisory. In networked mode, the application supplies a peer resolver evaluated for each accepted socket and a policy that maps the decoded credential and peer to a VFS identity or denies it. The server creates and caches callers per distinct identity, bounded by `maxIdentities`. Policy denials and cache exhaustion answer RPC `AUTH_FAILED` before the compound executes. A resolver returning `null` closes the connection. UNIX peers have `address: null` and `port: null`; `path` is the server socket path, not a client address. Applications must enforce their trusted-client boundary in the policy. This profile is experimental: protocol and socket tests pass, but a networked kernel-client gate has not been recorded. See the [authentication and export policy decision](https://github.com/lloydrichards/effect-virtual-fs/blob/main/.okf/decisions/nfs/nfs-authentication-and-export-policy.md).
25
+
26
+ `NfsServerConfig`, `NfsServerConfigOverrides`, `NfsServerLimits`, `NfsServerLimitOverrides`, `NfsServerAddress`, `NfsServerTcpAddress`, `NfsServerNetworkTcpAddress`, and `NfsServerUnixAddress` are public Effect schemas. Byte limits use `effect/ByteSize`, so their units are explicit and validated before the server converts them to the numeric representation used by XDR. `NfsServerConfig.default`, `NfsServerLimits.default`, and `NfsServerLimits.constrained` expose frozen complete policies. Callers can override only the settings they need. `Volume`, `Caller`, and `SocketServer` remain live Effect capabilities rather than schema data.
27
+
28
+ ```ts
29
+ import { NfsServer } from "@effect-vfs/nfs/NfsServer"
30
+ import * as BunSocketServer from "@effect/platform-bun/BunSocketServer"
31
+ import * as ByteSize from "effect/ByteSize"
32
+ import * as Effect from "effect/Effect"
33
+
34
+ const program = Effect.scoped(
35
+ NfsServer.make({
36
+ volume,
37
+ caller,
38
+ limits: { maxReadBytes: ByteSize.mebibytes(4) }
39
+ })
40
+ ).pipe(
41
+ Effect.provide(BunSocketServer.layer({ host: "127.0.0.1", port: 2049 }))
42
+ )
43
+ ```
44
+
45
+ For Node or Bun networked mode, the resolver can read `NodeSocket.NetSocket` from each connection's Effect context. The policy must check the peer before mapping a credential to authority:
46
+
47
+ ```ts
48
+ import * as NodeSocket from "@effect/platform-node-shared/NodeSocket"
49
+ import * as Effect from "effect/Effect"
50
+ import * as Option from "effect/Option"
51
+
52
+ const peer = Effect.map(
53
+ Effect.serviceOption(NodeSocket.NetSocket),
54
+ Option.match({
55
+ onNone: () => null,
56
+ onSome: (socket) =>
57
+ socket.remoteAddress === undefined || socket.remotePort === undefined
58
+ ? null
59
+ : { transport: "tcp" as const, address: socket.remoteAddress, port: socket.remotePort }
60
+ })
61
+ )
62
+
63
+ const networked = NfsServer.make({
64
+ volume,
65
+ peer,
66
+ allowNonLoopback: true,
67
+ policy: ({ credential, peer }) => {
68
+ if (peer.transport !== "tcp" || peer.address !== "192.0.2.10" || credential.flavor !== "sys") return null
69
+ return { uid: credential.uid, gid: credential.gid, groups: credential.groups, privileged: false }
70
+ }
71
+ })
72
+ ```
73
+
74
+ Provide the platform `SocketServer` and `Crypto` services and run this Effect in a scope, as in the local example. The peer address check above is only an example; applications choose their own trusted-client policy.
75
+
76
+ The package never mounts a filesystem and never invokes `sudo`. The repository's standalone
77
+ [`@repo/nfs-preview`](https://github.com/lloydrichards/effect-virtual-fs/blob/main/apps/nfs-preview/README.md) app provides a runnable fixture and complete macOS mount,
78
+ verification, troubleshooting, and cleanup instructions. Start it from the repository root with:
79
+
80
+ ```sh
81
+ bun run --filter @repo/nfs-preview start
82
+ ```
83
+
84
+ Applications continue writing through the VFS API while native clients read the mounted view. Stop the server,
85
+ unmount, and mount again after a restart because filehandles and sessions are intentionally volatile.
86
+
87
+ Run the focused checks from this directory:
88
+
89
+ ```sh
90
+ bun run type-check
91
+ bun run test
92
+ bun run build
93
+ ```