From 2134f83ac45986154adc09de3797b022cba67139 Mon Sep 17 00:00:00 2001
From: Mario Fetka <mario.fetka@gmail.com>
Date: Sat, 30 May 2026 06:36:36 +0000
Subject: [PATCH] tests: document AFP scan file information smoke coverage

Document the Linux AFP 2.0 Scan File Information smoke coverage after the endpoint was verified against SYS:PUBLIC.

The scan test exercises the WebSDK-documented NCP 0x23/0x11 request by walking a directory one entry at a time and feeding the returned next_last_seen AFP Entry ID into the next request. Record the verified multi-entry SYS:PUBLIC sequence and explain that the current Entry IDs are still stat-derived fallback values until persistent CNID/AppleDouble mapping is implemented.

Update the Linux test README with the afp_scan_info_smoke build target and examples, and move Scan File Information out of the generic unimplemented AFP follow-up list while keeping broader scan edge cases and full Mac namespace work tracked.

This is documentation-only and does not change AFP protocol behavior.
---
 TODO.md               | 14 +++++++++-----
 tests/linux/README.md | 33 +++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+), 5 deletions(-)

diff --git a/TODO.md b/TODO.md
index 55a2723..c2f13da 100644
--- a/TODO.md
+++ b/TODO.md
@@ -201,9 +201,13 @@ Current status:
   been verified against `SYS:`, `SYS:PUBLIC`, `SYS:SYSTEM`, and `SYS:BURST`.
   The same test verifies the AFP 2.0 Get File Information subfunction via
   `--afp20` against the same paths, using the same path-backed read-only reply
-  for now.  The current
-  reply fills stat/libatalk-derived fields and leaves persistent CNID Parent ID
-  / fuller Mac namespace metadata as future work.
+  for now.  The current reply fills stat/libatalk-derived fields and leaves
+  persistent CNID Parent ID / fuller Mac namespace metadata as future work.
+- `AFP 2.0 Scan File Information` is implemented for path-backed read-only
+  directory scans.  Linux smoke coverage exists in
+  `tests/linux/afp_scan_info_smoke` and has been verified against `SYS:PUBLIC`
+  by walking multiple directory entries with the returned `next_last_seen` AFP
+  Entry ID continuation value.
 - 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.
@@ -226,8 +230,8 @@ Follow-up:
 - Replace the temporary stat-derived AFP entry-id fallback with a persistent
   CNID/directory-id mapping once the libatalk/CNID backend is integrated.
 - Extend the Linux AFP smoke tests once additional AFP subfunctions are
-  implemented, especially Scan File Information, Finder Info updates, fork
-  open/read/write paths, and resource-fork handling.
+  implemented, especially Finder Info updates, fork open/read/write paths,
+  resource-fork handling, and broader directory-scan edge cases.
 
 ## Deferred / optional protocol work
 
diff --git a/tests/linux/README.md b/tests/linux/README.md
index d37a306..f8c1d72 100644
--- a/tests/linux/README.md
+++ b/tests/linux/README.md
@@ -13,6 +13,7 @@ Build with:
 cmake -DMARS_NWE_BUILD_LINUX_TESTS=ON ...
 cmake --build . --target afp_entry_id_smoke
 cmake --build . --target afp_file_info_smoke
+cmake --build . --target afp_scan_info_smoke
 ```
 
 ## AFP Entry ID smoke test
@@ -107,3 +108,35 @@ future Mac-namespace work.
 If the server was built without the optional Netatalk/libatalk backend, use
 `--allow-invalid-namespace` for the expected negative test.  Use
 `--allow-invalid-path` for path-resolution negative tests.
+
+## AFP Scan File Information smoke test
+
+`afp_scan_info_smoke` sends the WebSDK-documented NetWare AFP scan request:
+
+```text
+NCP 0x2222/35/17  AFP 2.0 Scan File Information
+```
+
+It scans one directory entry per request using the same read-only AFP file
+information record as `afp_file_info_smoke`.  The test sends raw `SYS:`-style
+path requests with directory handle 0 and uses the returned `next_last_seen` AFP
+Entry ID as the continuation token for the next call.
+
+Useful smoke sequence for a standard MARS-NWE `SYS:PUBLIC` directory:
+
+```sh
+./tests/linux/afp_scan_info_smoke -S MARS -U SUPERVISOR -P secret SYS:PUBLIC
+./tests/linux/afp_scan_info_smoke -S MARS -U SUPERVISOR -P secret --last-seen 0x23c8787d SYS:PUBLIC
+./tests/linux/afp_scan_info_smoke --allow-empty -S MARS -U SUPERVISOR -P secret --last-seen 0x260437f6 SYS:PUBLIC
+```
+
+The concrete Entry IDs vary by filesystem metadata and are currently marked as
+`fallback` in server diagnostics when they are derived from `stat(2)` rather
+than persistent CNID/AppleDouble metadata.  The verified smoke path walks
+multiple entries in `SYS:PUBLIC` by feeding each returned `next_last_seen` value
+into the next request.
+
+If the server was built without the optional Netatalk/libatalk backend, 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.