Files
mtusi2026lab4/contracts/extensions.md
T
Чиняева f39ae06ef3 Реализовать лабораторную 4 на оценку 5
Добавить приватное S3-хранилище, вложения, presigned upload, reconciler и доказательства.
2026-11-07 01:37:21 +03:00

2.0 KiB

Lab4 extensions: presigned direct upload (track 1)

The mandatory contract in openapi.json is unchanged. The proxy endpoint POST /api/v1/chats/{chat_id}/attachments remains the required path and is the fallback for clients that cannot reach S3. This extension adds an optional direct path:

  1. POST /api/v1/chats/{chat_id}/attachments/presign with {filename, content_type, size_bytes, sha256} creates a pending attachment row and returns a short-lived presigned PUT URL.
  2. The client uploads the bytes directly to the private bucket using the URL and the returned Content-Type / x-amz-meta-sha256 headers.
  3. POST /api/v1/attachments/{attachment_id}/complete with {sha256, size_bytes} verifies ownership, the stored object size and the SHA-256 of the bytes. Only then does the attachment become ready.

Rules

  • The bucket stays private. The URL is the only grant, expires after PRESIGN_TTL_SECONDS (default 300 s), and uses a unique server-generated object key.
  • Complete is owner-only and chat-member-only. A different user receives 404.
  • Complete is idempotent for the same (sha256, size_bytes) pair. A different pair on a ready attachment is 409.
  • Completing before the object exists, after the URL expired, or after the pending row was cleaned up is 409.
  • A wrong size or checksum is 400; the wrong object is deleted and is never promoted to ready.
  • GET /api/v1/attachments/{id} may return pending for this extension. The mandatory proxy path always returns ready.
  • Incomplete uploads are removed by python -m app.reconcile --apply after PRESIGN_GRACE_SECONDS (default 3600 s). Orphan objects that never got a metadata row are removed after ORPHAN_GRACE_SECONDS (default 86400 s).
  • The complete call reads the object once through the API to verify its checksum. That is a deliberate integrity cost: direct upload avoids API ingress, but the API still verifies egress. A future S3 checksum API could remove this read; SeaweedFS 3.80 does not provide the same portable hook.