App y HTTP¶
App¶
App es el centro del framework. Mantiene el router, las rutas WebSocket y las
integraciones opcionales de metricas, seguridad, cache, logs, proxy y tareas.
Una aplicacion puede usarse de dos formas:
- con
app.run(host, port), para aceptar conexiones reales. - con
app.dispatch(request), para pruebas o integraciones programaticas.
Constructor:
from wsbuilder import App
app = App(
cors_allow_origin="*",
thread_cookie_secret="dev-secret",
thread_cookie_name="wsbuilder-thread",
)
Tipos de ruta¶
@app.view¶
Pensada para HTML o texto. Si el handler devuelve:
Response, se envia tal cual.str,bytesoNone, se convierte enResponse.text(...).
from wsbuilder import Response
@app.view("/")
def home(_request):
return Response.html("<h1>Inicio</h1>")
@app.api¶
Pensada para JSON. Si el handler devuelve dict o list, la conversion a JSON
es automatica.
@app.api("/api/health")
def health(_request):
return {"ok": True}
@app.route¶
Es la forma mas generica. Permite elegir kind="plain" o kind="api".
@app.route("/status.txt", methods=("GET",), kind="plain")
def status(_request):
return "ok"
El path debe empezar con / y no puede contener caracteres de control. Los
metodos se normalizan a mayusculas. Si declaras una ruta GET, HEAD funciona
automaticamente con las mismas cabeceras y sin cuerpo.
Request¶
Request expone:
method,path,query_string,query.headers,body,client,tls.app, queApp.dispatch()rellena automaticamente.- helpers
text()yjson().
query decodifica percent-encoding y + con las reglas de formularios URL. Si
una clave aparece varias veces conserva el ultimo valor y limita el numero de
campos aceptados.
@app.api("/api/echo", methods=("POST",))
def echo(request):
payload = request.json() or {}
return {"received": payload, "query": request.query}
Si el cuerpo no es JSON valido, request.json() devuelve None. Eso permite
escribir handlers defensivos sin envolver cada parseo en try/except.
Response¶
Constructores de clase:
Response.json(data, status=200, headers=None)Response.text(text, status=200, headers=None)Response.html(html, status=200, headers=None)Response.stream(chunks, status=200, headers=None, content_type=None)
Ejemplo de streaming:
from wsbuilder import Response
@app.api("/api/stream")
def stream(_request):
def chunks():
yield '{"step": 1}\n'
yield '{"step": 2}\n'
return Response.stream(chunks(), content_type="application/x-ndjson")
Parametros de ruta¶
Un segmento {nombre} captura una parte de la ruta y la deja en
request.path_params. Los conversores disponibles son str (por defecto, un
segmento), int y path (el resto de la ruta, barras incluidas):
@app.api("/users/{user_id:int}")
def user(request):
return {"id": request.path_params["user_id"]} # int
@app.api("/files/{rest:path}")
def files(request):
return {"path": request.path_params["rest"]}
Las rutas estaticas tienen prioridad: /users/me gana a /users/{name}. Si el
valor no encaja con el conversor (/users/abc con int), la ruta no coincide.
Barra final¶
Con App(redirect_slashes=True) (valor por defecto), si solo existe /items,
GET /items/ responde 308 con Location: /items (conservando la query
string), y al reves. App(redirect_slashes=False) devuelve 404.
CORS y OPTIONS¶
El OPTIONS automatico responde 204 con la cabecera Allow y la union de
metodos permitidos. OPTIONS * describe los metodos del servidor.
Si cors_allow_origin esta configurado:
- las rutas
apiincluyenAccess-Control-Allow-Origin. - el
OPTIONSautomatico anadeAccess-Control-Allow-Methods,Access-Control-Allow-HeadersyAccess-Control-Allow-Origin. Sin CORS no se envian cabecerasAccess-Control-*.
El OPTIONS automatico solo actua cuando ninguna ruta declara ese metodo. Si
registras un handler propio para OPTIONS, la peticion llega a tu codigo:
@app.api("/api/items", methods=("OPTIONS",))
def items_options(request):
return Response(status=204, headers={"Allow": "GET, POST, OPTIONS"})
Ademas, HEAD reutiliza una ruta GET y envia sus mismas cabeceras sin cuerpo.
Un metodo no permitido para una ruta existente responde 405 e incluye
Allow; una ruta inexistente responde 404.
Probar una ruta sin red¶
from wsbuilder import Request
request = Request(
method="GET",
path="/api/health",
query_string="",
headers={},
body=b"",
client=("127.0.0.1", 1234),
)
response = app.dispatch(request)
assert response.status == 200
Ese patron aparece en la suite porque evita abrir sockets y permite probar la logica de rutas de forma determinista.
Vistas con hilos dedicados¶
Las rutas view soportan worker pools por ruta:
@app.view(
"/heavy",
min_threads=1,
max_threads=4,
requests_per_thread=8,
worker_timeout_seconds=2.0,
)
def heavy(_request):
return "ok"
Campos relevantes:
min_threadsymax_threads: rango del pool.requests_per_thread: cola maxima por worker.worker_timeout_seconds: timeout de ejecucion.thread_host,thread_base_port: metadatos de trazabilidad.
Cuando una vista usa pool, la respuesta incluye cabeceras de trazabilidad y una
cookie de afinidad por ruta, firmada con HMAC y limitada por
affinity_ttl_seconds. Configura un thread_cookie_secret privado y estable en
produccion. Si una solicitud vence mientras aun esta en cola se retira antes de
que el handler comience; un handler que ya esta ejecutandose no puede
interrumpirse de forma forzada.
Startup hooks¶
add_startup() permite preparar recursos antes de aceptar trafico:
def prepare():
print("ready")
app.add_startup(prepare)
Los hooks se ejecutan al inicio de HTTPServer.serve_forever(). Si un hook falla,
el error se imprime y el servidor sigue intentando arrancar.
Integraciones enable_*¶
App expone accesos rapidos para las capas mas comunes:
| Metodo | Que instala |
|---|---|
enable_metrics(...) |
app.metrics y endpoints JSON/NDJSON |
enable_security(policy=None) |
app.security con SecurityPolicy |
enable_caches(caches=None) |
app.caches con cache HTTP de vistas |
enable_logs(path=...) |
app.logs con escritor NDJSON |
enable_docs(...) |
rutas HTML/JSON de documentacion runtime |
La cache clave-valor usa install_cache(app, cache) porque puede haber muchas
instancias o namespaces segun el diseno de la aplicacion.
Documentacion automatica¶
app.enable_docs(
path="/docs",
json_path="/docs.json",
title="runtime docs",
description="Snapshot de la aplicacion en vivo.",
)
Esto publica las rutas HTTP, las rutas WS y el estado de integraciones como metricas, seguridad, cache, logs, tareas y proxy.
HTTPServer¶
HTTPServer es el servidor TCP/HTTP incluido. Se usa normalmente a traves de
app.run(host, port), pero tambien puede instanciarse de forma explicita.
Caracteristicas practicas:
- limite de workers de conexion.
- timeout de lectura de request.
- validacion estricta de linea inicial, cabeceras y cuerpo.
- rechazo de framing ambiguo, cuerpos incompletos y
Transfer-Encodingno soportado. - soporte de
Expect: 100-continuepara cuerpos conContent-Length. - soporte TLS via
ssl_context. - handshake WebSocket integrado.
- el bucle de
accept()sobrevive a errores transitorios del sistema operativo (descriptores agotados, conexiones abortadas) y solo termina cuando se lo pides.
Limites por defecto:
| Campo | Valor |
|---|---|
MAX_CONNECTION_WORKERS |
64 conexiones activas |
MAX_REQUEST_HEADER_BYTES |
64 KiB |
MAX_REQUEST_BODY_BYTES |
2 MiB |
REQUEST_READ_TIMEOUT_SECONDS |
10.0 segundos en total para leer cabeceras y cuerpo |
KEEPALIVE_TIMEOUT_SECONDS |
5.0 segundos entre peticiones |
MAX_KEEPALIVE_REQUESTS |
100 peticiones por conexion |
MAX_CONCURRENT_STREAMS |
100 streams HTTP/2 |
ACCEPT_TIMEOUT_SECONDS |
0.5 segundos |
GRACEFUL_SHUTDOWN_TIMEOUT_SECONDS |
10.0 segundos de espera al apagar |
HANDLE_SIGTERM |
True: SIGTERM detiene el servidor de forma ordenada |
MAX_WS_FRAME_BYTES / MAX_WS_MESSAGE_BYTES |
None: usa los 2 MiB de wsbuilder.ws |
REQUEST_READ_TIMEOUT_SECONDS es un plazo total: cuenta desde que llegan los
primeros bytes de la peticion hasta que se ha leido el cuerpo completo, de modo
que un cliente que envia los bytes muy despacio recibe 408 al agotarlo
aunque cada lectura individual sea rapida. KEEPALIVE_TIMEOUT_SECONDS solo
limita la espera entre peticiones de una conexion reutilizada.
Con app.enable_security(), el servidor HTTP/1 evalua la lista negra, la ACL y
el rate limit con las cabeceras, antes de responder 100 Continue y antes de
leer el cuerpo. Una peticion denegada recibe la respuesta de seguridad y la
conexion se cierra; App.dispatch() no vuelve a evaluar la misma peticion.
Se cambian con argumentos al crear el servidor, en app.run() o desde la CLI.
Un valor invalido (cero workers, timeout 0, tamano negativo) lanza
ValueError; una clave desconocida, TypeError.
from wsbuilder import HTTPServer
server = HTTPServer(
"127.0.0.1",
8765,
app,
max_connection_workers=128,
max_request_body_bytes=4 * 1024 * 1024,
keepalive_timeout=2.0,
)
server.serve_forever()
# equivalente
app.run("127.0.0.1", 8765, max_request_body_bytes=4 * 1024 * 1024)
| Argumento | Atributo | CLI |
|---|---|---|
max_connection_workers |
MAX_CONNECTION_WORKERS |
--max-workers |
max_request_header_bytes |
MAX_REQUEST_HEADER_BYTES |
--max-header-bytes |
max_request_body_bytes |
MAX_REQUEST_BODY_BYTES |
--max-body-bytes |
request_read_timeout |
REQUEST_READ_TIMEOUT_SECONDS |
--request-timeout |
keepalive_timeout |
KEEPALIVE_TIMEOUT_SECONDS |
--keepalive-timeout |
max_keepalive_requests |
MAX_KEEPALIVE_REQUESTS |
--max-keepalive-requests |
max_concurrent_streams |
MAX_CONCURRENT_STREAMS |
|
graceful_shutdown_timeout |
GRACEFUL_SHUTDOWN_TIMEOUT_SECONDS |
--shutdown-timeout |
max_ws_frame_bytes |
MAX_WS_FRAME_BYTES |
|
max_ws_message_bytes |
MAX_WS_MESSAGE_BYTES |
--max-ws-message-bytes |
python -m wsbuilder --max-workers 128 --max-body-bytes 4194304 --shutdown-timeout 5
Asignar los atributos (server.MAX_REQUEST_BODY_BYTES = ...) sigue funcionando.
Apagado ordenado¶
server.stop(), Ctrl+C y SIGTERM (el que envian Docker, systemd o
Kubernetes) siguen el mismo camino:
- se deja de aceptar conexiones nuevas;
- las peticiones en curso terminan y se responden con
Connection: close; - el servidor espera a esas conexiones hasta
GRACEFUL_SHUTDOWN_TIMEOUT_SECONDS; - por ultimo se llama a
app.close().
SIGTERM solo se captura cuando serve_forever() corre en el hilo principal;
el manejador anterior se restaura al terminar. server.active_connections()
devuelve cuantas conexiones siguen abiertas.
Ciclo de vida¶
Para levantar el servidor desde otro hilo (tests, embebido en otra app):
| Miembro | Uso |
|---|---|
stop() |
pide al bucle que deje de aceptar y termine |
wait_until_serving(timeout=None) |
espera a que el socket este escuchando |
server_address |
(host, port) real ya enlazado, util con puerto 0 |
import threading
server = HTTPServer("127.0.0.1", 0, app)
thread = threading.Thread(target=server.serve_forever, daemon=True)
thread.start()
server.wait_until_serving(timeout=5.0)
host, port = server.server_address
# ... ejercitar el servidor ...
server.stop()
thread.join(timeout=5.0)
Al salir del bucle se cierra el socket y se llama app.close().
Demo incluida¶
El paquete trae una demo ejecutable:
python -m wsbuilder --host 0.0.0.0 --port 8765
La demo habilita metricas, documentacion runtime, monitor HTML y una ruta
WebSocket de eco. El host predeterminado es 127.0.0.1; usa 0.0.0.0
explicitamente solo cuando quieras exponer la demo a la red.