Lidsky řečeno
Kód je jako šatna v divadle. Odevzdáš kabát, dostaneš malý lístek s číslem. Lístek je krátký a dá se snadno nosit, kabát zůstává bezpečně na věšáku. Šatnářka hlídá, co přijme, nikomu nevydá kabát bez platného lístku a počítá, kolikrát se pro něj kdo stavil.
Plán stavby
Každá vrstva zná jen tu pod sebou. Díky tomu jde každou otestovat samostatně a framework se dá kdykoli vyměnit.
HTTP požadavek
|
[ logování a request id ] krok 5
|
[ App: HTTP, klíč, stavy ] krok 4
|
[ LinkService: pravidla ] krok 3
| \
[ LinkRepo: SQL ] [ validate_url ]
krok 2 krok 1| Požadavek | Výsledek |
|---|---|
POST /links s klíčem a {"url": "..."} | 201, {"code": "...", "url": "..."} |
GET /{code} | 307 a hlavička Location |
GET /health | 200, {"status": "ok"} |
| špatný klíč / špatná data / neznámý kód | 401 / 422 / 404 |
Každý úkol běží samostatně, takže to, co potřebuje z ostatních vrstev, už má ve startovním kódu.
Krok 1: co vůbec přijmeme
Zkracovač, který přijme cokoli, je dar pro podvodníky. Adresa javascript:... by mohla spustit kód a https://[email protected]/ vypadá jako banka, ale vede na zlo.example, protože všechno před @ je jen přihlašovací jméno.
Krok 1: validate_url
Napiš validate_url(raw). Vrátí adresu bez okrajových mezer, nebo vyhodí InvalidUrl. Odmítni:
- cokoli, co není text, a prázdný text,
- adresu delší než
MAX_URL_LENGTHznaků, - bílé a řídicí znaky uvnitř adresy,
- jiné schéma než
httpahttps, - adresu bez hostitele,
- adresu se jménem nebo heslem před
@, - adresu, kterou
urlsplitnedokáže rozebrat (vyhodíValueError).
from urllib.parse import urlsplit
MAX_URL_LENGTH = 2048
class InvalidUrl(ValueError):
pass
def validate_url(raw):
return raw
Pod kapotou · proč znaky kontrolovat před parserem
urlsplit od bezpečnostní opravy (bpo-43882) odstraňuje z adresy \t, \r a \n a tiše ji tak mění. Když validuješ výsledek parseru, ale ukládáš původní text, kontroluješ něco jiného, než pak prohlížeč dostane. Z CR a LF se navíc v hlavičce Location může stát response splitting. Moderní servery to odmítnou, ale spoléhat na to netřeba.
Tahle validace neřeší reputaci cíle. Reálná služba by měla blocklist domén, zákaz vlastních krátkých adres (smyčky přesměrování) a kontrolu cílů proti seznamu phishingu. Zkracovač server sám nestahuje, takže tu nehrozí SSRF. Přibude-li náhled stránky, začne hrozit okamžitě.
Krok 2: paměť služby
Odkazy musí přežít restart, proto jdou do databáze. Primární klíč code hlídá jedinečnost za nás, a to i při souběžných zápisech. Kód se proto nezjišťuje dotazem předem. Zkusí se vložit a případná kolize se zachytí.
Počítadlo návštěv se zvyšuje přímo v SQL (hits = hits + 1). Varianta „přečti, přičti v Pythonu, zapiš“ by při dvou souběžných návštěvách jednu ztratila.
Krok 2: LinkRepo
Doplň metody třídy:
add(code, url)vloží řádek. Obsazený kód přelož naCodeTakena transakci nech čistou,resolve(code)zvýšíhitso 1 a vrátíurl, u neznámého kódu vrátíNone,hits(code)vrátí počet návštěv, u neznámého kóduNone.
Hodnoty předávej výhradně parametry ?.
import sqlite3
SCHEMA = """
CREATE TABLE IF NOT EXISTS links (
code TEXT PRIMARY KEY,
url TEXT NOT NULL,
hits INTEGER NOT NULL DEFAULT 0
)
"""
class CodeTaken(Exception):
pass
class LinkRepo:
def __init__(self, conn):
self.conn = conn
conn.execute(SCHEMA)
def add(self, code, url):
pass
def resolve(self, code):
pass
def hits(self, code):
pass
Krok 3: pravidla služby
LinkService je mozek. Neví nic o SQL ani o HTTP. Generátor kódů dostane zvenku jako funkci, takže test mu podstrčí předem dané kódy a kolizi vyrobí na povel. V provozu tam bude lambda: secrets.token_urlsafe(6).
Krok 3: LinkService
Doplň:
shorten(raw_url)adresu ověří přesvalidate_url, vezme kód zself.new_code()a uloží ho. PřiCodeTakenzkusí další kód, nejvýšeMAX_ATTEMPTSpokusů celkem. Potom vyhodíServiceBusy. VrátíLink(code, url).resolve(code)vrátí adresu, nebo vyhodíLinkNotFound.
from dataclasses import dataclass
MAX_ATTEMPTS = 5
class InvalidUrl(ValueError):
pass
class CodeTaken(Exception):
pass
class LinkNotFound(Exception):
pass
class ServiceBusy(Exception):
pass
@dataclass(frozen=True)
class Link:
code: str
url: str
def validate_url(raw):
if not isinstance(raw, str) or not raw.startswith("https://"):
raise InvalidUrl(raw)
return raw
class FakeRepo:
def __init__(self):
self.links = {}
def add(self, code, url):
if code in self.links:
raise CodeTaken(code)
self.links[code] = url
def resolve(self, code):
return self.links.get(code)
class LinkService:
def __init__(self, repo, new_code):
self.repo = repo
self.new_code = new_code
def shorten(self, raw_url):
pass
def resolve(self, code):
pass
Jak dlouhý má kód být? Kolize začínají mnohem dřív, než bys čekal. Je to stejný jev jako narozeninový paradox.
import math
for chars in (4, 6, 8):
space = 64 ** chars
half_chance = math.sqrt(2 * space * math.log(2))
print(f"délka {chars}: {space:>19,} možností, 50% šance na kolizi po {half_chance:>10,.0f} kódech")
délka 4: 16,777,216 možností, 50% šance na kolizi po 4,823 kódech délka 6: 68,719,476,736 možností, 50% šance na kolizi po 308,651 kódech délka 8: 281,474,976,710,656 možností, 50% šance na kolizi po 19,753,662 kódech
secrets.token_urlsafe(6) dá 6 náhodných bajtů, tedy 8 znaků z abecedy o 64 symbolech. Kolize jsou při rozumném provozu vzácné a smyčka s opakováním je bezpečně vyřeší. Náhodnost má ještě jeden důvod: při kódech 1, 2, 3 by kdokoli prošel všechny odkazy všech zákazníků.
Krok 4: HTTP vrstva
Tahle vrstva překládá mezi světem HTTP a službou. Záměrně je bez frameworku, abys viděl, co se děje. Ve FastAPI z ní zbude pár dekorátorů.
Krok 4: App.handle
Doplň App:
__init__: prázdnýapi_keyvyhodíValueError. Jinak by šlo projít s prázdnou hlavičkou.GET /healthvrátí200,{"status": "ok"}.POST /links: hlavičkax-api-keyse porovná přeshmac.compare_digestna bajtech a špatný klíč dá401, ještě před čtením těla. Nečitelný JSON dá400. Tělo, které není slovník, a neplatná adresa dají422.ServiceBusydá503. Úspěch dá201a{"code": ..., "url": ...}.- Jiná metoda na
/linksdá405s hlavičkouAllow: POST. GET /{code}(jeden segment cesty) dá307s hlavičkouLocation, neznámý kód404.- Všechno ostatní dá
404.
Chybová těla mají tvar {"detail": "..."}.
import hmac
import json
from dataclasses import dataclass, field
class InvalidUrl(ValueError):
pass
class LinkNotFound(Exception):
pass
class ServiceBusy(Exception):
pass
@dataclass(frozen=True)
class Link:
code: str
url: str
@dataclass(frozen=True)
class Request:
method: str
path: str
headers: dict = field(default_factory=dict) # lower-case names
body: bytes = b""
@dataclass
class Response:
status: int
body: dict | None = None
headers: dict = field(default_factory=dict)
class FakeService:
def __init__(self):
self.links = {"abc": "https://example.com/"}
def shorten(self, raw_url):
if raw_url == "https://busy.example/":
raise ServiceBusy()
if not isinstance(raw_url, str) or not raw_url.startswith("https://"):
raise InvalidUrl(raw_url)
self.links["new"] = raw_url
return Link("new", raw_url)
def resolve(self, code):
if code not in self.links:
raise LinkNotFound(code)
return self.links[code]
class App:
def __init__(self, service, api_key):
self.service = service
self.api_key = api_key
def handle(self, request):
return Response(404, {"detail": "Nenalezeno"})
Proč přesměrování používá 307, a ne trvalé 301?
Trvalé přesměrování smí klient ukládat do cache. Pak by počítadlo lhalo a odkaz by nešlo změnit ani zablokovat.
Krok 5: aby šlo ladit ve tři ráno
Když něco selže, musíš z logu poznat, co se stalo, a odpověď klientovi nesmí prozradit vnitřnosti. Obal kolem handle to vyřeší na jednom místě: každý požadavek dostane request id, které se vrátí klientovi v hlavičce a objeví se v logu. Zákazník nahlásí id a ty najdeš přesný řádek. Podrobnosti o logování jsou v lekci Logování a pozorovatelnost.
Krok 5: with_observability
Napiš with_observability(handler, logger, new_id, clock). Vrátí funkci wrapped(request), která:
- získá id přes
new_id()a čas přesclock()(v sekundách) před voláním i po něm, - zavolá
handler(request). Při výjimce vytvoříResponse(500, {"detail": "Interní chyba", "request_id": id}). Text výjimky do odpovědi nesmí, - do hlaviček odpovědi přidá
X-Request-Id, - zapíše jeden záznam
logger.log(úroveň, "request", extra={"fields": {...}})s polirequest_id,method,path,status,duration_ms. Úroveň jeERRORpro stav 500 a víc, jinakINFO.
Hlavičky ani tělo požadavku do logu nepatří, je v nich API klíč.
import io
import json
import logging
from dataclasses import dataclass, field
@dataclass(frozen=True)
class Request:
method: str
path: str
headers: dict = field(default_factory=dict)
body: bytes = b""
@dataclass
class Response:
status: int
body: dict | None = None
headers: dict = field(default_factory=dict)
class JsonFormatter(logging.Formatter):
def format(self, record):
data = {"level": record.levelname, "event": record.getMessage()}
data.update(getattr(record, "fields", {}))
return json.dumps(data, ensure_ascii=False, sort_keys=True)
def with_observability(handler, logger, new_id, clock):
def wrapped(request):
return handler(request)
return wrapped
Pod kapotou · co doplnit na ostrém provozu
Skutečný obal by při výjimce zalogoval i traceback (exc_info=True) a formátor by ho převedl do pole. Pozor, že traceback může obsahovat data z výjimek. Request id se přes vrstvy předává přes contextvars, aby ho viděly i logy hluboko v kódu bez předávání parametrem. Ty fungují i v asyncio, kde thread-local selhává. Příchozí X-Request-Id přebírej jen od důvěryhodné proxy a s omezením délky a znaků, jinak ti klient podstrčí do logů cokoli.
Logování path je tu u zkracovače v pořádku, ale kódy tvoří neomezený prostor hodnot. Do metrik proto dej šablonu trasy (/{code}), jinak ti exploduje kardinalita v Prometheu.
Co mise záměrně neřeší: rate limiting na /links i na přesměrování, idempotenci POSTu (Idempotency-Key, aby opakovaný požadavek po výpadku sítě nevyrobil druhý odkaz), expiraci a mazání odkazů. SQLite s WAL a busy_timeout zvládne překvapivě hodně čtení, ale zapisuje vždy jen jeden proces a soubor nesdílíš mezi stroji. A protože každé přesměrování je tady zápis, dřív nebo později přijde dávkování počítadel do paměti, nebo přechod na PostgreSQL.
Krok 6: testy, které něco chytí
Test, který projde vždy, je horší než žádný, protože uklidňuje. Kontrola tohoto úkolu to ověří tvrdě. Tvoje testy nejdřív poběží proti správnému kódu a pak proti úmyslně rozbitým verzím. Každou rozbitou verzi musí aspoň jeden test odhalit. Říká se tomu mutační testování.
Krok 6: testy služby
Doplň třídu ShortenerTests (unittest, bez volání unittest.main()). Testy musí poznat tyto chyby:
- služba přestane ověřovat adresy,
- služba při kolizi kódu nezkusí další,
resolveu neznámého kódu nevyhodíLinkNotFound.
Napiš aspoň tři testy. Službu si v nich vytvoř přes make_service.
import unittest
MAX_ATTEMPTS = 5
class InvalidUrl(ValueError):
pass
class CodeTaken(Exception):
pass
class LinkNotFound(Exception):
pass
class ServiceBusy(Exception):
pass
def validate_url(raw):
if not isinstance(raw, str) or not raw.startswith("https://"):
raise InvalidUrl(raw)
return raw
class FakeRepo:
def __init__(self):
self.links = {}
def add(self, code, url):
if code in self.links:
raise CodeTaken(code)
self.links[code] = url
def resolve(self, code):
return self.links.get(code)
class LinkService:
def __init__(self, repo, new_code):
self.repo = repo
self.new_code = new_code
def shorten(self, raw_url):
url = validate_url(raw_url)
for _ in range(MAX_ATTEMPTS):
code = self.new_code()
try:
self.repo.add(code, url)
except CodeTaken:
continue
return code, url
raise ServiceBusy()
def resolve(self, code):
url = self.repo.resolve(code)
if url is None:
raise LinkNotFound(code)
return url
def make_service(codes):
return LinkService(FakeRepo(), iter(codes).__next__)
class ShortenerTests(unittest.TestCase):
def test_placeholder(self):
self.assertTrue(True)
Složení a cesta do provozu
Všechny vrstvy dohromady, tentokrát se skutečnou databází. Tohle je celá služba.
import hmac
import json
import logging
import sqlite3
import sys
from dataclasses import dataclass, field
from urllib.parse import urlsplit
class InvalidUrl(ValueError): ...
class CodeTaken(Exception): ...
class LinkNotFound(Exception): ...
class ServiceBusy(Exception): ...
@dataclass(frozen=True)
class Link:
code: str
url: str
@dataclass(frozen=True)
class Request:
method: str
path: str
headers: dict = field(default_factory=dict)
body: bytes = b""
@dataclass
class Response:
status: int
body: dict | None = None
headers: dict = field(default_factory=dict)
def validate_url(raw):
if not isinstance(raw, str):
raise InvalidUrl("Adresa musí být text.")
url = raw.strip()
if not url or len(url) > 2048 or any(c.isspace() or ord(c) < 32 for c in url):
raise InvalidUrl("Neplatný text adresy.")
try:
parts = urlsplit(url)
host, user = parts.hostname, parts.username
except ValueError as error:
raise InvalidUrl("Adresu nejde rozebrat.") from error
if parts.scheme.lower() not in {"http", "https"} or not host or user is not None:
raise InvalidUrl("Nepovolená adresa.")
return url
class LinkRepo:
def __init__(self, conn):
self.conn = conn
conn.execute("""CREATE TABLE IF NOT EXISTS links (
code TEXT PRIMARY KEY, url TEXT NOT NULL, hits INTEGER NOT NULL DEFAULT 0)""")
def add(self, code, url):
try:
with self.conn:
self.conn.execute("INSERT INTO links (code, url) VALUES (?, ?)", (code, url))
except sqlite3.IntegrityError as error:
raise CodeTaken(code) from error
def resolve(self, code):
with self.conn:
rows = self.conn.execute(
"UPDATE links SET hits = hits + 1 WHERE code = ? RETURNING url", (code,)
).fetchall()
return rows[0][0] if rows else None
def hits(self, code):
row = self.conn.execute("SELECT hits FROM links WHERE code = ?", (code,)).fetchone()
return row[0] if row else None
class LinkService:
def __init__(self, repo, new_code):
self.repo, self.new_code = repo, new_code
def shorten(self, raw_url):
url = validate_url(raw_url)
for _ in range(5):
code = self.new_code()
try:
self.repo.add(code, url)
except CodeTaken:
continue
return Link(code, url)
raise ServiceBusy
def resolve(self, code):
url = self.repo.resolve(code)
if url is None:
raise LinkNotFound(code)
return url
def error(status, detail, headers=None):
return Response(status, {"detail": detail}, headers or {})
class App:
def __init__(self, service, api_key):
if not api_key:
raise ValueError("API klíč nesmí být prázdný.")
self.service, self.api_key = service, api_key.encode()
def handle(self, request):
method, path = request.method, request.path
if path == "/links":
return self.create(request) if method == "POST" else error(405, "Nepovoleno", {"Allow": "POST"})
if method == "GET" and path == "/health":
return Response(200, {"status": "ok"})
if method == "GET" and path.count("/") == 1 and len(path) > 1:
try:
return Response(307, None, {"Location": self.service.resolve(path[1:])})
except LinkNotFound:
return error(404, "Odkaz neexistuje")
return error(404, "Nenalezeno")
def create(self, request):
if not hmac.compare_digest(request.headers.get("x-api-key", "").encode(), self.api_key):
return error(401, "Neplatný klíč")
try:
data = json.loads(request.body)
except ValueError:
return error(400, "Tělo není platný JSON")
if not isinstance(data, dict):
return error(422, "Tělo musí být objekt")
try:
link = self.service.shorten(data.get("url"))
except InvalidUrl:
return error(422, "Neplatná adresa")
except ServiceBusy:
return error(503, "Zkuste to znovu")
return Response(201, {"code": link.code, "url": link.url})
class JsonFormatter(logging.Formatter):
def format(self, record):
data = {"level": record.levelname, "event": record.getMessage()}
data.update(getattr(record, "fields", {}))
return json.dumps(data, ensure_ascii=False, sort_keys=True)
def with_observability(handler, logger, new_id):
def wrapped(request):
request_id = new_id()
try:
response = handler(request)
except Exception:
response = Response(500, {"detail": "Interní chyba", "request_id": request_id})
response.headers["X-Request-Id"] = request_id
level = logging.ERROR if response.status >= 500 else logging.INFO
logger.log(level, "request", extra={"fields": {
"request_id": request_id, "method": request.method,
"path": request.path, "status": response.status,
}})
return response
return wrapped
# --- wiring: deterministic ids here, secrets.token_urlsafe in production
log_output = logging.StreamHandler(sys.stdout)
log_output.setFormatter(JsonFormatter())
logger = logging.Logger("kratce")
logger.addHandler(log_output)
codes = iter(["uvitani", "uvitani", "akce2026"])
request_ids = (f"req-{n}" for n in range(1, 100))
repo = LinkRepo(sqlite3.connect(":memory:"))
app = App(LinkService(repo, lambda: next(codes)), api_key="demo-klic")
serve = with_observability(app.handle, logger, lambda: next(request_ids))
key = {"x-api-key": "demo-klic"}
scenario = [
Request("GET", "/health"),
Request("POST", "/links", key, b'{"url": "https://example.com/dlouha/adresa"}'),
Request("POST", "/links", key, b'{"url": "https://example.com/podzimni-akce"}'),
Request("POST", "/links", key, b'{"url": "javascript:alert(1)"}'),
Request("POST", "/links", {}, b'{"url": "https://example.com/"}'),
Request("GET", "/akce2026"),
Request("GET", "/akce2026"),
Request("GET", "/neexistuje"),
]
for request in scenario:
response = serve(request)
print(" ->", response.status, response.body or response.headers.get("Location"))
print("návštěvy akce2026:", repo.hits("akce2026"))
{"event": "request", "level": "INFO", "method": "GET", "path": "/health", "request_id": "req-1", "status": 200}
-> 200 {'status': 'ok'}
{"event": "request", "level": "INFO", "method": "POST", "path": "/links", "request_id": "req-2", "status": 201}
-> 201 {'code': 'uvitani', 'url': 'https://example.com/dlouha/adresa'}
{"event": "request", "level": "INFO", "method": "POST", "path": "/links", "request_id": "req-3", "status": 201}
-> 201 {'code': 'akce2026', 'url': 'https://example.com/podzimni-akce'}
{"event": "request", "level": "INFO", "method": "POST", "path": "/links", "request_id": "req-4", "status": 422}
-> 422 {'detail': 'Neplatná adresa'}
{"event": "request", "level": "INFO", "method": "POST", "path": "/links", "request_id": "req-5", "status": 401}
-> 401 {'detail': 'Neplatný klíč'}
{"event": "request", "level": "INFO", "method": "GET", "path": "/akce2026", "request_id": "req-6", "status": 307}
-> 307 https://example.com/podzimni-akce
{"event": "request", "level": "INFO", "method": "GET", "path": "/akce2026", "request_id": "req-7", "status": 307}
-> 307 https://example.com/podzimni-akce
{"event": "request", "level": "INFO", "method": "GET", "path": "/neexistuje", "request_id": "req-8", "status": 404}
-> 404 {'detail': 'Odkaz neexistuje'}
návštěvy akce2026: 2Protože jádro nezávisí na frameworku, je FastAPI jen tenká slupka nad ním. Soubor kratce/core.py obsahuje třídy z mise:
import hmac
import os
import secrets
import sqlite3
from collections.abc import Iterator
from typing import Annotated
from fastapi import Depends, FastAPI, Header, HTTPException
from fastapi.responses import RedirectResponse
from pydantic import BaseModel
from kratce.core import InvalidUrl, LinkNotFound, LinkRepo, LinkService, ServiceBusy
API_KEY = os.environ["API_KEY"].encode() # missing key = crash at startup
DB_PATH = os.environ.get("DB_PATH", "kratce.db")
app = FastAPI(title="kratce", docs_url=None, redoc_url=None)
class LinkIn(BaseModel):
url: str
class LinkOut(BaseModel):
code: str
url: str
def get_service() -> Iterator[LinkService]:
conn = sqlite3.connect(DB_PATH, check_same_thread=False, timeout=5)
conn.execute("PRAGMA journal_mode=WAL")
try:
yield LinkService(LinkRepo(conn), lambda: secrets.token_urlsafe(6))
finally:
conn.close()
Service = Annotated[LinkService, Depends(get_service)]
def require_key(x_api_key: Annotated[str, Header()] = "") -> None:
if not hmac.compare_digest(x_api_key.encode(), API_KEY):
raise HTTPException(401, "Neplatný klíč")
@app.get("/health")
def health() -> dict[str, str]:
return {"status": "ok"}
@app.post("/links", status_code=201, dependencies=[Depends(require_key)])
def create_link(payload: LinkIn, service: Service) -> LinkOut:
try:
link = service.shorten(payload.url)
except InvalidUrl:
raise HTTPException(422, "Neplatná adresa") from None
except ServiceBusy:
raise HTTPException(503, "Zkuste to znovu") from None
return LinkOut(code=link.code, url=link.url)
@app.get("/{code}") # must stay the last route
def follow(code: str, service: Service) -> RedirectResponse:
try:
return RedirectResponse(service.resolve(code), status_code=307)
except LinkNotFound:
raise HTTPException(404, "Odkaz neexistuje") from NoneZbytek už znáš z předchozích lekcí. Image:
FROM python:3.12-slim AS build
COPY requirements.lock .
RUN python -m venv /opt/venv \
&& /opt/venv/bin/pip install --no-cache-dir --require-hashes -r requirements.lock
FROM python:3.12-slim
RUN useradd --system --uid 10001 --no-create-home app \
&& mkdir /data && chown app /data
WORKDIR /srv
COPY --from=build /opt/venv /opt/venv
COPY kratce/ ./kratce/
ENV PATH="/opt/venv/bin:$PATH" PYTHONUNBUFFERED=1 DB_PATH=/data/kratce.db
USER app
EXPOSE 8000
HEALTHCHECK --interval=10s --timeout=3s --start-period=5s \
CMD ["python", "-c", "import urllib.request as u; u.urlopen('http://127.0.0.1:8000/health', timeout=2)"]
CMD ["uvicorn", "kratce.api:app", "--host", "0.0.0.0", "--port", "8000"]A kroky v CI, které hlídají kvalitu i bezpečnost:
- run: pip install --require-hashes -r requirements-dev.lock
- run: ruff check .
- run: ruff check --select S kratce
- run: ruff format --check .
- run: mypy kratce
- run: pytest -q --cov=kratce --cov-fail-under=90
- run: pip-audit -r requirements.lockProč LinkService dostává generátor kódů jako parametr?
Náhoda je vstup jako každý jiný. Když ji předáš zvenku, je chování v testu přesně dané.
Proč se před vložením neptáme SELECTem, jestli je kód volný?
Vzorec „zkontroluj a pak udělej“ má při souběhu okno pro chybu. Nech rozhodnout databázi a ošetři výjimku.