6.9 KiB
API
Generated from the package comment and every exported declaration. Do not edit.
Regenerate with UPDATE_API_DOCS=1 go test -run TestAPIDoc -count=1.
Package goncfiles
Package goncfiles provides a Nextcloud User Files seam (local and WebDAV), Saved Default path storage, and Visit-scoped Working Folder resolution for ExApp Services.
Variables
ErrNotExist
ErrForbidden
ErrNotDir
var (
// ErrNotExist means the folder or file is missing.
// Callers should use IsNotExist rather than comparing text.
ErrNotExist = errors.New("not found")
// ErrForbidden means the caller may not read or write the path.
// Callers should use IsForbidden rather than comparing text.
ErrForbidden = errors.New("forbidden")
// ErrNotDir means the path exists and is not a directory.
ErrNotDir = errors.New("not a directory")
)
Functions
CleanRel
func CleanRel(rel string) string
CleanRel normalizes a User Files Root–relative path. The result is empty when rel is empty, contains "..", is a URL, or is a bare numeric Nextcloud file ID. An empty result is not a usable path. Backslashes are treated as slashes. A leading or trailing slash is removed.
IsForbidden
func IsForbidden(err error) bool
IsForbidden reports whether err wraps ErrForbidden.
IsNotExist
func IsNotExist(err error) bool
IsNotExist reports whether err wraps ErrNotExist.
LocalPath
func LocalPath(f Folder) (string, bool)
LocalPath returns the absolute directory when f is a local folder.
RequireBasename
func RequireBasename(name string) error
RequireBasename rejects path segments that are not a single basename.
Types
DefaultPathStore
type DefaultPathStore interface {
// GetDefault returns the stored path, or empty when none is set yet.
GetDefault() (string, error)
// SetDefault writes a User Files Root–relative Working Folder path.
SetDefault(rel string) error
}
DefaultPathStore persists the Saved Default Working Folder path (User Files Root–relative).
Entry
type Entry struct {
Name string
IsDir bool
}
Entry is a first-level name in a Working Folder.
FileStore
type FileStore struct {
Path string
}
FileStore is the local-adapter settings JSON file.
FileStore.GetDefault
func (s FileStore) GetDefault() (string, error)
GetDefault reads the saved default; empty means the caller should use the product initial default.
FileStore.SetDefault
func (s FileStore) SetDefault(rel string) error
SetDefault writes the saved Working Folder path.
Folder
type Folder interface {
// List returns first-level names in the Working Folder.
List() ([]Entry, error)
// Read returns the contents of a basename in the Working Folder.
Read(name string) ([]byte, error)
// Write creates or replaces a basename in the Working Folder.
Write(name string, data []byte) error
// Exists reports whether name is a non-directory file in the Working Folder.
Exists(name string) (bool, error)
// Remove deletes a basename in the Working Folder.
Remove(name string) error
}
Folder is flat storage for one Working Folder (basenames only).
LocalFolder
func LocalFolder(dir string) Folder
LocalFolder returns a Folder backed by an absolute local directory.
Local
type Local struct {
RootDir string
}
Local is a User Files Root on the local filesystem.
Local.EnsureFolder
func (l Local) EnsureFolder(rel string) (Folder, error)
EnsureFolder creates the directory and its parents if missing, then opens it. It returns an error wrapping ErrForbidden when the process cannot create the directory, or a plain error when rel is not valid.
Local.OpenFolder
func (l Local) OpenFolder(rel string) (Folder, error)
OpenFolder opens an existing directory under the local root. It returns an error wrapping ErrNotExist, ErrForbidden, or ErrNotDir, or a plain error when rel is not a valid User Files Root–relative path.
Memory
type Memory struct {
Value string
}
Memory is an in-memory DefaultPathStore for tests.
Memory.GetDefault
func (m *Memory) GetDefault() (string, error)
GetDefault returns the in-memory value.
Memory.SetDefault
func (m *Memory) SetDefault(rel string) error
SetDefault stores the value in memory.
Root
type Root interface {
// OpenFolder opens an existing folder at rel (User Files Root–relative).
OpenFolder(rel string) (Folder, error)
// EnsureFolder creates rel (and parents) if needed, then opens it.
EnsureFolder(rel string) (Folder, error)
}
Root is User Files Root–relative folder access.
Visit
type Visit struct {
SavedDefault string
WorkingRel string
VisitRelative string
FS Folder
// contains filtered or unexported fields
}
Visit is one ExApp opening: Working Folder for this request plus the Saved Default.
Open
func Open(root Root, defaults DefaultPathStore, initialFolderName, visitRelative string) (*Visit, error)
Open resolves the Working Folder for this visit. initialFolderName is used when no Saved Default is stored yet (app-icon first launch). visitRelative empty means app-icon launch (Saved Default, creating the initial folder empty if missing). A Files-view folder is used only for this visit and does not change the Saved Default. Missing or forbidden visit paths fail closed (no create, no fallback).
OpenLocal
func OpenLocal(filesRoot, settingsPath, initialFolderName, visitRelative string) (*Visit, error)
OpenLocal is the local-adapter convenience: files root + settings JSON.
Visit.SetDefault
func (v *Visit) SetDefault(relative string) error
SetDefault persists a new Saved Default and ensures the folder exists.
Visit.WorkingDir
func (v *Visit) WorkingDir() string
WorkingDir returns a local absolute path when using the local adapter; otherwise WorkingRel.
WebDAVRoot
type WebDAVRoot struct {
Cred gonexapp.Credentials
Client *http.Client
}
WebDAVRoot is a User Files Root at /remote.php/dav/files/{user}/. Cred supplies the user id and AppAPI auth headers. A nil Client uses http.DefaultClient.
WebDAVRoot.EnsureFolder
func (r WebDAVRoot) EnsureFolder(rel string) (Folder, error)
EnsureFolder creates the folder and missing parents with MKCOL, then opens it. It returns an error wrapping ErrForbidden on 401 or 403, or a plain error when rel is invalid or MKCOL fails for another status.
WebDAVRoot.OpenFolder
func (r WebDAVRoot) OpenFolder(rel string) (Folder, error)
OpenFolder opens an existing folder via WebDAV PROPFIND. It does not create the folder. It returns an error wrapping ErrNotExist when the server responds 404, ErrForbidden on 401 or 403, and ErrNotDir when the resource is not a collection. An invalid rel returns a plain error and does not call the server.