wsbuilder 1.0.2__tar.gz → 1.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. {wsbuilder-1.0.2/src/wsbuilder.egg-info → wsbuilder-1.1.0}/PKG-INFO +1 -1
  2. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/app-http.md +16 -0
  3. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/observability.md +24 -0
  4. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/pyproject.toml +1 -1
  5. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/__init__.py +1 -1
  6. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/app.py +13 -3
  7. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/cache.py +2 -2
  8. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/caches.py +2 -2
  9. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/db_replicas.py +3 -1
  10. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/http.py +4 -3
  11. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/http2.py +2 -1
  12. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/http3_server.py +11 -10
  13. wsbuilder-1.1.0/src/wsbuilder/logs.py +208 -0
  14. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/metrics.py +2 -2
  15. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/orm.py +3 -1
  16. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/proxyi.py +2 -2
  17. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/security.py +4 -4
  18. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/server.py +76 -19
  19. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/ws.py +3 -2
  20. {wsbuilder-1.0.2 → wsbuilder-1.1.0/src/wsbuilder.egg-info}/PKG-INFO +1 -1
  21. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_http.py +17 -0
  22. wsbuilder-1.1.0/tests/test_logs.py +226 -0
  23. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_security.py +18 -0
  24. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_server.py +92 -0
  25. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_ws.py +7 -0
  26. wsbuilder-1.0.2/src/wsbuilder/logs.py +0 -67
  27. wsbuilder-1.0.2/tests/test_logs.py +0 -101
  28. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/LICENSE +0 -0
  29. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/MANIFEST.in +0 -0
  30. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/README.md +0 -0
  31. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/404.html +0 -0
  32. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/CNAME +0 -0
  33. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/advanced.md +0 -0
  34. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/ai-predict.md +0 -0
  35. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/api-map.md +0 -0
  36. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/architecture.md +0 -0
  37. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/assets/wsbuilder-mark.svg +0 -0
  38. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/beginners.md +0 -0
  39. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/cache-security.md +0 -0
  40. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/cache.md +0 -0
  41. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/capabilities.md +0 -0
  42. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/data-orm.md +0 -0
  43. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/dns.md +0 -0
  44. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/full-project.md +0 -0
  45. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/getting-started.md +0 -0
  46. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/help/index.md +0 -0
  47. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/http-versions.md +0 -0
  48. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/http.md +0 -0
  49. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/ia.md +0 -0
  50. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/index.md +0 -0
  51. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/install.md +0 -0
  52. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/intermediate.md +0 -0
  53. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/mdns.md +0 -0
  54. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/network-edge.md +0 -0
  55. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/observability-tasks.md +0 -0
  56. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/persistence.md +0 -0
  57. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/proxy.md +0 -0
  58. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/reference/index.md +0 -0
  59. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/security.md +0 -0
  60. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/stylesheets/extra.css +0 -0
  61. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/tasks.md +0 -0
  62. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/tls-certificates.md +0 -0
  63. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/docs/websocket.md +0 -0
  64. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/examples/full-project/.gitignore +0 -0
  65. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/examples/full-project/README.md +0 -0
  66. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/examples/full-project/app.py +0 -0
  67. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/examples/full-project/pyproject.toml +0 -0
  68. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/examples/full-project/upstream.py +0 -0
  69. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/mkdocs.yml +0 -0
  70. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/setup.cfg +0 -0
  71. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/__main__.py +0 -0
  72. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/constants.py +0 -0
  73. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/cookies.py +0 -0
  74. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/dns.py +0 -0
  75. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/framework.py +0 -0
  76. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/headers.py +0 -0
  77. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/hpack.py +0 -0
  78. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/http1.py +0 -0
  79. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/http3.py +0 -0
  80. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/http3_websocket.py +0 -0
  81. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/ia.py +0 -0
  82. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/mdns.py +0 -0
  83. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/pki.py +0 -0
  84. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/predicts.py +0 -0
  85. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/qpack.py +0 -0
  86. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/quic/__init__.py +0 -0
  87. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/quic/address.py +0 -0
  88. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/quic/connection.py +0 -0
  89. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/quic/crypto.py +0 -0
  90. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/quic/frames.py +0 -0
  91. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/quic/packet.py +0 -0
  92. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/quic/recovery.py +0 -0
  93. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/quic/tls.py +0 -0
  94. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/quic/varint.py +0 -0
  95. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/tasks.py +0 -0
  96. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder/ws_demo.py +0 -0
  97. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder.egg-info/SOURCES.txt +0 -0
  98. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder.egg-info/dependency_links.txt +0 -0
  99. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder.egg-info/entry_points.txt +0 -0
  100. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder.egg-info/requires.txt +0 -0
  101. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/src/wsbuilder.egg-info/top_level.txt +0 -0
  102. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_app_threads.py +0 -0
  103. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_cache.py +0 -0
  104. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_caches.py +0 -0
  105. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_contributing_policy.py +0 -0
  106. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_demo_monitor.py +0 -0
  107. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_dns.py +0 -0
  108. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_docs.py +0 -0
  109. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_documentation_files.py +0 -0
  110. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_headers_cookies.py +0 -0
  111. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_hpack.py +0 -0
  112. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_http1.py +0 -0
  113. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_http2.py +0 -0
  114. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_http3.py +0 -0
  115. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_http3_server.py +0 -0
  116. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_http3_streaming.py +0 -0
  117. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_http3_streaming_udp.py +0 -0
  118. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_ia.py +0 -0
  119. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_mdns.py +0 -0
  120. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_metrics.py +0 -0
  121. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_orm.py +0 -0
  122. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_orm_replicas.py +0 -0
  123. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_pki.py +0 -0
  124. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_pr_identity_policy.py +0 -0
  125. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_predicts.py +0 -0
  126. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_proxyi.py +0 -0
  127. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_quic_address.py +0 -0
  128. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_quic_crypto.py +0 -0
  129. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_quic_protocol.py +0 -0
  130. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_quic_recovery.py +0 -0
  131. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_quic_tls.py +0 -0
  132. {wsbuilder-1.0.2 → wsbuilder-1.1.0}/tests/test_tasks.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: wsbuilder
3
- Version: 1.0.2
3
+ Version: 1.1.0
4
4
  Summary: Lightweight HTTP + WebSocket framework for Python.
5
5
  Author: wsbuilder Authors
6
6
  License-Expression: MIT
@@ -251,6 +251,8 @@ Limites por defecto:
251
251
  | `MAX_REQUEST_BODY_BYTES` | `2 MiB` |
252
252
  | `REQUEST_READ_TIMEOUT_SECONDS` | `10.0` segundos |
253
253
  | `ACCEPT_TIMEOUT_SECONDS` | `0.5` segundos |
254
+ | `GRACEFUL_SHUTDOWN_TIMEOUT_SECONDS` | `10.0` segundos de espera al apagar |
255
+ | `HANDLE_SIGTERM` | `True`: `SIGTERM` detiene el servidor de forma ordenada |
254
256
 
255
257
  Para cambiarlos, instancia `HTTPServer` manualmente y ajusta atributos antes de
256
258
  llamar `serve_forever()`.
@@ -263,6 +265,20 @@ server.MAX_REQUEST_BODY_BYTES = 4 * 1024 * 1024
263
265
  server.serve_forever()
264
266
  ```
265
267
 
268
+ ### Apagado ordenado
269
+
270
+ `server.stop()`, `Ctrl+C` y `SIGTERM` (el que envian Docker, systemd o
271
+ Kubernetes) siguen el mismo camino:
272
+
273
+ 1. se deja de aceptar conexiones nuevas;
274
+ 2. las peticiones en curso terminan y se responden con `Connection: close`;
275
+ 3. el servidor espera a esas conexiones hasta `GRACEFUL_SHUTDOWN_TIMEOUT_SECONDS`;
276
+ 4. por ultimo se llama a `app.close()`.
277
+
278
+ `SIGTERM` solo se captura cuando `serve_forever()` corre en el hilo principal;
279
+ el manejador anterior se restaura al terminar. `server.active_connections()`
280
+ devuelve cuantas conexiones siguen abiertas.
281
+
266
282
  ### Ciclo de vida
267
283
 
268
284
  Para levantar el servidor desde otro hilo (tests, embebido en otra app):
@@ -65,6 +65,30 @@ logger.event("server_start", host="0.0.0.0", port=8765)
65
65
 
66
66
  `NDJSONLog` escribe un evento por linea y funciona bien para ingest para herramientas externas.
67
67
 
68
+ ### Mensajes del framework
69
+
70
+ Los avisos y errores del propio framework (handlers que fallan, errores TLS,
71
+ arranque y apagado del servidor) pasan por `wsbuilder.logs`:
72
+
73
+ - sin `enable_logs()`, salen por **stderr** como `[evento] mensaje`; los errores
74
+ incluyen el traceback completo;
75
+ - con `enable_logs()`, cada mensaje se guarda en el NDJSON con `ts`, `level`,
76
+ `event`, `message` y, si hubo excepcion, `error.type`, `error.message` y
77
+ `error.traceback`. Los de nivel `warning` o superior tambien se muestran por
78
+ stderr.
79
+
80
+ ```python
81
+ logger = app.enable_logs(path="logs/wsbuilder.ndjson", console_level="error")
82
+ logger.info("deploy", "version publicada", version="1.0.3")
83
+ logger.exception("pagos", "fallo el cobro", exc)
84
+
85
+ from wsbuilder.logs import console
86
+ console.level = "warning" # sin enable_logs: oculta los mensajes info
87
+ ```
88
+
89
+ Niveles: `debug`, `info`, `warning`, `error`. `console_level=None` deja los
90
+ mensajes solo en el archivo.
91
+
68
92
  ## Docs nativas
69
93
 
70
94
  `App.enable_docs()` publica una vista HTML y un endpoint JSON con `App.describe()`.
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "wsbuilder"
7
- version = "1.0.2"
7
+ version = "1.1.0"
8
8
  description = "Lightweight HTTP + WebSocket framework for Python."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.11"
@@ -126,7 +126,7 @@ def __getattr__(name):
126
126
  def __dir__():
127
127
  return sorted(set(globals()) | _PKI_EXPORTS)
128
128
 
129
- __version__ = "1.0.2"
129
+ __version__ = "1.1.0"
130
130
 
131
131
  __all__ = [
132
132
  "App",
@@ -9,6 +9,7 @@ from html import escape as html_escape
9
9
  from .constants import DEFAULT_CORS_ALLOW_ORIGIN
10
10
  from .cookies import build_set_cookie, get_cookie
11
11
  from .http import Response
12
+ from .logs import get_log
12
13
  from .tasks import TaskManager
13
14
  from .ws import _normalize_protocols
14
15
 
@@ -455,7 +456,7 @@ class App:
455
456
  thread_id = parts[0]
456
457
  try:
457
458
  normalized = str(uuid.UUID(thread_id))
458
- except Exception:
459
+ except ValueError:
459
460
  return ""
460
461
 
461
462
  issued_text, sig = parts[1], parts[2]
@@ -711,7 +712,13 @@ class App:
711
712
  **kwargs,
712
713
  )
713
714
 
714
- def enable_logs(self, path="logs/wsbuilder.ndjson", attr_name="logs", ensure_parent=True):
715
+ def enable_logs(
716
+ self,
717
+ path="logs/wsbuilder.ndjson",
718
+ attr_name="logs",
719
+ ensure_parent=True,
720
+ console_level="warning",
721
+ ):
715
722
  from .logs import install_logs
716
723
 
717
724
  return install_logs(
@@ -719,6 +726,7 @@ class App:
719
726
  path=path,
720
727
  attr_name=attr_name,
721
728
  ensure_parent=ensure_parent,
729
+ console_level=console_level,
722
730
  )
723
731
 
724
732
  def describe(self):
@@ -1302,7 +1310,9 @@ class App:
1302
1310
  except _RouteExecutionError as e:
1303
1311
  return Response.text(e.message, status=e.status)
1304
1312
  except Exception as e:
1305
- print(f"[http] handler error {request.method} {request.path}: {e}")
1313
+ get_log(self).exception(
1314
+ "http", f"handler error {request.method} {request.path}: {e}", e
1315
+ )
1306
1316
  if route.kind == "api":
1307
1317
  headers = {}
1308
1318
  if cors_allow_origin:
@@ -16,14 +16,14 @@ DEFAULT_CLEANUP_INTERVAL_SECONDS = 30.0
16
16
  def _safe_float(value, default):
17
17
  try:
18
18
  return float(value)
19
- except Exception:
19
+ except (TypeError, ValueError, OverflowError):
20
20
  return default
21
21
 
22
22
 
23
23
  def _safe_int(value, default):
24
24
  try:
25
25
  return int(value)
26
- except Exception:
26
+ except (TypeError, ValueError, OverflowError):
27
27
  return default
28
28
 
29
29
 
@@ -39,14 +39,14 @@ _DROP_HEADERS = {
39
39
  def _safe_float(value, default):
40
40
  try:
41
41
  return float(value)
42
- except Exception:
42
+ except (TypeError, ValueError, OverflowError):
43
43
  return default
44
44
 
45
45
 
46
46
  def _safe_int(value, default):
47
47
  try:
48
48
  return int(value)
49
- except Exception:
49
+ except (TypeError, ValueError, OverflowError):
50
50
  return default
51
51
 
52
52
 
@@ -6,6 +6,8 @@ import sqlite3
6
6
  import threading
7
7
  from dataclasses import dataclass
8
8
 
9
+ from .logs import get_log
10
+
9
11
 
10
12
  @dataclass
11
13
  class SQLite3OptimizationConfig:
@@ -267,7 +269,7 @@ class OptimizedDatabase:
267
269
 
268
270
  def _log(self, *parts):
269
271
  if self.debug:
270
- print("[DB]", *parts)
272
+ get_log().info("db", " ".join(str(part) for part in parts))
271
273
 
272
274
  def _get_tx_depth(self) -> int:
273
275
  return getattr(self._tx_depth, "value", 0)
@@ -4,6 +4,7 @@ from urllib.parse import parse_qsl
4
4
 
5
5
  from .constants import STATUS_MESSAGES
6
6
  from .headers import validate_header_name, validate_header_value
7
+ from .logs import get_log
7
8
 
8
9
  MAX_QUERY_FIELDS = 1024
9
10
  HTTP_0_9 = "HTTP/0.9"
@@ -59,7 +60,7 @@ class Request:
59
60
  def json(self):
60
61
  try:
61
62
  return json.loads(self.text())
62
- except Exception:
63
+ except (ValueError, RecursionError):
63
64
  return None
64
65
 
65
66
 
@@ -231,7 +232,7 @@ def send_http_response(conn, response, *, send_body=True, keep_alive=False, vers
231
232
  else:
232
233
  conn.sendall(response.body)
233
234
  except Exception as e:
234
- print(f"[http] send error {status_code}: {e}")
235
+ get_log().warning("http", f"send error {status_code}: {e}")
235
236
  return
236
237
  reason = validate_header_value(
237
238
  response.reason or STATUS_MESSAGES.get(status_code, "Unknown")
@@ -290,7 +291,7 @@ def send_http_response(conn, response, *, send_body=True, keep_alive=False, vers
290
291
  else:
291
292
  conn.sendall(response.body)
292
293
  except Exception as e:
293
- print(f"[http] send error {status_code}: {e}")
294
+ get_log().warning("http", f"send error {status_code}: {e}")
294
295
 
295
296
 
296
297
  def _iter_stream_chunks(source):
@@ -14,6 +14,7 @@ it would desynchronise the decoder for every later stream.
14
14
  import struct
15
15
 
16
16
  from .hpack import Decoder, Encoder, HPACKError
17
+ from .logs import get_log
17
18
 
18
19
  #: RFC 9113 section 3.4. A client opens with this exact octet sequence.
19
20
  CONNECTION_PREFACE = b"PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n"
@@ -632,7 +633,7 @@ class Http2Connection:
632
633
  try:
633
634
  response = self.app.dispatch(request)
634
635
  except Exception as exc: # noqa: BLE001 - reported on the stream
635
- print(f"[http2] handler error on stream {stream.id}: {exc}")
636
+ get_log(self.app).exception("http2", f"handler error on stream {stream.id}: {exc}", exc)
636
637
  raise StreamError("handler failed", stream.id, ERROR_INTERNAL_ERROR) from exc
637
638
  self.send_response(stream, response, send_body=request.method != "HEAD")
638
639
 
@@ -18,6 +18,7 @@ from cryptography.hazmat.primitives import serialization
18
18
 
19
19
  from . import http3
20
20
  from .http3_websocket import Http3WebSocketStream
21
+ from .logs import get_log
21
22
  from .quic.address import AddressValidator
22
23
  from .quic.connection import QuicConnection
23
24
  from .quic.crypto import retry_integrity_tag
@@ -99,7 +100,7 @@ class Http3Server:
99
100
  self._sock = sock
100
101
  self.server_address = sock.getsockname()[:2]
101
102
  host, port = self.server_address
102
- print(f"HTTP/3 listening on udp://{host}:{port}/")
103
+ get_log(self.app).info("http3", f"listening on udp://{host}:{port}/")
103
104
  self._serving.set()
104
105
  try:
105
106
  while not self._stop.is_set():
@@ -114,13 +115,13 @@ class Http3Server:
114
115
  except OSError as e:
115
116
  if self._stop.is_set():
116
117
  break
117
- print(f"[http3] receive error: {e}")
118
+ get_log(self.app).warning("http3", f"receive error: {e}")
118
119
  continue
119
120
  try:
120
121
  for reply in self.handle_datagram(datagram, address):
121
122
  sock.sendto(reply, address)
122
123
  except Exception as e:
123
- print(f"[http3] error from {address}: {e}")
124
+ get_log(self.app).exception("http3", f"error from {address}: {e}", e)
124
125
  self._send_outbound()
125
126
  finally:
126
127
  self._serving.clear()
@@ -263,7 +264,7 @@ class Http3Server:
263
264
  try:
264
265
  ready = stream.feed(data, fin=complete)
265
266
  except http3.H3Error as e:
266
- print(f"[http3] stream {stream_id}: {e}")
267
+ get_log(self.app).warning("http3", f"stream {stream_id}: {e}")
267
268
  if stream.websocket is not None:
268
269
  stream.websocket.push_eof()
269
270
  return []
@@ -276,7 +277,7 @@ class Http3Server:
276
277
  try:
277
278
  extended = http3.is_extended_connect(stream)
278
279
  except http3.H3Error as e:
279
- print(f"[http3] malformed request on stream {stream_id}: {e}")
280
+ get_log(self.app).warning("http3", f"malformed request on stream {stream_id}: {e}")
280
281
  return []
281
282
  if extended:
282
283
  # RFC 9220: a WebSocket request is answered at once and its
@@ -294,7 +295,7 @@ class Http3Server:
294
295
  request = http3.build_request(stream, connection.client_address, tls_meta)
295
296
  response = self.app.dispatch(request)
296
297
  except http3.H3Error as e:
297
- print(f"[http3] malformed request on stream {stream_id}: {e}")
298
+ get_log(self.app).warning("http3", f"malformed request on stream {stream_id}: {e}")
298
299
  return []
299
300
  self._send_response(connection, stream_id, response, send_body=request.method != "HEAD")
300
301
  return []
@@ -321,7 +322,7 @@ class Http3Server:
321
322
  break
322
323
  connection.queue_stream_data(stream_id, http3.encode_frame(http3.FRAME_DATA, chunk))
323
324
  except Exception as e:
324
- print(f"[http3] streaming response on stream {stream_id} failed: {e}")
325
+ get_log(self.app).exception("http3", f"streaming response on stream {stream_id} failed: {e}", e)
325
326
  finally:
326
327
  # Closing the producer lets its own cleanup run (for example a
327
328
  # realtime client deregistering itself) once the peer is gone.
@@ -330,7 +331,7 @@ class Http3Server:
330
331
  if callable(close):
331
332
  close()
332
333
  except Exception as e:
333
- print(f"[http3] streaming cleanup on stream {stream_id} failed: {e}")
334
+ get_log(self.app).exception("http3", f"streaming cleanup on stream {stream_id} failed: {e}", e)
334
335
  finally:
335
336
  connection.queue_stream_data(stream_id, b"", fin=True)
336
337
 
@@ -342,7 +343,7 @@ class Http3Server:
342
343
  try:
343
344
  request = http3.build_request(stream, connection.client_address, tls_meta)
344
345
  except http3.H3Error as e:
345
- print(f"[http3] malformed WebSocket request on stream {stream.id}: {e}")
346
+ get_log(self.app).warning("http3", f"malformed WebSocket request on stream {stream.id}: {e}")
346
347
  connection.queue_stream_data(stream.id, self._refusal(400, "Bad Request"), fin=True)
347
348
  return
348
349
 
@@ -436,7 +437,7 @@ class Http3Server:
436
437
  try:
437
438
  route["handler"](ws, request)
438
439
  except Exception as e:
439
- print(f"[ws] error over HTTP/3: {e}")
440
+ get_log().exception("ws", f"handler error over HTTP/3: {e}", e)
440
441
  finally:
441
442
  transport.close()
442
443
 
@@ -0,0 +1,208 @@
1
+ """Framework logging: NDJSON files plus a console fallback.
2
+
3
+ Every framework message goes through ``get_log(app)``: the app's ``logs``
4
+ writer when ``app.enable_logs()`` was called, otherwise the stderr console.
5
+ """
6
+
7
+ import json
8
+ import sys
9
+ import threading
10
+ import time
11
+ import traceback
12
+ from collections.abc import Mapping
13
+ from pathlib import Path
14
+
15
+ DEFAULT_LOG_PATH = "logs/wsbuilder.ndjson"
16
+ _APPEND_LOCK = threading.RLock()
17
+ _CONSOLE_LOCK = threading.Lock()
18
+
19
+ LEVELS = {"debug": 10, "info": 20, "warning": 30, "error": 40}
20
+
21
+
22
+ def _level_number(level):
23
+ if level is None:
24
+ return None
25
+ name = str(level).lower()
26
+ if name not in LEVELS:
27
+ raise ValueError(f"unknown log level {level!r}; expected one of {sorted(LEVELS)}")
28
+ return LEVELS[name]
29
+
30
+
31
+ def _error_fields(exc):
32
+ return {
33
+ "type": type(exc).__name__,
34
+ "message": str(exc),
35
+ "traceback": "".join(traceback.format_exception(exc)),
36
+ }
37
+
38
+
39
+ def build_record(level, event, message="", *, exc=None, **fields):
40
+ """The dict both writers log: level, event, message, extra fields, error."""
41
+ _level_number(level)
42
+ record = {
43
+ "ts": time.time(),
44
+ "level": str(level).lower(),
45
+ "event": str(event),
46
+ "message": str(message),
47
+ }
48
+ record.update(fields)
49
+ if exc is not None:
50
+ record["error"] = _error_fields(exc)
51
+ return record
52
+
53
+
54
+ def _normalize_record(record):
55
+ if isinstance(record, Mapping):
56
+ return dict(record)
57
+ raise TypeError("NDJSON log records must be mappings")
58
+
59
+
60
+ def append_ndjson(path, record, *, ensure_parent=True):
61
+ target = Path(path)
62
+ payload = _normalize_record(record)
63
+ line = json.dumps(payload, ensure_ascii=False, separators=(",", ":")) + "\n"
64
+ with _APPEND_LOCK:
65
+ if ensure_parent:
66
+ target.parent.mkdir(parents=True, exist_ok=True)
67
+ with target.open("a", encoding="utf-8", newline="\n") as fh:
68
+ fh.write(line)
69
+ return payload
70
+
71
+
72
+ class _LevelMethods:
73
+ def debug(self, event, message="", **fields):
74
+ return self.log("debug", event, message, **fields)
75
+
76
+ def info(self, event, message="", **fields):
77
+ return self.log("info", event, message, **fields)
78
+
79
+ def warning(self, event, message="", **fields):
80
+ return self.log("warning", event, message, **fields)
81
+
82
+ def error(self, event, message="", **fields):
83
+ return self.log("error", event, message, **fields)
84
+
85
+ def exception(self, event, message, exc, **fields):
86
+ """Log ``exc`` at error level, traceback included."""
87
+ return self.log("error", event, message, exc=exc, **fields)
88
+
89
+
90
+ class ConsoleLog(_LevelMethods):
91
+ """Human-readable lines on stderr, for apps without ``enable_logs()``.
92
+
93
+ Error records carry their traceback; lower levels print one line.
94
+ """
95
+
96
+ def __init__(self, level="info", stream=None):
97
+ self.level = level
98
+ self.stream = stream
99
+
100
+ @property
101
+ def level(self):
102
+ return self._level
103
+
104
+ @level.setter
105
+ def level(self, value):
106
+ _level_number(value)
107
+ self._level = value
108
+
109
+ def enabled_for(self, level):
110
+ threshold = _level_number(self._level)
111
+ return threshold is not None and _level_number(level) >= threshold
112
+
113
+ def write(self, record):
114
+ if not self.enabled_for(record["level"]):
115
+ return
116
+ line = f"[{record['event']}] {record['message']}\n"
117
+ error = record.get("error")
118
+ if error and record["level"] == "error":
119
+ line += error["traceback"]
120
+ # Resolved per call so redirected or replaced stderr is honoured.
121
+ stream = self.stream if self.stream is not None else sys.stderr
122
+ with _CONSOLE_LOCK:
123
+ stream.write(line)
124
+ stream.flush()
125
+
126
+ def log(self, level, event, message="", *, exc=None, **fields):
127
+ record = build_record(level, event, message, exc=exc, **fields)
128
+ self.write(record)
129
+ return record
130
+
131
+
132
+ #: Shared console used when an app has no ``logs`` writer of its own.
133
+ console = ConsoleLog()
134
+
135
+
136
+ class NDJSONLog(_LevelMethods):
137
+ """Append records to an NDJSON file.
138
+
139
+ Records at ``console_level`` or above are echoed to ``console`` too, so
140
+ errors stay visible while they are stored; ``None`` keeps them file-only.
141
+ """
142
+
143
+ def __init__(self, path=DEFAULT_LOG_PATH, *, ensure_parent=True, console_level="warning"):
144
+ self.path = Path(path)
145
+ self.ensure_parent = bool(ensure_parent)
146
+ _level_number(console_level)
147
+ self.console_level = console_level
148
+
149
+ def log(self, level, event, message="", *, exc=None, **fields):
150
+ record = build_record(level, event, message, exc=exc, **fields)
151
+ self.append(record)
152
+ threshold = _level_number(self.console_level)
153
+ if threshold is not None and LEVELS[record["level"]] >= threshold:
154
+ console.write(record)
155
+ return record
156
+
157
+ def append(self, record):
158
+ return append_ndjson(self.path, record, ensure_parent=self.ensure_parent)
159
+
160
+ def event(self, name, **fields):
161
+ payload = {"event": str(name)}
162
+ payload.update(fields)
163
+ return self.append(payload)
164
+
165
+ def describe(self):
166
+ return {
167
+ "path": str(self.path),
168
+ "ensure_parent": self.ensure_parent,
169
+ "console_level": self.console_level,
170
+ }
171
+
172
+ def close(self):
173
+ return None
174
+
175
+ def __call__(self, record):
176
+ return self.append(record)
177
+
178
+
179
+ def install_logs(
180
+ app, path=DEFAULT_LOG_PATH, attr_name="logs", ensure_parent=True, console_level="warning"
181
+ ):
182
+ logger = NDJSONLog(path=path, ensure_parent=ensure_parent, console_level=console_level)
183
+ setattr(app, str(attr_name or "logs"), logger)
184
+ return logger
185
+
186
+
187
+ def get_log(app=None):
188
+ """The writer framework messages for ``app`` go to.
189
+
190
+ ``app.logs`` when it can take leveled records, else the shared console.
191
+ """
192
+ logs = getattr(app, "logs", None) if app is not None else None
193
+ if logs is not None and callable(getattr(logs, "log", None)):
194
+ return logs
195
+ return console
196
+
197
+
198
+ __all__ = [
199
+ "DEFAULT_LOG_PATH",
200
+ "LEVELS",
201
+ "ConsoleLog",
202
+ "NDJSONLog",
203
+ "append_ndjson",
204
+ "build_record",
205
+ "console",
206
+ "get_log",
207
+ "install_logs",
208
+ ]
@@ -19,14 +19,14 @@ def _iso_utc(ts):
19
19
  def _safe_int(value, default):
20
20
  try:
21
21
  return int(value)
22
- except Exception:
22
+ except (TypeError, ValueError, OverflowError):
23
23
  return default
24
24
 
25
25
 
26
26
  def _safe_float(value, default):
27
27
  try:
28
28
  return float(value)
29
- except Exception:
29
+ except (TypeError, ValueError, OverflowError):
30
30
  return default
31
31
 
32
32
 
@@ -8,6 +8,8 @@ import sqlite3
8
8
  import threading
9
9
  from datetime import date, datetime
10
10
 
11
+ from .logs import get_log
12
+
11
13
  _IDENTIFIER_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
12
14
  _WRITE_PREFIXES = {
13
15
  "INSERT",
@@ -364,7 +366,7 @@ class Database:
364
366
 
365
367
  def _log(self, *parts):
366
368
  if self.debug:
367
- print("[ORM]", *parts)
369
+ get_log().info("orm", " ".join(str(part) for part in parts))
368
370
 
369
371
  def set_pragma(self, name: str, value):
370
372
  validate_identifier(name)
@@ -99,14 +99,14 @@ _REDACTED_HEADER_VALUE = "[REDACTED]"
99
99
  def _safe_int(value, default):
100
100
  try:
101
101
  return int(value)
102
- except Exception:
102
+ except (TypeError, ValueError, OverflowError):
103
103
  return default
104
104
 
105
105
 
106
106
  def _safe_float(value, default):
107
107
  try:
108
108
  return float(value)
109
- except Exception:
109
+ except (TypeError, ValueError, OverflowError):
110
110
  return default
111
111
 
112
112
 
@@ -29,14 +29,14 @@ DEFAULT_MAX_TEMPORARY_BLOCKS = 20000
29
29
  def _safe_int(value, default):
30
30
  try:
31
31
  return int(value)
32
- except Exception:
32
+ except (TypeError, ValueError, OverflowError):
33
33
  return default
34
34
 
35
35
 
36
36
  def _safe_float(value, default):
37
37
  try:
38
38
  return float(value)
39
- except Exception:
39
+ except (TypeError, ValueError, OverflowError):
40
40
  return default
41
41
 
42
42
 
@@ -46,7 +46,7 @@ def _to_ip(value):
46
46
  return None
47
47
  try:
48
48
  return ipaddress.ip_address(text)
49
- except Exception:
49
+ except ValueError:
50
50
  return None
51
51
 
52
52
 
@@ -56,7 +56,7 @@ def _to_network(value):
56
56
  return None
57
57
  try:
58
58
  return ipaddress.ip_network(text, strict=False)
59
- except Exception:
59
+ except ValueError:
60
60
  ip_obj = _to_ip(text)
61
61
  if ip_obj is None:
62
62
  return None