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.
- sendproof_core/__init__.py +56 -0
- sendproof_core/assets.py +71 -0
- sendproof_core/capture.py +416 -0
- sendproof_core/effects.py +79 -0
- sendproof_core/identity.py +22 -0
- sendproof_core/jsonsafe.py +103 -0
- sendproof_core/limits.py +24 -0
- sendproof_core/marker.py +131 -0
- sendproof_core/options.py +129 -0
- sendproof_core/protocol.py +132 -0
- sendproof_core/provider.py +121 -0
- sendproof_core/py.typed +0 -0
- sendproof_core/redaction.py +88 -0
- sendproof_core/scope.py +146 -0
- sendproof_core/stores/__init__.py +119 -0
- sendproof_core/stores/base.py +99 -0
- sendproof_core/stores/cassandra_hook.py +173 -0
- sendproof_core/stores/classify.py +153 -0
- sendproof_core/stores/classify_batch_two.py +397 -0
- sendproof_core/stores/cosmos_hook.py +214 -0
- sendproof_core/stores/dynamodb_hook.py +214 -0
- sendproof_core/stores/elasticsearch_hook.py +248 -0
- sendproof_core/stores/firestore_hook.py +459 -0
- sendproof_core/stores/guard.py +205 -0
- sendproof_core/stores/mongo_hook.py +1406 -0
- sendproof_core/stores/redis_hook.py +536 -0
- sendproof_core/stores/tables.py +1486 -0
- sendproof_core/stores/versions.py +46 -0
- sendproof_core/sync_engine.py +308 -0
- sendproof_core/trace_store.py +92 -0
- sendproof_core/txguard.py +237 -0
- sendproof_core/ui/action-bar.js +91 -0
- sendproof_core/ui/api.js +239 -0
- sendproof_core/ui/app.css +848 -0
- sendproof_core/ui/app.js +742 -0
- sendproof_core/ui/autofill.js +137 -0
- sendproof_core/ui/code-copy.js +71 -0
- sendproof_core/ui/code-picker.js +149 -0
- sendproof_core/ui/commands.js +197 -0
- sendproof_core/ui/components.js +77 -0
- sendproof_core/ui/context-bar.js +82 -0
- sendproof_core/ui/copy.js +92 -0
- sendproof_core/ui/coverage-popover.js +35 -0
- sendproof_core/ui/crumb-fit.js +80 -0
- sendproof_core/ui/deprecation.js +164 -0
- sendproof_core/ui/display-settings.js +175 -0
- sendproof_core/ui/doc-diff.js +209 -0
- sendproof_core/ui/docs-view.js +347 -0
- sendproof_core/ui/favicon.png +0 -0
- sendproof_core/ui/favicon.svg +1 -0
- sendproof_core/ui/field-help.js +52 -0
- sendproof_core/ui/field-modules.js +23 -0
- sendproof_core/ui/fields/controls.js +179 -0
- sendproof_core/ui/fields/dom.js +36 -0
- sendproof_core/ui/fields/infer.js +71 -0
- sendproof_core/ui/fields/lookup-source.js +63 -0
- sendproof_core/ui/fields/lookup.js +285 -0
- sendproof_core/ui/fields/render.js +496 -0
- sendproof_core/ui/fields/select.js +175 -0
- sendproof_core/ui/fields/validate.js +363 -0
- sendproof_core/ui/fields/validation-formats.js +164 -0
- sendproof_core/ui/fields/validation-references.js +68 -0
- sendproof_core/ui/fields/validation-values.js +137 -0
- sendproof_core/ui/generate-menu.js +44 -0
- sendproof_core/ui/generate.js +184 -0
- sendproof_core/ui/header-editor.js +777 -0
- sendproof_core/ui/headers.js +188 -0
- sendproof_core/ui/highlight.js +257 -0
- sendproof_core/ui/history-popover.js +24 -0
- sendproof_core/ui/i18n.js +253 -0
- sendproof_core/ui/icons.js +87 -0
- sendproof_core/ui/index.html +70 -0
- sendproof_core/ui/issues.js +187 -0
- sendproof_core/ui/json-view.js +166 -0
- sendproof_core/ui/lang-icons.js +62 -0
- sendproof_core/ui/layout.js +262 -0
- sendproof_core/ui/listbox.js +334 -0
- sendproof_core/ui/locales/ar-capture.js +366 -0
- sendproof_core/ui/locales/ar-stores.js +116 -0
- sendproof_core/ui/locales/ar.js +561 -0
- sendproof_core/ui/locales/cs-capture.js +442 -0
- sendproof_core/ui/locales/cs-stores.js +116 -0
- sendproof_core/ui/locales/cs.js +689 -0
- sendproof_core/ui/locales/da-capture.js +347 -0
- sendproof_core/ui/locales/da-stores.js +116 -0
- sendproof_core/ui/locales/da.js +522 -0
- sendproof_core/ui/locales/de-capture.js +347 -0
- sendproof_core/ui/locales/de-stores.js +116 -0
- sendproof_core/ui/locales/de.js +519 -0
- sendproof_core/ui/locales/el-capture.js +347 -0
- sendproof_core/ui/locales/el-stores.js +116 -0
- sendproof_core/ui/locales/el.js +520 -0
- sendproof_core/ui/locales/en-capture.js +349 -0
- sendproof_core/ui/locales/en-stores.js +95 -0
- sendproof_core/ui/locales/en.js +522 -0
- sendproof_core/ui/locales/es-capture.js +353 -0
- sendproof_core/ui/locales/es-stores.js +116 -0
- sendproof_core/ui/locales/es.js +525 -0
- sendproof_core/ui/locales/fa-capture.js +348 -0
- sendproof_core/ui/locales/fa-stores.js +116 -0
- sendproof_core/ui/locales/fa.js +521 -0
- sendproof_core/ui/locales/fi-capture.js +347 -0
- sendproof_core/ui/locales/fi-stores.js +116 -0
- sendproof_core/ui/locales/fi.js +523 -0
- sendproof_core/ui/locales/fr-capture.js +353 -0
- sendproof_core/ui/locales/fr-stores.js +116 -0
- sendproof_core/ui/locales/fr.js +525 -0
- sendproof_core/ui/locales/he-capture.js +358 -0
- sendproof_core/ui/locales/he-stores.js +116 -0
- sendproof_core/ui/locales/he.js +529 -0
- sendproof_core/ui/locales/hi-capture.js +348 -0
- sendproof_core/ui/locales/hi-stores.js +116 -0
- sendproof_core/ui/locales/hi.js +523 -0
- sendproof_core/ui/locales/id-capture.js +347 -0
- sendproof_core/ui/locales/id-stores.js +116 -0
- sendproof_core/ui/locales/id.js +521 -0
- sendproof_core/ui/locales/it-capture.js +361 -0
- sendproof_core/ui/locales/it-stores.js +116 -0
- sendproof_core/ui/locales/it.js +523 -0
- sendproof_core/ui/locales/ja-capture.js +346 -0
- sendproof_core/ui/locales/ja-stores.js +116 -0
- sendproof_core/ui/locales/ja.js +521 -0
- sendproof_core/ui/locales/ko-capture.js +346 -0
- sendproof_core/ui/locales/ko-stores.js +116 -0
- sendproof_core/ui/locales/ko.js +522 -0
- sendproof_core/ui/locales/nb-capture.js +349 -0
- sendproof_core/ui/locales/nb-stores.js +116 -0
- sendproof_core/ui/locales/nb.js +521 -0
- sendproof_core/ui/locales/nl-capture.js +355 -0
- sendproof_core/ui/locales/nl-stores.js +116 -0
- sendproof_core/ui/locales/nl.js +520 -0
- sendproof_core/ui/locales/pl-capture.js +432 -0
- sendproof_core/ui/locales/pl-stores.js +116 -0
- sendproof_core/ui/locales/pl.js +528 -0
- sendproof_core/ui/locales/pt-BR-capture.js +350 -0
- sendproof_core/ui/locales/pt-BR-stores.js +116 -0
- sendproof_core/ui/locales/pt-BR.js +523 -0
- sendproof_core/ui/locales/pt-PT-capture.js +350 -0
- sendproof_core/ui/locales/pt-PT-stores.js +116 -0
- sendproof_core/ui/locales/pt-PT.js +523 -0
- sendproof_core/ui/locales/ru-capture.js +437 -0
- sendproof_core/ui/locales/ru-stores.js +116 -0
- sendproof_core/ui/locales/ru.js +624 -0
- sendproof_core/ui/locales/sv-capture.js +349 -0
- sendproof_core/ui/locales/sv-stores.js +116 -0
- sendproof_core/ui/locales/sv.js +518 -0
- sendproof_core/ui/locales/th-capture.js +347 -0
- sendproof_core/ui/locales/th-stores.js +116 -0
- sendproof_core/ui/locales/th.js +521 -0
- sendproof_core/ui/locales/tr-capture.js +348 -0
- sendproof_core/ui/locales/tr-stores.js +116 -0
- sendproof_core/ui/locales/tr.js +521 -0
- sendproof_core/ui/locales/uk-capture.js +442 -0
- sendproof_core/ui/locales/uk-stores.js +116 -0
- sendproof_core/ui/locales/uk.js +630 -0
- sendproof_core/ui/locales/vi-capture.js +346 -0
- sendproof_core/ui/locales/vi-stores.js +116 -0
- sendproof_core/ui/locales/vi.js +523 -0
- sendproof_core/ui/locales/zh-Hans-capture.js +347 -0
- sendproof_core/ui/locales/zh-Hans-stores.js +116 -0
- sendproof_core/ui/locales/zh-Hans.js +523 -0
- sendproof_core/ui/locales/zh-Hant-capture.js +346 -0
- sendproof_core/ui/locales/zh-Hant-stores.js +116 -0
- sendproof_core/ui/locales/zh-Hant.js +522 -0
- sendproof_core/ui/manifest.json +866 -0
- sendproof_core/ui/markdown.js +39 -0
- sendproof_core/ui/model-view.js +182 -0
- sendproof_core/ui/navigation.js +233 -0
- sendproof_core/ui/operation-header.js +76 -0
- sendproof_core/ui/operations.js +7 -0
- sendproof_core/ui/overview-view.js +63 -0
- sendproof_core/ui/personas.js +59 -0
- sendproof_core/ui/popover.js +71 -0
- sendproof_core/ui/preview-false.js +108 -0
- sendproof_core/ui/request-editor.js +496 -0
- sendproof_core/ui/response-metadata.js +354 -0
- sendproof_core/ui/response-viewer.js +618 -0
- sendproof_core/ui/result-blocked.js +155 -0
- sendproof_core/ui/result-capture.js +25 -0
- sendproof_core/ui/result-database.js +185 -0
- sendproof_core/ui/result-effects.js +176 -0
- sendproof_core/ui/result-headers.js +106 -0
- sendproof_core/ui/result-logs.js +408 -0
- sendproof_core/ui/result-states.js +213 -0
- sendproof_core/ui/results.js +371 -0
- sendproof_core/ui/router.js +118 -0
- sendproof_core/ui/schema-model.js +336 -0
- sendproof_core/ui/schema-tree.js +344 -0
- sendproof_core/ui/schema.js +397 -0
- sendproof_core/ui/security.js +31 -0
- sendproof_core/ui/seeded-menu.js +69 -0
- sendproof_core/ui/settings.js +93 -0
- sendproof_core/ui/shortcuts-sheet.js +73 -0
- sendproof_core/ui/shortcuts.js +190 -0
- sendproof_core/ui/sidebar.js +289 -0
- sendproof_core/ui/signin.js +259 -0
- sendproof_core/ui/snippets.js +530 -0
- sendproof_core/ui/store-marks.js +47 -0
- sendproof_core/ui/stores.js +131 -0
- sendproof_core/ui/styles.css +971 -0
- sendproof_core/ui/toggletip.js +53 -0
- sendproof_core/ui/uuid.js +10 -0
- sendproof_core/ui/view.js +122 -0
- sendproof_core/ui/views.css +653 -0
- sendproof_core/workbench.py +310 -0
- sendproof_core-0.1.0a1.dist-info/METADATA +116 -0
- sendproof_core-0.1.0a1.dist-info/RECORD +209 -0
- sendproof_core-0.1.0a1.dist-info/WHEEL +4 -0
- 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"
|
sendproof_core/assets.py
ADDED
|
@@ -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
|