From 74e32724ebd0f45ba2a58768dbdcf65cfa1a206e Mon Sep 17 00:00:00 2001 From: ChatGPT Date: Thu, 18 Jun 2026 06:48:52 +0000 Subject: [PATCH] docs: describe libnwnss integration boundaries --- REDESIGN.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) diff --git a/REDESIGN.md b/REDESIGN.md index 2cdcac0..8cb880d 100644 --- a/REDESIGN.md +++ b/REDESIGN.md @@ -14,6 +14,7 @@ major design areas. | DOS namespace adaptation | 🟨 Active next | Adapt NSS DOS namespace semantics before broad 4.x work. | | LONG/OS2 namespace adaptation | ⬜ Later | Start after DOS namespace is stable. | | Salvage metadata/export model | 🟨 Planned | Keep `.recycle` compatibility, add NSS-shaped deleted metadata/xattrs for backup tools through shared libnwcore/libnwfs helpers. | +| libnwnss semantic provider | 🟨 Planned | Use libnwnss first for names, Unicode, rights, xattrs, AdminVolume and reply-buffer ownership hooks; keep COMN file I/O for later. | | NCP dispatch context cleanup | ⬜ Later | Replace magic forwarding results with named dispatch results and a typed request context. | | Isolated live-test environment | ⬜ Later | Use the CMake/test build with generated SYS/QUOTA images once transport can run without host IPX. | @@ -623,6 +624,83 @@ This is especially important for nested selector families and old/new endpoint variants, where a provider may need to choose different reply structures based on a level, verb, or information type. +### NCP reply allocator boundary + +The imported NSS low-level library contains the real `mallocForNCPReply` and +`freeForNCPReply` entry points. Their original purpose is not to provide a +separate NSS pool; it is to allocate reply memory outside NSS internal malloc +debug/tracking because the NetWare NCP handler may own and free generated reply +buffers. + +In current MARS-NWE, normal NCP replies are built in the existing connection +reply buffers, so `libnwnss` should keep its userspace implementation as a plain +external allocator boundary (`malloc`/`free`) rather than trying to route through +`nwconn` or the MARS helper allocators. Do not use `xmalloc` here: NSS callers +expect allocation failure to be a return value, not a process exit. + +The design value is future ownership, not immediate replacement. If a later +provider path lets `libnwnss` or an NSS-shaped service generate client-visible +NCP reply payloads, `mallocForNCPReply` is the right semantic hook for those +buffers: + +```text +MARS-NWE NCP request + -> libnwnss / provider builds a logical reply payload + -> nwconn owns the final NCP response envelope and transport send + -> the reply-buffer owner frees through the matching NCP-reply free path +``` + +At that point the backend may become a MARS reply-buffer pool, a zero-copy send +buffer, or a statistics/debug wrapper. Until such a handoff exists, keep the +function as a documented boundary and do not make it an active dependency from +MARS connection code into `libnwnss`. + +### libnwnss as a future MARS-NWE semantics provider + +The useful long-term dependency direction is not to route all MARS-NWE file I/O +or all NCP replies through `libnwnss` immediately. MARS-NWE should remain the +connection/session/transport owner, while `libnwnss` grows into the provider for +NSS/NetWare semantics that are currently hard to keep compatible in scattered +MARS code. + +Good future integration points are: + +- namespace and Unicode handling: DOS/LONG/UNIX/MAC namespace startup, short-name + generation, case rules and NSS Unicode conversion should become reusable + helpers before broad 4.x endpoint work depends on name semantics; +- trustee, inherited-rights and effective-rights calculation: MARS endpoint code + should eventually ask one shared NSS-shaped rights engine instead of carrying + independent interpretations in several protocol handlers; +- EA/XATTR and NSS metadata export: `netware.metadata`, `netware.ncpstat`, quota + views and Mac metadata should serialize the same state used by NCP handlers, + backup tools and host-side admin views; +- AdminVolume / `_ADMIN`: first bring this up inside `libnwnss` as in-memory + AdminVolume and namespace state, then expose it through a small `nwadminvol` + smoke harness, and only later connect it to `nwconn` or a provider process; +- NCP reply buffers: keep `mallocForNCPReply` as a documented ownership hook so + an NSS-shaped provider can later hand reply payload buffers to the MARS NCP + layer without forcing normal `nwconn` replies to use `libnwnss` today; +- COMN file I/O: treat this as a later backend/provider candidate, not the first + integration step. The current MARS host-filesystem paths should not be + replaced until the `libnwnss` virtual-I/O boundary, metadata state and tests are + strong enough. + +This makes `libnwnss` a semantics layer first and a storage engine only later: + +```text +MARS-NWE transport / NCP session / endpoint dispatch + -> MARS providers or libnwfs bridge + -> libnwnss for NSS names, rights, metadata, AdminVolume and future reply + ownership hooks + -> host xattrs, sidecar state, virtual I/O or later storage backends +``` + +The rule for future patches is to integrate one semantic seam at a time. Do not +make `nwconn` depend on low-level `libnwnss` allocation or COMN file-I/O helpers +just because the symbols exist. Add an integration only when the caller can name +the NSS semantic it needs, when ownership is clear, and when tests cover both the +old MARS-visible behavior and the new NSS-shaped provider result. + ### Logging and audit benefit A normalized handoff reply gives logging one consistent shape: