From 3f84f6b2ec364034bc2c240af618f35ca1c89448 Mon Sep 17 00:00:00 2001 From: OpenAI Date: Sun, 31 May 2026 06:32:59 +0000 Subject: [PATCH] docs: add AFP final WebSDK audit checklist --- tests/afp/AFP_FINAL_AUDIT.md | 136 +++++++++++++++++++++++++++++++++++ 1 file changed, 136 insertions(+) create mode 100644 tests/afp/AFP_FINAL_AUDIT.md diff --git a/tests/afp/AFP_FINAL_AUDIT.md b/tests/afp/AFP_FINAL_AUDIT.md new file mode 100644 index 0000000..8d59a85 --- /dev/null +++ b/tests/afp/AFP_FINAL_AUDIT.md @@ -0,0 +1,136 @@ +# AFP final WebSDK / Novell header audit plan + +This document is the working checklist for the final AFP endpoint audit. It is +not a statement that the audit is complete. The goal is to make the final pass +repeatable and to keep the comparison focused on protocol compatibility and +mars_nwe backend discipline. + +## Required reference sources + +Before marking the audit complete, compare the current implementation against +all available authoritative local references: + +- WebSDK AFP definitions, especially the header or documentation equivalent to + `nwafp.h`. +- Novell/NWAFP include files from the SDK tree used for the compatibility work. +- Any WebSDK request/reply examples bundled with the uploaded SDK archive. +- mars_nwe current `src/nwconn.c`. +- mars_nwe AFP helper inventory: + +```sh +tests/afp/afp_endpoint_inventory.py +tests/afp/afp_endpoint_inventory.py --json +``` + +The final audit should record the exact source paths used, for example: + +```text +WebSDK source: /... +Novell headers: /... +mars_nwe source: src/nwconn.c +audit date: YYYY-MM-DD +``` + +## Source greps to run + +Run these in the mars_nwe tree and in the unpacked WebSDK / Novell header trees. + +```sh +grep -RIn "AFP.*Get Entry ID\|Get Macintosh Info On Deleted\|Scan File Information\|Open File Fork\|Set File Information" . +grep -RIn "0x2222.*35\|function 35\|NWAFP\|nwafp" . +grep -RIn "AFP.*0x0[0-9a-fA-F]\|AFP.*0x1[0-3]" . +grep -RIn "Scan Salvageable\|Recover Salvageable\|Purge Salvageable\|Deleted" . +``` + +Run these in mars_nwe to verify cleanup and backend discipline: + +```sh +grep -RIn "layout=websdk\|libatalk\|Netatalk\|HAVE_NETATALK\|ENABLE_NETATALK" src include tests/afp CMakeLists.txt cmake 2>/dev/null +grep -RIn "entry-id-only .*unsupported\|unsupported.*entry-id" src/nwconn.c tests/afp +grep -RIn "\bopen\s*(\|\bread\s*(\|\bwrite\s*(\|\brename\s*(\|\bunlink\s*(\|\brmdir\s*(\|\bmkdir\s*(" src/nwconn.c +``` + +The last grep is review material, not an automatic failure. Some direct POSIX +calls may be legitimate inside older mars_nwe core paths, but AFP endpoint code +should not bypass mars_nwe helpers for NetWare semantics. + +## Endpoint comparison table + +Fill this table during the final pass. `mars_nwe backend path` must name the +mars_nwe helper family used by the endpoint, not just the AFP handler. + +| Subfn | WebSDK / Novell name | mars_nwe handler | Request layout OK | Reply layout OK | Completion codes OK | mars_nwe backend path OK | Notes | +| --- | --- | --- | --- | --- | --- | --- | --- | +| `0x01` | AFP Create Directory | inline AFP create directory case | TODO | TODO | TODO | TODO | | +| `0x02` | AFP Create File | inline AFP create file case | TODO | TODO | TODO | TODO | | +| `0x03` | AFP Delete | inline AFP delete case | TODO | TODO | TODO | TODO | | +| `0x04` | AFP Get Entry ID From Name | `afp_get_entry_id_from_name` | TODO | TODO | TODO | TODO | | +| `0x05` | AFP Get File Information | `afp_get_file_information` | TODO | TODO | TODO | TODO | | +| `0x06` | AFP Get Entry ID From NetWare Handle | `afp_get_entry_id_from_netware_handle` | TODO | TODO | TODO | TODO | | +| `0x07` | AFP Rename | inline AFP rename case | TODO | TODO | TODO | TODO | | +| `0x08` | AFP Open File Fork | inline AFP open file fork case | TODO | TODO | TODO | TODO | data fork only; resource fork unsupported | +| `0x09` | AFP Set File Information | inline AFP set file information case | TODO | TODO | TODO | TODO | legacy variant | +| `0x0a` | AFP Scan File Information | `afp_scan_file_information` | TODO | TODO | TODO | TODO | entry-id-only scan is open review item | +| `0x0b` | AFP Alloc Temporary Dir Handle | inline AFP alloc temporary dir handle case | TODO | TODO | TODO | TODO | | +| `0x0c` | AFP Get Entry ID From Path Name | `afp_get_entry_id_from_path_name` | TODO | TODO | TODO | TODO | | +| `0x0d` | AFP 2.0 Create Directory | inline AFP 2.0 create directory case | TODO | TODO | TODO | TODO | | +| `0x0e` | AFP 2.0 Create File | inline AFP 2.0 create file case | TODO | TODO | TODO | TODO | | +| `0x0f` | AFP 2.0 Get File Information | `afp_get_file_information` | TODO | TODO | TODO | TODO | AFP 2.0 variant | +| `0x10` | AFP 2.0 Set File Information | inline AFP 2.0 set file information case | TODO | TODO | TODO | TODO | AFP 2.0 variant | +| `0x11` | AFP 2.0 Scan File Information | `afp_scan_file_information` | TODO | TODO | TODO | TODO | entry-id-only scan is open review item | +| `0x12` | AFP Get DOS Name From Entry ID | `afp_get_dos_name_from_entry_id` | TODO | TODO | TODO | TODO | | +| `0x13` | AFP Get Macintosh Info On Deleted Files | unsupported | TODO | TODO | TODO | TODO | requires salvage/deleted-entry backend | + +## Backend discipline checklist + +For every implemented endpoint, check these rules explicitly: + +- Path resolution uses mars_nwe path/namespace helpers. +- Directory identities use mars_nwe namespace/basehandle state. +- File entry-id reverse lookup uses the AFP entry-id xattr cache only for files. +- File open/read/write/close uses mars_nwe NetWare file handles. +- Rights use mars_nwe trustee/effective-rights checks. +- Hidden/system/archive attributes use mars_nwe attribute/archive paths. +- FinderInfo uses the AFP-only metadata store. +- Resource forks remain unsupported until a real backend exists. +- Deleted-file Macintosh metadata waits for mars_nwe salvage/deleted-entry state. +- AFP handlers do not introduce standalone POSIX filesystem semantics. + +## Known open decisions + +### Entry-id-only scan + +The inventory currently reports: + +```text +entry-id-only scan unsupported +``` + +This affects AFP `0x0a` and AFP 2.0 `0x11`. The final audit must decide whether +WebSDK / Novell require scan to accept a directory entry ID with no path for the +current compatibility slice. If required, implement it by resolving directory +entry IDs through mars_nwe namespace/basehandle logic only. + +### Deleted-file Macintosh metadata + +AFP `0x13` is intentionally unsupported for now. It should remain unsupported +until the normal NetWare salvage family is present and verified: + +- `NCP 0x2222 / 87 / 16` - Scan Salvageable Files +- `NCP 0x2222 / 87 / 17` - Recover Salvageable File +- `NCP 0x2222 / 87 / 18` - Purge Salvageable File +- optional legacy `NCP 0x2222 / 22 / 27` - Scan Salvageable File (old) + +Do not implement AFP `0x13` as an AFP-local deleted-file scan. + +## Completion criteria + +The final audit is complete only when: + +1. The endpoint table above is filled with explicit OK/unsupported decisions. +2. The exact WebSDK and Novell header paths used for the comparison are listed. +3. `tests/afp/afp_endpoint_inventory.py` has no unexpected warnings. +4. The only accepted warnings are documented final-slice limitations. +5. The AFP smoke suite still reports `failures=0`. +6. Any unsupported endpoint has a documented backend dependency or deliberate + compatibility-slice reason.