@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.
- package/README.md +17 -57
- 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,
|
|
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
|
-
|
|
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
|
-
`
|
|
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
|
-
|
|
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
|
-
|
|
44
|
+
## Configure and run
|
|
41
45
|
|
|
42
|
-
|
|
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
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
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.
|
|
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",
|