142 lines
8.2 KiB
Markdown
142 lines
8.2 KiB
Markdown
# Interface — 0.0.1
|
||
|
||
The interface uses the application's real API. It does not populate sample devices,
|
||
simulate operation results, or present disconnected actions as working features.
|
||
|
||
## Build and runtime
|
||
|
||
`build.rs` reads `web/assets.list` and combines the sources into **one `app.js` and
|
||
one `app.css`**. Both files and `index.html` are embedded in the Rust executable.
|
||
Building or running the application does not require Node, Angular, a frontend
|
||
server, nginx, an external CDN, or a font service.
|
||
|
||
| Source file | Responsibility |
|
||
| --- | --- |
|
||
| `web/js/i18n.js` | Polish, English, Spanish, and Norwegian dictionaries, including completed missing source translations |
|
||
| `web/js/core.js` | API access, formatting, HTML escaping, forms, and dialogs |
|
||
| `web/js/views.js` | Views and data presentation |
|
||
| `web/js/app.js` | Routing, sessions, and user actions |
|
||
| `web/css/app.css` | Responsive layout, themes, components, and diff styling |
|
||
|
||
Revision 4 translates project documentation into English. It does not change the
|
||
interface's four supported languages or users' saved language preferences.
|
||
|
||
## Views and actions
|
||
|
||
| Route | Features |
|
||
| --- | --- |
|
||
| `/login`, `/register` | Sign-in, registration only when enabled on the server, and validation errors |
|
||
| `/` | Counts, recent backups, saved connection status, disk usage, seven-day activity, logs, and batch actions with partial results |
|
||
| `/devices` | Device search/filtering, creation, editing, ping, and connection tests |
|
||
| `/devices/:id` | Metadata, the latest test, backups, policies, and device deletion; RSC exports only for RouterOS |
|
||
| `/files` | Filtering, sorting, download, RSC preview, email, binary upload, ZIP, and bulk deletion |
|
||
| `/diff-configs` | Export selection, side-by-side and unified views, line numbers, statistics, search, changes-only mode, synchronized scrolling, and diff/HTML download |
|
||
| `/logs` | Actual messages and timestamps, search, pagination, and confirmed cleanup |
|
||
| `/settings` | Retention, automation, credentials, SMTP, Pushover, and account preferences |
|
||
| `/settings?tab=automation` | Flat scheduled-task controls, cron expressions, and actual next execution times |
|
||
| `/settings?tab=account` | Account tab with password change, matching-password confirmation, and language/font preferences |
|
||
| `/schedule` | Compatibility redirect to `/settings?tab=automation` |
|
||
| `/change-password` | Compatibility redirect to `/settings?tab=account` |
|
||
|
||
`/routers` and `/routers/:id` are device-route aliases. A Git screen and a standalone
|
||
SwOS beta module were not part of the active source API, so they are not presented
|
||
as available features. Binary upload writes a file to the device; it does not
|
||
perform a restore or restart automatically.
|
||
|
||
## Behavior details
|
||
|
||
- Operations show results after receiving an API response. Deletion and upload
|
||
require confirmation. Batch backup results include failures and skipped devices.
|
||
- Comparison is available only for RSC exports. The bulk compare action appears
|
||
when exactly two exports are selected. Binary and SwitchOS files have no diff
|
||
action. SwitchOS has no exports tab, export action, or export policy control.
|
||
Diff errors use the existing toast notification without an extra error block
|
||
inside the form.
|
||
- Secret fields are never prefilled. A blank field preserves the secret; a separate
|
||
explicit control clears it. Revealing the global SSH key requires the account
|
||
password. Closing the dialog removes the revealed text from the interface.
|
||
- The SwitchOS form has an explicit credential-source selector.
|
||
`use_global_switchos_credentials=true` uses only the current global credentials;
|
||
`false` uses only the device's credentials. In global mode, the UI sends neither
|
||
`ssh_user` nor `ssh_password` nor their clear controls. Stored local values are
|
||
retained. `has_own_password` supplies a presence hint for the empty password field,
|
||
never the password itself. A legacy record with `null` preserves its original
|
||
fallback behavior on an ordinary save until the user explicitly selects a source.
|
||
- The Bearer token is kept in the current tab's `sessionStorage`. An existing
|
||
`routeros_token` from the old UI is moved into the session only after successful
|
||
verification through `/auth/me`. Signing out clears the client session.
|
||
- `API_PREFIX` comes from page metadata inserted by the server.
|
||
- The server supplies `ALLOW_REGISTRATION` through
|
||
`<meta name="allow-registration" content="false">`. If the tag is absent or its
|
||
value is anything other than `true`, the registration link is hidden and
|
||
`/register` redirects to sign-in. The API independently enforces the same setting.
|
||
- Password changes live in **Settings → Account**, without a separate navigation
|
||
item. The previous direct route continues to work through a redirect.
|
||
- Language and font are saved through `/auth/preferences`. Theme and sidebar width
|
||
are browser preferences. Font stacks preserve Inter/system UI, Roboto Mono/IBM
|
||
Plex Mono, Adwaita Mono, and Hack. If a font is not installed, the browser uses
|
||
the configured fallback; no font is downloaded at runtime.
|
||
- Names, logs, exports, and diff content are escaped as text before presentation.
|
||
Server-generated diff HTML is downloaded as a file, not inserted into the app DOM.
|
||
- Weekly scheduling writes weekday names `mon`–`sun`. Imported numbers preserve
|
||
APScheduler's actual semantics: **0 = Monday**, **6 = Sunday**. The old interface
|
||
described these numbers inconsistently; this editor shows the actual scheduled day.
|
||
- Automation is part of Settings without a separate navigation item.
|
||
`/settings?tab=schedule` also redirects to `automation`. Schedule fields and next-run
|
||
information use plain rows rather than nested cards or bordered panels.
|
||
- A small **API documentation** footer link opens local `/docs`. The backend serves
|
||
this page separately from the SPA router.
|
||
- If the host disallows ICMP socket creation, ping shows an unknown state with the
|
||
diagnostic reason. Missing process permissions are not reported as a router outage.
|
||
|
||
## Interface tests
|
||
|
||
These are development tools. Node and Playwright are not application dependencies.
|
||
|
||
```sh
|
||
node web/tests/core.test.cjs
|
||
```
|
||
|
||
The core suite runs without npm packages. It covers translations, HTML injection
|
||
protection, secret handling in forms, UTC dates, cron semantics, and presentation of
|
||
actual data structures. The browser suite requires Playwright and Chromium. It
|
||
starts an isolated server with controlled API responses and exercises sign-in,
|
||
device CRUD, backups, diff, settings, languages, policies, confirmation dialogs, and
|
||
mobile layout. It does not connect to routers or notification services.
|
||
|
||
For an optional, repeatable browser-tool installation outside the project, run the
|
||
following from the project root in one shell. Node.js and npm must be available:
|
||
|
||
```sh
|
||
MBS_UI_TEST_DIR="$(mktemp -d "${TMPDIR:-/tmp}/mbs-ui-tests.XXXXXX")"
|
||
npm install --prefix "$MBS_UI_TEST_DIR" --no-audit --no-fund --save-exact playwright@1.62.1
|
||
export NODE_PATH="$MBS_UI_TEST_DIR/node_modules${NODE_PATH:+:$NODE_PATH}"
|
||
export PLAYWRIGHT_BROWSERS_PATH="$MBS_UI_TEST_DIR/browsers"
|
||
node "$MBS_UI_TEST_DIR/node_modules/playwright/cli.js" install chromium
|
||
node web/tests/smoke.cjs
|
||
```
|
||
|
||
The npm package and downloaded browser remain under the temporary directory named
|
||
by `MBS_UI_TEST_DIR`; the project does not gain `node_modules`, `package.json`, or
|
||
an npm lockfile. Remove that temporary directory when finished. If Chromium is
|
||
already installed, skip its download and set `MBS_CHROMIUM` to the existing
|
||
executable path. These environment variables also apply to the live-server check
|
||
below.
|
||
|
||
To check an actual running server without changing its data:
|
||
|
||
```sh
|
||
MBS_BASE_URL=http://127.0.0.1:5581 \
|
||
MBS_TEST_USERNAME=admin \
|
||
MBS_TEST_PASSWORD='test-account-password' \
|
||
node web/tests/live.cjs
|
||
```
|
||
|
||
`MBS_CHROMIUM` optionally selects an existing Chromium executable.
|
||
`MBS_SCREENSHOT_DIR` saves local screenshots for inspection. The live check verifies
|
||
views against the actual backend, JavaScript/API/CSP errors, and responsive layout;
|
||
it does not create backups, upload files, or send notifications. Revision-specific
|
||
execution results are recorded in [the validation report](validation.md); the
|
||
presence of a test in the source tree does not imply that it has been rerun for
|
||
every revision.
|