docs: document third-party and forked component policy
This commit is contained in:
Mario Fetka
158
REDESIGN.md
158
REDESIGN.md
@@ -1067,6 +1067,164 @@ This keeps the future NetWare 4.x work aligned with the provider/process split:
|
||||
`nwdirectory`, `nwnds`, and `nwbind` may be separate processes or modules, but
|
||||
they should not be separate sources of truth for identity and directory data.
|
||||
|
||||
## Third-party and forked component integration policy
|
||||
|
||||
The long-term redesign should distinguish between three different kinds of
|
||||
imported code:
|
||||
|
||||
```text
|
||||
1. fixed third-party building blocks kept under third_party/
|
||||
2. optional third-party backends kept behind mars-nwe facades
|
||||
3. forked mars-nwe components kept at the repository root
|
||||
```
|
||||
|
||||
Do not treat all imported code the same way. A small, mostly unmodified library
|
||||
that is built as part of mars-nwe belongs under `third_party/`. A component that
|
||||
will be forked, renamed, given CMake support, wired into mars-nwe storage, and
|
||||
changed as part of the server design should live at the repository root like the
|
||||
existing project components (`admin`, `dosutils`, `mail`, `smart`).
|
||||
|
||||
The intended layout is:
|
||||
|
||||
```text
|
||||
third_party/yyjson
|
||||
existing fixed JSON dependency used by salvage metadata
|
||||
|
||||
third_party/wolfssl
|
||||
fixed TLS dependency used by mars-nwe TLS code
|
||||
configured through CMake for the server's supported platforms and features
|
||||
|
||||
third_party/zlog
|
||||
optional advanced logging backend used only through nwlog
|
||||
|
||||
mars-tinyldap/
|
||||
forked/integrated tinyldap-derived component in the repository root
|
||||
project-facing service name: nwdirectory
|
||||
converted to the mars-nwe CMake build
|
||||
later wired to libdirectory/libflaim instead of tinyldap's original flat files
|
||||
```
|
||||
|
||||
### TLS dependency rule
|
||||
|
||||
wolfSSL should be the fixed TLS implementation shipped with the tree, similar in
|
||||
spirit to the bundled yyjson dependency. Do not design the first TLS integration
|
||||
as an abstract zoo of OpenSSL, LibreSSL, wolfSSL, and other providers. wolfSSL is
|
||||
portable and can be configured through CMake for the needs of the target server,
|
||||
so it should be the implementation used for:
|
||||
|
||||
- LDAP/LDAPS/StartTLS at the `nwdirectory` network edge;
|
||||
- any future TCP-based internal provider IPC, where wolfSSL-backed mTLS is
|
||||
required;
|
||||
- future TLS-capable admin or service endpoints, if they are explicitly added.
|
||||
|
||||
However, mars-nwe code should still not include wolfSSL headers everywhere. TLS
|
||||
call sites should go through a small internal facade:
|
||||
|
||||
```text
|
||||
include/nwtls.h
|
||||
src/nwtls.c
|
||||
src/nwtls_wolfssl.c
|
||||
```
|
||||
|
||||
The facade is not meant to promise equal OpenSSL/LibreSSL support. Its purpose
|
||||
is to keep certificate loading, policy checks, mTLS requirements, error logging,
|
||||
secure defaults, and wolfSSL-specific setup in one place. If another TLS backend
|
||||
is ever evaluated much later, it can be hidden behind the same API, but the
|
||||
planned bundled backend is wolfSSL.
|
||||
|
||||
Protocol handlers and provider code should therefore use `nwtls` concepts, not
|
||||
raw wolfSSL types. Example ownership:
|
||||
|
||||
```text
|
||||
nwdirectory LDAP listener -> nwtls -> wolfSSL
|
||||
provider TCP IPC -> nwtls -> wolfSSL/mTLS
|
||||
nwlog/security logging -> logs TLS events, never private key material
|
||||
```
|
||||
|
||||
TLS configuration belongs in the documented INI, but private key material does
|
||||
not. The config may point at certificate/key files, while `nwsetup` should be
|
||||
able to generate or validate local defaults. Private keys and provider mTLS
|
||||
credentials must live in protected directories with strict permissions.
|
||||
|
||||
### zlog dependency rule
|
||||
|
||||
`zlog` should be treated as an optional advanced logging backend under
|
||||
`third_party/zlog`, not as a direct API used by handlers. The mars-nwe public
|
||||
logging API remains `include/nwlog.h`. If zlog is enabled, it is reached through
|
||||
`src/nwlog_zlog.c` only:
|
||||
|
||||
```text
|
||||
endpoint/provider code -> nwlog -> optional zlog backend
|
||||
```
|
||||
|
||||
This keeps secret redaction, structured correlation fields, fallback logging, and
|
||||
future backend changes centralized. zlog can provide administrator-controlled
|
||||
category/rule/format routing, but it must never receive raw decoded NCP or
|
||||
handoff payloads from bypass paths.
|
||||
|
||||
### Forked tinyldap / nwdirectory rule
|
||||
|
||||
`tinyldap` is different from yyjson, wolfSSL, and zlog. It is not merely a small
|
||||
library dependency. The planned integration requires a fork because the original
|
||||
code needs mars-nwe-specific work:
|
||||
|
||||
- CMake build support;
|
||||
- mars-nwe service naming (`nwdirectory`);
|
||||
- LDAP/LDAPS/StartTLS integration through `nwtls`/wolfSSL;
|
||||
- replacement or bypass of the original flat-file storage;
|
||||
- later `libdirectory` and libflaim-backed storage integration;
|
||||
- directory schema, bootstrap, and setup integration through `nwsetup`.
|
||||
|
||||
Because of that, the fork should live in the repository root as `mars-tinyldap/`,
|
||||
matching the existing pattern for project components that are not treated as
|
||||
plain third-party libraries. The code may still document its upstream origin,
|
||||
license, and local changes, but it is part of the mars-nwe component tree.
|
||||
|
||||
The architectural relationship remains:
|
||||
|
||||
```text
|
||||
LDAP/LDAPS client
|
||||
-> nwdirectory service built from mars-tinyldap
|
||||
-> libdirectory
|
||||
-> libflaim-backed store
|
||||
```
|
||||
|
||||
`nwbind` and future `nwnds` should not speak LDAP internally just because the LDAP
|
||||
service exists. They should use `libdirectory` directly, while `nwdirectory`
|
||||
exposes LDAP as an external protocol view of the same directory data.
|
||||
|
||||
### Versioning and local-change documentation
|
||||
|
||||
Each bundled or forked dependency should have a short mars-nwe note describing:
|
||||
|
||||
- upstream project and URL;
|
||||
- pinned commit/tag or submodule branch policy;
|
||||
- license;
|
||||
- whether it is fixed, optional, or forked;
|
||||
- which mars-nwe facade owns access to it;
|
||||
- local changes carried by mars-nwe;
|
||||
- CMake options used by the mars-nwe build.
|
||||
|
||||
Do not silently update third-party submodules together with unrelated functional
|
||||
changes. Dependency bumps should be separate patches. Forked root components
|
||||
should keep a `README.mars-nwe.md` or equivalent local-change note so future
|
||||
updates can be reviewed without guessing which changes are upstream and which are
|
||||
project integration work.
|
||||
|
||||
Suggested build options:
|
||||
|
||||
```text
|
||||
WITH_ZLOG=ON/OFF/AUTO optional advanced logging backend
|
||||
WITH_WOLFSSL=ON/OFF/AUTO bundled TLS backend; required when TLS features are enabled
|
||||
WITH_NWDIRECTORY=ON/OFF build the mars-tinyldap/nwdirectory component
|
||||
WITH_NWNDS=ON/OFF future NetWare 4.x/NDS compatibility layer
|
||||
WITH_LIBFLAIM=ON/OFF/AUTO future directory store backend
|
||||
WITH_TCP=ON/OFF future client-facing TCP/IP transport
|
||||
```
|
||||
|
||||
Conservative builds should still be able to disable incomplete future components,
|
||||
but once a feature requires TLS, its supported TLS implementation is wolfSSL.
|
||||
|
||||
## Configuration redesign and future typed INI files
|
||||
|
||||
The current `nw.ini`/`nwserv.conf` format is historically user-editable, but it
|
||||
|
||||
49
third_party/README.md
vendored
49
third_party/README.md
vendored
@@ -1,5 +1,10 @@
|
||||
# Third-party dependencies
|
||||
|
||||
This directory is for mostly external building blocks that are built or linked by
|
||||
mars-nwe but are not project-specific service forks. Code here should normally
|
||||
be accessed through a mars-nwe facade or subsystem instead of being included
|
||||
from endpoint/provider code directly.
|
||||
|
||||
## yyjson
|
||||
|
||||
The salvage metadata backend uses the bundled yyjson submodule for JSON
|
||||
@@ -16,3 +21,47 @@ CMake expects `third_party/yyjson/CMakeLists.txt` to exist. Reader and writer
|
||||
support stay enabled; yyjson tests, fuzzer, misc tools, docs, install targets,
|
||||
JSON5/non-standard support, utilities and incremental reader support are disabled
|
||||
for the mars-nwe build.
|
||||
|
||||
## Planned: wolfSSL
|
||||
|
||||
wolfSSL is the planned fixed TLS implementation for mars-nwe. It should be
|
||||
added as `third_party/wolfssl` and configured by CMake for the server's supported
|
||||
platforms and enabled TLS features.
|
||||
|
||||
mars-nwe code should not include wolfSSL headers directly from arbitrary
|
||||
subsystems. TLS users should go through the future `include/nwtls.h` facade and
|
||||
its wolfSSL backend, for example:
|
||||
|
||||
```text
|
||||
include/nwtls.h
|
||||
src/nwtls.c
|
||||
src/nwtls_wolfssl.c
|
||||
```
|
||||
|
||||
Planned uses include LDAP/LDAPS/StartTLS in `nwdirectory` and any future
|
||||
TCP-based internal provider IPC that requires mTLS.
|
||||
|
||||
## Planned: zlog
|
||||
|
||||
zlog is the planned optional advanced logging backend. If added, it should live
|
||||
under `third_party/zlog` and be used only through the mars-nwe `nwlog` facade:
|
||||
|
||||
```text
|
||||
include/nwlog.h
|
||||
src/nwlog.c
|
||||
src/nwlog_zlog.c
|
||||
```
|
||||
|
||||
Endpoint and provider code must not call zlog APIs directly. This keeps secret
|
||||
redaction, request correlation fields, and fallback logging centralized.
|
||||
|
||||
## Forked components are not third_party
|
||||
|
||||
Components that are forked and integrated as mars-nwe services should live at the
|
||||
repository root, following the existing pattern used by `admin`, `dosutils`,
|
||||
`mail`, and `smart`.
|
||||
|
||||
The planned tinyldap fork is such a component. It should live as
|
||||
`mars-tinyldap/` at the repository root, build the project-facing `nwdirectory`
|
||||
service, gain CMake support, and later use `libdirectory`/libflaim-backed
|
||||
storage instead of tinyldap's original flat-file storage.
|
||||
|
||||
Reference in New Issue
Block a user