# Copilot Instructions for nidus A self-hosted CalDAV, CardDAV, and WebDAV server written in Go, backed by a filesystem store. HTTP Basic Auth (bcrypt) with per-user isolated collections. ## Build, test, lint ```bash make build # go build -o bin/davserver ./cmd/server make run # build + ./bin/davserver -config config.yaml make test # go test ./... -v -race make lint # golangci-lint run ./... make tidy # go mod tidy go test ./internal/store/ -run TestStoreRoundTrip -v # single test ``` There is currently only one test file: `internal/store/store_test.go`. ## Architecture - `cmd/server/main.go` — entrypoint. Loads config, builds the `slog.Logger`, constructs the `store.Store`, pre-creates each user's configured calendars/address-books as collections, wires up `auth.Middleware`, and builds the `http.ServeMux` (`buildMux`). Routes: `/cal/`, `/card/`, `/files/`, `/.well-known/{caldav,carddav}`, `/healthz` (unauthenticated), and `/` (welcome page on GET/HEAD only; any other method — e.g. a WebDAV client pointed at the wrong URL — gets `405` instead of a misleading `200`). - `internal/config` — YAML config loading (`config.Load`), defaults (`applyDefaults`), and validation (`validate`). `Config.Users` is a `map[string]UserConfig` keyed by username; each user has a bcrypt `Password`, `Calendars`, and `AddressBooks` lists that seed collection names. - `internal/auth` — HTTP Basic Auth middleware (`auth.Middleware.Wrap`). Validates credentials against `cfg.Users` via bcrypt, then stores a `*Principal{Username, DisplayName, Email}` in the request context. Downstream code retrieves it with `auth.FromContext(ctx)` — every backend method needs this and returns `webdav.NewHTTPError(http.StatusUnauthorized, ...)` if it's nil. `auth.NewContext(ctx, p)` is the test-only inverse, used to build authenticated contexts without a real Basic Auth handshake. - `internal/store` — the single source of truth for all persisted data. A thin filesystem KV abstraction: `///`. All collection/object names pass through `sanitize()` (via `filepath.Base` + strip `..`) to prevent path traversal — preserve this when adding new store methods. Writes use temp-file + rename for atomicity (`PutObject`). Locking is sharded per-user (`lockFor(user)`, a `map[string]*sync.RWMutex` guarded by its own mutex) rather than one global lock, so different users' requests don't serialize against each other. - `internal/caldav` and `internal/carddav` — implement the `caldav.Backend`/`carddav.Backend` interfaces from `github.com/emersion/go-webdav` on top of `store.Store`. Calendars are stored as collections prefixed `cal-` and address books as `card-` (see `ListCalendars`, `parseCalPath`). **The URL scheme has no username segment**, but DOES have a fixed literal `home` segment: `/cal/` (principal), `/cal/home/` (calendar-home-set), `/cal/home//` (calendar), `/cal/home//` (object) — and equivalently `/card/`, `/card/home/`, `/card/home//`, `/card/home//` for carddav. These are identical for every user; the acting user always comes from `auth.FromContext(ctx)`, never from the path. **The `home` segment is load-bearing, not cosmetic**: go-webdav's `caldav`/`carddav` server (in the `github.com/emersion/go-webdav` dependency, not our code) classifies each request purely by counting URL path segments relative to the handler's `Prefix` (which we leave `""`) — 1 segment = user principal, 2 = home-set, 3 = calendar/address book, 4 = object. If the segment counts don't line up (e.g. removing `home` would make `/cal/` and `/cal//` collapse to 1 and 2 segments, misclassifying the calendar collection itself as the home-set), PROPFIND requests silently return an empty `` (200/207, zero `` elements) — no error, just nothing found, which breaks client auto-discovery (e.g. DAVx5 reporting "no resources found"). Keep this in mind when touching `parseCalPath`/`parseObjPath`/`parseBookPath`, `calHomePath`/`cardHomePath`, or `CurrentUserPrincipal` — always preserve the exact segment depth at each level. Query methods (`QueryCalendarObjects`) currently list all objects and filter in-memory via `caldav.Filter` — fine for small collections, not optimized for scale. - `internal/webdav` — plain-file WebDAV via `golang.org/x/net/webdav`, mounted at the single fixed URL `/files/` for all users (no username in the path either). `NewHandler` caches one `*xwebdav.Handler` per authenticated username (keyed off `auth.FromContext`), each rooted at `/files//` on disk with its own persistent `LockSystem` — the handler (and its lock table) must be created once and reused, not per-request, or LOCK/UNLOCK state resets on every call. - `tools/hashpwd` — standalone CLI (`go run ./tools/hashpwd `) to generate bcrypt hashes for `config.yaml`. ## Conventions - **No username in any DAV URL** (`/cal/`, `/card/`, `/files/` are the same for every account) — the acting user is always resolved from the Basic Auth identity (`auth.FromContext`), never parsed out of the request path. Don't reintroduce a `` path segment when adding routes/paths. - Path parsing in the CalDAV/CardDAV backends assumes fixed URL segment positions (e.g. `cal/home//`) split on `/` — see `parseCalPath`/`parseObjPath`/`parseBookPath`. The `home` segment must stay exactly one fixed literal segment (see note above on go-webdav's segment-count-based resource classification) — don't remove it or add/ remove segments elsewhere without re-checking all four resource-type depths still line up. New path-based operations should follow the same segment-index approach for consistency. - Store errors are sentinel values (`store.ErrNotFound`, `store.ErrConflict`) checked with `errors.Is`/direct comparison; backends translate them into `webdav.NewHTTPError` with the appropriate HTTP status. - Logging uses `log/slog` structured fields (e.g. `logger.Warn("...", "user", u, "error", err)`), passed down explicitly to every constructor (`NewBackend`, `NewHandler`, `NewMiddleware`) rather than a global logger. - Config module path is `github.com/yourusername/caldav-server` (go.mod name predates the `nidus` repo rename) — import paths still use this, not `nidus`.