File storage

Files go to the local filesystem, an S3 bucket or Google Cloud Storage, behind the same interface. Switching between them is a change in .env rather than a change in your code.

.env

STORAGE_BACKEND=local       # saves to static/uploads/

# or S3 and S3-compatible services
STORAGE_BACKEND=s3
S3_BUCKET=my-bucket

# or Google Cloud Storage
STORAGE_BACKEND=gcs
GCS_BUCKET=my-bucket

When STORAGE_BACKEND is unset, setting S3_BUCKET selects s3. Otherwise the app’s STORAGE_BACKEND_FALLBACK applies, then local. See automatic backends.

S3 and S3-compatible storage

The s3 backend works with AWS S3 and with services that speak its API, such as MinIO, Garage, Cloudflare R2 and Hetzner Object Storage. It needs the s3 extra:

pip install 'feather-framework[s3]'

.env

S3_BUCKET=my-bucket
S3_ENDPOINT=https://s3.example.com     # omit for AWS
S3_REGION=eu-central-1
S3_ACCESS_KEY_ID=...
S3_SECRET_ACCESS_KEY=...

Key	Default	Meaning
`S3_BUCKET`	required	Bucket name
`S3_ENDPOINT`	unset	Endpoint URL of an S3-compatible service. Unset means AWS
`S3_REGION`	boto3 default	Region name
`S3_ACCESS_KEY_ID`	unset	Access key. Leave both keys unset to use the boto3 credential chain (environment, profile, instance role)
`S3_SECRET_ACCESS_KEY`	unset	Secret key
`S3_ADDRESSING_STYLE`	`path` with `S3_ENDPOINT`, else `auto`	`path`, `virtual` or `auto`
`S3_URL_EXPIRES`	`3600`	Lifetime of presigned URLs, in seconds
`S3_PUBLIC_URL`	unset	Base URL the bucket is publicly served from

Buckets are treated as private. upload() and get_url() return a presigned GET URL that expires after S3_URL_EXPIRES seconds. If the bucket is public, or sits behind a CDN, set S3_PUBLIC_URL and they return S3_PUBLIC_URL/<key> instead. With S3_ENDPOINT set, Feather tells boto3 to send and check request checksums only when an operation requires them. boto3 1.36 turned them on for every request, and several S3-compatible services reject those requests. Object keys are checked before any request is made: empty keys, a leading /, . and .. segments, backslashes and control characters raise StorageError.

GCS credentials

Inline JSON
File path
Default credentials

Recommended for deployment, since it fits on one line.

.env

GCS_CREDENTIALS_JSON={"type":"service_account","project_id":"...","private_key":"..."}

For local development.

.env

GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json

On GCE or GKE, or after gcloud auth application-default login. Nothing else to set.

Usage

from feather.storage import get_storage

storage = get_storage()

url = storage.upload(file, 'uploads/photo.jpg', content_type='image/jpeg')
data = storage.download('uploads/photo.jpg')

# local returns a path, S3 and GCS return a signed URL
url = storage.get_url('uploads/photo.jpg', expires_in=3600)

if storage.exists('uploads/photo.jpg'):
    storage.delete('uploads/photo.jpg')

In a route

from flask import request
from feather.storage import get_storage

@api.post('/upload')
@auth_required
def upload_file():
    file = request.files['image']
    storage = get_storage()
    url = storage.upload(file, f'uploads/{current_user.id}/{file.filename}')
    return {'url': url}

Upload safety

LocalStorage serves files from static/, where the browser takes the content type from the extension. Script-capable extensions are refused by default, so an uploaded page cannot run on your origin. S3Storage applies the same lists, since a bucket served from one of your domains has the same problem.

Key	Default
`STORAGE_BLOCKED_EXTENSIONS`	`html, htm, svg, xhtml, xml, js, mjs, php, phtml`
`STORAGE_ALLOWED_EXTENSIONS`	unset

Setting the block list replaces it. The allow-list wins over the block list, which is how you permit SVG when you need it. An extension says nothing about content. When an upload has to be a particular type, check its first bytes as well: a PDF starts with %PDF-, and a renamed HTML file does not.

data = file.read(MAX_BYTES + 1)
if len(data) > MAX_BYTES or not data.startswith(b"%PDF-"):
    raise ValidationError("That file isn't a PDF under 10 MB.", field="file")
get_storage().upload(data, path, content_type="application/pdf")

Private files, and showing a PDF in the page

A signed URL works for anyone who holds it until it expires. For files that belong to one person, stream them through a route that checks access on every request instead:

@page.get("/cards/<card_id>/attachment")
@auth_required
@inject(CardService)
def view_attachment(card_service, card_id):
    card = card_service.get_by_id(card_id, current_user.id)  # 404 unless it's theirs
    response = make_response(get_storage().download(card.attachment_path))
    response.headers["Content-Type"] = "application/pdf"
    response.headers["Content-Disposition"] = 'inline; filename="attachment.pdf"'
    return response

To show that PDF in an <iframe> on your own page, allow same-origin framing. The security headers default to frame-ancestors 'none', which blocks your own iframe as well:

# config.py
FEATHER_CSP_DIRECTIVES = {"frame-ancestors": "'self'"}   # still DENY for other sites

Get started

Tutorial: build a Kanban app

Building the UI

Backend

Features

Tooling

Testing

Deployment

S3 and S3-compatible storage

GCS credentials

Usage

In a route

Upload safety

Private files, and showing a PDF in the page

​S3 and S3-compatible storage

​GCS credentials

​Usage

​In a route

​Upload safety

​Private files, and showing a PDF in the page

S3 and S3-compatible storage

GCS credentials

Usage

In a route

Upload safety

Private files, and showing a PDF in the page