konrad/go-nc-files
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document every exported symbol and how callers use the library.

Browse Source 
Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
konrad
2026-09-29 19:25:44 +02:00
co-authored by Cursor
parent 300484114f
commit 710234fba1
6 changed files with 864 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+26 -40
View File
@@ -4,58 +4,44 @@ Shared Go library for Nextcloud ExApp Services: a User Files seam (local disk an
Import: `gitea.neitzel.de/konrad/go-nc-files` (package `goncfiles`).
```bash
go get gitea.neitzel.de/konrad/go-nc-files
```
Depends on [go-nc-exapp](https://gitea.neitzel.de/konrad/go-nc-exapp) for AppAPI credentials on WebDAV.
## Scope
- [Guide](docs/guide.md) — how to call each capability
- [API](docs/api.md) — every exported symbol
- [Domain language](CONTEXT.md)
**Included**
## 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`
- [Files seam](docs/guide.md#files-seam) — `Root` and `Folder`
- [Local](docs/guide.md#local) — filesystem-backed User Files Root
- [WebDAVRoot](docs/guide.md#webdavroot) — Nextcloud Files over WebDAV
- [CleanRel](docs/guide.md#cleanrel) — User Files Root–relative paths
- [RequireBasename](docs/guide.md#requirebasename) — child file names
- [DefaultPathStore](docs/guide.md#defaultpathstore) — Saved Default path
- [Visit](docs/guide.md#visit) — Working Folder for one opening
**Excluded**
## Excluded
- ExApp lifecycle HTTP routes and HaRP bootstrap (see **go-nc-exapp**)
- AppAPI preference OCS wiring (ExApp adapts `gonexapp.AppAPIPreferences` to `DefaultPathStore`)
- AppAPI preference OCS wiring (the ExApp adapts `gonexapp.AppAPIPreferences` to `DefaultPathStore`)
- Catalog, DNS, or product-specific file semantics
- Recursive tree walks and Nextcloud numeric file IDs
## Usage
```go
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](./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.
Unit tests use a temporary local root and `httptest` for WebDAV. No live Nextcloud is required.
`go test ./...` fails when [`docs/api.md`](docs/api.md) does not match the exported API. Regenerate it with:
```bash
UPDATE_API_DOCS=1 go test -run TestAPIDoc -count=1
```
Runnable package examples: `go test -run Example`.
## Related