Saltar a contenido

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, bytes o None, se convierte en Response.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, que App.dispatch() rellena automaticamente.
  • helpers text() y json().

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 api incluyen Access-Control-Allow-Origin.
  • el OPTIONS automatico anade Access-Control-Allow-Methods, Access-Control-Allow-Headers y Access-Control-Allow-Origin. Sin CORS no se envian cabeceras Access-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_threads y max_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-Encoding no soportado.
  • soporte de Expect: 100-continue para cuerpos con Content-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:

  1. se deja de aceptar conexiones nuevas;
  2. las peticiones en curso terminan y se responden con Connection: close;
  3. el servidor espera a esas conexiones hasta GRACEFUL_SHUTDOWN_TIMEOUT_SECONDS;
  4. 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.