docs(spec): xcecli-presets: server preset directory, pull name collisions, /xce/v1 routes

- server presets live in <TopDir>/config/presets/ (or presets.dir in
  app.yaml), one file per preset, re-read on change; not in ClusterConfig
- pull refuses a name collision unless it updates the same server preset;
  --as / --force (keeps .bak); submit uses local presets only
- fix route prefix: /xce/v1/presets, not /api/v1

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Rongsong Shen 2026-10-12 10:33:31 +00:00
parent d1e03055e4
commit 83c6eb8024
Signed by untrusted user: rshen
GPG key ID: 80533536B0EB651C
3 changed files with 39 additions and 7 deletions

View file

@ -380,7 +380,7 @@ Not part of this spec, recorded here because they replace profile defaults:
values.
- Personal presets live one file per preset under `~/.config/xce/presets/`.
- The apiserver **only shares**: admin-deployed preset files served
read-only (`GET /api/v1/presets`, `GET /api/v1/presets/{name}`). Pulling
read-only (`GET /xce/v1/presets`, `GET /xce/v1/presets/{name}`) from `<TopDir>/config/presets/`. Pulling
copies a preset into the local file, so a server preset being removed
never affects users. `preset diff` / `pull --force` are user-initiated.
- User-to-user sharing by `preset export` / `import` (file, mail, git).

View file

@ -49,16 +49,48 @@ configuration level.
- **Personal presets** are files under `~/.config/xce/presets/`; users
change them on the fly (`xcecli preset set / edit / show / list / delete`).
- **The server only shares.** The apiserver serves admin-deployed preset
files read-only: `GET /api/v1/presets` (list) and
`GET /api/v1/presets/{name}` (fetch). Team presets are namespaced
(`<team>/<name>`, a subdirectory). No database, no HA; with several apiservers the files
are deployed to each, like `rbac.yaml`. Every authenticated user may see
them.
files read-only: `GET /xce/v1/presets` (list, with each preset's content
hash) and `GET /xce/v1/presets/{name}` / `{ns}/{name}` (fetch). Every
authenticated user may see them.
- **Where server presets live** (user, 2026-10-12): a directory beside the
apiserver's other config, `<TopDir>/config/presets/` (as
`config/rbac.yaml` and `config/auth.yaml`, `apiserver/cmd/main.go:144`,
`:152`), overridable by `presets.dir` in `app.yaml` (e.g.
`/etc/xce/presets`).
- One file per preset; site presets at the top level, team presets one
subdirectory deep (`cfd-team/openfoam-large.yaml`).
- Re-read when a file's mtime changes, no restart; a file that fails to
parse is skipped, logged and not listed, without affecting the others.
- No database, no HA. With several apiservers the directory is deployed
to each, like `rbac.yaml`; the content hashes in the listing let a
client notice a mismatch.
- Delegation needs no feature: `presets.dir` can be a git checkout pulled
by a timer, so teams change presets by pull request with history.
- Not in `ClusterConfig`: controller and scheduler never use presets
(independence rule, `config-design.md`) and presets change far more
often than cluster config (frequency rule); it would also turn every
preset edit into a cluster config upgrade.
- **Pull copies.** `xcecli preset pull <name>` writes a complete, standalone
local preset with an informational `origin` (server name, content hash,
pull date). Removing or changing a server preset never affects local
copies. `xcecli preset diff <name>` compares with the server (reports when
it is gone); `preset pull --force` refreshes. Both are user-initiated.
- **Name collisions on pull** (user, 2026-10-12). Namespaced presets go to
their subdirectory, so only the same path can collide:
- the local file is a pulled copy of the same server preset (its `origin`
matches): an update; pull shows the diff and stops, `--force` replaces
it;
- anything else (a personal preset, or a copy from another server or
path): pull refuses and suggests `--as <name>` (pull under another local
name; `origin` keeps the server name, so `diff` still works) or
`--force`;
- `--force` keeps the replaced file as `<name>.yaml.bak`;
- `preset pull --all [ns]` applies the same rules per preset, listing and
skipping collisions.
- **Submit uses local presets only.** `--preset X` not found locally but
present on the server stops with "not found locally; the server has `X`:
run `xcecli preset pull X`". Never an automatic pull, so server changes
or removals never affect a submit.
- **User-to-user sharing** without the server: `preset export` / `import`
(file, mail, git).
- **Site presets complement profiles.** Admins typically publish a preset