|
| 1 | +# NFSv4.2 Implementation Plan |
| 2 | + |
| 3 | +This document extends the v4.1 upgrade effort with the additional requirements defined in RFC 7862. Each task lists a ready-to-use LLM prompt to accelerate implementation. |
| 4 | + |
| 5 | +## Prerequisites |
| 6 | + |
| 7 | +- Completed NFSv4.1 implementation (sessions, pNFS, recovery tooling) and passing integration suite. |
| 8 | +- Working knowledge of RFC 7862 sections describing server-side copy, sparse files, application I/O advice, ADB, and labeled NFS. |
| 9 | +- Filesystem backend capable of hole punching, cloning, and extended attributes (or mockable interfaces when unavailable). |
| 10 | + |
| 11 | +## Phase 1 · Protocol Additions |
| 12 | + |
| 13 | +| # | Task | Guidance | LLM Prompt | |
| 14 | +|---|------|----------|------------| |
| 15 | +| 1 | Expand opcode/attribute catalogs | Add v4.2 operations (`ALLOCATE`, `DEALLOCATE`, `READ_PLUS`, `COPY`, etc.) and new attributes (`clone_blksize`, `space_freed`, `change_attr_type`, `sec_label`, etc.) to constants, builders, and attribute maps. | `Update src/nfs/v4/constants.ts, builder.ts, and attributes.ts to include every opcode, error, and attribute introduced in RFC 7862. Ensure bitmap handling scales beyond current word count and extend unit tests covering the new ranges.` | |
| 16 | +| 2 | Implement message/struct support | Create classes and serializers for new requests/responses (COPY_NOTIFY, OFFLOAD_STATUS, IO_ADVISE, SEEK, xattr ops, etc.). | `Add TypeScript request/response classes for all NFSv4.2 operations, wiring them into the encoder/decoder stack. Provide fixtures and round-trip tests proving binary compatibility with RFC 7862 examples.` | |
| 17 | + |
| 18 | +## Phase 2 · Sparse File & I/O Enhancements |
| 19 | + |
| 20 | +| # | Task | Guidance | LLM Prompt | |
| 21 | +|---|------|----------|------------| |
| 22 | +| 3 | READ_PLUS pipeline | Implement READ_PLUS decoding/encoding, supporting data, hole, and sparse-aware elements. | `Implement READ_PLUS handling on both client and server: encode READ_PLUS responses with data and hole segments, decode them client-side, and add tests demonstrating sparse file transfers.` | |
| 23 | +| 4 | ALLOCATE/DEALLOCATE semantics | Map allocation and hole-punching requests to filesystem APIs, including quota checks and error handling. | `Wire ALLOCATE and DEALLOCATE operations into the filesystem adapter layer, calling underlying fallocate/punch-hole APIs or mocks. Validate behavior with unit tests and ensure stateids remain consistent.` | |
| 24 | +| 5 | IO_ADVISE support | Accept and persist application I/O hints, applying them to caching policies or forwarding to backend drivers. | `Implement IO_ADVISE request processing, store per-file advice, and expose hooks for storage backends to react. Cover key hint types (sequential, random, willneed, dontneed) with tests.` | |
| 25 | + |
| 26 | +## Phase 3 · Server-Side Copy & Clone |
| 27 | + |
| 28 | +| # | Task | Guidance | LLM Prompt | |
| 29 | +|---|------|----------|------------| |
| 30 | +| 6 | COPY & COPY_NOTIFY workflows | Coordinate inter/intra-server copy lifecycle, including asynchronous state management and error mapping. | `Create a CopyManager coordinating COPY_NOTIFY exchanges, COPY execution, and OFFLOAD_STATUS polling. Handle chunked progress, cancellation, and error propagation per RFC 7862 §4.` | |
| 31 | +| 7 | CLONE integration | Support instantaneous clones when backend allows and fall back to server-side copy otherwise. | `Implement the CLONE operation, checking backend capabilities before cloning ranges. If unsupported, fall back to COPY-based replication. Add tests covering both clone-success and copy-fallback paths.` | |
| 32 | +| 8 | OFFLOAD controls | Handle `OFFLOAD_CANCEL` and `OFFLOAD_STATUS`, ensuring clients can monitor/cancel long-running copies. | `Add handlers for OFFLOAD_STATUS and OFFLOAD_CANCEL that query the CopyManager and control in-progress copies. Provide tests simulating cancellation mid-transfer and status polling.` | |
| 33 | + |
| 34 | +## Phase 4 · Extended Attributes & Data Integrity |
| 35 | + |
| 36 | +| # | Task | Guidance | LLM Prompt | |
| 37 | +|---|------|----------|------------| |
| 38 | +| 9 | XATTR operations | Implement `GETXATTR`, `SETXATTR`, `LISTXATTR`, `REMOVEXATTR`, respecting size limits and ACL constraints. | `Implement the xattr operation family, integrating with filesystem adapters for storage/retrieval. Add validation for size limits and permissions, and cover error paths in tests.` | |
| 39 | +| 10 | Application Data Block (ADB) | Introduce data block descriptors, integrity metadata, and READ_PLUS examples demonstrating corruption detection. | `Implement the Application Data Block framework: define data block descriptors, support READ_PLUS segments carrying block metadata, and add tests showing detection of mismatched checksums.` | |
| 40 | + |
| 41 | +## Phase 5 · Labeled NFS & Security |
| 42 | + |
| 43 | +| # | Task | Guidance | LLM Prompt | |
| 44 | +|---|------|----------|------------| |
| 45 | +| 11 | Security label attribute | Add `sec_label` attribute support to GETATTR/SETATTR, including policy translation layers. | `Implement security label handling: parse and set sec_label attributes, integrate with policy engine hooks, and enforce MAC checks on access. Add tests covering label propagation.` | |
| 46 | +| 12 | Labeled operation modes | Support Full, Limited Server, and Guest modes, including discovery via attributes and layout considerations. | `Implement Labeled NFS modes: expose capabilities through attributes, gate operations by policy, and ensure layout recall respects label constraints. Cover mode transitions with tests.` | |
| 47 | +| 13 | RPCSEC_GSSv3 integration | Enable secure inter-server copy by negotiating RPCSEC_GSSv3 contexts and propagating credentials. | `Integrate RPCSEC_GSSv3 for inter-server copy workflows. Negotiate security contexts during COPY_NOTIFY, wrap copy RPCs, and add tests verifying failure when peers lack support.` | |
| 48 | + |
| 49 | +## Phase 6 · Telemetry & Compliance |
| 50 | + |
| 51 | +| # | Task | Guidance | LLM Prompt | |
| 52 | +|---|------|----------|------------| |
| 53 | +| 14 | Metrics & logging | Extend observability to cover sparse operations, copy lifecycle, xattr usage, and labeled-mode decisions. | `Extend the logging/metrics framework to emit events for READ_PLUS holes, copy progress, xattr mutations, and label enforcement. Create tests ensuring logs appear with expected fields.` | |
| 54 | +| 15 | Integration scenarios | Build end-to-end tests covering sparse IO, server-side copy, xattrs, and labeled NFS enforcement. | `Create integration tests exercising READ_PLUS on sparse files, COPY/CLONE operations, xattr round-trips, and labeled NFS access control. Use fixtures mirroring RFC 7862 examples.` | |
| 55 | +| 16 | Documentation & rollout | Update docs with deployment guidance, compatibility notes, and new configuration toggles. | `Document the NFSv4.2 feature set: write setup guides for sparse file support, copy offload, and labeled NFS. Update docs/nfs/ with troubleshooting tips and release notes.` | |
| 56 | + |
| 57 | +## Exit Criteria |
| 58 | + |
| 59 | +- All NFSv4.2 mandatory and recommended features implemented or explicitly flagged as unsupported. |
| 60 | +- Integration suite validates sparse file handling, copy offload, xattrs, and security labels. |
| 61 | +- Documentation and observability ensure operators can deploy and monitor the new capabilities. |
0 commit comments