# go-nc-files guide

How to use the library. Symbol signatures and doc comments are in [API](api.md). Words for the domain are in [CONTEXT.md](../CONTEXT.md).

Sentinel errors are `ErrNotExist`, `ErrForbidden`, and `ErrNotDir`. `IsNotExist` and `IsForbidden` report whether an error wraps the first two. The features below name which calls return them.

## Files seam

### Purpose

`Root` opens a folder by a User Files Root–relative path. `Folder` is flat storage inside that folder: list, read, write, exists, and remove, by basename only.

### When to use it

Write product code against `Root` and `Folder`. Pass a `Local` root in tests and a `WebDAVRoot` against Nextcloud. The rest of the call sequence stays the same.

### Call sequence

1. Obtain a `Root` (`Local` or `WebDAVRoot`).
2. `OpenFolder` when the folder must already exist. `EnsureFolder` when missing parents should be created.
3. On the `Folder`, call `List`, `Read`, `Write`, `Exists`, or `Remove` with a basename.

`List` returns first-level names. `Exists` reports a non-directory file. `Entry.IsDir` is true for a child directory.

### Errors

`OpenFolder` and `EnsureFolder` return a plain error when the relative path is invalid (`CleanRel` yields empty). A missing folder from `OpenFolder` wraps `ErrNotExist`. A path that exists and is not a directory wraps `ErrNotDir`. Permission failures wrap `ErrForbidden`.

`Read`, `Write`, `Exists`, and `Remove` return an error from `RequireBasename` when the name is not a single basename. `Remove` and WebDAV `Read` wrap `ErrNotExist` when the child is missing. `Exists` returns false and a nil error when the child is missing.

### Example

```go
folder, err := root.OpenFolder("Zones")
if err != nil {
    return err
}
if err := folder.Write("note.txt", []byte("hi")); err != nil {
    return err
}
data, err := folder.Read("note.txt")
```

## Local

### Purpose

`Local` is a User Files Root on the local filesystem. `RootDir` is the absolute directory that corresponds to the user's files root.

### When to use it

Use `Local` for tests and for `go run` without Nextcloud. Use `LocalFolder` when the caller already has an absolute directory and only needs a `Folder`. `LocalPath` reports that absolute directory when the `Folder` came from the local adapter.

### Call sequence

1. Set `Local.RootDir`.
2. Call `OpenFolder` or `EnsureFolder` with a relative path. `EnsureFolder` creates the directory with mode `0755`.
3. Or call `LocalFolder` with an absolute directory and skip the root.

`OpenLocal` is the Visit helper that pairs `Local` with a `FileStore`. It is described under Visit.

### Errors

`OpenFolder` wraps `ErrNotExist`, `ErrForbidden`, or `ErrNotDir`, or returns a plain error for an invalid relative path. `EnsureFolder` wraps `ErrForbidden` when the process cannot create the directory.

### Example

```go
root := goncfiles.Local{RootDir: filesRoot}
folder, err := root.EnsureFolder("myapp")
if err != nil {
    return err
}
_ = folder
```

## WebDAVRoot

### Purpose

`WebDAVRoot` is a User Files Root at `/remote.php/dav/files/{user}/`. `Cred` supplies the user id and AppAPI auth headers from go-nc-exapp. A nil `Client` uses `http.DefaultClient`.

### When to use it

Use `WebDAVRoot` when the Working Folder is the user's Nextcloud files. The same `Root` and `Folder` methods apply as with `Local`.

### Call sequence

1. Fill `gonexapp.Credentials`, including `BaseURL` and `UserID`.
2. Store them on `WebDAVRoot.Cred`.
3. `OpenFolder` checks the folder with PROPFIND and does not create it.
4. `EnsureFolder` creates missing parents with MKCOL, then opens the folder.
5. `List` uses PROPFIND with depth 1. `Read` uses GET. `Write` uses PUT. `Remove` uses DELETE. `Exists` uses HEAD and falls back to GET when the status is neither success, not found, nor forbidden.

### Errors

An invalid relative path returns a plain error and does not call the server. `OpenFolder` wraps `ErrNotExist` on HTTP 404, `ErrForbidden` on 401 or 403, and `ErrNotDir` when the resource is not a collection. `EnsureFolder` wraps `ErrForbidden` on 401 or 403. Other unexpected statuses are plain errors that include the HTTP status.

### Example

```go
root := goncfiles.WebDAVRoot{Cred: cred}
folder, err := root.OpenFolder("Zones")
if err != nil {
    if goncfiles.IsNotExist(err) {
        return fmt.Errorf("folder missing")
    }
    return err
}
_ = folder
```

## CleanRel

### Purpose

`CleanRel` normalizes a User Files Root–relative path. The result uses forward slashes and has no leading or trailing slash.

### When to use it

The roots call `CleanRel` themselves. Call it directly when the product must reject a path before opening a folder, or must show the normalized form.

### Call sequence

1. Pass the raw path from a query parameter or a saved preference.
2. Treat an empty result as invalid. Do not open it.

Backslashes are treated as slashes. `..`, URLs, and a bare numeric Nextcloud file ID are rejected.

### Errors

`CleanRel` does not return an error. An empty string means the path is not usable. Callers that need an error, such as `OpenFolder`, turn that empty result into `invalid Working Folder path`.

### Example

```go
rel := goncfiles.CleanRel(r.URL.Query().Get("folder"))
if rel == "" {
    http.Error(w, "invalid folder", http.StatusBadRequest)
    return
}
```

## RequireBasename

### Purpose

`RequireBasename` accepts a single file name inside a Working Folder and rejects a path.

### When to use it

`Folder` methods call it before touching a child. Call it directly when the product checks a name before building a request.

### Call sequence

1. Pass the child name.
2. Continue only when the error is nil.

An empty name, a name containing `/` or `\`, a name containing `..`, or a name that is not `path.Base` of itself is rejected.

### Errors

The error text is `name must be a basename in the Working Folder`. It does not wrap `ErrNotExist` or `ErrForbidden`.

### Example

```go
if err := goncfiles.RequireBasename(name); err != nil {
    return err
}
```

## DefaultPathStore

### Purpose

`DefaultPathStore` persists the Saved Default Working Folder path, relative to the User Files Root. `GetDefault` returns that path, or empty when none is stored. `SetDefault` writes a new path.

### When to use it

Visit reads and writes the Saved Default through this interface. `FileStore` is a JSON file (`defaultPath`) for the local adapter. `Memory` is an in-memory store for tests. An ExApp that stores the path in Nextcloud preferences implements the same two methods around `gonexapp.AppAPIPreferences`. This library does not call OCS.

### Call sequence

1. Construct a `FileStore` with a file path, a `Memory`, or a product store.
2. Pass it to `Open`.
3. `GetDefault` on a missing file returns empty and a nil error.
4. `SetDefault` writes the path. `FileStore` creates parent directories and writes indented JSON.

`Visit.SetDefault` is the call that also ensures the folder exists. It is described under Visit.

### Errors

`FileStore.GetDefault` returns an error when the file exists and cannot be read or is not JSON. A missing file is not an error. `FileStore.SetDefault` returns an error when the directory cannot be created or the file cannot be written. `Memory` does not return an error.

### Example

```go
store := goncfiles.FileStore{Path: filepath.Join(dir, "settings.json")}
saved, err := store.GetDefault()
if err != nil {
    return err
}
_ = saved
```

## Visit

### Purpose

A Visit is one opening of the ExApp: the Working Folder for this request, and the Saved Default. App-icon launch uses the Saved Default and creates the initial folder when it is missing. A Files-view folder is used only for this visit and does not change the Saved Default.

### When to use it

Call `Open` at the start of a request that needs the user's Working Folder. Use `OpenLocal` when both the files root and the settings file are on local disk.

### Call sequence

1. Call `Open` with a `Root`, a `DefaultPathStore`, the product's initial folder name, and the visit-relative path.
2. Pass an empty visit-relative path for an app-icon launch. `Open` reads the Saved Default, uses `initialFolderName` when nothing is stored, and `EnsureFolder`s that path.
3. Pass the Files-view folder for a visit-only path. `Open` uses `OpenFolder` and does not create it and does not fall back to the Saved Default.
4. Use `Visit.FS` as the `Folder`, `WorkingRel` as the relative path, and `SavedDefault` as the stored default.
5. Call `SetDefault` when the user picks a new default. It `EnsureFolder`s the path, stores it, and updates `SavedDefault`. It does not switch `FS` to that folder.
6. `WorkingDir` returns a local absolute path when `FS` is a local folder, and `WorkingRel` otherwise.

### Errors

`Open` returns the error from `GetDefault`. An invalid saved path or an invalid visit path is a plain error (`invalid Working Folder path` or `invalid saved Working Folder path`). A missing or forbidden visit path fails closed: the error from `OpenFolder` is wrapped with the path, and the Saved Default is not opened instead.

`SetDefault` returns a plain error for an invalid path, or the error from `EnsureFolder` or `SetDefault` on the store.

### Example

```go
visit, err := goncfiles.Open(root, store, "myapp", visitRelative)
if err != nil {
    if goncfiles.IsForbidden(err) {
        http.Error(w, "forbidden", http.StatusForbidden)
        return err
    }
    return err
}
data, err := visit.FS.Read("note.txt")
_ = visit.WorkingRel
_ = data
```