go-nc-files/CONTEXT.md

go-nc-files

Shared Go Library for reading and writing a Nextcloud user's files from ExApp Services: a storage seam (local and WebDAV), path hygiene, saved default folder preferences, and visit-scoped folder resolution. Depends on go-nc-exapp for AppAPI credentials on WebDAV. ExApps import gitea.neitzel.de/konrad/go-nc-files.

Language

User Files Root: The root of that Nextcloud user's files tree. Working Folder paths are relative to it (including paths that appear in shares as the user sees them). Avoid: absolute WebDAV URLs, numeric file IDs

Working Folder: The single folder an ExApp uses for the current operation. Its path is relative to the User Files Root. Each ExApp defines what files inside that folder mean; this Library only opens, lists, reads, and writes there. Avoid: catalog folder, zones directory, app-specific suffixes in Library code

Saved Default: The Working Folder path persisted for app-icon launches for that user. Stored via a DefaultPathStore implementation (ExApp preferences in production, a JSON file in local/test mode). The ExApp supplies the preference key and initial folder name. Avoid: visit-only path as saved default, admin AppConfig

Visit: One inbound ExApp request bound to one Working Folder. App-icon launch uses the Saved Default (creating the initial folder empty if missing). Files-view launch may pass a User Files Root–relative visit path for that request only; if that folder is missing or forbidden, the Visit fails — no fallback to Saved Default and no implicit create. Avoid: silently switching folders, creating a visit path that was not saved as default

Files seam: The Root and Folder interfaces: open or ensure a relative path, then list, read, write, and test existence. Local disk and WebDAV are two implementations of the same seam. Avoid: coupling the seam to a specific on-disk layout beyond basename rules