Tag 9: Web-Service – shorturl
Ziel: Einen getesteten Mini-URL-Shortener
shorturlmit 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:
HttpUrllässt nurhttp/httpsdurch. - SQLite reicht für einen Dienst mit einer Instanz; die Verbindung kommt per Dependency.
TestClienttestet 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"}
EOFIn einem zweiten Terminal den Server mit Auto-Reload starten und laufen lassen:
cd ~/py-lab/tag09-shorturl && uv run uvicorn shorturl.app:app --reloadErwartet (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:
httpx2braucht derTestClientin aktuellen Starlette-Versionen (ältere nutzenhttpx). 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)))
EOFErwartet (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)
EOFWarum? 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/nichtda1Erwartet (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:- unddata:-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.badErwartet:
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-simErwartet:
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 shorturlIm 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 == 401uv run pytest -qErwartet:
........ [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.
psycopgoder SQLAlchemy) und Migrationen mit Alembic. - Hinter Ingress/Load Balancer läuft TLS dort; uvicorn mit
--proxy-headersund--forwarded-allow-ipsstarten, 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,runAsNonRootund 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.