wsbuilder 1.3.0__tar.gz → 1.4.0__tar.gz

{wsbuilder-1.3.0/src/wsbuilder.egg-info → wsbuilder-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wsbuilder
-Version: 1.3.0
+Version: 1.4.0
 Summary: Lightweight HTTP + WebSocket framework for Python.
 Author: wsbuilder Authors
 License-Expression: MIT
@@ -8,7 +8,7 @@ Project-URL: Homepage, https://github.com/jorgelsc-dev/wsbuilder
 Project-URL: Documentation, https://wsbuilder.jorgelsc.dev/
 Project-URL: Repository, https://github.com/jorgelsc-dev/wsbuilder
 Project-URL: Issues, https://github.com/jorgelsc-dev/wsbuilder/issues
-Keywords: websocket,http,framework,server,python
+Keywords: websocket,http,http3,quic,rpc,cbor,llm,gguf,framework,server,python
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: Operating System :: OS Independent
@@ -24,9 +24,11 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Provides-Extra: tls
-Requires-Dist: cryptography>=42; extra == "tls"
+Requires-Dist: cryptography>=43; extra == "tls"
 Provides-Extra: mdns
 Requires-Dist: zeroconf>=0.131; extra == "mdns"
+Provides-Extra: llm
+Requires-Dist: llama-cpp-python>=0.3; extra == "llm"
 Dynamic: license-file
 
 # wsbuilder
@@ -44,7 +46,11 @@ Sirve para crear:
 - rate limiting, ACL, listas de IP y bloqueo temporal.
 - metricas JSON, stream NDJSON, logs y tareas en background.
 - DNS local, mDNS y descubrimiento de servicios, reverse proxy y balanceo.
+- comunicacion entre microservicios en binario (CBOR) sobre HTTP/3 cifrado,
+  con identidad de servicio por mTLS.
 - prediccion simple y redes neuronales basicas desde Python puro.
+- modelos de lenguaje (LLM): importar, guardar y descargar GGUF/safetensors,
+  ejecutarlos con llama.cpp u Ollama y servirlos con API compatible con OpenAI.
 
 ## Ruta de documentacion
 
@@ -64,6 +70,8 @@ Tambien puedes leer:
 - [Arquitectura](docs/architecture.md)
 - [API publica](docs/api-map.md)
 - [mDNS y DNS-SD](docs/mdns.md) (extra opcional `wsbuilder[mdns]`)
+- [Modelos de lenguaje (LLM)](docs/llm.md) (GGUF, Hugging Face, llama.cpp/Ollama; ejecucion local con `wsbuilder[llm]`)
+- [RPC entre servicios](docs/rpc.md) (CBOR sobre HTTP/3; HTTP/3 usa el extra `wsbuilder[tls]`)
 - [Proyecto integral](docs/full-project.md)
 
 ## Instalacion rapida
@@ -153,7 +161,31 @@ La demo incluye:
 | Seguridad | `security.py` | `SecurityPolicy`, `ACLRule`, `SecurityDecision` |
 | Observabilidad | `metrics.py`, `logs.py`, `tasks.py` | `AppMetrics`, `NDJSONLog`, `TaskManager` |
 | Red y edge | `dns.py`, `mdns.py`, `proxyi.py` | `LocalDNSServer`, `LocalMDNSServer`, `discover_mdns_services`, `ProxyI` |
+| Entre servicios | `rpc.py`, `codec.py`, `http3_client.py` | `App.rpc`, `RpcClient`, `RpcError`, `cbor_dumps`, `Http3Client` |
 | IA y prediccion | `ia.py`, `predicts.py` | `DataSet`, `NeuralNetwork`, `Predictor` |
+| Modelos de lenguaje | `llm.py`, `gguf.py` | `ModelStore`, `LanguageModel`, `GGUFReader`, `GGUFWriter`, `App.enable_llm` |
+
+## Comunicacion entre servicios
+
+Los servicios se llaman entre si con el payload en CBOR (binario, alrededor de
+un 30 % mas pequeno que JSON y sin base64 para `bytes`) sobre una conexion
+HTTP/3 reutilizada y cifrada con TLS 1.3:
+
+```python
+from wsbuilder import App, RpcClient
+
+app = App()
+
+@app.rpc("/users.get")
+def get_user(request, payload):
+    return {"id": payload["id"], "name": "Ada"}
+
+# En otro servicio:
+with RpcClient("https://users.internal:8443", trust=ca) as users:
+    user = users.call("/users.get", {"id": 7})
+```
+
+Detalles, mTLS y limites en [RPC entre servicios](docs/rpc.md).
 
 ## Ejemplo con datos
 

{wsbuilder-1.3.0 → wsbuilder-1.4.0}/README.md

@@ -13,7 +13,11 @@ Sirve para crear:
 - rate limiting, ACL, listas de IP y bloqueo temporal.
 - metricas JSON, stream NDJSON, logs y tareas en background.
 - DNS local, mDNS y descubrimiento de servicios, reverse proxy y balanceo.
+- comunicacion entre microservicios en binario (CBOR) sobre HTTP/3 cifrado,
+  con identidad de servicio por mTLS.
 - prediccion simple y redes neuronales basicas desde Python puro.
+- modelos de lenguaje (LLM): importar, guardar y descargar GGUF/safetensors,
+  ejecutarlos con llama.cpp u Ollama y servirlos con API compatible con OpenAI.
 
 ## Ruta de documentacion
 
@@ -33,6 +37,8 @@ Tambien puedes leer:
 - [Arquitectura](docs/architecture.md)
 - [API publica](docs/api-map.md)
 - [mDNS y DNS-SD](docs/mdns.md) (extra opcional `wsbuilder[mdns]`)
+- [Modelos de lenguaje (LLM)](docs/llm.md) (GGUF, Hugging Face, llama.cpp/Ollama; ejecucion local con `wsbuilder[llm]`)
+- [RPC entre servicios](docs/rpc.md) (CBOR sobre HTTP/3; HTTP/3 usa el extra `wsbuilder[tls]`)
 - [Proyecto integral](docs/full-project.md)
 
 ## Instalacion rapida
@@ -122,7 +128,31 @@ La demo incluye:
 | Seguridad | `security.py` | `SecurityPolicy`, `ACLRule`, `SecurityDecision` |
 | Observabilidad | `metrics.py`, `logs.py`, `tasks.py` | `AppMetrics`, `NDJSONLog`, `TaskManager` |
 | Red y edge | `dns.py`, `mdns.py`, `proxyi.py` | `LocalDNSServer`, `LocalMDNSServer`, `discover_mdns_services`, `ProxyI` |
+| Entre servicios | `rpc.py`, `codec.py`, `http3_client.py` | `App.rpc`, `RpcClient`, `RpcError`, `cbor_dumps`, `Http3Client` |
 | IA y prediccion | `ia.py`, `predicts.py` | `DataSet`, `NeuralNetwork`, `Predictor` |
+| Modelos de lenguaje | `llm.py`, `gguf.py` | `ModelStore`, `LanguageModel`, `GGUFReader`, `GGUFWriter`, `App.enable_llm` |
+
+## Comunicacion entre servicios
+
+Los servicios se llaman entre si con el payload en CBOR (binario, alrededor de
+un 30 % mas pequeno que JSON y sin base64 para `bytes`) sobre una conexion
+HTTP/3 reutilizada y cifrada con TLS 1.3:
+
+```python
+from wsbuilder import App, RpcClient
+
+app = App()
+
+@app.rpc("/users.get")
+def get_user(request, payload):
+    return {"id": payload["id"], "name": "Ada"}
+
+# En otro servicio:
+with RpcClient("https://users.internal:8443", trust=ca) as users:
+    user = users.call("/users.get", {"id": 7})
+```
+
+Detalles, mTLS y limites en [RPC entre servicios](docs/rpc.md).
 
 ## Ejemplo con datos
 

{wsbuilder-1.3.0 → wsbuilder-1.4.0}/docs/api-map.md

@@ -16,7 +16,7 @@ Para ejemplos completos por nivel, lee [Principiantes](beginners.md),
 
 Metodos habituales:
 
-- `App.view`, `App.api`, `App.route`, `App.ws`
+- `App.view`, `App.api`, `App.rpc`, `App.route`, `App.ws`
 - `App.enable_metrics`, `App.enable_security`, `App.enable_caches`,
   `App.enable_logs`, `App.enable_docs`
 - `App.dispatch`, `App.describe`, `App.run`, `App.close`
@@ -68,6 +68,17 @@ Filtros `QuerySet` documentados:
 | Cabeceras | `normalize_header_name`, `get_header`, `has_header`, `set_header`, `add_header` |
 | Cookies | `parse_cookie_header`, `get_cookie`, `build_set_cookie` |
 
+## Comunicacion entre servicios
+
+| Grupo | Exportaciones |
+| --- | --- |
+| RPC | `RpcClient`, `RpcError`, `RpcTransportError`, `RpcCodec`, `rpc_endpoint` |
+| Codec CBOR | `cbor_dumps`, `cbor_loads`, `CBORTag`, `CBORSimple`, `CBORDecodeError`, `CBOREncodeError` |
+| HTTP/3 cliente (extra `tls`) | `Http3Client`, `Http3Response`, `Http3Error` |
+
+Metodo de la app: `App.rpc(path, methods=("POST",), *, codec="cbor")`. Guia
+completa en [RPC entre servicios](rpc.md).
+
 ## DNS y proxy
 
 | Grupo | Exportaciones |
@@ -101,6 +112,19 @@ Filtros `QuerySet` documentados:
 | Redes | `DenseLayer`, `NeuralNetwork`, `submit_training_task` |
 | Analisis | `describe_data`, `evaluate_errors` |
 | Prediccion | `Predictor` |
+| Persistencia de redes | `NeuralNetwork.save`, `NeuralNetwork.load` (GGUF) |
+
+## Modelos de lenguaje
+
+| Grupo | Exportaciones |
+| --- | --- |
+| Almacen | `ModelStore`, `ModelRecord` |
+| Descargas | `download_file`, `huggingface_files`, `huggingface_url`, `DownloadError` |
+| Ejecucion | `LanguageModel`, `LlamaCppBackend` (extra `llm`), `OpenAICompatibleBackend` |
+| HTTP | `install_llm`, `App.enable_llm` |
+| GGUF | `GGUFReader`, `GGUFWriter`, `GGMLType`, `GGUFError`, `read_gguf_metadata` |
+
+Guia completa en [Modelos de lenguaje](llm.md).
 
 ## Modulos directos utiles
 

{wsbuilder-1.3.0 → wsbuilder-1.4.0}/docs/cache.md

@@ -81,6 +81,10 @@ install_metrics(app, app_name="cache-demo")
 ```
 
 Cuando la cache esta activa, `App.dispatch()` puede responder con `X-WSBuilder-Cache: HIT`.
+Las claves de respuestas distinguen el `Host` y el esquema del transporte
+(`http` o `https`); las cabeceras reenviadas no cambian ese esquema.
+`App.close()` cierra las caches instaladas, también cuando usan un `attr_name`
+personalizado, y evita cerrar dos veces un store compartido.
 
 ## Lo que conviene recordar
 

{wsbuilder-1.3.0 → wsbuilder-1.4.0}/docs/http-versions.md

@@ -105,6 +105,10 @@ threading.Thread(target=h3.serve_forever, daemon=True).start()
 Un cliente no descubre HTTP/3 solo: llega por la cabecera `Alt-Svc` que anuncia
 una respuesta HTTP/1 o HTTP/2.
 
+Una peticion HTTP/3 con `Content-Length` debe usar digitos ASCII y coincidir con
+los DATA recibidos al finalizar. Una longitud invalida termina ese stream con
+`H3_MESSAGE_ERROR`, sin ejecutar el handler ni interrumpir las otras peticiones.
+
 ```python
 @app.api("/algo")
 def algo(request):

{wsbuilder-1.3.0 → wsbuilder-1.4.0}/docs/http.md

@@ -35,7 +35,10 @@ Response.stream(iter(["a", "b", "c"]), content_type="text/plain")
 
 `Response.stream` devuelve una respuesta en streaming con soporte para generadores, iterables y objetos con `read()`.
 Al terminar el envio (o si el cliente se desconecta) el servidor llama a
-`close()` sobre el origen del stream cuando existe.
+`close()` sobre el origen del stream cuando existe. Tambien lo cierra sin
+consumirlo para `HEAD` y para los estados sin cuerpo (`1xx`, `204`, `304`).
+Esto se aplica a HTTP/1, HTTP/2 y HTTP/3. Un `Content-Length` explicito en `HEAD`
+o `304` describe la representacion; los estados `1xx` y `204` lo omiten.
 
 `Response.headers` es un diccionario con un valor por nombre. Un valor puede ser
 una lista o tupla para enviar el campo repetido, que es lo que necesita
@@ -127,3 +130,8 @@ def sum_view(request):
 - `parse_http_request` para parseo de requests en bruto.
 - `send_http_response` si necesitas escribir respuestas manualmente.
 - `parse_query_string` para utilidades ligeras de query strings.
+
+`send_http_response` devuelve `True` al completar el envio y `False` si falla
+la escritura o el productor. En HTTP/1, una respuesta incompleta obliga a cerrar
+la conexion antes de procesar otra peticion. Los errores de validacion de
+cabeceras anteriores al envio siguen lanzando `ValueError`.

{wsbuilder-1.3.0 → wsbuilder-1.4.0}/docs/ia.md

@@ -16,6 +16,8 @@ WSBuilder incluye herramientas sencillas de data science y redes neuronales hech
 - `ByteTokenizer`
 - `HashingTextVectorizer`
 - `AudioData`, `load_wav`, `audio_features`
+- `NeuralNetwork.save`, `NeuralNetwork.load` (GGUF)
+- [Modelos de lenguaje](llm.md): `ModelStore`, `LanguageModel`, `GGUFReader`, `GGUFWriter`
 
 ## Texto, tokens y audio
 
@@ -29,6 +31,21 @@ Consulta los [ejemplos de texto y audio](ai-predict.md#texto-unicode-y-tokens).
 Estos adaptadores preparan datos: no incorporan un modelo de conversacion,
 traduccion, reconocimiento de voz, generacion de audio, imagen o video.
 
+## Modelos de lenguaje y archivos GGUF
+
+Para modelos de lenguaje (LLM) existe [`wsbuilder.llm`](llm.md). Permite
+importar, guardar, exportar y descargar modelos GGUF y safetensors (por ejemplo
+desde Hugging Face, con verificacion SHA-256), ejecutarlos con llama.cpp
+(extra `wsbuilder[llm]`) o mediante un servidor compatible con OpenAI como
+Ollama, y servirlos por HTTP.
+
+Las redes propias tambien se guardan y cargan en GGUF:
+
+```python
+network.save("modelo.gguf", name="mi-red")
+network = NeuralNetwork.load("modelo.gguf")
+```
+
 ## Datos
 
 ```python

wsbuilder-1.4.0/docs/llm.md

@@ -0,0 +1,181 @@
+# Modelos de lenguaje (LLM)
+
+`wsbuilder.llm` permite importar, guardar, descargar y ejecutar modelos de
+lenguaje. Tambien puede servirlos por HTTP, con un endpoint compatible con la
+API de OpenAI.
+
+| Pieza | Para que sirve | Dependencias |
+| --- | --- | --- |
+| `GGUFReader` / `GGUFWriter` | Leer y escribir archivos GGUF, el formato de llama.cpp y Ollama | Ninguna |
+| `ModelStore` | Directorio de modelos: importar, descargar, exportar, verificar y borrar | Ninguna |
+| `download_file`, `huggingface_files` | Descargas reanudables y verificadas con SHA-256 | Ninguna |
+| `LanguageModel` + `OpenAICompatibleBackend` | Usar un modelo servido por Ollama, llama.cpp server, vLLM, LM Studio u OpenAI | Ninguna |
+| `LanguageModel` + `LlamaCppBackend` | Ejecutar un GGUF local en este proceso | `pip install 'wsbuilder[llm]'` |
+| `install_llm` / `App.enable_llm` | Exponer los modelos por HTTP | Ninguna |
+
+Para ejecutar un LLM hace falta un motor de inferencia escrito en C/C++, y
+wsbuilder no intenta serlo. Todo lo demas funciona solo con la biblioteca
+estandar.
+
+## Guardar modelos: el almacen
+
+```python
+from wsbuilder import ModelStore
+
+store = ModelStore()          # $WSBUILDER_MODELS o ~/.cache/wsbuilder/models
+record = store.import_file("descargas/qwen2.5-0.5b-instruct-q4_k_m.gguf")
+print(record.id, record.summary["architecture"], record.summary["quantization"])
+
+for model in store.list():
+    print(model.id, model.format, model.size, model.sha256)
+
+store.export(record.id, "/backup/")        # copia el archivo fuera del almacen
+store.verify(record.id)                    # recalcula el SHA-256
+store.rename(record.id, "Qwen 0.5B")
+store.remove(record.id)
+```
+
+- Cada modelo vive en `<raiz>/<id>/` junto a un `manifest.json` con su nombre,
+  formato, tamano, SHA-256, origen y un resumen de sus metadatos. Como no hay
+  un indice compartido, no hay nada comun que se pueda corromper. Las
+  escrituras pasan por archivos temporales y `os.replace`.
+- Se reconocen GGUF y safetensors. Otros formatos se rechazan salvo que se
+  pase `require_known_format=False`. Un archivo malformado nunca entra al
+  almacen.
+- `import_file(..., move=True)` mueve el archivo en vez de copiarlo.
+
+En un GGUF, el resumen incluye `name`, `architecture`, `parameters`,
+`quantization` (por ejemplo `Q4_K_M`), `context_length`, `embedding_length`,
+`block_count`, `attention_heads`, `tokenizer`, `vocabulary_size`,
+`chat_template`, `license` y `file_size`.
+
+## Descargar modelos
+
+Desde Hugging Face:
+
+```python
+from wsbuilder import ModelStore, huggingface_files
+
+files = huggingface_files("Qwen/Qwen2.5-0.5B-Instruct-GGUF", suffix=".gguf")
+# [{"path": "qwen2.5-0.5b-instruct-q4_k_m.gguf", "size": 491400032, "sha256": "..."}, ...]
+
+store = ModelStore()
+record = store.download_huggingface(
+    "Qwen/Qwen2.5-0.5B-Instruct-GGUF",
+    "qwen2.5-0.5b-instruct-q4_k_m.gguf",
+    progress=lambda done, total: print(done, total),
+)
+```
+
+Desde cualquier URL HTTPS:
+
+```python
+record = store.download("https://example.com/modelo.gguf", sha256="...")
+```
+
+- **Verificacion.** `download_huggingface` toma de la API del Hub el SHA-256
+  publicado y lo comprueba. Si no coincide, el archivo se borra y se lanza
+  `DownloadError`.
+- **Reanudacion.** Si la descarga se corta, el siguiente intento continua desde
+  el archivo `.part` con una peticion `Range`. Solo se reanuda cuando hay un
+  SHA-256 con el que verificar el resultado.
+- **Limites.** Solo se aceptan URLs `https://`. `max_bytes` acota el tamano
+  (200 GiB por defecto) y `cancel_event` permite cancelar la descarga.
+- **Repositorios privados.** El token se toma de `token=` o de `HF_TOKEN` y se
+  envia solo al host original: si el Hub redirige a su CDN, la cabecera
+  `Authorization` no viaja. `HF_ENDPOINT` permite usar un mirror.
+
+## Ejecutar modelos
+
+Un GGUF local con llama.cpp (`pip install 'wsbuilder[llm]'`):
+
+```python
+model = store.load(record.id, n_ctx=4096, n_gpu_layers=0)   # se cachea por id
+print(model.chat("Explica que es QUIC en una frase"))
+for piece in model.stream_chat([{"role": "user", "content": "Hola"}], max_tokens=64):
+    print(piece, end="", flush=True)
+```
+
+Un modelo servido por Ollama u otro servidor compatible con OpenAI:
+
+```python
+from wsbuilder import LanguageModel
+
+model = LanguageModel.from_openai("http://localhost:11434/v1", "llama3.2")
+print(model.chat("Hola"))
+```
+
+| Metodo | Devuelve |
+| --- | --- |
+| `generate(prompt, **opciones)` | El texto completado. |
+| `chat(messages, **opciones)` | La respuesta del asistente. `messages` puede ser un texto o una lista de `{"role", "content"}`. |
+| `chat_completion(messages, **opciones)` | `{"text", "finish_reason", "usage"}`. |
+| `stream_generate`, `stream_chat` | Generadores que van entregando el texto. |
+
+Las opciones admitidas son `max_tokens`, `temperature`, `top_p`, `top_k`,
+`stop`, `seed`, `repeat_penalty`, `presence_penalty` y `frequency_penalty`.
+
+## Servir modelos por HTTP
+
+```python
+from wsbuilder import App, LanguageModel, ModelStore
+
+app = App()
+app.enable_security(...)  # protege estas rutas antes de exponerlas
+app.enable_llm(
+    ModelStore(),
+    models={"llama3.2": LanguageModel.from_openai("http://localhost:11434/v1", "llama3.2")},
+    backend_options={"n_ctx": 4096},
+)
+app.run("0.0.0.0", 8765)
+```
+
+| Ruta | Uso |
+| --- | --- |
+| `GET /api/llm/models` | Lista los modelos del almacen y los remotos. |
+| `GET /api/llm/model?id=` | Devuelve el manifiesto de un modelo. |
+| `POST /api/llm/chat` | Recibe `{"model", "messages", "stream"}`. Con `stream`, responde en NDJSON (`{"content": ...}` por linea). |
+| `POST /api/llm/generate` | Recibe `{"model", "prompt", "stream"}`. |
+| `GET /v1/models`, `POST /v1/chat/completions` | API de OpenAI, con streaming SSE incluido. Cualquier cliente de OpenAI puede apuntar a la app. |
+
+Las rutas que modifican el disco del servidor estan desactivadas por defecto:
+
+- `allow_download=True` activa `POST /api/llm/download` (`{"repo", "filename"}`
+  o `{"url", "sha256"}`). La descarga corre como tarea en segundo plano y su
+  progreso se consulta en `GET /api/llm/tasks?id=`. `download_hosts`
+  restringe los hosts permitidos.
+- `allow_import=True` activa `POST /api/llm/import` (`{"path"}`).
+- `allow_delete=True` activa `POST /api/llm/delete` (`{"id"}`).
+
+## Archivos GGUF y redes propias
+
+```python
+from wsbuilder import GGUFReader, GGUFWriter
+
+with GGUFReader("modelo.gguf") as gguf:
+    gguf.metadata["general.architecture"]
+    gguf.summary()
+    gguf.tensor("token_embd.weight").shape
+
+writer = GGUFWriter(architecture="mi-modelo")
+writer.add_metadata("general.name", "demo")
+writer.add_tensor("capa.0.weight", [0.1, 0.2, 0.3, 0.4], shape=(2, 2), ggml_type="F16")
+writer.write("demo.gguf")
+```
+
+- **Lectura sin cargar pesos.** El lector solo lee la cabecera y las tablas,
+  asi que abrir un modelo de varios GB es inmediato. Los arrays largos, como
+  el vocabulario, quedan como `GGUFArray` (tipo y longitud) salvo que se pase
+  `max_array_items=None`.
+- **Decodificacion de tensores.** `tensor.values()` decodifica F32, F16, BF16,
+  F64, I8 a I64, Q8_0 y Q4_0. Las cuantizaciones K e IQ se leen como bytes
+  crudos.
+- **Entrada no confiable.** Cada conteo y cada longitud se comprueban contra el
+  tamano del archivo antes de reservar memoria.
+
+Las redes de `NeuralNetwork` tambien se guardan en GGUF:
+
+```python
+network.save("xor.gguf", name="xor")          # dtype="F64" (exacto), "F32" o "F16"
+same = NeuralNetwork.load("xor.gguf")          # mismas predicciones
+```

{wsbuilder-1.3.0 → wsbuilder-1.4.0}/docs/persistence.md

@@ -76,6 +76,10 @@ with db.transaction():
 
 Si una excepcion rompe el bloque, la transaccion se revierte.
 
+Fuera de un bloque explicito, `execute()` y `executemany()` revierten la
+transaccion si falla su confirmacion automatica, tambien con restricciones
+diferidas. La conexion queda disponible para operaciones posteriores.
+
 ## Replicas de lectura
 
 La familia `db_replicas` agrega lectura optimizada:
@@ -94,6 +98,10 @@ db = Database("app.db", enable_wal=True, enable_replicas=True, replica_count=3)
 rows = db.read_replica_fetchall("SELECT * FROM users")
 ```
 
+`db.close()` es idempotente y cierra tambien las replicas. Las lecturas
+posteriores lanzan `sqlite3.ProgrammingError`; para volver a operar, crea otra
+instancia de la base.
+
 En `QuerySet`, puedes forzar el camino de replica con:
 
 ```python

{wsbuilder-1.3.0 → wsbuilder-1.4.0}/docs/proxy.md

@@ -55,6 +55,8 @@ proxy.vhost("api.test.local", name="api-vhost").location("/api").upstream("http:
   `%5c`, tambien `..;param`), se rechaza con `400` antes de evaluar reglas, para
   que no escape de un prefijo ni del `base_path` del target.
 - Las respuestas con `Content-Length` se leen con buffer bajo esos dos limites.
+  Si el upstream cierra antes de entregar la longitud declarada, se responde
+  `502`.
   Las respuestas `chunked`, delimitadas por el cierre de la conexion o
   `text/event-stream` se retransmiten como `Response.stream` por bloques, sin
   cargarlas en memoria. En ese modo no hay plazo total ni limite de bytes: cada

wsbuilder-1.4.0/docs/rpc.md

@@ -0,0 +1,182 @@
+# Comunicacion entre servicios (RPC)
+
+`wsbuilder.rpc` sirve para que un servicio llame a otro gastando menos red. El
+servicio que llama entrega un objeto Python. Ese objeto se codifica directamente
+a bytes en formato CBOR (RFC 8949), viaja cifrado y el servicio de destino lo
+recibe ya decodificado. En ningun punto del camino se escribe JSON como texto.
+
+```text
+dict (servicio A) -> CBOR -> bytes cifrados por HTTP/3 -> CBOR -> dict (servicio B)
+```
+
+Si un servicio necesita responder JSON a un navegador, lo genera solo en su
+borde. Entre servicios no hace falta.
+
+## Por que ahorra red
+
+- **Cuerpo mas pequeno.** CBOR escribe tipos y longitudes en binario, sin
+  comillas, sin escapes y sin numeros como texto. En registros tipicos el cuerpo
+  ocupa alrededor de un 30 % menos que el JSON compacto equivalente.
+- **Bytes sin base64.** Un `bytes` (audio, imagen, firma) viaja tal cual. En
+  JSON tendria que ir en base64, que ocupa un 33 % mas.
+- **Una conexion reutilizada.** Con HTTP/3 se mantiene abierta una conexion
+  QUIC y cada llamada abre un stream nuevo dentro de ella. Solo la primera
+  llamada paga el handshake y una respuesta lenta no bloquea a las demas.
+- **Cifrado incluido.** QUIC exige TLS 1.3, asi que todo lo que viaja va
+  cifrado. No hace falta una capa de cifrado propia.
+
+!!! note "CPU frente a red"
+    El codec CBOR esta escrito en Python puro para no anadir dependencias. El
+    modulo `json` de la biblioteca estandar esta escrito en C, de modo que
+    codificar y decodificar CBOR consume mas CPU que JSON: unas 3 a 5 veces
+    mas, alrededor de 1 ms por cada 20 KB de cuerpo. El ahorro esta en los
+    bytes que viajan. Si para un servicio pesa mas la CPU, usa `codec="json"`,
+    que mantiene el resto de ventajas (conexion reutilizada, errores
+    estructurados, mTLS).
+
+## Servidor
+
+```python
+from wsbuilder import App, RpcError
+
+app = App()
+
+@app.rpc("/users.get")
+def get_user(request, payload):
+    user = USERS.get(payload["id"])
+    if user is None:
+        raise RpcError("usuario inexistente", code="not_found", status=404,
+                       details={"id": payload["id"]})
+    return {"id": user.id, "name": user.name, "avatar": user.avatar_bytes}
+```
+
+- El handler recibe `request` y el `payload` ya decodificado. Si el cuerpo
+  llega vacio, `payload` es `None`.
+- Lo que el handler devuelve se codifica con el mismo codec de la peticion, o
+  con el que pida la cabecera `Accept`. Si la peticion no indica ninguno, se
+  usa el valor de `codec`, que por defecto es `"cbor"`.
+- Si el handler lanza `RpcError(message, code=..., status=..., details=...)`,
+  el servidor responde ese status con el cuerpo
+  `{"error": {"code", "message", "details"}}`.
+- Cualquier otra excepcion produce un `500` con `code="internal"`, sin revelar
+  detalles internos. La excepcion se registra en los logs de la app.
+- Un `Content-Type` desconocido produce un `415` y un cuerpo que no se puede
+  decodificar produce un `400`.
+- `app.rpc()` admite las mismas opciones de workers que `app.route()`.
+
+La misma app atiende RPC por HTTP/1.1, HTTP/2 y HTTP/3. Para HTTP/3 levanta un
+`Http3Server` (UDP) junto al servidor TCP. Ambos pueden compartir el mismo
+puerto (ver [versiones de HTTP](http-versions.md)):
+
+```python
+import threading
+
+from wsbuilder import CertificateAuthority, CertificateManager
+from wsbuilder.http3_server import Http3Server
+
+ca = CertificateAuthority.create("Servicios internos")
+tls = CertificateManager(ca=ca, common_name="users.internal",
+                         dns_names=["users.internal"])
+h3 = Http3Server("0.0.0.0", 8443, app, tls)
+threading.Thread(target=h3.serve_forever, daemon=True).start()
+app.run("0.0.0.0", 8443, ssl_context=tls.ssl_context())
+```
+
+## Cliente
+
+```python
+from wsbuilder import RpcClient, RpcError, RpcTransportError
+
+with RpcClient("https://users.internal:8443", trust=ca) as users:
+    user = users.call("/users.get", {"id": 7})
+```
+
+| Opcion | Uso |
+| --- | --- |
+| `base_url` | `https://host:puerto` usa HTTP/3; `http://host:puerto` usa HTTP/1.1 sin cifrar, pensado para desarrollo local. |
+| `transport` | Fuerza `"http3"` o `"http1"`. `"http1"` con `https://` usa TLS sobre TCP. |
+| `codec` | `"cbor"` (por defecto) o `"json"`. |
+| `trust` / `ca_pem` | CA que debe firmar el certificado del servidor: un `CertificateAuthority` o un PEM. Si no se indica, se usa el almacen del sistema. |
+| `client_material` | Certificado del cliente (`TLSMaterial`) para mTLS. |
+| `server_name` | Nombre que se verifica en el certificado cuando no coincide con el host (por ejemplo, al llamar a una IP). |
+| `timeout` | Segundos por llamada (10 por defecto). |
+| `headers` | Cabeceras que se envian en todas las llamadas. |
+| `max_response_bytes` | Limite del cuerpo de cada respuesta (64 MiB por defecto). |
+
+- `call(path, payload=None, *, headers=None, timeout=None)` devuelve el
+  resultado decodificado.
+- Una respuesta de error lanza `RpcError` en el cliente con el mismo `status`,
+  `code`, `message` y `details` que envio el servidor.
+- Si no llega ninguna respuesta (conexion rechazada, timeout, certificado no
+  valido, respuesta rota), se lanza `RpcTransportError`.
+- El cliente es seguro entre hilos: todas las llamadas comparten la conexion
+  HTTP/3. Con HTTP/1.1 cada hilo usa su propia conexion keep-alive.
+- `describe()` informa del transporte, el codec, el numero de llamadas y los
+  bytes enviados y recibidos.
+
+HTTP/3 necesita el extra `tls` (`pip install 'wsbuilder[tls]'`). Sin ese extra,
+`RpcClient` funciona con `http://` y `transport="http1"`.
+
+## Identidad de cada servicio (mTLS)
+
+Con TLS mutuo cada servicio demuestra quien es con un certificado de la CA
+interna, y el servidor rechaza durante el handshake a quien no lo presente.
+
+```python
+# Servidor: exige certificados firmados por la CA interna.
+tls = CertificateManager(ca=ca, common_name="users.internal",
+                         dns_names=["users.internal"],
+                         client_ca_pem=ca.certificate_pem,
+                         require_client_cert=True)
+
+@app.rpc("/users.get")
+def get_user(request, payload):
+    caller = request.tls["peer_cert"]   # verificado durante el handshake
+    ...
+
+# Cliente: presenta su propio certificado.
+orders_cert = ca.issue("orders-service", client_auth=True, server_auth=False)
+users = RpcClient("https://users.internal:8443", trust=ca,
+                  client_material=orders_cert)
+```
+
+La misma configuracion `client_ca_pem` / `require_client_cert` se aplica a
+HTTP/1.1, HTTP/2 y HTTP/3. Por HTTP/3, `request.tls["peer_cert"]` es un
+diccionario con `common_name`, `dns_names`, `ip_addresses`, `uris`, `subject`,
+`issuer`, `serial_number`, `not_valid_after` y `fingerprint_sha256`. Por
+TCP conserva el formato de `ssl.getpeercert()`.
+
+La verificacion de cadenas usa el verificador WebPKI de `cryptography`. Para
+certificados de cliente sobre HTTP/3 hace falta `cryptography>=43`.
+
+## Codec CBOR directo
+
+El codec tambien se puede usar fuera de RPC:
+
+```python
+from wsbuilder import cbor_dumps, cbor_loads
+
+data = cbor_dumps({"id": 7, "blob": b"\x00\x01", "tags": ["a", "b"]})
+assert cbor_loads(data) == {"id": 7, "blob": b"\x00\x01", "tags": ["a", "b"]}
+```
+
+- Tipos soportados: `None`, `bool`, `int` (de cualquier tamano), `float`,
+  `str`, `bytes`, `list`/`tuple` y `dict`. `CBORTag` y `CBORSimple` cubren
+  etiquetas y valores simples.
+- Cada valor se escribe en su forma mas corta. Por ejemplo, un `float` usa 16,
+  32 o 64 bits segun haga falta para conservarlo exacto.
+- La entrada se trata como no confiable. Se comprueban las longitudes antes de
+  reservar memoria, la profundidad esta limitada (`max_depth`, 256 por
+  defecto) y se rechazan los bytes sobrantes.
+
+## Limites actuales
+
+- No hay 0-RTT ni reanudacion de sesion: cada conexion QUIC nueva hace un
+  handshake completo de 1-RTT. Como la conexion se reutiliza, esto solo afecta
+  a la primera llamada y a cada rotacion.
+- El servidor HTTP/3 de wsbuilder concede 100 streams por conexion. Al
+  agotarlos, el cliente abre otra conexion de forma transparente.
+- En una red local sin perdidas, el transporte HTTP/1.1 con keep-alive puede
+  tener menos latencia por llamada que HTTP/3, porque su TLS esta escrito en C.
+  HTTP/3 compensa cuando hay muchas llamadas concurrentes, perdida de paquetes
+  o conexiones nuevas frecuentes.