Guia para usuarios avanzados¶
Esta guia cubre decisiones de operacion, limites y composicion avanzada. Esta pensada para servicios internos, laboratorios de red, herramientas de borde y demos con varias capas activas.
Configurar el servidor HTTP¶
app.run(host, port, ssl_context=None) crea un HTTPServer. Si necesitas tocar
limites de transporte, instancia el servidor:
from wsbuilder import App, HTTPServer
app = App()
server = HTTPServer(
"127.0.0.1",
8765,
app,
max_connection_workers=128,
max_request_header_bytes=128 * 1024,
max_request_body_bytes=4 * 1024 * 1024,
request_read_timeout=15.0,
)
server.serve_forever()
El servidor valida:
- HTTP/1.0 y HTTP/1.1.
Hostrequerido en HTTP/1.1.- duplicados peligrosos como
Content-LengthyHost. - combinacion ambigua de
Content-LengthyTransfer-Encoding. - cuerpos incompletos, demasiado grandes o sin framing.
Expect: 100-continuesolo conContent-Length.- lineas terminadas solo en LF (se rechazan con
400al instante) y metodos en minusculas (getno esGET). - destinos en absolute-form (
GET http://host/ruta), cuyohostsustituye aHost, yOPTIONS *.
Capacidad y sobrecarga¶
| Opcion | Por defecto | Efecto |
|---|---|---|
max_connection_workers |
64 | Conexiones HTTP atendidas a la vez |
max_ws_connections |
1024 | WebSockets abiertos; no consumen hilos HTTP |
max_concurrent_streams |
100 | Streams HTTP/2 por conexion, incluidos los reseteados con handler pendiente |
max_http2_handler_threads |
64 | Hilos de handlers compartidos por todas las conexiones HTTP/2 |
Una conexion que llega sin hueco libre recibe 503 Service Unavailable con
Retry-After (sin TLS) en lugar de un reset.
HTTP/2 tambien se protege del abuso del protocolo: si un cliente cancela
demasiados streams antes de recibir respuesta ("Rapid Reset", CVE-2023-44487)
o inunda la conexion de PING, SETTINGS, frames vacios o CONTINUATION, la
conexion se cierra con GOAWAY(ENHANCE_YOUR_CALM). Los umbrales son atributos
de wsbuilder.http2.Http2Connection (MAX_EARLY_RESETS,
MAX_CONTROL_FRAMES, MAX_CONTINUATION_FRAMES, ABUSE_WINDOW_SECONDS).
Para medir el rendimiento en tu maquina: python benchmarks/http1_keepalive.py.
TLS¶
HTTPServer acepta un ssl_context ya construido:
import ssl
from wsbuilder import HTTPServer
ctx = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
ctx.load_cert_chain("cert.pem", "key.pem")
HTTPServer("0.0.0.0", 8443, app, ssl_context=ctx).serve_forever()
Request.tls queda poblado con enabled, peer_cert, cipher y version.
Worker pools por ruta¶
Las rutas view pueden ejecutarse en un pool dedicado. Sirve para trabajo CPU o
I/O pesado que quieres aislar de rutas directas.
@app.view(
"/reports",
min_threads=1,
max_threads=4,
requests_per_thread=8,
worker_timeout_seconds=2.0,
affinity_ttl_seconds=900,
)
def reports(_request):
return "ready"
Seleccion de worker:
- Se respeta afinidad por cookie firmada si el worker todavia tiene capacidad.
- Si no hay afinidad valida, se elige el worker menos cargado.
- El pool puede crecer hasta
max_threads. - Si el handler ya empezo, el timeout no lo interrumpe por fuerza; evita trabajos no acotados dentro de rutas.
Configura thread_cookie_secret con un valor privado y estable cuando uses
afinidad en produccion.
Seguridad detras de proxies¶
No confies en X-Forwarded-For salvo que controles el proxy directo. Usa
trusted_proxy_cidrs:
from wsbuilder import SecurityPolicy
policy = SecurityPolicy(
trust_x_forwarded_for=True,
trusted_proxy_cidrs=("10.0.0.0/8", "192.168.0.0/16"),
rate_limit_requests=600,
rate_limit_window_seconds=60,
)
app.enable_security(policy)
La IP se resuelve desde la derecha de la cadena X-Forwarded-For, descartando
saltos confiables. Si el peer directo no pertenece a una red confiable, se ignora
la cabecera.
ProxyI como reverse proxy¶
ProxyI puede instalar metricas y dashboard, pero el forwarding real ocurre
cuando una ruta llama app.proxyi.dispatch(request).
from wsbuilder import ProxyI
proxy = ProxyI(
name="edge",
default_balance="least_response_time",
max_request_body_bytes=2 * 1024 * 1024,
)
proxy.vhost("api.example.local", name="api").location("/api").balance("round_robin").upstream(
"http://127.0.0.1:9001",
name="api-1",
).upstream(
"http://127.0.0.1:9002",
name="api-2",
).build()
proxy.install(
app,
metrics_path="/api/proxy/metrics",
stream_path="/api/proxy/metrics/stream",
dashboard_path="/proxy",
)
@app.api("/api/upstream")
def upstream(request):
return app.proxyi.dispatch(request)
Puntos importantes:
verify_tls=Truepor defecto en targets HTTPS.- headers hop-by-hop se eliminan antes de reenviar.
X-Forwarded-*se reconstruye desde el peer, host y TLS reales.- headers sensibles en snapshots se redactan.
- targets
enabled=Falseno participan en balanceo. - los snapshots no avanzan round-robin.
DNS local avanzado¶
LocalDNSServer soporta records en formato nombrado y plano:
from wsbuilder import LocalDNSServer
dns = LocalDNSServer(
host="127.0.0.1",
port=5533,
ttl=60,
records={
"app.local": {
"A": "127.0.0.1",
"TXT": "internal demo",
"MX": {"preference": 10, "exchange": "mail.app.local"},
},
"*.dev.local": {"A": "127.0.0.2"},
},
upstream_servers=[("1.1.1.1", 53)],
fallback_to_upstream=True,
)
dns.start()
Tipos con encoding especifico incluyen A, AAAA, NS, CNAME, PTR, MX,
TXT, SRV, SOA, CAA, NAPTR, URI, DS, DNSKEY, TLSA y SSHFP.
Para otros tipos puedes usar TYPE#### con rdata, hex o base64.
El fallback upstream valida endpoint de origen, transaction ID y pregunta antes de aceptar una respuesta.
WebSocket con ciclo de vida controlado¶
def on_close(ws, code, reason):
print("closed", code, reason)
def on_timeout(ws, reason):
print("timeout", reason)
@app.ws(
"/ws/events",
subprotocols=("json",),
idle_timeout=60,
keepalive_interval=20,
pong_timeout=10,
auto_pong=True,
on_close=on_close,
on_timeout=on_timeout,
)
def events(ws, _request):
while True:
frame = ws.recv_frame()
if frame.opcode == 0x8:
ws.close(1000, "bye")
break
if frame.opcode == 0x1:
ws.send_text(frame.payload.decode("utf-8"))
El lector reensambla mensajes fragmentados y valida RSV, opcodes, mascaras, longitudes minimas, frames de control y UTF-8 en texto.
SQLite de lectura intensiva¶
Para lectura intensiva sobre archivo SQLite:
from wsbuilder import OptimizedDatabase, SQLite3OptimizationConfig
cfg = SQLite3OptimizationConfig(cache_size=32768, wal_autocheckpoint=500)
db = OptimizedDatabase(
"data/app.sqlite3",
optimization_config=cfg,
enable_replicas=True,
replica_count=4,
)
Usa replicas para lecturas:
rows = db.read_replica_fetchall("SELECT * FROM events ORDER BY id DESC LIMIT 100")
Las replicas son conexiones read-only. Las escrituras deben ir a la conexion principal.
Observabilidad para operacion¶
Activa metricas y logs al iniciar:
app.enable_metrics(app_name="edge-service")
app.enable_logs(path="logs/edge.ndjson")
app.enable_docs(path="/docs", json_path="/docs.json")
Endpoints utiles:
/api/metrics: snapshot JSON./api/metrics/stream?interval=1&limit=10: stream NDJSON finito./api/metrics/stream?interval=1&follow=1: stream continuo./docs.json: snapshot de rutas e integraciones activas.
Apagado y recursos¶
App.close() cierra tareas, cache HTTP, proxy, logs y pools de rutas. Si adjuntas
recursos propios como app.db o app.dns, cierralos en tu flujo principal:
try:
app.run("127.0.0.1", 8765)
finally:
if getattr(app, "db", None):
app.db.close()
if getattr(app, "dns", None):
app.dns.close()
Checklist avanzado¶
- Define limites de body, headers y workers segun tu carga.
- Usa TLS o un proxy TLS delante cuando salgas de localhost.
- Configura
trusted_proxy_cidrsantes de leer IPs de cabeceras forwarded. - No uses
verify_tls=Falsepara upstreams no confiables. - Activa metricas y logs desde el arranque.
- Usa replicas solo para lecturas.
- Invalida caches despues de escrituras.
- Mantiene rutas WebSocket con timeouts y keepalive.
- Cierra recursos propios en
finally.