# Design This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them. ## Data model Use the database in the `database` input. | Table | Columns | | --- | --- | | `files` | `id`, `uploader_id`, `storage_key` (unique), `preview_key`, `name`, `media_type`, `size`, `state`, `reject_reason`, `created_at`, `ready_at`, `deleted_at` | | `file_attachments` | `file_id`, `record_type`, `record_id`; primary key on all three | `state` is one of `pending`, `scanning`, `ready`, `rejected` and `deleting`. ## Types and their first bytes A type in the `allowed_types` input must be in this table. Bytes are in hexadecimal. | Type | Extension | The file starts with | | --- | --- | --- | | `image/png` | `.png` | `89 50 4E 47 0D 0A 1A 0A` | | `image/jpeg` | `.jpg` | `FF D8 FF` | | `image/gif` | `.gif` | `47 49 46 38 37 61` or `47 49 46 38 39 61` | | `image/webp` | `.webp` | `52 49 46 46`, then any 4 bytes, then `57 45 42 50` | | `application/pdf` | `.pdf` | `25 50 44 46 2D` | | `application/zip` | `.zip` | `50 4B 03 04` | | `text/plain` | `.txt` | No fixed start. The first 4,096 bytes must be valid UTF-8 with no zero byte. | | `text/csv` | `.csv` | The same rule as `text/plain`. | Office documents are zip files and cannot be told apart by their first bytes. To allow them, add their types here with the zip start, and serve them as attachments only. ## The signed address With `storage` set to `s3_compatible`, the address in R1 is a presigned `PUT` with `Content-Length` and `Content-Type` among the signed headers, so storage refuses any other size or type. Read only the first 16 bytes back for R2, with a range request, and the size from the object's metadata. The bucket blocks all public access. Its CORS rule allows `PUT` from the app's own origin only. ## Names | Name given | Name kept | | --- | --- | | `../../etc/passwd` | `etcpasswd` | | `report` then a newline then `.pdf` | `report.pdf` | | `.htaccess` | `htaccess` | | 500 letters `a` then `.png` | 196 letters `a` then `.png` | | An empty name, type `image/png` | `file.png` | In the `Content-Disposition` header, send the name both ways: an ASCII fallback with anything else replaced by `_`, and `filename*=UTF-8''` with the real name percent-encoded. ## Deleting 1. Set `state` to `deleting`. 2. Delete the stored file and its preview. A file that is already gone counts as deleted. 3. Delete the row. A clean-up run once an hour starts this for unattached and unfinished files older than 24 hours, and finishes it for rows left in `deleting`. ## Configuration | Secret | Purpose | | --- | --- | | `DATABASE_URL` | Connection string for the chosen database. | | `STORAGE_ENDPOINT` | Address of the storage service. Not needed for `local_disk`. | | `STORAGE_BUCKET` | Name of the bucket. Not needed for `local_disk`. | | `STORAGE_ACCESS_KEY_ID` | Storage credentials. Not needed for `local_disk`. | | `STORAGE_SECRET_ACCESS_KEY` | Storage credentials. Not needed for `local_disk`. | ## Who is signed in The spec reaches the app's sign-in through one function, `current_user(request)`. It answers with the person's id, and says whether they are an administrator where this spec asks. In the person's app it reads their session. When there is no app yet, build this stand-in and nothing more: a page that lists two seeded people, one of them an administrator, with a button for each that sets a signed cookie naming them. The stand-in refuses to start in production. ## What this spec leaves to you Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.