wellapi 0.10.0__tar.gz → 0.10.2__tar.gz

{wellapi-0.10.0 → wellapi-0.10.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wellapi
-Version: 0.10.0
+Version: 0.10.2
 Summary: A simple web framework for aws lambda
 Author-email: romayuhym <romayuhym@gmail.com>
 Requires-Python: >=3.12

{wellapi-0.10.0 → wellapi-0.10.2}/docs/telemetry.md

@@ -107,6 +107,36 @@ to the function name).
 `OTEL_SERVICE_NAME` and `OTEL_RESOURCE_ATTRIBUTES` override these without code
 changes.
 
+## SnapStart and ID uniqueness
+
+When `warmup`/`use_snap_start` is on, the function is published with AWS Lambda
+SnapStart: Lambda boots one environment, snapshots its memory, and restores that
+**same** snapshot into every execution environment. Anything seeded once at init
+is therefore shared by all restored environments.
+
+OpenTelemetry's default ID generator draws trace/span IDs from Python's
+module-level `random` (a Mersenne Twister seeded once at import). Under SnapStart
+that frozen state is cloned, so every restored environment emits the **same
+sequence** of trace/span IDs — you see one `trace_id` reused across unrelated
+requests. wellapi avoids this by configuring the tracer provider with a
+`SystemRandom` (`os.urandom`-backed) ID generator: the kernel CSPRNG is reseeded
+with fresh entropy on restore, so IDs stay unique. No action needed for telemetry.
+
+If your own handlers (or other libraries) rely on the `random` module, `uuid1`,
+or any non-CSPRNG source for uniqueness, they have the same SnapStart hazard.
+Reseed them in an after-restore hook:
+
+```python
+import random
+from snapshot_restore_py import register_after_restore
+
+@register_after_restore
+def _reseed():
+    random.seed()  # pull fresh entropy from the OS after restore
+```
+
+`os.urandom`, `secrets`, and `uuid4` read the kernel CSPRNG and are already safe.
+
 ## Local development
 
 Telemetry is off until `use_telemetry()` is called. If you call it locally without

{wellapi-0.10.0 → wellapi-0.10.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "wellapi"
-version = "0.10.0"
+version = "0.10.2"
 description = "A simple web framework for aws lambda"
 readme = "README.md"
 authors = [

{wellapi-0.10.0 → wellapi-0.10.2}/src/wellapi/telemetry/config.py

@@ -1,4 +1,5 @@
 import os
+import random
 from dataclasses import dataclass
 from typing import Any
 
@@ -13,6 +14,37 @@ _INSTALL_HINT = (
 )
 
 
+class _SystemRandomIdGenerator:
+    """Trace/span ID generator backed by the kernel CSPRNG (`os.urandom`).
+
+    OpenTelemetry's default `RandomIdGenerator` draws IDs from the module-level
+    Mersenne Twister, which Python seeds once at import. AWS Lambda SnapStart
+    captures that PRNG state in the snapshot and shares it across every restored
+    execution environment, so the default generator emits identical trace/span
+    IDs in lockstep across environments — observed as duplicate `trace_id`s on
+    unrelated requests. The kernel CSPRNG is reseeded with fresh entropy on
+    restore, so `random.SystemRandom` (i.e. `os.urandom`) stays unique. Duck-typed
+    against `opentelemetry.sdk.trace.id_generator.IdGenerator` to avoid importing
+    the SDK at module import time (kept lazy, like the rest of this module)."""
+
+    _rand = random.SystemRandom()
+
+    def generate_span_id(self) -> int:
+        span_id = self._rand.getrandbits(64)
+        while span_id == trace.INVALID_SPAN_ID:
+            span_id = self._rand.getrandbits(64)
+        return span_id
+
+    def generate_trace_id(self) -> int:
+        trace_id = self._rand.getrandbits(128)
+        while trace_id == trace.INVALID_TRACE_ID:
+            trace_id = self._rand.getrandbits(128)
+        return trace_id
+
+    def is_trace_id_random(self) -> bool:
+        return True
+
+
 @dataclass
 class TelemetryHandle:
     """Handles to the configured providers. Returned by `app.use_telemetry()` so
@@ -73,7 +105,10 @@ def _build_providers(resource: Any) -> tuple[Any, Any, Any]:
 
     # Exporters default to OTEL_EXPORTER_OTLP_ENDPOINT or http://localhost:4318,
     # i.e. the collector-only Lambda layer running on localhost.
-    tracer_provider = TracerProvider(resource=resource)
+    # _SystemRandomIdGenerator keeps IDs unique under SnapStart (see its docstring).
+    tracer_provider = TracerProvider(
+        resource=resource, id_generator=_SystemRandomIdGenerator()
+    )
     tracer_provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
 
     meter_provider = MeterProvider(

{wellapi-0.10.0 → wellapi-0.10.2}/tests/telemetry/test_config.py

@@ -1,3 +1,5 @@
+import random
+
 import wellapi.telemetry.config as config_mod
 from wellapi.telemetry.config import TelemetryHandle, _build_resource
 
@@ -6,6 +8,40 @@ def _attrs(resource):
     return dict(resource.attributes)
 
 
+def _ids_after_seed(generator, seed):
+    """IDs a freshly snapshot-restored env would emit: identical frozen
+    module-level random state (the AWS SnapStart failure mode)."""
+    state = random.getstate()
+    try:
+        random.seed(seed)
+        return generator.generate_trace_id(), generator.generate_span_id()
+    finally:
+        random.setstate(state)
+
+
+def test_default_random_id_generator_collides_under_cloned_random_state():
+    # Documents the bug: the OTel default generator draws from the module-level
+    # Mersenne Twister, which SnapStart freezes and shares across restored envs.
+    from opentelemetry.sdk.trace.id_generator import RandomIdGenerator
+
+    gen = RandomIdGenerator()
+    assert _ids_after_seed(gen, 1234) == _ids_after_seed(gen, 1234)
+
+
+def test_snapstart_safe_id_generator_survives_cloned_random_state():
+    gen = config_mod._SystemRandomIdGenerator()
+    # Two envs restored from the same snapshot (same frozen MT state) must still
+    # produce distinct trace/span IDs.
+    assert _ids_after_seed(gen, 1234) != _ids_after_seed(gen, 1234)
+
+
+def test_snapstart_safe_id_generator_marks_trace_id_random():
+    gen = config_mod._SystemRandomIdGenerator()
+    assert gen.is_trace_id_random() is True
+    assert 0 < gen.generate_trace_id() < 2**128
+    assert 0 < gen.generate_span_id() < 2**64
+
+
 def test_resource_uses_faas_env(monkeypatch):
     monkeypatch.setenv("AWS_LAMBDA_FUNCTION_NAME", "orders-fn")
     monkeypatch.setenv("AWS_REGION", "eu-west-1")
@@ -53,6 +89,9 @@ def test_build_providers_attaches_resource_and_returns_sdk_types():
     assert isinstance(mp, MeterProvider)
     assert isinstance(lp, LoggerProvider)
     assert dict(tp.resource.attributes)["service.name"] == "t"
+    # SnapStart-safe IDs: the tracer provider must not use the default MT-backed
+    # generator, otherwise restored envs emit duplicate trace/span IDs.
+    assert isinstance(tp.id_generator, config_mod._SystemRandomIdGenerator)
 
 
 def test_configure_reuses_existing_sdk_provider(monkeypatch):