Anexo con Docker: las imágenes de tu reto

git clone https://github.com/rpversontec/reto-imagenes-fastapi-docker.git
cd reto-imagenes-fastapi-docker

[project]
name = "imagenes-fastapi"
version = "0.1.0"
description = "Modulo de identidad e imagenes de referencia para el reto de TC2007B: FastAPI + PostgreSQL + RustFS (S3), mismo contrato que la API de las Practicas 6, 8 y 10."
requires-python = ">=3.11"
dependencies = [
    "fastapi==0.141.1",
    "uvicorn[standard]==0.53.0",
    "sqlalchemy==2.0.54",
    "psycopg[binary]==3.3.6",
    "pyjwt==2.14.0",
    "pwdlib[argon2]==0.3.1",
    "pydantic-settings==2.15.0",
    "python-multipart==0.0.32",
    "boto3==1.43.108",
]

# Todo el backend en la red de Docker:
#   docker compose up -d                   la base, el almacén y el servidor (http://localhost:8000)
#   docker compose --profile tunel up -d   además, el túnel HTTPS
#   docker compose logs tunel              ahí aparece la dirección https://…trycloudflare.com
services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: avisos
    volumes:
      - pgdata:/var/lib/postgresql/data
    # Sin `ports`: la base solo se ve dentro de la red de Docker. Así no choca con
    # un PostgreSQL que ya tengas en el 5432. Para entrar: docker compose exec db psql -U postgres avisos
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d avisos"]
      interval: 2s
      retries: 30

  # El almacén de objetos: guarda las imágenes. Habla S3, como Amazon, MinIO o R2.
  almacen:
    image: rustfs/rustfs:1.0.1
    environment:
      # Las mismas llaves del .env: RustFS las toma como su administrador y la API entra con ellas.
      RUSTFS_ACCESS_KEY: ${S3_ACCESS_KEY}
      RUSTFS_SECRET_KEY: ${S3_SECRET_KEY}
      RUSTFS_CONSOLE_ENABLE: "true"
    volumes:
      - objetos:/data
    # La consola web (9001) es una página que le habla a la API S3 (9000) desde tu
    # navegador: por eso se publican las dos. Solo en 127.0.0.1: el resto del wifi no llega.
    # La app NUNCA habla con el almacén: todo pasa por `api`.
    ports:
      - "127.0.0.1:9000:9000"
      - "127.0.0.1:9001:9001"
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:9000/health"]
      interval: 2s
      retries: 30

  api:
    build: .
    env_file: .env
    environment:
      # Dentro de la red de Docker, la base se llama `db` y el almacén `almacen`, no `localhost`.
      DATABASE_URL: postgresql+psycopg://postgres:postgres@db:5432/avisos
      S3_ENDPOINT: http://almacen:9000
    # --reload + el volumen: editas app/ en tu máquina y el servidor se reinicia solo.
    command: ["uv", "run", "--no-sync", "uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000", "--reload"]
    volumes:
      - ./app:/code/app
    # Solo en 127.0.0.1: tu máquina y el emulador (10.0.2.2) llegan; el resto del wifi, no.
    ports:
      - "127.0.0.1:8000:8000"
    depends_on:
      db:
        condition: service_healthy
      almacen:
        condition: service_healthy

  tunel:
    image: cloudflare/cloudflared:2026.9.3
    # Llega a la API por su nombre en la red de Docker. http2 porque muchas redes bloquean QUIC (UDP).
    command: ["tunnel", "--no-autoupdate", "--protocol", "http2", "--url", "http://api:8000"]
    depends_on:
      - api
    profiles: ["tunel"]

volumes:
  pgdata:
  # Las imágenes. Como pgdata: sobrevive a `docker compose down`; `down -v` lo borra.
  objetos:

cp .env.example .env

# Copia este archivo a .env y cambia los valores. .env NUNCA se sube al repositorio.
# DATABASE_URL y S3_ENDPOINT no van aquí: los pone docker-compose.yml, porque dentro de
# Docker la base se llama `db` y el almacén se llama `almacen`.
JWT_SECRET=cambia-esto-por-48-bytes-al-azar
CODIGO_PROFESOR=cambia-este-codigo
ACCESS_TTL_S=300
REFRESH_TTL_S=604800

# Las llaves del almacén de objetos. Las usan los DOS lados: RustFS las toma como su
# usuario administrador y la API las usa para entrar. También son el usuario y la
# contraseña de la consola web (http://localhost:9001).
S3_ACCESS_KEY=avisos-admin
S3_SECRET_KEY=cambia-esto-por-otra-clave-larga

docker compose up -d
bash smoke.sh

== 23 profesor sube (201)
{"id":"5b074bc4dc3a4fc6a6328b6620ddf464.png","tipo":"image/png","bytes":73} [201]
== 24 no es imagen aunque diga .png (415)
{"error":"El archivo no es una imagen","code":"no_es_imagen","hint":"Se aceptan JPEG, PNG y WebP."} [415]
== 25 demasiado grande (413)
{"error":"La imagen es demasiado grande","code":"imagen_grande","hint":"El máximo es 2048 KB. Redúcela en el teléfono antes de subirla."} [413]
== 29 bajar (200, mismos bytes)
  identica [200]
== 30 bajar otra vez con su ETag (304)
 [304]

    # El almacén de objetos (RustFS, compatible con S3). Las imágenes viven ahí, no en PostgreSQL.
    # Dentro de Docker se llama `almacen`; docker-compose.yml pone S3_ENDPOINT.
    s3_endpoint: str = "http://localhost:9000"
    s3_access_key: str
    s3_secret_key: str
    s3_bucket: str = "avisos"

    # Lo más grande que se acepta. La app de la Práctica 10 manda ~300 KB; una foto sin comprimir, 4 MB o más.
    imagen_max_bytes: int = 2 * 1024 * 1024

"""El almacén de objetos, en un solo archivo. Todo lo demás le habla a estas cinco
funciones y no sabe que del otro lado hay S3.

Se usa boto3, el cliente oficial de Amazon S3: habla con cualquier almacén
compatible —RustFS aquí, MinIO, Cloudflare R2, Amazon S3 en producción—
cambiando solo `S3_ENDPOINT` y las llaves.

Un objeto es una clave ("3f2a….jpg"), unos bytes y su tipo. No hay carpetas, no
hay consultas, no hay transacciones: guardar, leer, preguntar si existe y borrar.
Por eso las imágenes van aquí y no en PostgreSQL, y por eso la base solo guarda
la clave.
"""

from typing import Any

import boto3
from botocore.config import Config
from botocore.exceptions import ClientError

from .config import settings

_s3 = boto3.client(
    "s3",
    endpoint_url=settings.s3_endpoint,
    aws_access_key_id=settings.s3_access_key,
    aws_secret_access_key=settings.s3_secret_key,
    # S3 exige una región aunque el almacén sea tuyo; RustFS acepta esta.
    region_name="us-east-1",
    # "path": http://almacen:9000/avisos/clave. El estilo por omisión pone el bucket en el
    # nombre del host (avisos.almacen), y ese nombre no existe en la red de Docker.
    config=Config(s3={"addressing_style": "path"}, connect_timeout=3, retries={"max_attempts": 2}),
)


def preparar() -> None:
    """Crea el bucket si no existe. Se llama una vez, al arrancar."""
    try:
        _s3.head_bucket(Bucket=settings.s3_bucket)
    except ClientError:
        _s3.create_bucket(Bucket=settings.s3_bucket)


def guardar(clave: str, datos: bytes, tipo: str) -> None:
    _s3.put_object(Bucket=settings.s3_bucket, Key=clave, Body=datos, ContentType=tipo)


def abrir(clave: str) -> dict[str, Any] | None:
    """El objeto listo para mandarse por partes, o None si no existe.

    `Body` es un flujo: los bytes salen del almacén conforme el cliente los lee,
    sin cargar la imagen completa en la memoria del servidor.
    """
    try:
        return _s3.get_object(Bucket=settings.s3_bucket, Key=clave)
    except ClientError as e:
        if e.response["Error"]["Code"] in ("NoSuchKey", "404"):
            return None
        raise


def existe(clave: str) -> bool:
    try:
        _s3.head_object(Bucket=settings.s3_bucket, Key=clave)
        return True
    except ClientError as e:
        if e.response["Error"]["Code"] in ("NoSuchKey", "404"):
            return False
        raise


def borrar(clave: str) -> None:
    # Borrar lo que no existe no es error en S3: así borrar dos veces no truena.
    _s3.delete_object(Bucket=settings.s3_bucket, Key=clave)

import re
import uuid

from fastapi import APIRouter, Depends, Request, Response, UploadFile
from fastapi.responses import StreamingResponse

from .. import almacen
from ..config import settings
from ..deps import Identidad, requiere_profesor, usuario_actual
from ..errors import ApiError
from ..schemas import ImagenOut

router = APIRouter(prefix="/imagenes", tags=["imagenes"])

# Las claves las inventa el servidor: 32 hexadecimales y una extensión. Lo que no
# tenga esa forma no se le pregunta al almacén (así nadie pide "../../.env").
CLAVE_RE = re.compile(r"^[0-9a-f]{32}\.(jpg|png|webp)$")


def tipo_de(inicio: bytes) -> tuple[str, str] | None:
    """El tipo real, por los primeros bytes del archivo ("número mágico").

    No por el nombre ni por el Content-Type que manda el cliente: esos los
    escribe quien sube, y un .exe renombrado a foto.jpg sigue siendo un .exe.
    """
    if inicio.startswith(b"\xff\xd8\xff"):
        return "image/jpeg", "jpg"
    if inicio.startswith(b"\x89PNG\r\n\x1a\n"):
        return "image/png", "png"
    if inicio[:4] == b"RIFF" and inicio[8:12] == b"WEBP":
        return "image/webp", "webp"
    return None


@router.post("", response_model=ImagenOut, status_code=201)
def subir(archivo: UploadFile, _: Identidad = Depends(requiere_profesor)) -> ImagenOut:
    """Recibe una imagen (multipart, campo `archivo`), la guarda en el almacén y devuelve su clave.

    Todavía no pertenece a ningún aviso: la clave se manda después en `POST /avisos`.
    """
    # Se lee un byte de más: si llega, el archivo se pasó del límite.
    datos = archivo.file.read(settings.imagen_max_bytes + 1)
    if len(datos) > settings.imagen_max_bytes:
        raise ApiError(
            413,
            "La imagen es demasiado grande",
            "imagen_grande",
            f"El máximo es {settings.imagen_max_bytes // 1024} KB. Redúcela en el teléfono antes de subirla.",
        )
    tipo = tipo_de(datos[:12])
    if tipo is None:
        raise ApiError(415, "El archivo no es una imagen", "no_es_imagen", "Se aceptan JPEG, PNG y WebP.")
    mime, extension = tipo
    clave = f"{uuid.uuid4().hex}.{extension}"
    almacen.guardar(clave, datos, mime)
    return ImagenOut(id=clave, tipo=mime, bytes=len(datos))


@router.get("/{clave}")
def descargar(clave: str, request: Request, _: Identidad = Depends(usuario_actual)) -> Response:
    """La imagen, para quien tenga sesión. Se manda por partes, conforme sale del almacén."""
    if not CLAVE_RE.match(clave):
        raise ApiError(404, "No existe esa imagen")
    objeto = almacen.abrir(clave)
    if objeto is None:
        raise ApiError(404, "No existe esa imagen")
    etag = objeto["ETag"]
    # Una clave nunca cambia de contenido: puede guardarse para siempre en el teléfono.
    cache = {"ETag": etag, "Cache-Control": "private, max-age=31536000, immutable"}
    if request.headers.get("If-None-Match") == etag:
        objeto["Body"].close()
        return Response(status_code=304, headers=cache)
    return StreamingResponse(
        objeto["Body"].iter_chunks(64 * 1024),
        media_type=objeto["ContentType"],
        headers={**cache, "Content-Length": str(objeto["ContentLength"])},
    )

    # La CLAVE del objeto en el almacén ("3f2a….jpg"), no la imagen. NULL si el aviso no lleva.
    imagen: Mapped[str | None] = mapped_column(String(64), nullable=True)

    @field_validator("imagen")
    @classmethod
    def imagen_valida(cls, v: str | None) -> str | None:
        if v is not None and not IMAGEN_RE.match(v):
            raise ValueError("imagen debe ser la clave que devolvió POST /api/imagenes")
        return v

    # Una clave con buena forma no basta: la imagen tiene que estar en el almacén.
    if body.imagen is not None and not almacen.existe(body.imagen):
        raise ApiError(422, "Esa imagen no existe", "imagen_inexistente", "Súbela primero con POST /api/imagenes y manda la clave que te devuelve.")
    aviso = Aviso(titulo=body.titulo, cuerpo=body.cuerpo, autor=quien.usuario, imagen=body.imagen)

    db.delete(aviso)
    db.commit()
    # Primero la fila y después el objeto: si el almacén falla, queda un archivo huérfano
    # (estorba) en vez de un aviso que apunta a una imagen que ya no existe (truena).
    if aviso.imagen:
        almacen.borrar(aviso.imagen)