storage

Overview ¶

Command storage shows object storage end to end: files uploaded to and downloaded from App.Storage() through plain HTTP handlers. The store is the local driver under ./storage by default (GOMBIT_STORAGE_DRIVER=memory keeps files in the process instead); handlers never see which.

go run ./examples/storage
curl -X PUT --data-binary @photo.jpg -H 'Content-Type: image/jpeg' localhost:8080/files/photo
curl localhost:8080/files/photo -o copy.jpg
curl -X DELETE localhost:8080/files/photo
curl -F file=@photo.jpg localhost:8080/uploads
curl localhost:8080/uploads/<id> -OJ
curl localhost:8080/uploads/<id>/link   # a download link valid for up to 5 minutes

A direct upload is a signed PUT the client makes on its own, with the grant the app gave it. Only with S3 (GOMBIT_STORAGE_DRIVER=s3) do the bytes go straight to the bucket, bypassing the app process; with the local driver (the default) and memory, the PUT goes to the app's own storage route (/_storage), which streams the bytes into the store, so they pass through the app process (though not through these handlers):

curl -X POST localhost:8080/uploads/direct -d '{"size":1234,"content_type":"image/png","filename":"a.png"}'
curl -X PUT --data-binary @a.png -H 'Content-Type: image/png' '<data.upload.url>'
curl -X POST localhost:8080/uploads/direct/<id>/confirm

The key is built by the server: "files/" + the id in the path (checked first, so a malformed one is a 404, not a server error), or, for a form upload, a random id under "uploads/" from storage/upload, which also bounds the size, checks the detected type, and keeps the client's filename as metadata only.

A link is a signed URL: the browser downloads straight from storage (here, the app's own /_storage route; on S3, the bucket) until it expires. Links need a signing key, GOMBIT_STORAGE_URL_SECRET (32 bytes or more) or GOMBIT_JWT_SECRET, for the local and memory drivers; this example sets a development-only one when neither is configured.

internal/document is a generated resource with storage-backed fields (a file and an image): ask the field's upload endpoint for a grant, upload, then create the record with the key.

curl -X POST localhost:8080/api/v1/documents/uploads/attachment -d '{"size":1234,"content_type":"application/pdf","filename":"a.pdf"}'
curl -X PUT --data-binary @a.pdf -H 'Content-Type: application/pdf' 'localhost:8080<data.upload.url>'
curl -X POST localhost:8080/api/v1/documents -d '{"title":"A","attachment":"<data.key>","cover":null}'
curl localhost:8080/api/v1/documents

Uploads are recorded in a SQLite database (in memory) under the ownership protocol of storage/claims: every upload's key is claimed (pending) before anything is stored; the record that refers to it holds it in the same transaction; deleting the record releases it; and an hourly sweep deletes uploads no record ever held. So no cleanup ever deletes a file a record refers to, whatever fails or races.