@effect-vfs/nfs 0.7.1 → 0.8.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.
Files changed (2) hide show
  1. package/README.md +17 -57
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -7,8 +7,7 @@ to mount a fixture and observe live updates.
7
7
  The scoped server supports TCP or a UNIX-domain socket, metadata and directory reads, symlinks, regular-file reads,
8
8
  and NFSv4.1 sessions. Mutations return `NFS4ERR_ROFS` by default. Explicit `writable: true` requires a volume whose
9
9
  `durability` is at least `survives-power-loss`; the server rejects weaker volumes before listening. It is not a conformant NFSv4.1 server: RFC 8881 requires
10
- RPCSEC_GSS with Kerberos, which this package excludes. It also omits delegations, write locks, layouts, migration,
11
- and recovery. Backchannels and connection trunking are implemented, but the server grants no delegation or layout to
10
+ RPCSEC_GSS with Kerberos, which this package excludes. It also omits delegations, layouts, migration, and restart recovery. Backchannels and connection trunking are implemented, but the server grants no delegation or layout to
12
11
  recall.
13
12
 
14
13
  ## Supported profile and maturity
@@ -22,11 +21,16 @@ The package describes what it does with a capability profile and how well that i
22
21
  | `writable` | create, write, rename, remove, durable `WRITE` and `COMMIT`, share reservations, and advisory byte-range locks | experimental |
23
22
  | `stateful` | grace and reclaim, restart recovery of sessions, opens, and locks | not public |
24
23
 
25
- 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.
24
+ `read-only-local` has recorded macOS, Linux, and pinned pynfs read-side checks. The preview app's
25
+ [conformance baseline](../../apps/nfs-preview/CONFORMANCE.md) records the tested clients and remaining failures.
26
+ Mount explicitly with NFSv4.1. The package excludes NFSv4.0, NFSv4.2, and RPCSEC_GSS.
26
27
 
27
- `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.
28
+ `NfsServer.make` and `NfsServer.layer` accept local `{ volume, caller }` or networked `{ volume, policy, peer }`
29
+ options. Both require an Effect `SocketServer`. Local mode accepts loopback TCP or a UNIX-domain socket.
30
+ Networked mode requires an application identity policy and `allowNonLoopback: true` to bind elsewhere.
28
31
 
29
- `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`.
32
+ Read locks are advisory between NFS clients. Direct VFS callers do not participate. Write locks return
33
+ `NFS4ERR_ROFS` in read-only mode. Lease expiry and client revocation remove in-memory lock state.
30
34
 
31
35
  The optional `writable: true` profile is limited to one gateway owning one qualified live volume. The application
32
36
  must prevent another gateway from opening the same storage image; the server does not provide a distributed lease.
@@ -37,60 +41,16 @@ whose commits survive at least a process crash they persist across a restart and
37
41
  `FH4_PERSISTENT`. The key's tag keeps a client from forging a handle for an object by guessing its inode number. Sessions, opens, and locks do not survive, so remount clients after gateway restart; this is not
38
42
  the `stateful` recovery profile. Do not set a stronger `Volume.durability` for an unqualified storage provider.
39
43
 
40
- 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).
44
+ ## Configure and run
41
45
 
42
- `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.
46
+ Start with the [local NFS guide](../../apps/docs/app/content/guides/local-nfs.mdx) for a complete server program.
47
+ The [API reference](../../apps/docs/app/content/api/nfs/nfs-server.mdx) lists configuration, schemas, and finite
48
+ resource limits. Byte limits use Effect `ByteSize`.
43
49
 
44
- The following configuration assumes an existing `volume` and `caller`. The preview app supplies both in a complete
45
- runnable example.
46
-
47
- ```ts
48
- import { NfsServer } from "@effect-vfs/nfs/NfsServer"
49
- import * as BunSocketServer from "@effect/platform-bun/BunSocketServer"
50
- import * as ByteSize from "effect/ByteSize"
51
- import * as Effect from "effect/Effect"
52
-
53
- const program = Effect.scoped(
54
- NfsServer.make({
55
- volume,
56
- caller,
57
- limits: { maxReadBytes: ByteSize.mebibytes(4) }
58
- })
59
- ).pipe(
60
- Effect.provide(BunSocketServer.layer({ host: "127.0.0.1", port: 2049 }))
61
- )
62
- ```
63
-
64
- 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:
65
-
66
- ```ts
67
- import * as NodeSocket from "@effect/platform-node-shared/NodeSocket"
68
- import * as Effect from "effect/Effect"
69
- import * as Option from "effect/Option"
70
-
71
- const peer = Effect.map(
72
- Effect.serviceOption(NodeSocket.NetSocket),
73
- Option.match({
74
- onNone: () => null,
75
- onSome: (socket) =>
76
- socket.remoteAddress === undefined || socket.remotePort === undefined
77
- ? null
78
- : { transport: "tcp" as const, address: socket.remoteAddress, port: socket.remotePort }
79
- })
80
- )
81
-
82
- const networked = NfsServer.make({
83
- volume,
84
- peer,
85
- allowNonLoopback: true,
86
- policy: ({ credential, peer }) => {
87
- if (peer.transport !== "tcp" || peer.address !== "192.0.2.10" || credential.flavor !== "sys") return null
88
- return { uid: credential.uid, gid: credential.gid, groups: credential.groups, privileged: false }
89
- }
90
- })
91
- ```
92
-
93
- 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.
50
+ In local mode, one supplied caller performs every read. `AUTH_SYS` credentials grant no VFS authority.
51
+ In networked mode, the application resolves each socket's peer and maps its credentials to a VFS identity or denies
52
+ access. Applications own the trusted-client policy. See the
53
+ [authentication and export policy](../../.okf/decisions/nfs/nfs-authentication-and-export-policy.md) for that contract.
94
54
 
95
55
  The package never mounts a filesystem and never invokes `sudo`. The repository's standalone
96
56
  [`@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,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@effect-vfs/nfs",
3
- "version": "0.7.1",
3
+ "version": "0.8.0",
4
4
  "description": "NFSv4.1 server for one live Effect VFS volume, with guarded experimental writes.",
5
5
  "homepage": "https://github.com/lloydrichards/effect-virtual-fs#readme",
6
6
  "license": "MIT",