250 lines
8.5 KiB
Python
250 lines
8.5 KiB
Python
"""
|
|
app/utils/storage.py
|
|
---------------------
|
|
Storage abstraction for uploaded photo files (R2 object-storage migration).
|
|
|
|
One interface, backend selected by config ``STORAGE_BACKEND``:
|
|
- ``local`` (default): files under ``app/static/uploads``, served via
|
|
``url_for('static', ...)``. **Byte-for-byte identical** to the behavior
|
|
before this abstraction existed — Phase 1 is a no-op.
|
|
- ``s3``: Cloudflare R2 / any S3-compatible store. Private bucket; browser/API
|
|
URLs are short-lived presigned GETs. Requires ``boto3`` and the ``R2_*``
|
|
config keys. boto3 is imported lazily, so a ``local`` deploy needs neither.
|
|
|
|
The stored **key** is always the relative path ``uploads/<subfolder>/<file>`` —
|
|
the exact string persisted in the DB (`Issue.photo_path`, `result_photos[]`,
|
|
`mobile_photo_paths[]`, `Inspection.form_data` image values,
|
|
`InspectionResult.photo_path`). It never changes between backends, so there is
|
|
**no schema migration**.
|
|
|
|
Public module-level API (delegates to the active backend):
|
|
|
|
save(file_obj, subfolder) -> key # write an uploaded file, return its key
|
|
media_url(key) -> str # browser/API URL for a key ('' if falsy)
|
|
read(key) -> bytes # raw bytes (e.g. PDF export image embed)
|
|
exists(key) -> bool
|
|
delete(key) -> None # best-effort file removal
|
|
abs_local_path(key) -> str # physical path under static/ (local backend)
|
|
|
|
NOTE: extension / magic-byte validation stays in the CALLER (e.g. `_save_photo`,
|
|
`api/photos.upload_photo`) — this module only moves bytes and builds URLs.
|
|
"""
|
|
|
|
import os
|
|
import uuid
|
|
import logging
|
|
|
|
from flask import current_app, url_for
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
|
|
def _ext_of(filename):
|
|
"""Lower-case extension of a filename, defaulting to 'jpg' when absent."""
|
|
name = filename or ''
|
|
return name.rsplit('.', 1)[-1].lower() if '.' in name else 'jpg'
|
|
|
|
|
|
# ── Local filesystem backend (current behavior) ───────────────────────────────
|
|
|
|
class LocalBackend:
|
|
"""Files under ``app/static/uploads``, served by Flask/Nginx static route."""
|
|
|
|
name = 'local'
|
|
|
|
def _uploads_root(self):
|
|
# config UPLOAD_FOLDER == <root>/app/static/uploads
|
|
return current_app.config['UPLOAD_FOLDER']
|
|
|
|
def _static_folder(self):
|
|
# <root>/app/static — key 'uploads/...' resolves under here
|
|
return os.path.join(current_app.root_path, 'static')
|
|
|
|
def save(self, file_obj, subfolder):
|
|
"""Write ``file_obj`` under ``subfolder``; return the ``uploads/...`` key.
|
|
|
|
Replicates the previous inline logic in `_save_photo` / `upload_photo`
|
|
exactly: random uuid filename, `os.makedirs(exist_ok=True)`, same key.
|
|
"""
|
|
ext = _ext_of(file_obj.filename)
|
|
filename = f'{uuid.uuid4().hex}.{ext}'
|
|
dest_dir = os.path.join(self._uploads_root(), subfolder)
|
|
os.makedirs(dest_dir, exist_ok=True)
|
|
file_obj.save(os.path.join(dest_dir, filename))
|
|
return f'uploads/{subfolder}/{filename}'
|
|
|
|
def abs_local_path(self, key):
|
|
return os.path.normpath(os.path.join(self._static_folder(), key))
|
|
|
|
def media_url(self, key):
|
|
if not key:
|
|
return ''
|
|
return url_for('static', filename=key)
|
|
|
|
def read(self, key):
|
|
with open(self.abs_local_path(key), 'rb') as fh:
|
|
return fh.read()
|
|
|
|
def exists(self, key):
|
|
return bool(key) and os.path.isfile(self.abs_local_path(key))
|
|
|
|
def delete(self, key):
|
|
if not key:
|
|
return
|
|
try:
|
|
path = self.abs_local_path(key)
|
|
if os.path.isfile(path):
|
|
os.remove(path)
|
|
except OSError:
|
|
pass
|
|
|
|
|
|
# ── Cloudflare R2 / S3-compatible backend ─────────────────────────────────────
|
|
|
|
_CONTENT_TYPES = {
|
|
'jpg': 'image/jpeg', 'jpeg': 'image/jpeg',
|
|
'png': 'image/png', 'gif': 'image/gif',
|
|
}
|
|
|
|
|
|
class S3Backend:
|
|
"""
|
|
Cloudflare R2 (or any S3-compatible store). Objects are private; browser/API
|
|
URLs are short-lived presigned GETs. The object key == the DB path string.
|
|
|
|
boto3 is imported lazily so a 'local' deployment doesn't require it installed.
|
|
"""
|
|
|
|
name = 's3'
|
|
|
|
def __init__(self):
|
|
import boto3 # lazy — only when s3 is active
|
|
from botocore.config import Config as _BotoConfig
|
|
|
|
cfg = current_app.config
|
|
missing = [k for k in ('R2_ENDPOINT_URL', 'R2_ACCESS_KEY_ID',
|
|
'R2_SECRET_ACCESS_KEY', 'R2_BUCKET') if not cfg.get(k)]
|
|
if missing:
|
|
raise RuntimeError(f'STORAGE_BACKEND=s3 but missing config: {", ".join(missing)}')
|
|
|
|
self.bucket = cfg['R2_BUCKET']
|
|
self.ttl = int(cfg.get('R2_PRESIGN_TTL', 86400))
|
|
self.fallback = bool(cfg.get('R2_MEDIA_FALLBACK', False))
|
|
self._client = boto3.client(
|
|
's3',
|
|
endpoint_url = cfg['R2_ENDPOINT_URL'],
|
|
aws_access_key_id = cfg['R2_ACCESS_KEY_ID'],
|
|
aws_secret_access_key = cfg['R2_SECRET_ACCESS_KEY'],
|
|
region_name = 'auto',
|
|
config = _BotoConfig(signature_version='s3v4'),
|
|
)
|
|
# A LocalBackend for transition fallback (read/media_url when object absent).
|
|
self._local = LocalBackend()
|
|
|
|
def _content_type(self, key):
|
|
return _CONTENT_TYPES.get(_ext_of(key), 'application/octet-stream')
|
|
|
|
def save(self, file_obj, subfolder):
|
|
ext = _ext_of(file_obj.filename)
|
|
key = f'uploads/{subfolder}/{uuid.uuid4().hex}.{ext}'
|
|
file_obj.stream.seek(0)
|
|
body = file_obj.stream.read()
|
|
self._client.put_object(
|
|
Bucket=self.bucket, Key=key, Body=body,
|
|
ContentType=_CONTENT_TYPES.get(ext, 'application/octet-stream'),
|
|
)
|
|
return key
|
|
|
|
def abs_local_path(self, key):
|
|
# No local path for an S3 object; expose the local mirror path (may or may
|
|
# not exist) so transition code / callers can still reference it.
|
|
return self._local.abs_local_path(key)
|
|
|
|
def media_url(self, key):
|
|
if not key:
|
|
return ''
|
|
if self.fallback and not self._head(key):
|
|
# Object not in R2 yet — serve the local copy during transition.
|
|
if self._local.exists(key):
|
|
return self._local.media_url(key)
|
|
return self._client.generate_presigned_url(
|
|
'get_object',
|
|
Params={'Bucket': self.bucket, 'Key': key},
|
|
ExpiresIn=self.ttl,
|
|
)
|
|
|
|
def read(self, key):
|
|
try:
|
|
resp = self._client.get_object(Bucket=self.bucket, Key=key)
|
|
return resp['Body'].read()
|
|
except Exception:
|
|
# Transition safety: fall back to a local copy if present.
|
|
if self._local.exists(key):
|
|
return self._local.read(key)
|
|
raise
|
|
|
|
def _head(self, key):
|
|
try:
|
|
self._client.head_object(Bucket=self.bucket, Key=key)
|
|
return True
|
|
except Exception:
|
|
return False
|
|
|
|
def exists(self, key):
|
|
return bool(key) and self._head(key)
|
|
|
|
def delete(self, key):
|
|
if not key:
|
|
return
|
|
try:
|
|
self._client.delete_object(Bucket=self.bucket, Key=key)
|
|
except Exception as e:
|
|
logger.warning('S3 delete failed for %s: %s', key, e)
|
|
|
|
|
|
_BACKENDS = {
|
|
'local': LocalBackend,
|
|
's3': S3Backend,
|
|
}
|
|
|
|
|
|
def get_backend():
|
|
"""Return the active storage backend (one cached instance per app)."""
|
|
name = (current_app.config.get('STORAGE_BACKEND') or 'local').lower()
|
|
cls = _BACKENDS.get(name)
|
|
if cls is None:
|
|
logger.warning('Unknown STORAGE_BACKEND=%r — falling back to local', name)
|
|
cls = LocalBackend
|
|
cache_key = f'_storage_backend_{cls.name}'
|
|
inst = current_app.extensions.get(cache_key)
|
|
if inst is None:
|
|
inst = cls()
|
|
current_app.extensions[cache_key] = inst
|
|
return inst
|
|
|
|
|
|
# ── Module-level convenience delegates ────────────────────────────────────────
|
|
|
|
def save(file_obj, subfolder):
|
|
return get_backend().save(file_obj, subfolder)
|
|
|
|
|
|
def media_url(key):
|
|
return get_backend().media_url(key)
|
|
|
|
|
|
def read(key):
|
|
return get_backend().read(key)
|
|
|
|
|
|
def exists(key):
|
|
return get_backend().exists(key)
|
|
|
|
|
|
def delete(key):
|
|
return get_backend().delete(key)
|
|
|
|
|
|
def abs_local_path(key):
|
|
return get_backend().abs_local_path(key)
|