Skip to content

Server: add a detach/clear route for file fields (unblocks entity file clear) #120

Description

@rrrodzilla

Problem

#118 added entity file upload / download CLI verbs (PR #119), but entity file clear from the original proposal was deliberately omitted: no server route exists to detach an attachment from a file field.

Working around it client-side is wrong:

  • A PATCH setting the field to null would orphan the S3 object — the bytes stay in the bucket with no entity reference, invisible to retention/forensics tooling.
  • It bypasses the attachment state machine (pending → uploaded → scanning → available | quarantined | rejected) and the durable audit chain that the file routes write to (forge.file.* events).

The attachment lifecycle is deliberately centralized server-side (see crates/schema-forge-acton/src/routes/files.rs), so detach must be too.

Proposed route

DELETE /schemas/{schema}/entities/{id}/fields/{field}

  • Requires Write access on the schema (same as mint/confirm), audited to the durable chain (forge.file.detached).
  • Sets the field to null on the entity.
  • Decide and document the object-disposition policy: delete the S3 object, or retain it under its key for forensics (consistent with how quarantined objects are retained in v1) and rely on lifecycle rules. Retention seems more consistent with the existing posture; deletion could be a config or query flag.
  • required file fields: detach should be refused (409/422) since it would leave the entity invalid.
  • Hook surface: consider whether a before_detach-style event is needed, or whether the existing audit entry suffices for v1.

CLI follow-up

Once the route lands, add schemaforge entity file clear <schema> <id> <field> wrapping it — the CLI scaffolding from PR #119 (ForgeClient, EntityFileCommands) makes that a small addition.

Refs #118, #119.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions