-
Notifications
You must be signed in to change notification settings - Fork 3
Development and Architecture
FolderView Plus is an Unraid webGUI plugin with PHP endpoints, browser runtimes, persistent JSON configuration on the flash device, shared contracts, and generated Slackware packages.
| Path | Purpose |
|---|---|
src/folderview.plus/ |
Source copied into the installed plugin package. |
src/.../usr/local/emhttp/plugins/folderview.plus/ |
Deployed plugin root layout. |
scripts/ |
CI, guards, packaging, smoke tests, and maintenance tools. |
tests/ |
Contract, regression, lifecycle, integration, privacy, workflow, and browser tests. |
docs/ |
User, architecture, security, compatibility, and release documentation. |
archive/ |
Generated versioned .txz packages and checksum files. |
asset-packs/ |
Independently versioned icon assets. |
folderview.plus.plg |
Unraid plugin manifest and install/update/remove hooks. |
pkg_build.sh |
Authoritative package builder. |
| Layer | Responsibility |
|---|---|
| Page integration | Loads assets into Settings, Docker, VMs, Dashboard, and folder editor. |
| Host adapters | Find native structures, observe host changes, and expose lifecycle hooks. |
| Runtime state | Normalize inventory, resolve membership/order, render groups, and reconcile changes. |
| Docker provider/coordinator | Detect GraphQL capabilities, merge API state into known PHP identities, control retries/fallback, and cancel stale work. |
| Settings/editor | Edit folders/preferences and orchestrate previewed workflows. |
| Request client | Tokens, nonces, trace IDs, encoding, timeouts, parsing, uploads, and errors. |
| Endpoint contract | Declares methods, guards, content types, limits, parameters, response types, and audit category. |
| Durable storage | Validates and atomically commits configuration/recovery data with last-good support. |
| Shared UI | Buttons, fields, dialogs, confirmations, status, progress, empty/loading states. |
| Localization | Versioned namespaces, English fallback, generated coverage, aliases. |
| Diagnostics | Build, health, storage, localization, theme, telemetry, integrity, and sanitized support data. |
| Packaging | Core archive, manifest/checksums, release notes, and separate icon pack. |
- A page calls the shared browser request client.
- The client attaches request protection and trace metadata.
- The PHP endpoint resolves its declaration from
server/api-endpoints.json. - Shared runtime enforces method, content type, size, parameters, mutation guard, and response contract.
- Domain validation runs.
- Durable mutations commit through shared storage.
- Responses/activity preserve bounded trace, transaction, and audit context.
Docker and VM adapters preserve native content during bootstrap, load a coherent snapshot, then render folders. For Docker, the native/PHP inventory owns identity and metadata while a single API coordinator prefers supported GraphQL reads for runtime state. Structural changes can rebuild grouping; lifecycle changes reconcile incrementally. Timers, observers, event listeners, requests, subscriptions, retry timers, and host hooks must be torn down on navigation/pagehide to prevent duplicate behavior.
Dashboard consumes the same normalized folder/inventory contracts but renders cards. Settings and editor use shared request/UI primitives rather than separate ad-hoc protocols.
- Capability paths are checked dynamically; an API version string is never treated as proof that an operation exists.
- Full reads and targeted post-action reads share one in-flight owner and generation counter, so superseded responses cannot overwrite newer state.
- Container names plus full/short IDs may match an existing runtime entry, but API data cannot create an unknown FolderView row.
- PHP metadata survives partial API responses. Only supported runtime fields are enriched.
- Authentication, permission, endpoint, and required-capability failures disable the API read path for that page lifecycle.
- Transient failures use bounded cooldowns of 15, 30, 60, 120, then 300 seconds; the PHP snapshot remains available throughout.
- Diagnostics receive aggregate status only. Raw results and server error details remain outside support exports.
Docker actions on the legacy host surface continue through native eventControl. Provider mutation capabilities are discovered independently for future-compatible consumers, but API-first reads do not transfer ownership of existing Unraid controls.
The repository treats upstream compatibility and supply-chain health as reviewed contracts:
-
docs/unraid-compatibility-baseline.jsonrecords reviewed public Unraid OS/PHP, webGUI, plugin-manager, API, and Community Applications identities. Daily automation reports drift but cannot rewrite or approve the baseline. -
docs/sbom.cdx.jsonis the generated CycloneDX inventory for shipped libraries, host runtime contracts, development dependencies, and pinned GitHub Actions. Weekly OSV scanning evaluates supported package identities and publishes SARIF. - CodeQL, OpenSSF Scorecard, OSV, cross-browser fixtures, upstream compatibility, and traffic-metric jobs are covered by a scheduled-workflow health check so silent schedule failures create a deduplicated recovery issue.
All tracked automated validation uses isolated fixtures, public upstream inputs, or disposable runner profiles. Live Unraid systems and their credentials are outside repository automation.
Docker and VM maps/preferences are separate. Writes use validated sibling temporary files, flush where supported, and atomic rename. Metadata tracks revisions; last-good mirrors support recovery from malformed current JSON. Batch operations validate the plan before a single guarded commit.
The repository records long-lived decisions for branch/package integrity, browser compatibility, native Docker safe mode, diagnostics privacy, and artifact storage under docs/adr.
FolderView Plus Wiki · Stable releases · Report an issue · Unraid forum · Security reporting