go-nc-files

Shared Go library for Nextcloud ExApp Services: a User Files seam (local disk and WebDAV), Saved Default path storage, and Visit-scoped Working Folder resolution.

Import: gitea.neitzel.de/konrad/go-nc-files (package goncfiles).

Depends on go-nc-exapp for AppAPI credentials on WebDAV.

Scope

Included

• Files seam — Root and Folder interfaces with OpenFolder, EnsureFolder, List, Read, Write, Exists
• Local — filesystem-backed User Files Root for tests and local go run
• WebDAVRoot — Nextcloud Files at /remote.php/dav/files/{user}/ using gonexapp.Credentials
• CleanRel — rejects .., URLs, and numeric file IDs
• RequireBasename — shared basename rules for child file names
• DefaultPathStore — GetDefault / SetDefault for Saved Default paths; FileStore (JSON) and Memory implementations
• Visit — Open / OpenLocal resolve Working Folder from Saved Default (app-icon) or visit-only path (Files view); fail-closed on missing/forbidden visit paths
• Sentinel errors: ErrNotExist, ErrForbidden, ErrNotDir

Excluded

• ExApp lifecycle HTTP routes and HaRP bootstrap (see go-nc-exapp)
• AppAPI preference OCS wiring (ExApp adapts gonexapp.AppAPIPreferences to DefaultPathStore)
• Catalog, DNS, or product-specific file semantics
• Recursive tree walks and Nextcloud numeric file IDs

Usage

import (
    goncfiles "gitea.neitzel.de/konrad/go-nc-files"
    gonexapp "gitea.neitzel.de/konrad/go-nc-exapp"
)

// Local mode
visit, err := goncfiles.OpenLocal("/data/files", "/data/settings.json", "myapp", "")

// WebDAV + ExApp preferences (adapter in your ExApp)
cred := gonexapp.Credentials{ /* ... */ }
root := goncfiles.WebDAVRoot{Cred: cred}
prefs := gonexapp.NewAppAPIPreferences(cred, "myexapp", "savedDefault")
store := myAppAPIPathStore{prefs} // implement DefaultPathStore
visit, err := goncfiles.Open(root, store, "myapp", visitRelative)

Each ExApp chooses its Saved Default preference key and initial folder name; this library stays key-agnostic.

Runnable package examples: go test -run Example.

Domain language

See CONTEXT.md for User Files Root, Working Folder, Saved Default, Visit, and Files seam terminology.

Testing

Unit tests use a temporary local root (and httptest for WebDAV). No live Nextcloud is required for Library CI.

Related

• go-nc-exapp — AppAPI credentials and OCS preferences
• Workspace ADR 0013 — extraction from CheckDNS