From e98231decaa6591d9fc0ea737d3b75da1c68835e Mon Sep 17 00:00:00 2001 From: OpenAI Date: Sat, 13 Jun 2026 04:53:07 +0000 Subject: [PATCH] 0444 docs: record provider handoff audit and enum vocabulary --- AI.md | 7 +++ ENDPOINTS.md | 6 +++ REDESIGN.md | 28 ++++++++++ TODO.md | 17 ++++++ doc/HANDOFF_AUDIT.md | 119 +++++++++++++++++++++++++++++++++++++++++ doc/README.md | 2 + include/ncp_endpoint.h | 71 ++++++++++++++++++++++++ 7 files changed, 250 insertions(+) create mode 100644 doc/HANDOFF_AUDIT.md create mode 100644 include/ncp_endpoint.h diff --git a/AI.md b/AI.md index 6e96910..bc96fc8 100644 --- a/AI.md +++ b/AI.md @@ -14,6 +14,7 @@ Keep it short enough to read before touching code. - `doc/NSS_NAMESPACE_AUDIT.md` - `doc/NSS_PUBLIC_CORE_AUDIT.md` - `doc/NWFS_SALVAGE_COMPRESSION_TOOLS.md` + - `doc/HANDOFF_AUDIT.md` 3. Do not assume an older bundle is current. Use the latest applied user state or the latest bundle/patch explicitly accepted by the user. 4. Default language with the user is German; repository documentation remains @@ -72,6 +73,12 @@ and no INI option may enable it. `nwlog`/zlog remains a facade/backend plan, not a reason to call zlog directly. See `doc/LOG_LEVEL_AUDIT.md`. +Before namespace code changes, use the handoff audit rules in `doc/HANDOFF_AUDIT.md`. +New namespace/NWFS work must not add new magic `return(-1)` / `return(-2)` paths. +Use the provider names in `include/ncp_endpoint.h` for audits and future endpoint +tables, but do not wire the enum into runtime dispatch until the current +`nwconn` to `nwbind` handoff sites are annotated. + Then begin the namespace track: 1. Start with DOS namespace compatibility for NetWare 1.x/2.x/3.x clients. diff --git a/ENDPOINTS.md b/ENDPOINTS.md index 32ae9ce..733e893 100644 --- a/ENDPOINTS.md +++ b/ENDPOINTS.md @@ -1,5 +1,11 @@ # NCP endpoint audit + +Provider and status vocabulary for future endpoint table work is declared in +`include/ncp_endpoint.h`. The current tables remain documentation/audit data; +the enum header must not be treated as runtime dispatch until the `nwconn` to +`nwbind` magic-return paths are fully annotated. + This file is the detailed endpoint audit for MARS-NWE. It is deliberately more mechanical than `TODO.md`: it records the NetWare SDK/NDK endpoint numbers, the wire/code selectors used by MARS-NWE, the implementation state, and the source diff --git a/REDESIGN.md b/REDESIGN.md index 67c38db..83cd97d 100644 --- a/REDESIGN.md +++ b/REDESIGN.md @@ -323,6 +323,12 @@ This table would help with the ongoing endpoint audit: The first version should not drive runtime dispatch. It should only make review and missing-endpoint checks less error-prone. +The initial shared vocabulary for this audit now lives in +`include/ncp_endpoint.h`. That header is intentionally declarative: it names +logical providers, endpoint flags, current compatibility dispatch results, and +future handoff reply kinds without changing runtime dispatch. Keep it as a +review aid until the active `nwconn.c` magic handoff sites are annotated. + The table should be able to represent a selector path rather than only a single subfunction. This matters for later NetWare 4.x families and for extension mechanisms. The first selector element is usually the documented subfunction @@ -629,6 +635,28 @@ This would also make the endpoint documentation pass easier: each audited endpoint can identify the provider, the request layout, the logical reply kind, the reply payload layout, and any caller-side post-processing. +### NSS message-layer references + +The imported NSS sources contain several useful references for handoff design, +but they should not be treated as a drop-in MARS IPC runtime. The relevant +patterns are: + +- `include/nwfs/nss/sdk/include/msg.h` and related `msg*.h` files define an + object/key/method/message vocabulary with `MSG_Call`, `MSG_Send`, + `MSG_SendKey`, `mpkMSG_Call` and `zMSG_Call`. This is useful precedent for + method-based provider calls, but the NSS Door/Object runtime is too large and + too NSS-specific for the MARS provider boundary. +- `src/nwfs/nss/common/fsmsg.c` and `fsmsg.h` show NSS filesystem method tables. + These are useful for future libnwfs object methods, not for replacing the NCP + endpoint dispatcher. +- `include/nwfs/nss/sdk/include/nsskr.h` and the `NSSKR_REQUEST` handling in + `src/nwfs/nss/lsaSuper.c` show a simple signature/version/opcode request + header with typed payloads. That is a good reference for a future native + MARS handoff header. + +`doc/HANDOFF_AUDIT.md` records the current MARS magic-return sites and the NSS +references in one focused place. + ### Migration order for handoff normalization The safe order is: diff --git a/TODO.md b/TODO.md index 9f36821..bc3550c 100644 --- a/TODO.md +++ b/TODO.md @@ -17,6 +17,7 @@ why it matters, and where the work belongs. | Logging level cleanup | P0 | Pre-namespace audit done / cleanup pending | Keep new code at levels `1..5`; review touched legacy call sites while namespace code moves. | | Salvage metadata / backup-tool compatibility | P0 | Planned next / unfinished | Keep `.recycle` payloads; make `netware.metadata` authoritative for deleted entries; deprecate `.salvage` JSON. | | NetWare 3.x NCP endpoint completion | P1 | Active audit + implementation | `ENDPOINTS.md` is the detailed decimal/hex audit table; keep this TODO as the short implementation queue. | +| NCP provider handoff cleanup | P0 | Pre-namespace audit started | Use `doc/HANDOFF_AUDIT.md` and `include/ncp_endpoint.h`; annotate real `nwconn` magic handoffs before changing control flow. | | NetWare 4.x endpoint compatibility | P2 | Partial / guarded | `ENDPOINTS.md` tracks active compatibility vs guarded 4.x selectors. | | Admin, queues, printing and TTS | P2 | Ongoing | Console-operator model, queue path case handling, print/TTS compatibility cleanup. | | Test infrastructure | P1 | Ongoing | CTest where offline, live all-smokes where server/client state is required, DOS tool smokes. | @@ -25,6 +26,22 @@ why it matters, and where the work belongs. | Transport split and IPX/TCP config | P2 | Documented plan | Keep TCP/IP and IPX under `nwtransport`; make IPX kernel setup internal later, with `ipx-utils` as fallback/debug tooling. | | External file reconciliation | P1 | Planned next | Add libnwfs watcher/scanner support so Samba, rsync and host-created files receive `netware.metadata` and namespace records. | +## NCP provider handoff cleanup + +Before namespace implementation grows new provider paths, finish the first +handoff audit pass: + +- keep `include/ncp_endpoint.h` declarative until endpoint rows and magic-return + sites are annotated; +- do not bulk-rewrite every `return(-1)` in the tree, because most are ordinary + local error returns; +- start with the active `nwconn.c` dispatcher clusters listed in + `doc/HANDOFF_AUDIT.md`; +- add provider/result flags to endpoint-table work before replacing existing + `return(-1)` / `return(-2)` handoff behaviour; +- new namespace/NWFS code may use provider vocabulary, but must not create new + process-specific magic return conventions. + ## NetWare 3.x endpoint implementation queue Default runtime work should finish documented NetWare 1.x/2.x/3.x behaviour diff --git a/doc/HANDOFF_AUDIT.md b/doc/HANDOFF_AUDIT.md new file mode 100644 index 0000000..b01ff87 --- /dev/null +++ b/doc/HANDOFF_AUDIT.md @@ -0,0 +1,119 @@ +# NCP handoff and provider audit + +This note records the current `nwconn` to `nwbind` handoff model and the NSS +message-layer references that can guide a later cleanup. It is an audit and +vocabulary document first; it does not change runtime dispatch. + +## Current MARS behaviour + +The active MARS server path still uses the historical two-process split: + +```text +client transport -> nwconn -> local handler or nwbind handoff -> client reply +``` + +`nwconn.c` owns the client-facing connection, task, sequence and final network +reply path for most requests. `nwbind.c` owns bindery state and also handles +message, semaphore, queue, accounting and several server-management selectors. + +The important problem is that the active `nwconn.c` dispatcher uses magic integer +returns for process handoff: + +| Result | Current dispatcher meaning | +| ---: | --- | +| `0` | request handled locally; send the local reply path | +| `-1` | forward to `nwbind`; `nwbind` handles the remaining operation/reply | +| `-2` | forward to `nwbind` after `nwconn` saved or rewrote request state; `nwconn` may do post-processing | + +This meaning is scoped. A random `return(-1)` in helper code, salvage code, +SSL compatibility, or even inside `nwbind.c` is usually just a local error or an +unsupported selector. It is not automatically an inter-process handoff marker. + +`include/ncp_endpoint.h` now records the shared names that future cleanup patches +should use for audits and endpoint tables: + +- `NcpProvider` for logical owner/provider names; +- `NcpDispatchResult` for current `nwconn` dispatcher compatibility results; +- `NcpEndpointFlag` for endpoint table/audit annotations; +- `NwHandoffReplyKind` for the future normalized provider reply contract. + +## Active magic-return sites to audit first + +The relevant initial search is not "all `return(-1)` in the tree". That finds +ordinary local error returns too. Start with the active `nwconn.c` dispatcher +handoff sites and annotate them endpoint-by-endpoint. + +Known active `nwconn.c` handoff clusters in the current tree include: + +| Area | Current return | Notes | +| --- | --- | --- | +| decimal 21 / wire `0x15` Message group | `-1` | Entire group is forwarded to `nwbind` with the NCP 21 group header intact. | +| decimal 22/33, 22/34 / wire `0x16/0x21`, `0x16/0x22` quota/user restriction prehandling | `-2` | `nwbind` maps bindery object IDs before quota handling. | +| decimal 22/41 / wire `0x16/0x29` object disk usage/restriction with quota support | `-2` | QUOTA builds forward for ObjectID-to-uid mapping. | +| decimal 23/20, 23/24 / wire `0x17/0x14`, `0x17/0x18` login paths | `-2` | Bindery authentication prehandling. | +| decimal 23 queue selectors / wire `0x17/0x68`, `0x17/0x79`, `0x17/0x69`, `0x17/0x7f`, `0x17/0x71`, `0x17/0x7c` | `-2` | Queue job file/prehandling paths. | +| decimal 23 queue read/change/service selectors / wire `0x17/0x6c`, `0x17/0x7a`, `0x17/0x72`, `0x17/0x73`, `0x17/0x83`, `0x17/0x84` | `-1` or `-2` | Some requests are rewritten with handles before the `nwbind` side completes them. | +| decimal 23 unknown/default selectors / wire `0x17/*` | `-1` | Catch-all delegation to `nwbind`; must be split from truly unsupported endpoints later. | +| decimal 24 End of Job / wire `0x18` | `-1` | `nwconn` frees task-local state, then `nwbind` closes remaining print jobs and replies. | +| decimal 25 Logout / wire `0x19` | `-1` | `nwconn` clears connection-local state, then `nwbind` finishes bindery/print cleanup. | +| decimal 32 Semaphore / wire `0x20` | `-1` | Group is handled by `nwbind` with a one-byte semaphore subfunction. | + +The first functional cleanup should replace comments and endpoint-table metadata +around these sites before changing control flow. Do not bulk-rewrite unrelated +`return(-1)` helper errors. + +## Desired provider contract + +The later normalized shape is: + +```text +nwconn -> provider request -> provider reply -> nwconn final NCP envelope +``` + +Providers should return logical completion plus reply payload, not send raw +client packets directly. `nwconn` remains the final owner of the client-visible +NCP response envelope. Legacy paths may keep provider-built replies while being +converted, but new namespace/NWFS work should not introduce new magic return +values or hidden process-specific reply conventions. + +The conceptual reply kinds are the names in `NwHandoffReplyKind`: + +| Kind | Meaning | +| --- | --- | +| `NW_HANDOFF_REPLY` | provider produced a client NCP completion/payload | +| `NW_HANDOFF_NO_REPLY` | provider handled the request but no client reply is allowed | +| `NW_HANDOFF_DEFERRED` | provider accepted the request and will complete later | +| `NW_HANDOFF_FORWARD` | provider asks the caller to forward to another provider | +| `NW_HANDOFF_ERROR` | internal provider/handoff failure, mapped centrally | + +## NSS references + +The imported NSS reference tree contains useful concepts but not a direct MARS +IPC implementation: + +| NSS area | Files | Useful idea | MARS policy | +| --- | --- | --- | --- | +| NSS message layer | `include/nwfs/nss/sdk/include/msg.h`, `msgGen.h`, `msgIO.h`; calls in `src/nwfs/nss/common/*.c` | key/object/method/message calls such as `MSG_Call`, `MSG_Send`, `MSG_SendKey`, `mpkMSG_Call`, `zMSG_Call` | Reference only. Do not import NSS Door/Object runtime as the MARS provider IPC. | +| NSS filesystem method layer | `src/nwfs/nss/common/fsmsg.c`, `include/nwfs/nss/sdk/include/fsmsg.h` | method tables for NSS file/volume operations | Useful model for future libnwfs object methods, not a replacement for NCP endpoint dispatch. | +| NSSKR ioctl layer | `include/nwfs/nss/sdk/include/nsskr.h`, `src/nwfs/nss/lsaSuper.c` | signature/version/opcode header plus typed request payloads | Good reference for a simple handoff header shape. Do not copy the ioctl protocol directly. | +| `ipc2ncp` headers | `include/nwfs/nss/ipc2ncp.h`, `include/nwfs/nss/sdk/public/ipc2ncp.h` | NCP-to-internal-request boundary vocabulary | Reference while auditing, not a ready-to-use MARS ABI. | + +NSS confirms that method/opcode/message boundaries are normal for this problem +space. MARS should still use a small, native provider contract rather than a +large NSS runtime subsystem. + +## Migration order + +1. Keep `include/ncp_endpoint.h` as vocabulary only. +2. Add endpoint table rows with provider/result flags before changing switch + logic. +3. Annotate each active `nwconn` magic handoff site with the exact endpoint and + provider owner. +4. Add a small wrapper such as `ncp_handoff_to_provider()` that initially calls + the existing `nwbind` path. +5. Replace magic `return(-1)` / `return(-2)` in the active dispatcher with named + `NcpDispatchResult` values only after the audit table can prove which sites + are real handoffs. +6. Convert provider replies to `NwHandoffReplyKind` behind the wrapper. +7. Only then add new provider processes. New namespace/NWFS code may start as an + in-process provider module without becoming a process. diff --git a/doc/README.md b/doc/README.md index 8b8ea7a..c87fb89 100644 --- a/doc/README.md +++ b/doc/README.md @@ -25,6 +25,8 @@ directory small and put new material into topic subdirectories. recommended `1..5` policy for new code. - `KERNEL_REFERENCE_AUDIT.md` - Linux kernel reference imports, currently the disabled Linux 2.4.37.9 SPX implementation. +- `HANDOFF_AUDIT.md` - current `nwconn`/`nwbind` magic-return audit, + provider vocabulary and NSS message-layer references. ## Layout rule diff --git a/include/ncp_endpoint.h b/include/ncp_endpoint.h new file mode 100644 index 0000000..957bdce --- /dev/null +++ b/include/ncp_endpoint.h @@ -0,0 +1,71 @@ +#ifndef _NCP_ENDPOINT_H_ +#define _NCP_ENDPOINT_H_ + +/* + * Common NCP endpoint and provider vocabulary. + * + * This header is intentionally declarative first. It gives audits, future + * endpoint tables, and later dispatcher cleanup patches one shared set of + * names without changing the current switch/return-value behaviour. + */ + +typedef enum ncp_provider_e { + NCP_PROVIDER_UNKNOWN = 0, + NCP_PROVIDER_NWCONN, + NCP_PROVIDER_NWBIND, + NCP_PROVIDER_BINDERY, + NCP_PROVIDER_QUEUE, + NCP_PROVIDER_NWFS, + NCP_PROVIDER_NAMESPACE, + NCP_PROVIDER_SEMAPHORE, + NCP_PROVIDER_MESSAGE, + NCP_PROVIDER_SERVERMGMT, + NCP_PROVIDER_TRANSPORT, + NCP_PROVIDER_DIRECTORY, + NCP_PROVIDER_NWNDS, + NCP_PROVIDER_NCP_EXTENSION, + NCP_PROVIDER_AFP, + NCP_PROVIDER_ACCOUNTING, + NCP_PROVIDER_AUTH, + NCP_PROVIDER_LEGACY_STUB +} NcpProvider; + +/* + * Current nwconn dispatcher compatibility values. + * + * Only the relevant nwconn dispatch path gives -1/-2 the handoff meaning + * described here. Other functions may still return -1 as a normal local error. + */ +typedef enum ncp_dispatch_result_e { + NCP_DISPATCH_DONE = 0, + NCP_DISPATCH_FORWARD_NWBIND = -1, + NCP_DISPATCH_FORWARD_NWBIND_POST = -2, + NCP_DISPATCH_NOT_IMPLEMENTED = 1, + NCP_DISPATCH_BAD_REQUEST = 2, + NCP_DISPATCH_INTERNAL_ERROR = 3 +} NcpDispatchResult; + +typedef enum ncp_endpoint_flag_e { + NCP_ENDPOINT_LOCAL = 1U << 0, + NCP_ENDPOINT_FORWARDED = 1U << 1, + NCP_ENDPOINT_NEEDS_POSTPROCESS = 1U << 2, + NCP_ENDPOINT_PROVIDER_BUILDS_REPLY = 1U << 3, + NCP_ENDPOINT_NETWARE3 = 1U << 4, + NCP_ENDPOINT_NETWARE4_GUARDED = 1U << 5, + NCP_ENDPOINT_REFERENCE_ONLY = 1U << 6, + NCP_ENDPOINT_LEGACY_STUB = 1U << 7 +} NcpEndpointFlag; + +/* + * Future normalized provider handoff reply kind. These are internal MARS + * results, not client-visible NCP completion codes. + */ +typedef enum nw_handoff_reply_kind_e { + NW_HANDOFF_REPLY = 0, + NW_HANDOFF_NO_REPLY, + NW_HANDOFF_DEFERRED, + NW_HANDOFF_FORWARD, + NW_HANDOFF_ERROR +} NwHandoffReplyKind; + +#endif