Guia para usuarios intermedios¶
Esta guia parte de una app HTTP basica y agrega las piezas que se usan en un servicio interno real: persistencia, cache, seguridad, metricas, logs y tareas.
Estructura recomendada¶
Para una app pequena, un solo archivo funciona bien:
my_service/
├── app.py
├── data/
└── logs/
Cuando crece, separa por responsabilidad:
my_service/
├── app.py
├── models.py
├── routes.py
├── services.py
└── settings.py
wsbuilder no impone esta estructura. Lo importante es que la instancia App
sea el punto donde se registran rutas e integraciones.
Modelo y base SQLite¶
from datetime import UTC, datetime
from wsbuilder import Database, DateTimeField, IntegerField, JSONField, Model, TextField
class Note(Model):
__tablename__ = "notes"
id = IntegerField(primary_key=True, auto_increment=True)
title = TextField(unique=True, null=False, index=True)
body = TextField(default="", null=False)
tags = JSONField(default=list, null=False)
created_at = DateTimeField(default=lambda: datetime.now(UTC), null=False)
db = Database("data/app.sqlite3", enable_wal=True, enable_replicas=True, replica_count=2)
Note.create_table(db)
Consultas frecuentes:
Note.create(db, title="hola", tags=["demo"])
latest = Note.objects(db).order_by("-id").limit(10).all()
tagged = Note.objects(db).filter(title__icontains="ho").all()
count = Note.objects(db).using("replica").count()
Usa transaction() para operaciones que deben confirmarse juntas:
with db.transaction():
Note.create(db, title="a")
Note.create(db, title="b")
API CRUD simple¶
from wsbuilder import App, Response
app = App(cors_allow_origin="*")
app.db = db
@app.api("/api/notes", methods=("GET", "POST"))
def notes(request):
if request.method == "GET":
rows = [note.to_dict() for note in Note.objects(app.db).order_by("-id").all()]
return {"items": rows, "total": len(rows)}
payload = request.json() or {}
title = str(payload.get("title", "")).strip()
if not title:
return Response.json({"message": "title is required"}, status=400)
note = Note.create(
app.db,
title=title,
body=str(payload.get("body", "")),
tags=list(payload.get("tags", [])),
)
return Response.json(note.to_dict(), status=201)
Cache clave-valor¶
Instala una cache para datos calculados, contadores o snapshots temporales:
from wsbuilder import SQLiteMemoryCache, install_cache
app.cache = install_cache(
app,
SQLiteMemoryCache(default_ttl=120, cleanup_interval_seconds=0, max_entries=512),
)
@app.api("/api/cache/demo")
def cache_demo(_request):
counter = app.cache.incr("counter", namespace="demo", initial=0)
app.cache.set("last", {"counter": counter}, namespace="demo", tags=["demo"])
return {"counter": counter, "stats": app.cache.stats()}
Usa tags cuando necesites invalidar grupos:
app.cache.set("note:1", {"title": "hola"}, tags=["notes"])
app.cache.invalidate_tag("notes")
Cache HTTP de vistas¶
ViewResponseCache trabaja sobre rutas view, no sobre rutas api.
from wsbuilder import ViewResponseCache
http_cache = ViewResponseCache(default_ttl=20)
http_cache.add_global_rule(
ttl_seconds=30,
path_pattern="/pages/*",
mimetype_pattern="text/html*",
methods=("GET",),
name="html-pages",
)
app.enable_caches(http_cache)
@app.view("/pages/overview", cache={"ttl": 20, "vary_query": ["lang"]})
def overview(request):
lang = request.query.get("lang", "es")
return f"lang={lang}"
Si una ruta cambia datos que afectan vistas cacheadas, invalida el path:
app.caches.invalidate_path("/pages/overview")
Seguridad basica¶
from wsbuilder import SecurityPolicy
policy = SecurityPolicy(
rate_limit_requests=240,
rate_limit_window_seconds=60.0,
block_duration_seconds=30.0,
)
policy.deny(name="deny-admin-post", methods=("POST",), path="/api/admin")
app.enable_security(policy=policy)
Para una politica cerrada, usa acl_default="deny" y agrega reglas allow(...).
policy = SecurityPolicy(acl_default="deny")
policy.allow(methods=("GET",), path_prefix="/api/public")
policy.allow(methods=("GET",), path="/api/health")
Metricas, logs y docs runtime¶
app.enable_metrics(app_name="notes-service")
app.enable_logs(path="logs/app.ndjson")
app.enable_docs(path="/docs", json_path="/docs.json")
Cada snapshot de metricas puede incluir:
- HTTP y conexiones TCP.
- WebSocket.
- workers por ruta.
- cache KV.
- cache HTTP.
- seguridad.
- proxy, si esta instalado.
- tareas en background.
Tareas en background¶
@app.api("/api/tasks/run", methods=("POST",))
def run_task(request):
def work():
return {"ok": True}
task = request.app.tasks.spawn(work, name="demo", group="jobs", request=request)
return {"task_id": task.id, "status": task.status}
@app.api("/api/tasks/status")
def task_status(request):
task_id = request.query.get("task_id", "")
task = request.app.tasks.get(task_id)
if task is None:
return Response.json({"message": "task not found"}, status=404)
return task.snapshot()
La cancelacion es cooperativa. Si tu funcion tarda mucho, usa
pass_handle=True y revisa handle.cancelled dentro del trabajo.
def work(handle):
for step in range(100):
if handle.cancelled:
return {"cancelled_at": step}
return {"ok": True}
task = app.tasks.spawn(work, pass_handle=True)
Checklist para apps intermedias¶
- Usa
venvy Python3.11+. - Activa
enable_docs()en entornos internos para verificar rutas. - Devuelve
Response.json(..., status=...)cuando necesites estados distintos a200. - Usa
Database(..., enable_wal=True)para archivos SQLite persistentes. - Invalida cache HTTP despues de escrituras que afectan vistas.
- Configura
SecurityPolicyantes de exponer rutas sensibles. - Cierra recursos propios (
db, DNS, caches externas) en tu flujo de apagado.