API consistency follow-ups from batch A (REST rename overwrite, .trash name, OCM PUT codes, OIDC log level) #926

Closed
opened 2026-10-15 21:22:27 +00:00 by Cordy · 4 comments
Owner

Follow-ups from batch A (v0.6.343) that need a decision:

  1. REST rename onto an existing file: it overwrites silently, while REST copy answers 409. Should rename refuse existing destinations too?
  2. The .trash name: it is not reserved for user-created files and folders.
  3. OCM grant PUT: it answers 500 for quota, held, locked and read-only, with no code. This predates batch A.
  4. OIDC sign-in reason: the DEBUG line explaining why a sign-in did not count as the confirmation is invisible, because cairnd has no log-level setting.
  5. Claims.Reauthed: it is set but never read.

Related, already filed: #918 (renames and trash paths), #920 (purge audit).

Follow-ups from batch A (v0.6.343) that need a decision: 1. **REST rename onto an existing file:** it overwrites silently, while REST copy answers 409. Should rename refuse existing destinations too? 2. **The `.trash` name:** it is not reserved for user-created files and folders. 3. **OCM grant PUT:** it answers 500 for quota, held, locked and read-only, with no code. This predates batch A. 4. **OIDC sign-in reason:** the DEBUG line explaining why a sign-in did not count as the confirmation is invisible, because cairnd has no log-level setting. 5. **`Claims.Reauthed`:** it is set but never read. Related, already filed: #918 (renames and trash paths), #920 (purge audit).
Author
Owner

Batch 4 (2026-10-19)

Items 3 and 5: fixed on branch fix-b4-a; they ship in v0.6.351.

  • Item 3: the OCM grant PUT now answers each refusal with its own status and code:

    • quota: 507 quota-exceeded
    • legal hold: 423 legal-hold, the WebDAV status, because this is a WebDAV surface
    • lock: 423 locked
    • read-only: 403 read-only

    The body text is unchanged, and a rate-limited WARN ocm grant write refused is logged.

  • Item 5: Claims.Reauthed was dead and is removed. #907 moved its only reader to Claims.Confirms.

Deep research, items 1, 2 and 4

The full write-up, with sources, is in ~/cairn-work/scratch/b7e/backlog/research-b4.md §4 to §6.

1. REST rename onto an existing file (confirmed on posix and s3)

  • Today: the file is silently replaced, while folders are refused with 409 and REST copy answers 409 with no code.
  • What the UI does: the rename dialog blocks taken names. Move to, drag and drop, bulk move and "new space from selection" all replace silently. Since #908 the old content survives only as a version.
  • Others: Dropbox, Box and Microsoft Graph all refuse with 409 unless the caller explicitly asks to replace or rename.
  • Recommendation: 409 destination-exists unless the body sends "overwrite": true. Copy's 409 gets the same code.
  • UI: until a conflict prompt exists, the move flows show the existing "Move failed" message. A Replace / Keep both / Skip prompt needs a mockup.

2. .trash is half reserved (confirmed)

  • What happens: about ten layers treat a .trash folder at any depth as trash. A user-made .trash is hidden from the web and WebDAV listings but still exists: it holds quota and drops locks and owner records. At a space root, creating one answers 404.
  • Who creates it: Obsidian keeps a vault-local .trash, and the Nextcloud desktop client does not exclude that name.
  • Others: Nextcloud, Synology and the operating systems reserve trash names only at a root.
  • Recommendation:
    • Use one exact predicate: /.trash and /spaces/<x>/.trash only.
    • .trash anywhere else becomes an ordinary folder.
    • Creating .trash at a space root (and at the backend root in flat mode) is refused with 409 name-reserved and a clear text.

4. Invisible OIDC DEBUG line

  • Today: cairnd has no log-level setting.
  • Others: Nextcloud, Forgejo, Keycloak and Caddy all have one. Nextcloud's default level suppresses its own audit log, a trap Cairn must avoid.
  • Recommendation, both parts:
    • Add log.level / CAIRN_LOG_LEVEL (default info). It is read at start and never affects the audit log.
    • Make the line INFO.
    • The "no auth_time" case (a configuration fault that hits every sign-in) becomes a WARN at most once an hour, with the fix in the message.

Decisions: asked now.

## Batch 4 (2026-10-19) **Items 3 and 5: fixed on branch fix-b4-a; they ship in v0.6.351.** - **Item 3:** the OCM grant PUT now answers each refusal with its own status and code: - quota: 507 `quota-exceeded` - legal hold: 423 `legal-hold`, the WebDAV status, because this is a WebDAV surface - lock: 423 `locked` - read-only: 403 `read-only` The body text is unchanged, and a rate-limited WARN `ocm grant write refused` is logged. - **Item 5:** `Claims.Reauthed` was dead and is removed. #907 moved its only reader to `Claims.Confirms`. ## Deep research, items 1, 2 and 4 The full write-up, with sources, is in `~/cairn-work/scratch/b7e/backlog/research-b4.md` §4 to §6. **1. REST rename onto an existing file (confirmed on posix and s3)** - **Today:** the file is silently replaced, while folders are refused with 409 and REST copy answers 409 with no code. - **What the UI does:** the rename dialog blocks taken names. Move to, drag and drop, bulk move and "new space from selection" all replace silently. Since #908 the old content survives only as a version. - **Others:** Dropbox, Box and Microsoft Graph all refuse with 409 unless the caller explicitly asks to replace or rename. - **Recommendation:** 409 `destination-exists` unless the body sends `"overwrite": true`. Copy's 409 gets the same code. - **UI:** until a conflict prompt exists, the move flows show the existing "Move failed" message. A Replace / Keep both / Skip prompt needs a mockup. **2. `.trash` is half reserved (confirmed)** - **What happens:** about ten layers treat a `.trash` folder at any depth as trash. A user-made `.trash` is hidden from the web and WebDAV listings but still exists: it holds quota and drops locks and owner records. At a space root, creating one answers 404. - **Who creates it:** Obsidian keeps a vault-local `.trash`, and the Nextcloud desktop client does not exclude that name. - **Others:** Nextcloud, Synology and the operating systems reserve trash names only at a root. - **Recommendation:** - Use one exact predicate: `/.trash` and `/spaces/<x>/.trash` only. - `.trash` anywhere else becomes an ordinary folder. - Creating `.trash` at a space root (and at the backend root in flat mode) is refused with 409 `name-reserved` and a clear text. **4. Invisible OIDC DEBUG line** - **Today:** cairnd has no log-level setting. - **Others:** Nextcloud, Forgejo, Keycloak and Caddy all have one. Nextcloud's default level suppresses its own audit log, a trap Cairn must avoid. - **Recommendation, both parts:** - Add `log.level` / `CAIRN_LOG_LEVEL` (default `info`). It is read at start and never affects the audit log. - Make the line INFO. - The "no auth_time" case (a configuration fault that hits every sign-in) becomes a WARN at most once an hour, with the fix in the message. **Decisions:** asked now.
Author
Owner

Decision (Nikola, 2026-10-19). All recommendations accepted for items 1, 2 and 4.

  • Item 1, rename onto an existing name (D5 a, D6 a):
    • A rename onto an existing name answers 409 destination-exists unless the request sends {"overwrite": true}.
    • Copy's 409 gets the same code. Copy does not get an overwrite flag yet.
    • This ships now. The web move flows show the existing "Move failed" message until a Replace / Keep both / Skip prompt is designed, which needs its own mockup and is filed separately.
  • Item 2, the .trash name (D7 b): one exact trash predicate everywhere: only /.trash and /spaces/<x>/.trash. A .trash anywhere else is an ordinary folder. Creating .trash at a space root, or at the root in flat mode, answers 409 name-reserved with a clear text.
  • Item 4, logging (D8 c):
    • New log.level / CAIRN_LOG_LEVEL setting, default info, read at start. It never affects the audit log.
    • The OIDC confirmation line becomes INFO.
    • The "no auth_time" case becomes a WARN at most once an hour, with the fix in the message.

Implemented in batch 4 (v0.6.351).

**Decision (Nikola, 2026-10-19).** All recommendations accepted for items 1, 2 and 4. - **Item 1, rename onto an existing name (D5 a, D6 a):** - A rename onto an existing name answers 409 `destination-exists` unless the request sends `{"overwrite": true}`. - Copy's 409 gets the same code. Copy does not get an `overwrite` flag yet. - This ships now. The web move flows show the existing "Move failed" message until a Replace / Keep both / Skip prompt is designed, which needs its own mockup and is filed separately. - **Item 2, the `.trash` name (D7 b):** one exact trash predicate everywhere: only `/.trash` and `/spaces/<x>/.trash`. A `.trash` anywhere else is an ordinary folder. Creating `.trash` at a space root, or at the root in flat mode, answers 409 `name-reserved` with a clear text. - **Item 4, logging (D8 c):** - New `log.level` / `CAIRN_LOG_LEVEL` setting, default `info`, read at start. It never affects the audit log. - The OIDC confirmation line becomes INFO. - The "no auth_time" case becomes a WARN at most once an hour, with the fix in the message. Implemented in batch 4 (v0.6.351).
Author
Owner

One deviation from the decision text (item 2), made during the build (2026-10-19): WebDAV and the OCM grant PUT answer creating .trash at a space root with 403 name-reserved, not 409.

The reason: RFC 4918 uses 409 to mean "a parent folder is missing", and sync clients answer a 409 by creating parent folders and retrying. 403 means "this name is not allowed here". REST, TUS and the public drop link still answer 409 name-reserved, as decided. The release docs will state both.

**One deviation from the decision text (item 2), made during the build (2026-10-19):** WebDAV and the OCM grant PUT answer creating `.trash` at a space root with **403** `name-reserved`, not 409. The reason: RFC 4918 uses 409 to mean "a parent folder is missing", and sync clients answer a 409 by creating parent folders and retrying. 403 means "this name is not allowed here". REST, TUS and the public drop link still answer **409** `name-reserved`, as decided. The release docs will state both.
Author
Owner

Shipped in v0.6.351 (PR #984). Both dogfoods run it.

Live check, 2026-10-20 (files-bao on S3 and files on posix, throwaway data, now removed): PASS

  • Item 1, rename onto an existing name. POST /api/v1/rename onto an existing b.txt answered 409 destination-exists with "Something with this name is already there." and X-Cairn-Code. POST /api/v1/copy onto it gave the same 409 and code. With "overwrite": true the rename answered 200, and b.txt's replaced content was kept as a version.
  • Item 2, .trash folders.
    • A .trash folder in a home subfolder, and one in a space subfolder, were both created (201).
    • In the web list, the home one shows with "Show hidden files" on, like any dot-folder.
    • At a space root, as a session admin, creating .trash answered 403 trash-managed. That is the admin path, which stays; other people get name-reserved (covered by tests).
  • Item 3, OCM grant PUT codes. Not reproducible live: no OCM share is active on the dogfoods. Covered by tests on posix and s3.
  • Item 4, logging. Both instances start at the default level with no new WARN. The auth_time WARN did not appear, so the Keycloak client sends auth_time.
  • Item 5: a code removal only; the build and tests cover it.

Follow-up for the move conflict prompt: #975.

**Shipped in v0.6.351 (PR #984). Both dogfoods run it.** **Live check, 2026-10-20 (files-bao on S3 and files on posix, throwaway data, now removed): PASS** - **Item 1, rename onto an existing name.** `POST /api/v1/rename` onto an existing `b.txt` answered 409 `destination-exists` with "Something with this name is already there." and `X-Cairn-Code`. `POST /api/v1/copy` onto it gave the same 409 and code. With `"overwrite": true` the rename answered 200, and `b.txt`'s replaced content was kept as a version. - **Item 2, `.trash` folders.** - A `.trash` folder in a home subfolder, and one in a space subfolder, were both created (201). - In the web list, the home one shows with "Show hidden files" on, like any dot-folder. - At a space root, as a session admin, creating `.trash` answered 403 `trash-managed`. That is the admin path, which stays; other people get `name-reserved` (covered by tests). - **Item 3, OCM grant PUT codes.** Not reproducible live: no OCM share is active on the dogfoods. Covered by tests on posix and s3. - **Item 4, logging.** Both instances start at the default level with no new WARN. The `auth_time` WARN did not appear, so the Keycloak client sends `auth_time`. - **Item 5:** a code removal only; the build and tests cover it. Follow-up for the move conflict prompt: #975.
Cordy closed this issue 2026-10-20 13:58:09 +00:00
Sign in to join this conversation.
No labels
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference: Cordy/Cairn#926
No description provided.