sendproof-core 0.1.0a1__py3-none-any.whl

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 (209) hide show
  1. sendproof_core/__init__.py +56 -0
  2. sendproof_core/assets.py +71 -0
  3. sendproof_core/capture.py +416 -0
  4. sendproof_core/effects.py +79 -0
  5. sendproof_core/identity.py +22 -0
  6. sendproof_core/jsonsafe.py +103 -0
  7. sendproof_core/limits.py +24 -0
  8. sendproof_core/marker.py +131 -0
  9. sendproof_core/options.py +129 -0
  10. sendproof_core/protocol.py +132 -0
  11. sendproof_core/provider.py +121 -0
  12. sendproof_core/py.typed +0 -0
  13. sendproof_core/redaction.py +88 -0
  14. sendproof_core/scope.py +146 -0
  15. sendproof_core/stores/__init__.py +119 -0
  16. sendproof_core/stores/base.py +99 -0
  17. sendproof_core/stores/cassandra_hook.py +173 -0
  18. sendproof_core/stores/classify.py +153 -0
  19. sendproof_core/stores/classify_batch_two.py +397 -0
  20. sendproof_core/stores/cosmos_hook.py +214 -0
  21. sendproof_core/stores/dynamodb_hook.py +214 -0
  22. sendproof_core/stores/elasticsearch_hook.py +248 -0
  23. sendproof_core/stores/firestore_hook.py +459 -0
  24. sendproof_core/stores/guard.py +205 -0
  25. sendproof_core/stores/mongo_hook.py +1406 -0
  26. sendproof_core/stores/redis_hook.py +536 -0
  27. sendproof_core/stores/tables.py +1486 -0
  28. sendproof_core/stores/versions.py +46 -0
  29. sendproof_core/sync_engine.py +308 -0
  30. sendproof_core/trace_store.py +92 -0
  31. sendproof_core/txguard.py +237 -0
  32. sendproof_core/ui/action-bar.js +91 -0
  33. sendproof_core/ui/api.js +239 -0
  34. sendproof_core/ui/app.css +848 -0
  35. sendproof_core/ui/app.js +742 -0
  36. sendproof_core/ui/autofill.js +137 -0
  37. sendproof_core/ui/code-copy.js +71 -0
  38. sendproof_core/ui/code-picker.js +149 -0
  39. sendproof_core/ui/commands.js +197 -0
  40. sendproof_core/ui/components.js +77 -0
  41. sendproof_core/ui/context-bar.js +82 -0
  42. sendproof_core/ui/copy.js +92 -0
  43. sendproof_core/ui/coverage-popover.js +35 -0
  44. sendproof_core/ui/crumb-fit.js +80 -0
  45. sendproof_core/ui/deprecation.js +164 -0
  46. sendproof_core/ui/display-settings.js +175 -0
  47. sendproof_core/ui/doc-diff.js +209 -0
  48. sendproof_core/ui/docs-view.js +347 -0
  49. sendproof_core/ui/favicon.png +0 -0
  50. sendproof_core/ui/favicon.svg +1 -0
  51. sendproof_core/ui/field-help.js +52 -0
  52. sendproof_core/ui/field-modules.js +23 -0
  53. sendproof_core/ui/fields/controls.js +179 -0
  54. sendproof_core/ui/fields/dom.js +36 -0
  55. sendproof_core/ui/fields/infer.js +71 -0
  56. sendproof_core/ui/fields/lookup-source.js +63 -0
  57. sendproof_core/ui/fields/lookup.js +285 -0
  58. sendproof_core/ui/fields/render.js +496 -0
  59. sendproof_core/ui/fields/select.js +175 -0
  60. sendproof_core/ui/fields/validate.js +363 -0
  61. sendproof_core/ui/fields/validation-formats.js +164 -0
  62. sendproof_core/ui/fields/validation-references.js +68 -0
  63. sendproof_core/ui/fields/validation-values.js +137 -0
  64. sendproof_core/ui/generate-menu.js +44 -0
  65. sendproof_core/ui/generate.js +184 -0
  66. sendproof_core/ui/header-editor.js +777 -0
  67. sendproof_core/ui/headers.js +188 -0
  68. sendproof_core/ui/highlight.js +257 -0
  69. sendproof_core/ui/history-popover.js +24 -0
  70. sendproof_core/ui/i18n.js +253 -0
  71. sendproof_core/ui/icons.js +87 -0
  72. sendproof_core/ui/index.html +70 -0
  73. sendproof_core/ui/issues.js +187 -0
  74. sendproof_core/ui/json-view.js +166 -0
  75. sendproof_core/ui/lang-icons.js +62 -0
  76. sendproof_core/ui/layout.js +262 -0
  77. sendproof_core/ui/listbox.js +334 -0
  78. sendproof_core/ui/locales/ar-capture.js +366 -0
  79. sendproof_core/ui/locales/ar-stores.js +116 -0
  80. sendproof_core/ui/locales/ar.js +561 -0
  81. sendproof_core/ui/locales/cs-capture.js +442 -0
  82. sendproof_core/ui/locales/cs-stores.js +116 -0
  83. sendproof_core/ui/locales/cs.js +689 -0
  84. sendproof_core/ui/locales/da-capture.js +347 -0
  85. sendproof_core/ui/locales/da-stores.js +116 -0
  86. sendproof_core/ui/locales/da.js +522 -0
  87. sendproof_core/ui/locales/de-capture.js +347 -0
  88. sendproof_core/ui/locales/de-stores.js +116 -0
  89. sendproof_core/ui/locales/de.js +519 -0
  90. sendproof_core/ui/locales/el-capture.js +347 -0
  91. sendproof_core/ui/locales/el-stores.js +116 -0
  92. sendproof_core/ui/locales/el.js +520 -0
  93. sendproof_core/ui/locales/en-capture.js +349 -0
  94. sendproof_core/ui/locales/en-stores.js +95 -0
  95. sendproof_core/ui/locales/en.js +522 -0
  96. sendproof_core/ui/locales/es-capture.js +353 -0
  97. sendproof_core/ui/locales/es-stores.js +116 -0
  98. sendproof_core/ui/locales/es.js +525 -0
  99. sendproof_core/ui/locales/fa-capture.js +348 -0
  100. sendproof_core/ui/locales/fa-stores.js +116 -0
  101. sendproof_core/ui/locales/fa.js +521 -0
  102. sendproof_core/ui/locales/fi-capture.js +347 -0
  103. sendproof_core/ui/locales/fi-stores.js +116 -0
  104. sendproof_core/ui/locales/fi.js +523 -0
  105. sendproof_core/ui/locales/fr-capture.js +353 -0
  106. sendproof_core/ui/locales/fr-stores.js +116 -0
  107. sendproof_core/ui/locales/fr.js +525 -0
  108. sendproof_core/ui/locales/he-capture.js +358 -0
  109. sendproof_core/ui/locales/he-stores.js +116 -0
  110. sendproof_core/ui/locales/he.js +529 -0
  111. sendproof_core/ui/locales/hi-capture.js +348 -0
  112. sendproof_core/ui/locales/hi-stores.js +116 -0
  113. sendproof_core/ui/locales/hi.js +523 -0
  114. sendproof_core/ui/locales/id-capture.js +347 -0
  115. sendproof_core/ui/locales/id-stores.js +116 -0
  116. sendproof_core/ui/locales/id.js +521 -0
  117. sendproof_core/ui/locales/it-capture.js +361 -0
  118. sendproof_core/ui/locales/it-stores.js +116 -0
  119. sendproof_core/ui/locales/it.js +523 -0
  120. sendproof_core/ui/locales/ja-capture.js +346 -0
  121. sendproof_core/ui/locales/ja-stores.js +116 -0
  122. sendproof_core/ui/locales/ja.js +521 -0
  123. sendproof_core/ui/locales/ko-capture.js +346 -0
  124. sendproof_core/ui/locales/ko-stores.js +116 -0
  125. sendproof_core/ui/locales/ko.js +522 -0
  126. sendproof_core/ui/locales/nb-capture.js +349 -0
  127. sendproof_core/ui/locales/nb-stores.js +116 -0
  128. sendproof_core/ui/locales/nb.js +521 -0
  129. sendproof_core/ui/locales/nl-capture.js +355 -0
  130. sendproof_core/ui/locales/nl-stores.js +116 -0
  131. sendproof_core/ui/locales/nl.js +520 -0
  132. sendproof_core/ui/locales/pl-capture.js +432 -0
  133. sendproof_core/ui/locales/pl-stores.js +116 -0
  134. sendproof_core/ui/locales/pl.js +528 -0
  135. sendproof_core/ui/locales/pt-BR-capture.js +350 -0
  136. sendproof_core/ui/locales/pt-BR-stores.js +116 -0
  137. sendproof_core/ui/locales/pt-BR.js +523 -0
  138. sendproof_core/ui/locales/pt-PT-capture.js +350 -0
  139. sendproof_core/ui/locales/pt-PT-stores.js +116 -0
  140. sendproof_core/ui/locales/pt-PT.js +523 -0
  141. sendproof_core/ui/locales/ru-capture.js +437 -0
  142. sendproof_core/ui/locales/ru-stores.js +116 -0
  143. sendproof_core/ui/locales/ru.js +624 -0
  144. sendproof_core/ui/locales/sv-capture.js +349 -0
  145. sendproof_core/ui/locales/sv-stores.js +116 -0
  146. sendproof_core/ui/locales/sv.js +518 -0
  147. sendproof_core/ui/locales/th-capture.js +347 -0
  148. sendproof_core/ui/locales/th-stores.js +116 -0
  149. sendproof_core/ui/locales/th.js +521 -0
  150. sendproof_core/ui/locales/tr-capture.js +348 -0
  151. sendproof_core/ui/locales/tr-stores.js +116 -0
  152. sendproof_core/ui/locales/tr.js +521 -0
  153. sendproof_core/ui/locales/uk-capture.js +442 -0
  154. sendproof_core/ui/locales/uk-stores.js +116 -0
  155. sendproof_core/ui/locales/uk.js +630 -0
  156. sendproof_core/ui/locales/vi-capture.js +346 -0
  157. sendproof_core/ui/locales/vi-stores.js +116 -0
  158. sendproof_core/ui/locales/vi.js +523 -0
  159. sendproof_core/ui/locales/zh-Hans-capture.js +347 -0
  160. sendproof_core/ui/locales/zh-Hans-stores.js +116 -0
  161. sendproof_core/ui/locales/zh-Hans.js +523 -0
  162. sendproof_core/ui/locales/zh-Hant-capture.js +346 -0
  163. sendproof_core/ui/locales/zh-Hant-stores.js +116 -0
  164. sendproof_core/ui/locales/zh-Hant.js +522 -0
  165. sendproof_core/ui/manifest.json +866 -0
  166. sendproof_core/ui/markdown.js +39 -0
  167. sendproof_core/ui/model-view.js +182 -0
  168. sendproof_core/ui/navigation.js +233 -0
  169. sendproof_core/ui/operation-header.js +76 -0
  170. sendproof_core/ui/operations.js +7 -0
  171. sendproof_core/ui/overview-view.js +63 -0
  172. sendproof_core/ui/personas.js +59 -0
  173. sendproof_core/ui/popover.js +71 -0
  174. sendproof_core/ui/preview-false.js +108 -0
  175. sendproof_core/ui/request-editor.js +496 -0
  176. sendproof_core/ui/response-metadata.js +354 -0
  177. sendproof_core/ui/response-viewer.js +618 -0
  178. sendproof_core/ui/result-blocked.js +155 -0
  179. sendproof_core/ui/result-capture.js +25 -0
  180. sendproof_core/ui/result-database.js +185 -0
  181. sendproof_core/ui/result-effects.js +176 -0
  182. sendproof_core/ui/result-headers.js +106 -0
  183. sendproof_core/ui/result-logs.js +408 -0
  184. sendproof_core/ui/result-states.js +213 -0
  185. sendproof_core/ui/results.js +371 -0
  186. sendproof_core/ui/router.js +118 -0
  187. sendproof_core/ui/schema-model.js +336 -0
  188. sendproof_core/ui/schema-tree.js +344 -0
  189. sendproof_core/ui/schema.js +397 -0
  190. sendproof_core/ui/security.js +31 -0
  191. sendproof_core/ui/seeded-menu.js +69 -0
  192. sendproof_core/ui/settings.js +93 -0
  193. sendproof_core/ui/shortcuts-sheet.js +73 -0
  194. sendproof_core/ui/shortcuts.js +190 -0
  195. sendproof_core/ui/sidebar.js +289 -0
  196. sendproof_core/ui/signin.js +259 -0
  197. sendproof_core/ui/snippets.js +530 -0
  198. sendproof_core/ui/store-marks.js +47 -0
  199. sendproof_core/ui/stores.js +131 -0
  200. sendproof_core/ui/styles.css +971 -0
  201. sendproof_core/ui/toggletip.js +53 -0
  202. sendproof_core/ui/uuid.js +10 -0
  203. sendproof_core/ui/view.js +122 -0
  204. sendproof_core/ui/views.css +653 -0
  205. sendproof_core/workbench.py +310 -0
  206. sendproof_core-0.1.0a1.dist-info/METADATA +116 -0
  207. sendproof_core-0.1.0a1.dist-info/RECORD +209 -0
  208. sendproof_core-0.1.0a1.dist-info/WHEEL +4 -0
  209. sendproof_core-0.1.0a1.dist-info/licenses/LICENSE +21 -0
@@ -0,0 +1,56 @@
1
+ """Framework-neutral core of the Sendproof Python adapters.
2
+
3
+ Applications normally import the framework package (``sendproof_fastapi``) and use this
4
+ module for the effect recording helpers::
5
+
6
+ from sendproof_core import record_email
7
+
8
+ if not record_email("Welcome", sender, [to], [], "Hello", "Welcome aboard"):
9
+ send_mail(...)
10
+ """
11
+
12
+ from .effects import (
13
+ is_previewing,
14
+ record_effect,
15
+ record_email,
16
+ record_http,
17
+ record_job,
18
+ record_log,
19
+ record_message,
20
+ )
21
+ from .identity import Identity
22
+ from .options import AuthProvider, BenchOptions, OpenApiDocument
23
+ from .provider import (
24
+ PreviewChange,
25
+ PreviewObservation,
26
+ PreviewProvider,
27
+ PreviewRollbackError,
28
+ PreviewSession,
29
+ PreviewUnavailable,
30
+ )
31
+ from .scope import RequestScope, current_scope, detached
32
+
33
+ __all__ = [
34
+ "detached",
35
+ "AuthProvider",
36
+ "BenchOptions",
37
+ "Identity",
38
+ "OpenApiDocument",
39
+ "PreviewChange",
40
+ "PreviewObservation",
41
+ "PreviewProvider",
42
+ "PreviewRollbackError",
43
+ "PreviewSession",
44
+ "PreviewUnavailable",
45
+ "RequestScope",
46
+ "current_scope",
47
+ "is_previewing",
48
+ "record_effect",
49
+ "record_email",
50
+ "record_http",
51
+ "record_job",
52
+ "record_log",
53
+ "record_message",
54
+ ]
55
+
56
+ __version__ = "0.1.0a1"
@@ -0,0 +1,71 @@
1
+ """The embedded workbench UI.
2
+
3
+ The files come from the shared packer (``node tools/pack-ui.mjs``). It writes a
4
+ ``manifest.json`` with a SHA-256 for every file. This module serves only files listed there and
5
+ verifies each digest before first use, so an incomplete or edited bundle is never served.
6
+ """
7
+
8
+ from __future__ import annotations
9
+
10
+ import hashlib
11
+ import json
12
+ import os
13
+ from dataclasses import dataclass
14
+ from pathlib import Path
15
+
16
+
17
+ @dataclass(frozen=True)
18
+ class Asset:
19
+ """A verified file and its media type."""
20
+
21
+ content: bytes
22
+ content_type: str
23
+
24
+
25
+ class UiBundleError(RuntimeError):
26
+ """The UI bundle is missing or fails verification."""
27
+
28
+
29
+ class UiAssets:
30
+ """Lazy, verified access to a packed UI directory."""
31
+
32
+ def __init__(self, directory: str | os.PathLike[str] | None = None) -> None:
33
+ configured = directory or os.environ.get("SENDPROOF_UI_DIR")
34
+ self._directory = Path(configured) if configured else Path(__file__).parent / "ui"
35
+ self._manifest: dict | None = None
36
+ self._cache: dict[str, Asset] = {}
37
+
38
+ @property
39
+ def version(self) -> str:
40
+ """The bundle version recorded in the manifest."""
41
+ return str(self._load()["version"])
42
+
43
+ def get(self, path: str) -> Asset | None:
44
+ """Return the asset at a manifest-relative path or ``None`` if it is not part of the bundle."""
45
+ files = self._load()["files"]
46
+ entry = files.get(path)
47
+ if entry is None:
48
+ return None
49
+ cached = self._cache.get(path)
50
+ if cached is not None:
51
+ return cached
52
+ content = (self._directory / path).read_bytes()
53
+ if hashlib.sha256(content).hexdigest() != entry["sha256"] or len(content) != entry["bytes"]:
54
+ raise UiBundleError(f"UI asset '{path}' does not match its manifest digest.")
55
+ asset = Asset(content, entry["contentType"])
56
+ self._cache[path] = asset
57
+ return asset
58
+
59
+ def _load(self) -> dict:
60
+ if self._manifest is None:
61
+ manifest = self._directory / "manifest.json"
62
+ if not manifest.is_file():
63
+ raise UiBundleError(
64
+ "The Sendproof UI bundle is not embedded. Run adapters/python/scripts/embed_ui.py "
65
+ "or set SENDPROOF_UI_DIR to a directory produced by tools/pack-ui.mjs."
66
+ )
67
+ data = json.loads(manifest.read_text("utf-8"))
68
+ if not isinstance(data.get("files"), dict) or "version" not in data:
69
+ raise UiBundleError("The UI manifest is malformed.")
70
+ self._manifest = data
71
+ return self._manifest
@@ -0,0 +1,416 @@
1
+ """Per-request capture of effects, logs and SQL for previews and observed sends."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ import threading
7
+ import time
8
+ from dataclasses import dataclass, field
9
+ from typing import Any, Callable, Iterable, Mapping
10
+
11
+ from . import jsonsafe, limits
12
+
13
+ _LEVELS = {
14
+ logging.DEBUG: "Debug",
15
+ logging.INFO: "Information",
16
+ logging.WARNING: "Warning",
17
+ logging.ERROR: "Error",
18
+ logging.CRITICAL: "Critical",
19
+ }
20
+
21
+
22
+ @dataclass(frozen=True)
23
+ class CaptureTiming:
24
+ """Final timing in milliseconds."""
25
+
26
+ auth: float
27
+ handler: float
28
+ db: float
29
+ query_count: int
30
+ serialize: float
31
+
32
+ def server_timing(self) -> str:
33
+ """Render the ``Server-Timing`` header value."""
34
+ return (
35
+ f"auth;dur={self.auth:.3f}, handler;dur={self.handler:.3f}, "
36
+ f'db;dur={self.db:.3f};desc="{self.query_count} queries", serialize;dur={self.serialize:.3f}'
37
+ )
38
+
39
+ def as_trace(self) -> dict[str, Any]:
40
+ """Return the trace schema ``timing`` object."""
41
+ return {
42
+ "auth": self.auth,
43
+ "handler": self.handler,
44
+ "db": self.db,
45
+ "queryCount": self.query_count,
46
+ "serialize": self.serialize,
47
+ }
48
+
49
+
50
+ @dataclass
51
+ class CaptureSnapshot:
52
+ """Immutable result of :meth:`Capture.finish`."""
53
+
54
+ effects: list[dict[str, Any]]
55
+ logs: list[dict[str, Any]]
56
+ logs_truncated: bool
57
+ effects_truncated: bool
58
+
59
+
60
+ @dataclass
61
+ class Capture:
62
+ """Collects the effects and logs of a single request.
63
+
64
+ ``rollback`` is true for a preview, where effects must be suppressed by the host.
65
+ For an observed send the effects are recorded as intended deliveries and the host still
66
+ delivers them.
67
+ """
68
+
69
+ rollback: bool
70
+ started: float = field(default_factory=time.perf_counter)
71
+ _lock: threading.RLock = field(default_factory=threading.RLock, repr=False)
72
+ _effects: list[dict[str, Any]] = field(default_factory=list, repr=False)
73
+ _logs: list[dict[str, Any]] = field(default_factory=list, repr=False)
74
+ _active: bool = True
75
+ _logs_truncated: bool = False
76
+ _effects_truncated: bool = False
77
+ _log_size: int = 0
78
+ _effect_size: int = 0
79
+ _db_ms: float = 0.0
80
+ _queries: int = 0
81
+ _serialize_ms: float = 0.0
82
+ _handler_start: float | None = None
83
+ _handler_end: float | None = None
84
+ _blocked: dict[str, str] | None = None
85
+ _fault: BaseException | None = None
86
+ _quiet: bool = False
87
+
88
+ # ------------------------------------------------------------ write guard
89
+ @property
90
+ def blocked(self) -> dict[str, str] | None:
91
+ """The first write the guard refused during a Preview: ``store``, ``operation`` and ``detail``."""
92
+ return self._blocked
93
+
94
+ @property
95
+ def fault(self) -> BaseException | None:
96
+ """The first transaction-control refusal or escape of a Preview; it withholds confirmation."""
97
+ return self._fault
98
+
99
+ def block(self, store: str, operation: str, detail: str) -> None:
100
+ """Keep the first refused write. It decides the Preview's 409, whatever the handler returns.
101
+
102
+ Recording works after :meth:`finish` too, so a write sent late by a handler is never lost.
103
+ """
104
+ with self._lock:
105
+ if self.rollback and self._blocked is None:
106
+ self._blocked = {
107
+ "store": limits.clip(store, limits.NAME),
108
+ "operation": limits.clip(operation, limits.NAME),
109
+ "detail": limits.clip(detail),
110
+ }
111
+
112
+ def refuse(self, error: BaseException) -> None:
113
+ """Keep the first fault. It withholds confirmation, whatever the handler returns."""
114
+ with self._lock:
115
+ if self.rollback and self._fault is None:
116
+ self._fault = error
117
+
118
+ # ------------------------------------------------------------------ effects
119
+ def record_effect(self, kind: str, description: str, data: Any = None) -> bool:
120
+ """Record an effect and return ``True`` when the host must suppress its delivery."""
121
+ with self._lock:
122
+ if not self._active:
123
+ return False
124
+ if len(self._effects) >= limits.EFFECTS or self._effect_size >= limits.LOG_BUDGET:
125
+ self._effects_truncated = True
126
+ return self.rollback
127
+ began = time.perf_counter()
128
+ captured = None if data is None else jsonsafe.snapshot(data)
129
+ self._serialize_ms += (time.perf_counter() - began) * 1000
130
+ data_missing = captured is not None and jsonsafe.is_missing(captured)
131
+ if data_missing:
132
+ captured = None
133
+ clipped_kind = limits.clip(kind, limits.NAME)
134
+ clipped_description = limits.clip(description)
135
+ self._effects_truncated |= (
136
+ clipped_kind != kind or clipped_description != description or data_missing
137
+ )
138
+ size = len(clipped_kind) + len(clipped_description) + (len(str(captured)) if captured else 0)
139
+ if self._effect_size + size <= limits.LOG_BUDGET:
140
+ self._effect_size += size
141
+ effect: dict[str, Any] = {"kind": clipped_kind, "description": clipped_description}
142
+ if captured is not None:
143
+ effect["data"] = captured
144
+ else:
145
+ effect["data"] = None
146
+ if not self.rollback:
147
+ effect["delivered"] = True
148
+ self._effects.append(effect)
149
+ else:
150
+ self._effects_truncated = True
151
+ return self.rollback
152
+
153
+ # --------------------------------------------------------------------- logs
154
+ def record_log(
155
+ self,
156
+ level: str,
157
+ message: str,
158
+ *,
159
+ category: str | None = None,
160
+ event_id: tuple[int, str | None] | None = None,
161
+ properties: Mapping[str, Any] | None = None,
162
+ exception: tuple[str, str] | None = None,
163
+ elapsed_ms: float | None = None,
164
+ offset_ms: float | None = None,
165
+ sql: dict[str, Any] | None = None,
166
+ db: dict[str, Any] | None = None,
167
+ ) -> None:
168
+ """Append a structured log entry when there is room."""
169
+ with self._lock:
170
+ if not self._active or not self._has_room():
171
+ return
172
+ entry: dict[str, Any] = {
173
+ "level": limits.clip(level, limits.NAME),
174
+ "message": limits.clip(message),
175
+ }
176
+ self._logs_truncated |= entry["message"] != message
177
+ if category:
178
+ entry["category"] = limits.clip(category, limits.NAME)
179
+ if event_id is not None:
180
+ entry["eventId"] = {"id": event_id[0]}
181
+ if event_id[1]:
182
+ entry["eventId"]["name"] = limits.clip(event_id[1], limits.NAME)
183
+ entry["offsetMs"] = max(0.0, self._offset_ms() if offset_ms is None else offset_ms)
184
+ if elapsed_ms is not None:
185
+ entry["elapsedMs"] = max(0.0, elapsed_ms)
186
+ if properties:
187
+ kept = {}
188
+ for key, value in properties.items():
189
+ if key == "{OriginalFormat}":
190
+ continue
191
+ if len(kept) >= limits.PROPERTIES:
192
+ self._logs_truncated = True
193
+ break
194
+ kept[limits.clip(str(key), limits.NAME)] = limits.clip(str(value))
195
+ if kept:
196
+ entry["properties"] = kept
197
+ if exception is not None:
198
+ entry["exception"] = {
199
+ "type": limits.clip(exception[0], limits.NAME),
200
+ "message": limits.clip(exception[1]),
201
+ }
202
+ if sql is not None:
203
+ entry["sql"] = sql
204
+ if db is not None:
205
+ entry["db"] = db
206
+ size = _entry_size(entry)
207
+ if self._log_size + size <= limits.LOG_BUDGET:
208
+ self._logs.append(entry)
209
+ self._log_size += size
210
+ else:
211
+ self._logs_truncated = True
212
+
213
+ def record_sql(
214
+ self,
215
+ text: str,
216
+ parameters: Iterable[tuple[str, str | None, str]],
217
+ *,
218
+ rows_affected: int | None = None,
219
+ duration_ms: float = 0.0,
220
+ category: str = "sql",
221
+ truncated: bool = False,
222
+ ) -> None:
223
+ """Record one executed SQL command and add its duration to the ``db`` timing."""
224
+ with self._lock:
225
+ if not self._active:
226
+ return
227
+ self._db_ms += duration_ms
228
+ self._queries += 1
229
+ if not self._has_room():
230
+ return
231
+ clipped = limits.clip(text)
232
+ listed = []
233
+ for index, (name, value, db_type) in enumerate(parameters):
234
+ if index >= limits.PARAMETERS:
235
+ truncated = True
236
+ break
237
+ listed.append({
238
+ "name": limits.clip(name, limits.NAME),
239
+ "value": None if value is None else limits.clip(value),
240
+ "dbType": limits.clip(db_type, limits.NAME),
241
+ })
242
+ self._logs_truncated |= truncated or clipped != text
243
+ sql: dict[str, Any] = {"text": clipped, "parameters": listed}
244
+ if rows_affected is not None and rows_affected >= 0:
245
+ sql["rowsAffected"] = rows_affected
246
+ self.record_log(
247
+ "Sql",
248
+ clipped,
249
+ category=category,
250
+ elapsed_ms=duration_ms,
251
+ offset_ms=max(0.0, self._offset_ms() - duration_ms),
252
+ sql=sql,
253
+ )
254
+
255
+ def record_db(
256
+ self,
257
+ system: str,
258
+ operation: str,
259
+ *,
260
+ target: str | None = None,
261
+ namespace: str | None = None,
262
+ statement: str | None = None,
263
+ rows_affected: int | None = None,
264
+ blocked: bool = False,
265
+ error: str | None = None,
266
+ elapsed_ms: float | None = None,
267
+ ) -> None:
268
+ """Record one data-store command as a ``Db`` log entry.
269
+
270
+ The message is the OpenTelemetry span name, ``{operation} {target}``. Hooks pass sanitized
271
+ statements only: values never reach this method. A blocked command never ran, so it adds
272
+ nothing to the ``db`` timing.
273
+ """
274
+ with self._lock:
275
+ if not self._active or self._quiet:
276
+ return
277
+ if not blocked:
278
+ self._queries += 1
279
+ self._db_ms += elapsed_ms or 0.0
280
+ db: dict[str, Any] = {
281
+ "system": limits.clip(system, limits.NAME), "operation": limits.clip(operation, limits.NAME),
282
+ }
283
+ if target is not None:
284
+ db["target"] = limits.clip(target, limits.NAME)
285
+ if namespace is not None:
286
+ db["namespace"] = limits.clip(namespace, limits.NAME)
287
+ if statement is not None:
288
+ self._logs_truncated |= len(statement) > limits.TEXT
289
+ db["statement"] = limits.clip(statement)
290
+ if rows_affected is not None and rows_affected >= 0:
291
+ db["rowsAffected"] = int(rows_affected)
292
+ if blocked:
293
+ db["blocked"] = True
294
+ if error:
295
+ db["error"] = limits.clip(error, limits.NAME)
296
+ message = db["operation"] if "target" not in db else f"{db['operation']} {db['target']}"
297
+ offset = None if elapsed_ms is None else max(0.0, self._offset_ms() - elapsed_ms)
298
+ self.record_log("Db", message, elapsed_ms=elapsed_ms, offset_ms=offset, db=db)
299
+
300
+ # ------------------------------------------------------------------- timing
301
+ def handler_started(self) -> None:
302
+ """Mark entry into the application handler (end of the ``auth`` phase)."""
303
+ if self._handler_start is None:
304
+ self._handler_start = time.perf_counter()
305
+
306
+ def handler_finished(self) -> None:
307
+ """Mark the end of handler execution.
308
+
309
+ Data-store commands the binding itself sends after this point (reading document changes,
310
+ aborting a transaction) are not logged as the handler's.
311
+ """
312
+ self._handler_end = time.perf_counter()
313
+ self._quiet = True
314
+
315
+ def timing(self, extra_serialize_ms: float = 0.0) -> CaptureTiming:
316
+ """Compute the current timing breakdown."""
317
+ with self._lock:
318
+ handler_start = self._handler_start or self.started
319
+ handler_end = self._handler_end or time.perf_counter()
320
+ serialize = self._serialize_ms
321
+ db = self._db_ms
322
+ handler = max(0.0, (handler_end - handler_start) * 1000 - db - serialize)
323
+ return CaptureTiming(
324
+ (handler_start - self.started) * 1000, handler, db, self._queries, serialize + extra_serialize_ms
325
+ )
326
+
327
+ def finish(self) -> CaptureSnapshot:
328
+ """Stop capturing and return the collected data."""
329
+ with self._lock:
330
+ self._active = False
331
+ snapshot = CaptureSnapshot(
332
+ list(self._effects), list(self._logs), self._logs_truncated, self._effects_truncated
333
+ )
334
+ self._effects.clear()
335
+ self._logs.clear()
336
+ return snapshot
337
+
338
+ @property
339
+ def is_active(self) -> bool:
340
+ """Whether the capture still accepts records."""
341
+ return self._active
342
+
343
+ # ----------------------------------------------------------------- internals
344
+ def _offset_ms(self) -> float:
345
+ return (time.perf_counter() - self.started) * 1000
346
+
347
+ def _has_room(self) -> bool:
348
+ room = len(self._logs) < limits.LOGS and self._log_size < limits.LOG_BUDGET
349
+ self._logs_truncated |= not room
350
+ return room
351
+
352
+
353
+ def _entry_size(entry: Mapping[str, Any]) -> int:
354
+ size = len(entry["level"]) + len(entry["message"]) + len(entry.get("category", ""))
355
+ for key, value in entry.get("properties", {}).items():
356
+ size += len(key) + len(value)
357
+ if "exception" in entry:
358
+ size += len(entry["exception"]["type"]) + len(entry["exception"]["message"])
359
+ if "db" in entry:
360
+ db = entry["db"]
361
+ size += sum(len(str(value)) for value in db.values())
362
+ if "sql" in entry:
363
+ sql = entry["sql"]
364
+ size += len(sql["text"])
365
+ for parameter in sql["parameters"]:
366
+ size += len(parameter["name"]) + len(parameter["value"] or "") + len(parameter["dbType"])
367
+ return size
368
+
369
+
370
+ # Loggers that print SQL with its bound values (SQLAlchemy ``echo``, Django's DEBUG query log).
371
+ # The data-layer providers record every statement themselves with redaction applied, so these
372
+ # records would only duplicate them with secrets in clear text.
373
+ _SQL_ECHO_LOGGERS = ("sqlalchemy.engine", "django.db.backends")
374
+
375
+
376
+ def _is_sql_echo(name: str) -> bool:
377
+ return any(name == prefix or name.startswith(prefix + ".") for prefix in _SQL_ECHO_LOGGERS)
378
+
379
+
380
+ def _exception_message(error: BaseException | None) -> str:
381
+ """The message of a logged exception without SQL parameter values.
382
+
383
+ SQLAlchemy's ``StatementError`` appends ``[parameters: ...]`` to its text; only the driver's
384
+ own message (``orig``) is kept for those.
385
+ """
386
+ if error is None:
387
+ return ""
388
+ if hasattr(error, "statement") and hasattr(error, "params"):
389
+ original = getattr(error, "orig", None)
390
+ return f"{type(original).__name__}: {original}" if original is not None else type(error).__name__
391
+ return str(error)
392
+
393
+
394
+ class CaptureLogHandler(logging.Handler):
395
+ """Forwards standard ``logging`` records to the capture of the current request."""
396
+
397
+ def __init__(self, scope_getter: Callable[[], Any]) -> None:
398
+ super().__init__(level=logging.DEBUG)
399
+ self._scope_getter = scope_getter
400
+
401
+ def emit(self, record: logging.LogRecord) -> None: # noqa: D401 - logging API
402
+ scope = self._scope_getter()
403
+ if scope is None or _is_sql_echo(record.name):
404
+ return
405
+ try:
406
+ exception = None
407
+ if record.exc_info and record.exc_info[0] is not None:
408
+ exception = (record.exc_info[0].__qualname__, _exception_message(record.exc_info[1]))
409
+ scope.capture.record_log(
410
+ _LEVELS.get(record.levelno, record.levelname.title()),
411
+ record.getMessage(),
412
+ category=record.name,
413
+ exception=exception,
414
+ )
415
+ except Exception: # capture must never interrupt the application
416
+ self.handleError(record)
@@ -0,0 +1,79 @@
1
+ """Application-facing API for recording effects and logs during previews.
2
+
3
+ Call these at the boundary where the application would deliver an email, publish a message,
4
+ call another service or schedule a job. Each returns ``True`` when the delivery must be
5
+ skipped because the request is a rollback preview::
6
+
7
+ if not sendproof_core.record_email("Welcome", sender, [to], [], subject, text):
8
+ mailer.send(...)
9
+ """
10
+
11
+ from __future__ import annotations
12
+
13
+ from datetime import datetime
14
+ from typing import Any, Iterable
15
+
16
+ from .scope import current_scope
17
+
18
+
19
+ def is_previewing() -> bool:
20
+ """Whether the running request is a rollback-only preview."""
21
+ scope = current_scope()
22
+ return scope is not None and scope.rollback
23
+
24
+
25
+ def record_effect(kind: str, description: str, data: Any = None) -> bool:
26
+ """Record an effect. Returns ``True`` if the caller must suppress its delivery."""
27
+ scope = current_scope()
28
+ return False if scope is None else scope.capture.record_effect(kind, description, data)
29
+
30
+
31
+ def record_email(
32
+ description: str,
33
+ sender: str,
34
+ to: Iterable[str],
35
+ cc: Iterable[str],
36
+ subject: str,
37
+ text: str,
38
+ html: str | None = None,
39
+ ) -> bool:
40
+ """Record an email. Returns ``True`` if delivery must be suppressed."""
41
+ return record_effect(
42
+ "email",
43
+ description,
44
+ {"from": sender, "to": list(to), "cc": list(cc), "subject": subject, "text": text, "html": html},
45
+ )
46
+
47
+
48
+ def record_http(description: str, method: str, url: str, status: int | None = None, body: Any = None) -> bool:
49
+ """Record an outgoing HTTP call. Returns ``True`` if the call must be suppressed."""
50
+ return record_effect("http", description, {"method": method, "url": url, "status": status, "body": body})
51
+
52
+
53
+ def record_job(
54
+ description: str,
55
+ name: str,
56
+ arguments: Any = None,
57
+ queue: str | None = None,
58
+ run_at: datetime | None = None,
59
+ ) -> bool:
60
+ """Record a background job. Returns ``True`` if scheduling must be suppressed."""
61
+ return record_effect(
62
+ "job",
63
+ description,
64
+ {"name": name, "arguments": arguments, "queue": queue, "runAt": run_at.isoformat() if run_at else None},
65
+ )
66
+
67
+
68
+ def record_message(description: str, topic: str, payload: Any = None, key: str | None = None) -> bool:
69
+ """Record a published message. Returns ``True`` if publishing must be suppressed."""
70
+ return record_effect("message", description, {"topic": topic, "payload": payload, "key": key})
71
+
72
+
73
+ def record_log(level: str, message: str) -> bool:
74
+ """Record a log line directly. Returns whether a capture is active."""
75
+ scope = current_scope()
76
+ if scope is None:
77
+ return False
78
+ scope.capture.record_log(level, message)
79
+ return True
@@ -0,0 +1,22 @@
1
+ """Identity of the caller as established by the host application."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass
6
+
7
+
8
+ @dataclass(frozen=True)
9
+ class Identity:
10
+ """An authenticated caller.
11
+
12
+ ``subject`` is a stable identifier issued by the host. Observed-send traces are owned by
13
+ ``(authentication_type, issuer, subject)``, so callers without a subject cannot read traces.
14
+ Set ``issuer`` when subjects come from more than one identity provider (for example the
15
+ ``iss`` claim of a token), so equal subjects from different issuers stay separate.
16
+ """
17
+
18
+ name: str | None
19
+ role: str | None = None
20
+ subject: str | None = None
21
+ authentication_type: str = "session"
22
+ issuer: str | None = None