From aa041a405b16b5b9c6a897a7654883b70027d72b Mon Sep 17 00:00:00 2001 From: OpenAI Date: Sun, 31 May 2026 04:24:14 +0000 Subject: [PATCH] docs: clarify standalone AFP xattr metadata backend --- CMakeLists.txt | 6 ++- TODO.md | 20 +++++----- tests/linux/README.md | 89 +++++++++++++++++++------------------------ 3 files changed, 55 insertions(+), 60 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 7b75388..9b804f6 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -186,7 +186,11 @@ else() message(STATUS "XAttr support: disabled") endif() -message(STATUS "AFP metadata backend: mars_nwe xattrs") +if(MARS_NWE_XATTR_SUPPORT) + message(STATUS "AFP metadata backend: mars_nwe xattrs") +else() + message(STATUS "AFP metadata backend: disabled (requires xattr support)") +endif() # we want to use systemd, if possible set(SYSTEMD_SERVICES_INSTALL_DIR "" CACHE PATH "Directory for systemd service files") diff --git a/TODO.md b/TODO.md index 14ef704..911cf59 100644 --- a/TODO.md +++ b/TODO.md @@ -297,9 +297,10 @@ Current status: - The AFP dispatcher now decodes the WebSDK/NWAFP subfunction number in diagnostics so real client probes can be mapped to the corresponding AFP call before implementation work starts. -- Optional build-time detection/linking for mars_nwe AFP xattr exists as a first - local metadata backend hook. It is deliberately not an AFP protocol - implementation yet. +- AFP metadata now uses the standalone mars_nwe AFP xattr backend. There is no + Netatalk/libatalk dependency for Entry ID, FinderInfo, or AFP-only attribute + storage; AFP protocol support remains limited to the endpoints explicitly + implemented in `nwconn.c` and guarded by the existing build configuration. - Existing mars_nwe private xattr payloads use the `org.mars-nwe..*` namespace (`org.mars-nwe.netware.archive` and `org.mars-nwe.netware.fileinfo`) rather than the unreleased test-only `user.mars_nwe.*` names. There is no legacy read @@ -323,16 +324,17 @@ Follow-up: than proxying requests to `afpd`. Create Directory, Create File, AFP Delete, and AFP Rename are now implemented through existing mars_nwe create/remove/rename helpers and covered by Linux smoke tests. -- Candidate mars_nwe AFP xattr pieces include the new AppleDouble/Finder Info/resource - fork helper wrappers, plus future CNID/directory-id helpers, attribute - mapping, and filename conversion. +- Candidate future AFP-only pieces should stay under `org.mars-nwe.afp.*`. + FinderInfo and regular-file Entry IDs are already implemented there. Do not + add NetWare semantics such as Hidden/System/Archive attributes or timestamps to + AFP xattrs; route them through the existing mars_nwe NetWare helpers. - Keep returning invalid namespace for AFP calls that still lack a real per-volume Mac namespace/AFP metadata layer. Do not return success for additional AFP calls without data/resource fork and Finder Info semantics. - AFP Entry IDs now prefer the existing mars_nwe NetWare namespace/basehandle - mapping before consulting cached AFP metadata or the old fallback path. A - future mars_nwe AFP xattr/CNID backend may still provide Apple-native identity, but AFP - must not grow a second mars_nwe object-id resolver in parallel to the existing + mapping for directories. Regular files use mars_nwe AFP xattr Entry IDs for + entry-id-only reverse lookup. AFP must not grow a second mars_nwe object-id + resolver in parallel to the existing namespace machinery. - The full smoke suite verifies path-backed file identity end to end: Entry ID From Path Name, Entry ID From NetWare Handle, Get File Information, diff --git a/tests/linux/README.md b/tests/linux/README.md index 7a8abbc..1db07ad 100644 --- a/tests/linux/README.md +++ b/tests/linux/README.md @@ -7,18 +7,17 @@ The tests use the ncpfs/libncp client library. They are not built by default because they require the host ncpfs development headers/library and a running NetWare-compatible server. -The AFP endpoints are intentionally conservative. AFP Entry IDs now prefer the -existing mars_nwe NetWare namespace/basehandle mapping, with cached -`org.mars-nwe.afp.entry-id` metadata kept only as Apple/AFP compatibility state -and legacy fallback. This keeps object identity on the existing mars_nwe -namespace path instead of creating a parallel AFP resolver. The first AFP write -smoke path is deliberately limited to the FinderInfo bitmap of -AFP 2.0 Set File Information; CNID allocation, DOS attribute mapping, resource -fork writes, and data-fork writes remain separate write-safety work. mars_nwe -source uses mars_nwe `org.mars-nwe..*` xattr names; AFP -metadata stays under `org.mars-nwe.afp.*` while NetWare-core metadata uses -`org.mars-nwe.netware.*`. On Linux the local xattr helper stores those through -the portable `user.` namespace with mars_nwe-owned Apple/AFP metadata keys. +The AFP endpoints are intentionally conservative but are now backed by mars_nwe +itself rather than Netatalk/libatalk. Directory Entry IDs prefer the existing +mars_nwe NetWare namespace/basehandle mapping. Regular-file Entry IDs use the +mars_nwe-owned `org.mars-nwe.afp.entry-id` xattr so entry-id-only AFP probes can +resolve back to files without treating file IDs as DOS namespace directory +numbers. FinderInfo uses `org.mars-nwe.afp.finder-info`; only future AFP-only +attribute bits belong in `org.mars-nwe.afp.attributes`. NetWare semantics such +as Hidden/System/Archive attributes, timestamps, trustee rights, create, rename, +delete, and data-fork open/write stay on the existing mars_nwe NetWare paths. +Resource forks remain unsupported. On Linux the local xattr helper stores +source-level `org.mars-nwe.*` names through the portable `user.` namespace. Build with: @@ -74,13 +73,14 @@ user.org.mars-nwe.afp.entry-id ``` -The suite now also exercises the additional metadata-only AFP attribute bits that -`afp_set_file_info_smoke` supports: Hidden (`0x0200`), System (`0x0400`), and Archive (`0x2000`). -It additionally runs the legacy AFP `0x09` path for FinderInfo and the Invisible -attribute so both Set File Information entry points cover the metadata write -path. It clears each attribute bit again before the final xattr dump so repeated -runs leave the attribute payload in the clean `0x01000000` state unless a -previous command fails. +The suite now also exercises the WebSDK AFP attribute bits that +`afp_set_file_info_smoke` supports: Hidden (`0x0200`), System (`0x0400`), and +Archive (`0x2000`). Those bits are verified through the NetWare attribute path, +not through a parallel AFP attribute store. The legacy AFP `0x09` path still +runs for FinderInfo and Hidden so both Set File Information entry points cover +the same WebSDK packet layout. Each attribute bit is cleared again before the +final xattr dump so repeated runs leave no AFP-only attribute payload unless a +future AFP-only bit is explicitly tested. Use `--no-log` when the log file is unavailable or when the server log is being collected separately. Use `--stop-on-failure` for strict bisect-style runs; by @@ -354,9 +354,9 @@ A successful reply prints the request path, directory handle, and returned existing NetWare namespace/basehandle mapping. A full-suite run after that change returned `entry_id=0x00000004` for `SYS:PUBLIC/pmdflts.ini`. -If the server was built without the optional mars_nwe AFP xattr metadata backend, the -endpoint is expected to return invalid namespace. To treat that as a successful -negative smoke test, use: +If the server was built without xattr support, AFP metadata-dependent endpoints +are expected to return invalid namespace. To treat that as a successful negative +smoke test, use: ```sh ./tests/linux/afp_entry_id_smoke --allow-invalid-namespace -S MARS -U SUPERVISOR -P secret SYS:PUBLIC @@ -486,7 +486,7 @@ helper, so the client prints `0xff`. The server diagnostic logs the internal NetWare effective-rights mask before that AFP reply narrowing, so a fully privileged directory can appear as `0x1ff` in `mars_nwe.log`. -If the server was built without the optional mars_nwe AFP xattr metadata backend, use +If the server was built without xattr support, use `--allow-invalid-namespace` for the expected negative test. Use `--allow-invalid-path` for path-resolution negative tests. @@ -571,7 +571,7 @@ A rejected resource-fork probe should print: AFP Open File Fork returned expected completion 0x9c: path=SYS:PUBLIC/pmdflts.ini fork=1 access=0x01 ``` -If the server was built without the optional mars_nwe AFP xattr metadata backend, use +If the server was built without xattr support, use `--allow-invalid-namespace` for the expected negative test. Use `--allow-invalid-path` for path-resolution or Entry-ID-only negative tests. @@ -652,11 +652,10 @@ currently exercises the same path-backed read-only reply as the older call. The current implementation fills fields from the existing mars_nwe sources of truth where possible: NetWare attributes, namespace/basehandle Entry IDs, trustee-derived AccessPrivileges, Unix file sizes and timestamps, and optional -AFP/mars_nwe AFP xattr metadata such as FinderInfo. Parent ID, persistent Apple -CNID/AppleDouble IDs, and fuller resource-fork semantics remain future +AFP metadata such as FinderInfo. Parent ID refinements and fuller resource-fork semantics remain future Mac-namespace work. -If the server was built without the optional mars_nwe AFP xattr metadata backend, use +If the server was built without xattr support, use `--allow-invalid-namespace` for the expected negative test. Use `--allow-invalid-path` for path-resolution negative tests. @@ -715,7 +714,7 @@ shares the same conservative scan implementation so older AFP callers can probe the same read-only directory listing semantics before fuller multi-response and CNID-backed scans are implemented. -If the server was built without the optional mars_nwe AFP xattr metadata backend, use +If the server was built without xattr support, use `--allow-invalid-namespace` for the expected negative test. Use `--allow-invalid-path` for path-resolution negative tests, and `--allow-empty` when a scan continuation is expected to reach the end of the directory. @@ -838,29 +837,19 @@ For the verified FinderInfo smoke run, the FinderInfo xattr starts with user.org.mars-nwe.afp.finder-info=0x544558544d415253000000000000000000000000000000000000000000000000 ``` -AFP Hidden can be tested without mutating DOS/NetWare mode bits: +AFP Hidden is tested through the same NetWare attribute path as System and +Archive: ```sh ./tests/linux/afp_set_file_info_smoke \ -S MARS -U SUPERVISOR -P secret \ --attributes-only --hidden \ SYS:PUBLIC/pmdflts.ini - -getfattr -n user.org.mars-nwe.afp.attributes -e hex /var/mars_nwe/SYS/public/pmdflts.ini ``` -The xattr payload is versioned. For an invisible file the expected Linux form -is: - -```text -user.org.mars-nwe.afp.attributes=0x01000001 -``` - -Use `--clear-hidden --attributes-only` to clear that bit; the same xattr then -stores `0x01000000`. The same helper can exercise the two additional -additional file attribute bits. System remains AFP metadata-only; Archive is -routed through the existing NetWare file attribute store (`FILE_ATTR_A`) rather -than the AFP metadata xattr: +The helper also exercises the two additional file attribute bits. Hidden, +System, and Archive are routed through the existing NetWare file attribute store +rather than the AFP metadata xattr: ```sh ./tests/linux/afp_set_file_info_smoke \ @@ -874,9 +863,9 @@ than the AFP metadata xattr: SYS:PUBLIC/pmdflts.ini ``` -For System the AFP metadata xattr stores `0x01000004`. Archive is verified -through AFP Get File Information after updating the NetWare attribute store; it -no longer lives in `user.org.mars-nwe.afp.attributes`. Use `--clear-system` +System and Archive are verified through AFP Get File Information after updating +the NetWare attribute store; they do not live in +`user.org.mars-nwe.afp.attributes`. Use `--clear-system` and `--clear-archive` to remove those bits. @@ -942,11 +931,11 @@ directory timestamp, or fork-write semantics. All other Set File Information bitmap bits and AFP attribute bits, including NoWrite, NoRename, NoDelete, NoCopy, and the computed data/resource-fork-open -flags, are intentionally rejected for now. That keeps create/access/backup -timestamps, DOS/NetWare mode-bit mapping, enforcement, resource-fork, and -Entry-ID-only write semantics out of this conservative smoke path. +flags, are intentionally rejected for now. That keeps unsupported AFP-only +flags, resource-fork semantics, and unimplemented write modes out of this +conservative smoke path. -If the server was built without the optional mars_nwe AFP xattr metadata backend, use +If the server was built without xattr support, use `--allow-invalid-namespace` for the expected negative test. Use `--allow-invalid-path` for path-resolution negative tests.