Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 9: Web-Service – shorturl

Ziel: Einen getesteten Mini-URL-Shortener shorturl mit FastAPI, SQLite und Dockerfile bauen · Dauer: ca. 120 min · Voraussetzung: Tag 8

Briefing

  • FastAPI baut aus Typ-Hints Routing, Validierung und OpenAPI-Doku; uvicorn ist der ASGI-Server.
  • pydantic-Modelle sind der API-Vertrag: HttpUrl lässt nur http/https durch.
  • SQLite reicht für einen Dienst mit einer Instanz; die Verbindung kommt per Dependency.
  • TestClient testet die App im Prozess, ohne Server und ohne Port.
  • Das Dockerfile wird nur statisch geprüft (docker build --check), nicht gebaut.
curl POST /api/links {"url": ...} --> pydantic LinkIn --> db.create() --> 201 + code
curl GET  /<code> ------------------> db.hit() (hits+1) --> 307 Location: <url>
curl GET  /api/links/<code> --------> db.get() ----------> LinkOut (Statistik)

Drill 1: Projekt und erste Route

cd ~/py-lab
uv init -q --package --name shorturl tag09-shorturl
cd tag09-shorturl && mkdir tests
uv add -q fastapi uvicorn
uv add -q --dev pytest ruff httpx2
cat > src/shorturl/__init__.py <<'EOF'
"""shorturl – Mini-URL-Shortener mit FastAPI und SQLite."""
EOF
cat > src/shorturl/app.py <<'EOF'
from fastapi import FastAPI

app = FastAPI(title="shorturl")


@app.get("/healthz")
def healthz() -> dict[str, str]:
    return {"status": "ok"}
EOF

In einem zweiten Terminal den Server mit Auto-Reload starten und laufen lassen:

cd ~/py-lab/tag09-shorturl && uv run uvicorn shorturl.app:app --reload

Erwartet (gekürzt):

INFO:     Will watch for changes in these directories: [...]
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Application startup complete.

Zurück im ersten Terminal:

curl -s http://127.0.0.1:8000/healthz; echo
curl -s http://127.0.0.1:8000/openapi.json | jq -c '.paths | keys'

Erwartet:

{"status":"ok"}
["/healthz"]

Warum? FastAPI erzeugt aus dem Code eine OpenAPI-Beschreibung. Öffne http://127.0.0.1:8000/docs im Browser: interaktive Doku, ohne eine Zeile extra.

Tipp: httpx2 braucht der TestClient in aktuellen Starlette-Versionen (ältere nutzen httpx). Es ist eine Dev-Abhängigkeit und landet nicht im Container.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Die SQLite-Schicht

cat > src/shorturl/db.py <<'EOF'
"""SQLite-Schicht: Schema, Anlegen, Auflösen, Statistik."""

import secrets
import sqlite3
from datetime import UTC, datetime

SCHEMA = """
CREATE TABLE IF NOT EXISTS links (
    code TEXT PRIMARY KEY,
    url TEXT NOT NULL,
    created TEXT NOT NULL,
    hits INTEGER NOT NULL DEFAULT 0
)
"""


def connect(path: str) -> sqlite3.Connection:
    conn = sqlite3.connect(path, check_same_thread=False)
    conn.row_factory = sqlite3.Row  # Zugriff per Spaltenname
    conn.execute("PRAGMA journal_mode=WAL")  # Lesen blockiert Schreiben nicht
    conn.execute(SCHEMA)
    return conn


def create(conn: sqlite3.Connection, url: str) -> str:
    for _ in range(5):
        code = secrets.token_urlsafe(6)  # 8 Zeichen, nicht erratbar
        try:
            with conn:
                conn.execute(
                    "INSERT INTO links (code, url, created) VALUES (?, ?, ?)",
                    (code, url, datetime.now(UTC).isoformat(timespec="seconds")),
                )
            return code
        except sqlite3.IntegrityError:  # Kollision: neuer Versuch
            continue
    raise RuntimeError("kein freier Code gefunden")


def get(conn: sqlite3.Connection, code: str) -> sqlite3.Row | None:
    return conn.execute("SELECT * FROM links WHERE code = ?", (code,)).fetchone()


def hit(conn: sqlite3.Connection, code: str) -> str | None:
    """Zählt einen Aufruf und gibt die Ziel-URL zurück."""
    with conn:
        row = conn.execute(
            "UPDATE links SET hits = hits + 1 WHERE code = ? RETURNING url", (code,)
        ).fetchone()
    return row["url"] if row else None
EOF
uv run python - <<'EOF'
from shorturl import db

conn = db.connect(":memory:")
code = db.create(conn, "https://docs.python.org/3/")
print(code, db.hit(conn, code), db.hit(conn, "gibtsnicht"))
print(dict(db.get(conn, code)))
EOF

Erwartet (Code und Zeit sind zufällig):

9moxVx4w https://docs.python.org/3/ None
{'code': '9moxVx4w', 'url': 'https://docs.python.org/3/', 'created': '2026-10-...

Warum? secrets.token_urlsafe(6) liefert 8 URL-sichere Zeichen aus einem kryptografischen Zufallsgenerator – fortlaufende IDs würden alle Links aufzählbar machen. UPDATE ... RETURNING zählt und liest in einem Statement, also ohne Race zwischen zwei Requests.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Modelle und Endpunkte

cat > src/shorturl/models.py <<'EOF'
"""API-Verträge: was rein darf und was rausgeht."""

from pydantic import BaseModel, Field, HttpUrl


class LinkIn(BaseModel):
    url: HttpUrl = Field(max_length=2048)  # nur http/https, kein javascript:


class LinkOut(BaseModel):
    code: str
    short_url: str
    url: str
    hits: int
    created: str
EOF
cat > src/shorturl/app.py <<'EOF'
"""FastAPI-App: JSON-API unter /api, Redirect unter /{code}."""

import os
import sqlite3
from collections.abc import Iterator
from typing import Annotated

from fastapi import Depends, FastAPI, HTTPException, Path, status
from fastapi.responses import RedirectResponse

from shorturl import db
from shorturl.models import LinkIn, LinkOut

BASE_URL = os.environ.get("SHORTURL_BASE", "http://127.0.0.1:8000")
DB_PATH = os.environ.get("SHORTURL_DB", "shorturl.db")
Code = Annotated[str, Path(pattern=r"^[A-Za-z0-9_-]{8}$")]

app = FastAPI(title="shorturl", version="0.1.0")


def get_conn() -> Iterator[sqlite3.Connection]:
    conn = db.connect(DB_PATH)
    try:
        yield conn
    finally:
        conn.close()


Conn = Annotated[sqlite3.Connection, Depends(get_conn)]


def to_out(row: sqlite3.Row) -> LinkOut:
    return LinkOut(short_url=f"{BASE_URL}/{row['code']}", **dict(row))


@app.get("/healthz")
def healthz() -> dict[str, str]:
    return {"status": "ok"}


@app.post("/api/links", status_code=status.HTTP_201_CREATED)
def create_link(link: LinkIn, conn: Conn) -> LinkOut:
    code = db.create(conn, str(link.url))
    return to_out(db.get(conn, code))


@app.get("/api/links/{code}")
def link_stats(code: Code, conn: Conn) -> LinkOut:
    row = db.get(conn, code)
    if row is None:
        raise HTTPException(status.HTTP_404_NOT_FOUND, "unbekannter Code")
    return to_out(row)


@app.get("/{code}")
def follow(code: Code, conn: Conn) -> RedirectResponse:
    url = db.hit(conn, code)
    if url is None:
        raise HTTPException(status.HTTP_404_NOT_FOUND, "unbekannter Code")
    return RedirectResponse(url, status_code=status.HTTP_307_TEMPORARY_REDIRECT)
EOF

Warum? Depends(get_conn) öffnet pro Request eine Verbindung und schließt sie im finally – auch bei Exceptions. Rückgabe-Typ LinkOut sorgt dafür, dass FastAPI die Antwort validiert und nur die deklarierten Felder ausliefert. Code mit pattern weist Unsinn wie /x schon vor der Datenbank ab. Die Konfiguration kommt aus Umgebungsvariablen (12-Factor), damit derselbe Code lokal und im Container läuft.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Mit curl durchspielen

Im zweiten Terminal meldet uvicorn StatReload detected changes in 'src/shorturl/app.py'. Reloading... – die neue App läuft bereits.

B=http://127.0.0.1:8000
curl -s -X POST $B/api/links -H 'Content-Type: application/json' \
  -d '{"url": "https://docs.python.org/3/library/sqlite3.html"}' | tee resp.json | jq .
CODE=$(jq -r .code resp.json)
curl -s -o /dev/null -w '%{http_code} -> %{redirect_url}\n' $B/$CODE
curl -s $B/api/links/$CODE | jq -c '{code, hits}'
curl -s -X POST $B/api/links -H 'Content-Type: application/json' \
  -d '{"url": "javascript:alert(1)"}' | jq -c '.detail[0].msg'
curl -s -o /dev/null -w '%{http_code}\n' $B/nichtda1

Erwartet (Code und Zeit sind zufällig):

{
  "code": "DvV5IC0X",
  "short_url": "http://127.0.0.1:8000/DvV5IC0X",
  "url": "https://docs.python.org/3/library/sqlite3.html",
  "hits": 0,
  "created": "2026-10-10T06:55:09+00:00"
}
307 -> https://docs.python.org/3/library/sqlite3.html
{"code":"DvV5IC0X","hits":1}
"URL scheme should be 'http' or 'https'"
404

Warum? 422 mit präziser Fehlermeldung kommt gratis von pydantic. 307 statt 301: Browser cachen 301 dauerhaft – dann zählt hits nicht mehr und ein geänderter Link wirkt nie.

Sicherheit: Ein Shortener ist ein offener Redirector. Die Schema-Prüfung blockt javascript:- und data:-Links; für interne Dienste zusätzlich eine Allowlist erlaubter Ziel-Domains vorsehen.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Tests mit TestClient

dependency_overrides tauscht die Datenbank-Dependency gegen eine Test-DB in tmp_path – der Rest der App bleibt echt.

cat > tests/test_api.py <<'EOF'
from collections.abc import Iterator

import pytest
from fastapi.testclient import TestClient

from shorturl import db
from shorturl.app import app, get_conn


@pytest.fixture
def client(tmp_path) -> Iterator[TestClient]:
    def test_conn():
        conn = db.connect(str(tmp_path / "test.db"))
        try:
            yield conn
        finally:
            conn.close()

    app.dependency_overrides[get_conn] = test_conn  # eigene DB pro Test
    with TestClient(app) as c:
        yield c
    app.dependency_overrides.clear()


def test_healthz(client):
    assert client.get("/healthz").json() == {"status": "ok"}


def test_create_redirect_and_count(client):
    resp = client.post("/api/links", json={"url": "https://example.org/a?b=1"})
    assert resp.status_code == 201
    code = resp.json()["code"]
    assert len(code) == 8

    for _ in range(2):
        hop = client.get(f"/{code}", follow_redirects=False)
        assert hop.status_code == 307
        assert hop.headers["location"] == "https://example.org/a?b=1"

    stats = client.get(f"/api/links/{code}").json()
    assert stats["hits"] == 2
    assert stats["short_url"].endswith(f"/{code}")


@pytest.mark.parametrize(
    "url", ["javascript:alert(1)", "ftp://example.org", "kein-url", "https://x/" * 300]
)
def test_rejects_bad_urls(client, url):
    assert client.post("/api/links", json={"url": url}).status_code == 422


def test_unknown_and_invalid_codes(client):
    assert client.get("/AAAAAAAA").status_code == 404
    assert client.get("/api/links/AAAAAAAA").status_code == 404
    assert client.get("/x").status_code == 422  # passt nicht aufs Muster
EOF
cat >> pyproject.toml <<'EOF'

[tool.ruff.lint]
extend-select = ["E501", "B", "UP", "SIM"]

[tool.pytest.ini_options]
testpaths = ["tests"]
EOF
uv run pytest -q && uv run ruff check . && uv run ruff format --check .

Erwartet:

.......                                                                  [100%]
7 passed in 0.19s
All checks passed!
6 files already formatted

Warum? follow_redirects=False prüft den Redirect selbst, statt ihm zu folgen. Der parametrisierte Test deckt die Angriffs- und Fehlerfälle in vier Zeilen ab – darunter eine 3000 Zeichen lange URL gegen max_length.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Startskript und Dockerfile

Erst ein Konsolenskript, damit der Container nur shorturl aufrufen muss. Den --reload-Server im zweiten Terminal jetzt mit Ctrl-C beenden.

cat > src/shorturl/cli.py <<'EOF'
"""Startet den Server: shorturl [--host 127.0.0.1] [--port 8000]"""

import argparse

import uvicorn


def main() -> None:
    parser = argparse.ArgumentParser(description="Mini-URL-Shortener")
    parser.add_argument("--host", default="127.0.0.1")
    parser.add_argument("--port", type=int, default=8000)
    args = parser.parse_args()
    uvicorn.run("shorturl.app:app", host=args.host, port=args.port)
EOF
cat > src/shorturl/__init__.py <<'EOF'
"""shorturl – Mini-URL-Shortener mit FastAPI und SQLite."""

from shorturl.cli import main

__all__ = ["main"]
EOF
cat > src/shorturl/__main__.py <<'EOF'
from shorturl import main

main()
EOF
cat > Dockerfile <<'EOF'
# Build-Stage: Abhängigkeiten und Projekt in ein venv installieren
FROM python:3.14-slim AS build
COPY --from=ghcr.io/astral-sh/uv:0.9 /uv /bin/uv
ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_PYTHON_DOWNLOADS=never
WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --locked --no-dev --no-install-project
COPY README.md ./
COPY src ./src
RUN uv sync --locked --no-dev --no-editable

# Runtime-Stage: nur Python + venv, kein uv, kein Quellcode, kein root
FROM python:3.14-slim
RUN useradd --system --uid 10001 app && mkdir /data && chown app /data
COPY --from=build /app/.venv /app/.venv
ENV PATH="/app/.venv/bin:$PATH" SHORTURL_DB=/data/shorturl.db
USER app
EXPOSE 8000
VOLUME /data
HEALTHCHECK --interval=30s --timeout=3s CMD python -c \
    "import urllib.request as u; u.urlopen('http://127.0.0.1:8000/healthz', timeout=2)"
CMD ["shorturl", "--host", "0.0.0.0", "--port", "8000"]
EOF
cat > .dockerignore <<'EOF'
.venv
.git
**/__pycache__
.pytest_cache
.ruff_cache
tests
*.db*
EOF
docker build --check .

Erwartet (gekürzt):

#2 [internal] load metadata for ghcr.io/astral-sh/uv:0.9
#3 [internal] load metadata for docker.io/library/python:3.14-slim
Check complete, no warnings found.

Warum? Zwei Stages: Die Build-Stage hat uv und installiert zuerst nur die Abhängigkeiten (eigener, gut cachebarer Layer), dann das Projekt als normales Paket (--no-editable). Die Runtime-Stage bekommt nur das fertige venv – kein uv, keine Dev-Tools, kein Quellcode – und läuft als User app statt root. --check lädt nur Metadaten der Basis-Images und prüft die Build-Regeln, ohne etwas zu bauen.

Was --check findet, siehst du mit zwei typischen Fehlern:

sed 's/^CMD .*/CMD shorturl --host 0.0.0.0/; s/ AS build/ as build/' Dockerfile \
  > Dockerfile.bad
docker build --check -f Dockerfile.bad . 2>&1 | grep WARNING
rm Dockerfile.bad

Erwartet:

WARNING: FromAsCasing - https://docs.docker.com/go/dockerfile/rule/from-as-casing/
WARNING: JSONArgsRecommended - https://docs.docker.com/go/dockerfile/rule/json-args...

CMD in Shell-Form startet eine Shell als PID 1 – die reicht SIGTERM nicht weiter, und der Container stirbt erst nach dem Kill-Timeout.

Ohne Docker-Build lässt sich die Installation der Build-Stage trotzdem nachstellen:

rm -rf ~/py-lab/shorturl-sim && mkdir ~/py-lab/shorturl-sim
cp -R pyproject.toml uv.lock README.md src ~/py-lab/shorturl-sim/
cd ~/py-lab/shorturl-sim && uv sync -q --locked --no-dev --no-editable && rm -rf src
.venv/bin/python -c 'import shorturl.app; print("ok ohne Quellcode")'
ls .venv/bin | grep -E 'shorturl|pytest|ruff'
cd - >/dev/null && rm -rf ~/py-lab/shorturl-sim

Erwartet:

ok ohne Quellcode
shorturl

Das Projekt ist installiert, pytest und ruff fehlen – genau so soll das Runtime-venv aussehen.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Das Tool ist fertig

Im zweiten Terminal den Dienst so starten, wie er im Container läuft – über das Konsolenskript und mit Umgebungsvariablen:

cd ~/py-lab/tag09-shorturl
SHORTURL_DB=$PWD/links.db SHORTURL_BASE=http://127.0.0.1:8000 uv run shorturl

Im ersten Terminal:

B=http://127.0.0.1:8000
CODE=$(curl -s -X POST $B/api/links -H 'Content-Type: application/json' \
  -d '{"url": "https://github.com/astral-sh/uv"}' | jq -r .code)
for i in 1 2 3; do curl -s -o /dev/null $B/$CODE; done
curl -s $B/api/links/$CODE | jq -c '{code, hits, url}'
sqlite3 links.db 'SELECT code, hits FROM links'
uv run pytest -q && uv run ruff check . && uv run ruff format --check .

Erwartet (Code ist zufällig):

{"code":"pT3x_9Qa","hits":3,"url":"https://github.com/astral-sh/uv"}
pT3x_9Qa|3
.......                                                                  [100%]
7 passed in 0.19s
All checks passed!
7 files already formatted

Die Daten liegen in links.db und überleben einen Neustart – im Container entspricht das dem Volume /data.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

#!/usr/bin/env bash
check() { if eval "$2" >/dev/null 2>&1; then echo "✔ $1"; else echo "✘ $1"; fi; }
cd ~/py-lab/tag09-shorturl
B=http://127.0.0.1:8000
check "Tests grün" "uv run pytest -q"
check "ruff sauber" "uv run ruff check . && uv run ruff format --check ."
check "Dienst gesund" "curl -sf $B/healthz | grep -q ok"
check "javascript: abgelehnt" "test \$(curl -s -o /dev/null -w '%{http_code}' \
  -X POST $B/api/links -H 'Content-Type: application/json' \
  -d '{\"url\": \"javascript:alert(1)\"}') = 422"
check "Dockerfile ohne Warnungen" "docker build --check . 2>&1 | grep -q 'no warnings'"
check "Container läuft nicht als root" "grep -q '^USER app' Dockerfile"

Erwartet:

✔ Tests grün
✔ ruff sauber
✔ Dienst gesund
✔ javascript: abgelehnt
✔ Dockerfile ohne Warnungen
✔ Container läuft nicht als root

Aufräumen: Server im zweiten Terminal mit Ctrl-C beenden.

Challenge

Jeder kann Links anlegen. Schütze POST /api/links mit einem API-Key aus SHORTURL_API_KEY im Header X-API-Key; Redirects bleiben öffentlich.

Hinweis: Eine Dependency mit Header(), eingehängt über dependencies=[Depends(...)] am Decorator; vergleichen mit secrets.compare_digest.

Lösung

In src/shorturl/app.py import secrets und Header ergänzen, dann:

def require_key(x_api_key: Annotated[str, Header()] = "") -> None:
    expected = os.environ.get("SHORTURL_API_KEY", "")
    if not expected or not secrets.compare_digest(x_api_key, expected):
        raise HTTPException(status.HTTP_401_UNAUTHORIZED, "API-Key fehlt/falsch")


@app.post(
    "/api/links",
    status_code=status.HTTP_201_CREATED,
    dependencies=[Depends(require_key)],
)
def create_link(link: LinkIn, conn: Conn) -> LinkOut:

In tests/test_api.py die Fixture anpassen und einen Test anhängen:

@pytest.fixture
def client(tmp_path, monkeypatch) -> Iterator[TestClient]:
    monkeypatch.setenv("SHORTURL_API_KEY", "lab-key-123")  # Lab-Wert
    ...
    with TestClient(app, headers={"X-API-Key": "lab-key-123"}) as c:
...
def test_post_needs_api_key(client):
    body = {"url": "https://example.org"}
    wrong = client.post("/api/links", json=body, headers={"X-API-Key": "falsch"})
    assert wrong.status_code == 401
uv run pytest -q

Erwartet:

........                                                                 [100%]
8 passed in 0.19s

Warum compare_digest? Ein normales == bricht beim ersten falschen Zeichen ab; die Laufzeit verrät dann, wie viele Zeichen stimmen (Timing-Angriff). Ohne gesetzten Key lehnt die Dependency alles ab – fail closed.

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • SQLite heißt: genau eine Instanz. Für mehrere Replicas PostgreSQL (z. B. psycopg oder SQLAlchemy) und Migrationen mit Alembic.
  • Hinter Ingress/Load Balancer läuft TLS dort; uvicorn mit --proxy-headers und --forwarded-allow-ips starten, damit Client-IPs und Schema stimmen.
  • Basis-Images per Digest pinnen (python:3.14-slim@sha256:...), im CI bauen, scannen (Trivy/Grype), signieren (cosign) und eine SBOM erzeugen.
  • In Kubernetes readOnlyRootFilesystem, runAsNonRoot und Probes auf /healthz; API-Keys aus einem Secret-Store (Vault/OpenBao), nie im Image.
  • Rate-Limiting und Missbrauchs-Erkennung (Phishing-Links!) gehören vor einen öffentlichen Shortener – oder er bleibt intern.