From 774d64e27841dc7bbe264e7acff7bdaa6d4b3c90 Mon Sep 17 00:00:00 2001 From: Mario Fetka Date: Sat, 13 Jun 2026 11:37:03 +0000 Subject: [PATCH] 0474 docs: name nwConsole and clarify web restart boundaries --- AI.md | 31 ++++++++-------- REDESIGN.md | 37 +++++++++++-------- TODO.md | 2 +- doc/NWADMIN_CLIENT_PLAN.md | 75 ++++++++++++++++++++++++++------------ doc/README.md | 2 +- 5 files changed, 91 insertions(+), 56 deletions(-) diff --git a/AI.md b/AI.md index ee2e08a..26ec6b9 100644 --- a/AI.md +++ b/AI.md @@ -47,7 +47,7 @@ unfinished work out of `TODO.md` merely because its architecture is documented. Latest patch marker expected in an up-to-date bundle: -- `0473 docs: split nwwebui ssl offload from nwadmin plugins` +- `0474 docs: name nwConsole and clarify web restart boundaries` When a later chat receives a new `mars-nwe-master` bundle, compare `git log -1` with this marker. If the uploaded bundle already contains this commit subject, @@ -67,23 +67,24 @@ The active line is expected to include: Last generated patch: -- `0473 docs: split nwwebui ssl offload from nwadmin plugins` +- `0474 docs: name nwConsole and clarify web restart boundaries` Purpose of that patch: -- Clarify the SMArT replacement split: `nwwebui` is the small HTTP/HTTPS/TLS - offloader, session and static-asset frontend, while `nwadmin` is the backend - management process. -- Put web/config plugin dispatch in `nwadmin`, not in `nwwebui`; plugins declare - IDs, titles, icon IDs, navigation sections, required capabilities and command - handlers so web and future desktop frontends can share one admin vocabulary. -- Keep the visual direction iManager/ConsoleOne-inspired with open-source or - project-owned icons shared between web and desktop frontends; do not copy - proprietary Novell assets. -- Record service lifecycle rules: `nwserv` or a service manager may restart - backend services such as `nwadmin`, `nwconn`, NCP, directory, FTP/WebDAV/NFS - modules individually, but `nwwebui` should keep running unless explicitly - restarted. +- Define user-facing names: `nwConsole` for the browser/web administration + surface and `nwAdmin` for the remote/desktop administrator client family. + The small web listener process may remain `nwwebui` internally. +- Clarify lifecycle boundaries: a host-level systemd/init restart may restart + the whole MARS-NWE service family including `nwwebui`, but restarts requested + from nwConsole must keep the web listener alive unless the operator explicitly + restarts the web frontend itself. +- Require embedded nwConsole static/status pages in `nwwebui` for backend + restart and reconnect states such as `Restarting nwadmin`, `Restarting + ncpserv`, `Restarting nwconn`, `Restarting nwbind`, backend unavailable and + reconnect pending. +- Keep the split from the previous plan: `nwwebui` owns HTTP/HTTPS/TLS/session + and IPC frontend work, while `nwadmin` owns web/config plugins and backend + management dispatch. Directory/NDS work order before any FLAIM storage conversion: diff --git a/REDESIGN.md b/REDESIGN.md index 637a601..1c60366 100644 --- a/REDESIGN.md +++ b/REDESIGN.md @@ -2578,22 +2578,27 @@ Terminal UI, toolbox and curses replacement plan: evaluated later, but they must not become required dependencies for the common admin client library or server daemons. - A server-local web admin frontend may eventually replace the old SMArT role, - but it must be split into a small `nwwebui` frontend and an `nwadmin` backend. - `nwwebui` owns HTTP/HTTPS, TLS offload, sessions and static assets, and should - stay alive while server services restart. `nwadmin` owns web/config plugin - dispatch and calls the portable admin API over localhost NCP or explicit - control IPC. The `nwwebui`-to-`nwadmin` boundary should be an explicit local - IPC socket/protocol, replacing the old SMArT-style subprocess stdout/console - scraping model. Restarting `nwserv` as the file-server service family may restart - backend services such as `nwadmin`, `nwconn`, NCP, directory, FTP or later - service daemons individually, but it must not restart `nwwebui` unless the web - frontend itself was explicitly requested. Authentication is bindery/server - auth first for 3.x, later directory/`libnwds` auth first for 4.x, and PAM only - fallback. Socket and HTTP helper work should prefer bundled `libowfat`, and - HTTPS/TLS should use the MatrixSSL/`libnwssl` project TLS path instead of - another local implementation. Web and desktop admin frontends should share an - open-source or project-owned icon catalog and iManager/ConsoleOne-inspired - navigation language without copying proprietary Novell assets. + but it must be split into a small `nwwebui` frontend process and an `nwadmin` + backend. The user-facing web name should be `nwConsole`; the remote/desktop + client family should be `nwAdmin`. `nwwebui` owns HTTP/HTTPS, TLS offload, + sessions, static assets and embedded nwConsole status/restart pages, while + `nwadmin` owns web/config plugin dispatch and calls the portable admin API over + localhost NCP or explicit control IPC. The `nwwebui`-to-`nwadmin` boundary + should be an explicit local IPC socket/protocol, replacing the old SMArT-style + subprocess stdout/console scraping model. A host-level systemd/init restart of + the MARS-NWE service may restart the whole service family, including + `nwwebui`. A restart requested through nwConsole must keep `nwwebui` running + unless the operator explicitly restarts the web frontend; targeted restarts may + restart backend services such as `nwadmin`, `nwconn`, `ncpserv`, `nwbind`, + directory, FTP or later service daemons individually and show embedded + `Restarting ...` / backend-unavailable pages meanwhile. Authentication is + bindery/server auth first for 3.x, later directory/`libnwds` auth first for + 4.x, and PAM only fallback. Socket and HTTP helper work should prefer bundled + `libowfat`, and HTTPS/TLS should use the MatrixSSL/`libnwssl` project TLS path + instead of another local implementation. nwConsole and nwAdmin frontends + should share an open-source or project-owned icon catalog and + iManager/ConsoleOne-inspired navigation language without copying proprietary + Novell assets. - Production daemons must not depend on the TUI stack or on administrator GUI toolkits. - See `doc/TUI_TOOLBOX_PLAN.md` for the detailed UI/toolbox plan, diff --git a/TODO.md b/TODO.md index 6252d17..df5628d 100644 --- a/TODO.md +++ b/TODO.md @@ -115,7 +115,7 @@ may remain active. | Additional File Server Environment 4.x monitor/admin selectors | later / guarded | Implement only when a concrete admin tool or compatibility test requires it. | | Remote `nwadmin` 3.x client roadmap | 3.x | open | Audit `mars-nweadmin` workflows and define a portable NCP-based admin client API. Linux should investigate ncpfs behind a transport adapter; macOS and Windows backends remain open until the 3.x NCP needs are known. Do not link the admin GUI directly to local server libraries. | | Remote admin GUI frontend | later / guarded | open | A GUI may use Lazarus LCL/FreePascal or another cross-platform toolkit, but only after the portable admin client API has a console/CTest frontend. Keep first-pass dependencies small; Cross.Codebot/TMS WEB Core/uniGUI-style stacks are later evaluations, not required dependencies. Directory/ConsoleOne-like features come later after the directory stack is ready. | -| Server-local nwwebui/nwadmin admin frontend | later / guarded | open | Replace the old SMArT role with a split design: `nwwebui` is the small HTTP/HTTPS/TLS/session/static frontend and SSL offloader; `nwadmin` is the backend process that owns web/config plugins and calls the portable admin API. Keep bindery/server authentication first for 3.x, later directory/`libnwds` authentication first for 4.x, PAM fallback only, `libowfat` for socket/helper work where suitable, and MatrixSSL/`libnwssl` for TLS. `nwserv` or a service manager may restart backend services such as `nwadmin`, `nwconn`, NCP, directory, FTP/WebDAV/NFS service modules individually, but must not restart `nwwebui` as a side effect. Replace SMArT-style subprocess console-output coupling with an explicit local IPC socket between `nwwebui` and `nwadmin`. | +| Server-local nwConsole/nwadmin admin frontend | later / guarded | open | Replace the old SMArT role with a split design: `nwwebui` is the small HTTP/HTTPS/TLS/session/static frontend and SSL offloader exposed to users as nwConsole; `nwadmin` is the backend process that owns web/config plugins and calls the portable admin API. Keep bindery/server authentication first for 3.x, later directory/`libnwds` authentication first for 4.x, PAM fallback only, `libowfat` for socket/helper work where suitable, and MatrixSSL/`libnwssl` for TLS. A host-level systemd/init restart may restart the whole MARS-NWE service family including `nwwebui`, but nwConsole-requested backend restarts must keep `nwwebui` running unless the operator explicitly restarts the web frontend. `nwwebui` needs embedded nwConsole status pages for `Restarting nwadmin`, `Restarting ncpserv`, `Restarting nwconn`, `Restarting nwbind`, backend unavailable and reconnect states. Replace SMArT-style subprocess console-output coupling with an explicit local IPC socket between `nwwebui` and `nwadmin`. | | NDS/NCP Fragger and related 4.x infrastructure | later / guarded | Keep out of default runtime until transport/client scope is explicit. | | TimeSync and NCP Extension families | later / guarded | Reference/stub only unless a real 3.x/4.x client path requires them. | | Migration, compression, data migration and later OES/MOAB-style selectors | reference-only | Study reusable data models only; do not add default live endpoints during the 3.x push. | diff --git a/doc/NWADMIN_CLIENT_PLAN.md b/doc/NWADMIN_CLIENT_PLAN.md index 7d6c0bb..fcc6592 100644 --- a/doc/NWADMIN_CLIENT_PLAN.md +++ b/doc/NWADMIN_CLIENT_PLAN.md @@ -1,4 +1,4 @@ -# nwadmin client roadmap +# nwAdmin and nwConsole roadmap `mars-nweadmin` is useful as a historical workflow reference, but the old Pascal program must not become the architecture for new administrator clients. @@ -13,6 +13,20 @@ later extension, but the design should keep a ConsoleOne-like direction in mind: one administrator application can grow from bindery/server administration into directory administration when the directory stack is ready. +## Product names + +Use distinct user-facing names for the two frontend families: + +- `nwAdmin` is the remote administrator client family. It may start as a + console/CTest client and later gain a desktop GUI. +- `nwConsole` is the web administration surface. Its small web listener process + may still be named `nwwebui` internally, but the UI, page titles and user + documentation should call the browser interface `nwConsole`. + +The names intentionally separate the remote client from the server-local web +console even when both share the same icon catalog, navigation vocabulary and +admin operation model. + ## Client/server boundary Administrator tools are remote clients. They must talk to a mars-nwe server @@ -84,7 +98,7 @@ as TMS WEB Core or uniGUI can be compared for a later web UI, but none of them i a first-pass dependency. The first-pass rule is: common admin logic stays in the portable client library, and every frontend remains replaceable. -## Server-local web administration +## Server-local web administration / nwConsole A server-local web admin path is allowed and may eventually replace the old SMArT role. Treat it as a separate frontend, not as the architecture for the @@ -141,17 +155,28 @@ or a Pascal-to-JavaScript compiler a required dependency for a server admin tool A richer browser UI can be added later if the small web UI and admin API prove insufficient. -`nwwebui` and `nwserv` also have independent lifecycles. A `nwserv` restart must -not automatically restart the web UI process. If `nwserv` is restarted while the -web UI remains running, `nwwebui` should keep its HTTP/HTTPS listener alive, -report the server as restarting or temporarily unavailable, and reconnect or -refresh its server session after the server comes back. Restarting `nwwebui` -should be an explicit web-admin/service-manager action, not a side effect of -restarting the file server. +`nwwebui` and `nwserv` have separate lifecycle rules depending on who requested +the restart. A host-level restart of the MARS-NWE service through systemd, an +init script or a package/service manager may restart the whole service family, +including `nwwebui`, because that is an explicit server-side service restart. +A restart requested from the web UI must not restart the web listener itself as a +side effect. In that case `nwwebui` should keep its HTTP/HTTPS listener alive, +report the selected backend as restarting or temporarily unavailable, and +reconnect or refresh its backend IPC/server session after the backend comes back. +Restarting `nwwebui` should be an explicit service-manager action, not an +implicit side effect of restarting `nwserv`, `nwadmin`, `nwconn`, `nwbind`, +`ncpserv`, `nwdirectory`, `nwftp` or another managed backend from nwConsole. + +Because `nwwebui` remains up during web-requested backend restarts, nwConsole +needs embedded static/status pages that do not depend on a live `nwadmin` +backend. Those pages should use the same nwConsole visual language and be able +to show messages such as `Restarting nwadmin`, `Restarting ncpserv`, +`Restarting nwconn`, `Restarting nwbind`, `Restarting nwdirectory`, `Service +unavailable`, and `Reconnect pending`. ## Shared visual language and plugins -The web and desktop admin frontends should share the same visual vocabulary. +The nwConsole web UI and the nwAdmin desktop/client frontends should share the same visual vocabulary. Use an open-source icon set or project-owned icons, but keep a common icon ID catalog so the desktop UI and web UI show the same symbols for users, groups, volumes, trustees, server status, restart actions and later directory objects. @@ -180,13 +205,15 @@ nwadmin ``` When `nwserv` gains service-management awareness, it may support targeted -restarts such as restarting only `nwadmin`, only `nwconn`, only the NCP server, -only the directory server, only `nwftp`, or another optional service. Restarting -`nwserv` as the file-server service family may restart managed backend services, -including `nwadmin`, but it should not restart `nwwebui` unless the web frontend -itself was explicitly requested. If `nwadmin` is restarted, `nwwebui` should -keep the listener and sessions alive, reconnect to the IPC socket when the -backend comes back, and show a temporary backend unavailable notice meanwhile. +restarts such as restarting only `nwadmin`, only `nwconn`, only `ncpserv`, only +`nwbind`, only the directory server, only `nwftp`, or another optional service. +For a host-level systemd/init restart of the MARS-NWE service, restarting the +whole service family including `nwwebui` is allowed. For a restart requested +through nwConsole, the frontend must keep running unless the operator explicitly +chooses to restart the web frontend itself. If `nwadmin` or another backend is +restarted, `nwwebui` should keep the listener and sessions alive, reconnect to +the IPC socket when the backend comes back, and show an embedded nwConsole +`restarting` or `backend unavailable` page meanwhile. ## Work order @@ -198,7 +225,7 @@ backend comes back, and show a temporary backend unavailable notice meanwhile. behind the transport adapter. 4. Add a console/CLI test frontend so CTest can exercise the client API without a GUI. -5. Add a simple server-local `nwwebui` plus `nwadmin` pair only after the API is +5. Add a simple server-local nwConsole (`nwwebui`) plus `nwadmin` pair only after the API is stable enough: `nwwebui` handles HTTP/HTTPS/TLS/session/static frontend work, while `nwadmin` owns plugin dispatch and management operations. 6. Add a desktop GUI frontend only after the admin client API and transport @@ -228,11 +255,13 @@ backend comes back, and show a temporary backend unavailable notice meanwhile. authentication is primary for 3.x; later directory authentication through `libnwds` or the matching server-side directory API is primary for 4.x; PAM is fallback only. -- Do not make `nwserv` restarts restart `nwwebui` as a side effect. Treat the - web frontend as separately supervised so it can survive server-service - restarts. `nwserv` or a service manager may restart backend services such as - `nwadmin`, `nwconn`, NCP, directory, FTP or other optional daemons - individually, but `nwwebui` restarts must remain explicit. +- Do not make web-requested backend restarts restart `nwwebui` as a side + effect. A host-level systemd/init restart of the MARS-NWE service may restart + the whole service family, including `nwwebui`; nwConsole-requested backend + restarts must keep the web listener alive unless the operator explicitly + restarts the web frontend itself. `nwserv` or a service manager may restart + backend services such as `nwadmin`, `nwconn`, `ncpserv`, `nwbind`, directory, + FTP or other optional daemons individually. - Do not put the web/config plugin system into `nwwebui`. Keep `nwwebui` as the HTTP/HTTPS/TLS/session/static frontend and put plugin dispatch into the `nwadmin` backend process. diff --git a/doc/README.md b/doc/README.md index 187590f..19b146d 100644 --- a/doc/README.md +++ b/doc/README.md @@ -35,7 +35,7 @@ directory small and put new material into topic subdirectories. flatfile-first LDAP CTest plan and later FLAIM storage-backend swap. - `NWADMIN_CLIENT_PLAN.md` - remote NCP-based administrator client roadmap, `mars-nweadmin` portability audit notes, future cross-platform GUI plan and - split `nwwebui`/`nwadmin` web-admin/plugin architecture. + split nwConsole (`nwwebui`)/`nwadmin` web-admin/plugin architecture. ## Layout rule