iii-sdk 0.11.7.dev1__tar.gz → 0.11.7.dev3__tar.gz

{iii_sdk-0.11.7.dev1 → iii_sdk-0.11.7.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: iii-sdk
-Version: 0.11.7.dev1
+Version: 0.11.7.dev3
 Summary: III SDK for Python
 Project-URL: Homepage, https://github.com/iii-hq/iii
 Project-URL: Repository, https://github.com/iii-hq/iii

{iii_sdk-0.11.7.dev1 → iii_sdk-0.11.7.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "iii-sdk"
-version = "0.11.7.dev1"
+version = "0.11.7.dev3"
 description = "III SDK for Python"
 authors = [{ name = "III" }]
 license = { text = "Apache-2.0" }

{iii_sdk-0.11.7.dev1 → iii_sdk-0.11.7.dev3}/src/iii/__init__.py

@@ -1,5 +1,6 @@
 """III SDK for Python."""
 
+from .baggage_span_processor import DEFAULT_ALLOWLIST, BaggageSpanProcessor
 from .channels import ChannelReader, ChannelWriter
 from .errors import IIIForbiddenError, IIIInvocationError, IIITimeoutError
 from .format_utils import extract_request_format, extract_response_format, python_type_to_format
@@ -35,6 +36,18 @@ from .iii_types import (
     TriggerTypeInfo,
 )
 from .logger import Logger
+from .payload import (
+    REDACTED_PLACEHOLDER,
+    redact,
+    redact_and_truncate,
+    resolve_max_bytes_from_env,
+)
+from .span_ops import (
+    current_span_is_recording,
+    record_span_event,
+    set_current_span_attribute,
+    set_current_span_error,
+)
 from .stream import (
     IStream,
     StreamChangeEvent,
@@ -59,6 +72,17 @@ from .types import (
 from .utils import http
 
 __all__ = [
+    # Telemetry helpers
+    "BaggageSpanProcessor",
+    "DEFAULT_ALLOWLIST",
+    "REDACTED_PLACEHOLDER",
+    "current_span_is_recording",
+    "record_span_event",
+    "set_current_span_attribute",
+    "set_current_span_error",
+    "redact",
+    "redact_and_truncate",
+    "resolve_max_bytes_from_env",
     # Channels
     "ChannelReader",
     "ChannelWriter",

iii_sdk-0.11.7.dev3/src/iii/baggage_span_processor.py

@@ -0,0 +1,42 @@
+"""Baggage -> span attribute processor."""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+from opentelemetry import baggage
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor
+
+#: DEFAULT_ALLOWLIST drift across languages would break worker chains;
+#: lockstep tests in each SDK pin this constant at CI time.
+DEFAULT_ALLOWLIST: tuple[str, ...] = (
+    "iii.session.id",
+    "iii.message.id",
+    "iii.function.id",
+)
+
+
+class BaggageSpanProcessor(SpanProcessor):
+
+    def __init__(self, allowlist: Sequence[str] = DEFAULT_ALLOWLIST) -> None:
+        self._allowlist: tuple[str, ...] = tuple(allowlist)
+
+    def on_start(self, span: Span, parent_context: Context | None = None) -> None:
+        # NoOp guard: skip allocation when sampler drops the span.
+        if not span.is_recording():
+            return
+
+        for key in self._allowlist:
+            value = baggage.get_baggage(key, parent_context)
+            if value is not None:
+                span.set_attribute(key, str(value))
+
+    def on_end(self, span: ReadableSpan) -> None:  # noqa: ARG002
+        pass
+
+    def shutdown(self) -> None:
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:  # noqa: ARG002
+        return True

{iii_sdk-0.11.7.dev1 → iii_sdk-0.11.7.dev3}/src/iii/iii.py

@@ -500,17 +500,58 @@ class III:
             propagate.extract(carrier) if carrier else otel_context.get_current()
         )
         tracer = trace.get_tracer("iii-python-sdk")
+        import os
+
+        from .payload import redact_and_truncate, resolve_max_bytes_from_env
+
+        trace_payloads = os.environ.get("III_DISABLE_TRACE_PAYLOADS", "").lower() not in (
+            "1",
+            "true",
+        )
+        payload_max_bytes = resolve_max_bytes_from_env()
+
         with tracer.start_as_current_span(
             f"call {handler.__name__}",
             context=parent_ctx,
             kind=trace.SpanKind.SERVER,
         ) as span:
+            if trace_payloads and span.is_recording():
+                input_json, input_truncated = redact_and_truncate(data, payload_max_bytes)
+                span.add_event(
+                    "iii.invocation.input",
+                    attributes={
+                        "iii.payload.json": input_json,
+                        "iii.payload.truncated": input_truncated,
+                    },
+                )
             try:
                 result = await handler(data)
+                if trace_payloads and span.is_recording():
+                    out_json, out_truncated = redact_and_truncate(result, payload_max_bytes)
+                    span.add_event(
+                        "iii.invocation.output",
+                        attributes={
+                            "iii.payload.json": out_json,
+                            "iii.payload.truncated": out_truncated,
+                            "iii.payload.ok": True,
+                        },
+                    )
                 span.set_status(trace.StatusCode.OK)
                 response_traceparent = self._inject_traceparent()
                 return result, response_traceparent
             except Exception as e:
+                if trace_payloads and span.is_recording():
+                    err_json, err_truncated = redact_and_truncate(
+                        {"error": str(e)}, payload_max_bytes
+                    )
+                    span.add_event(
+                        "iii.invocation.output",
+                        attributes={
+                            "iii.payload.json": err_json,
+                            "iii.payload.truncated": err_truncated,
+                            "iii.payload.ok": False,
+                        },
+                    )
                 span.record_exception(e)
                 span.set_status(trace.StatusCode.ERROR, str(e))
                 response_traceparent = self._inject_traceparent()

iii_sdk-0.11.7.dev3/src/iii/payload.py

@@ -0,0 +1,92 @@
+"""Payload redaction + truncation for invocation event capture."""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any, Optional
+
+REDACTED_PLACEHOLDER = "[REDACTED]"
+_TRUNCATION_MARKER = '..."[TRUNCATED]"'
+
+
+def resolve_max_bytes_from_env() -> Optional[int]:
+    raw = os.environ.get("III_TRACE_PAYLOAD_MAX_BYTES")
+    if raw is None:
+        return None
+    trimmed = raw.strip()
+    if not trimmed or trimmed.lower() == "unlimited":
+        return None
+    try:
+        parsed = int(trimmed)
+    except ValueError:
+        return None
+    if parsed <= 0:
+        return None
+    return parsed
+
+_SENSITIVE_FRAGMENTS = (
+    "api_key",
+    "apikey",
+    "api-key",
+    "password",
+    "secret",
+    "credential",
+    "authorization",
+    "auth_token",
+    "access_token",
+    "refresh_token",
+    "bearer",
+    "private_key",
+    "client_secret",
+)
+
+
+def _is_sensitive_key(key: str) -> bool:
+    lower = key.lower()
+    if any(fragment in lower for fragment in _SENSITIVE_FRAGMENTS):
+        return True
+    # ``token`` alone is too common a substring; require whole-key or suffix match.
+    return lower == "token" or lower.endswith("_token") or lower.endswith("-token")
+
+
+def redact(value: Any) -> Any:
+    if isinstance(value, dict):
+        return {
+            k: REDACTED_PLACEHOLDER if _is_sensitive_key(k) else redact(v)
+            for k, v in value.items()
+        }
+    if isinstance(value, list):
+        return [redact(item) for item in value]
+    if isinstance(value, tuple):
+        return tuple(redact(item) for item in value)
+    return value
+
+
+def redact_and_truncate(
+    value: Any, max_bytes: Optional[int] = None
+) -> tuple[str, bool]:
+    redacted = redact(value)
+    try:
+        serialized = json.dumps(redacted, default=str, ensure_ascii=False)
+    except (TypeError, ValueError):
+        serialized = "null"
+
+    if max_bytes is None or max_bytes <= 0:
+        return serialized, False
+
+    encoded = serialized.encode("utf-8")
+    if len(encoded) <= max_bytes:
+        return serialized, False
+
+    marker_len = len(_TRUNCATION_MARKER.encode("utf-8"))
+    if max_bytes <= marker_len:
+        return _TRUNCATION_MARKER[:max_bytes], True
+
+    cap = max_bytes - marker_len
+    # Walk back to a UTF-8 boundary so we don't emit half-codepoints.
+    cut = cap
+    while cut > 0 and (encoded[cut] & 0xC0) == 0x80:
+        cut -= 1
+    truncated = encoded[:cut].decode("utf-8", errors="ignore") + _TRUNCATION_MARKER
+    return truncated, True

iii_sdk-0.11.7.dev3/src/iii/span_ops.py

@@ -0,0 +1,38 @@
+"""High-level span operations so consumers don't need ``opentelemetry``."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from opentelemetry import trace
+from opentelemetry.trace import Status, StatusCode
+
+
+def current_span_is_recording() -> bool:
+    """Returns ``False`` when there is no active span or the sampler dropped it."""
+    span = trace.get_current_span()
+    return bool(span and span.is_recording())
+
+
+def set_current_span_attribute(key: str, value: Any) -> None:
+    """No-op when the current span is not recording."""
+    span = trace.get_current_span()
+    if not span or not span.is_recording():
+        return
+    span.set_attribute(key, value)
+
+
+def set_current_span_error(message: str) -> None:
+    """No-op when there is no active span."""
+    span = trace.get_current_span()
+    if not span:
+        return
+    span.set_status(Status(StatusCode.ERROR, message))
+
+
+def record_span_event(name: str, attrs: dict[str, Any] | None = None) -> None:
+    """No-op when the current span is not recording."""
+    span = trace.get_current_span()
+    if not span or not span.is_recording():
+        return
+    span.add_event(name, attributes=attrs or {})

{iii_sdk-0.11.7.dev1 → iii_sdk-0.11.7.dev3}/src/iii/stream.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from abc import ABC, abstractmethod
 from typing import Any, Generic, List, Literal, TypeVar
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_serializer
 
 TData = TypeVar("TData")
 
@@ -117,11 +117,13 @@ class StreamUpdateResult(BaseModel, Generic[TData]):
 
     old_value: TData | None = None
     new_value: TData
-    # Per-op errors. Currently emitted only by the ``merge`` op for
-    # validation rejections. Field is omitted from the JSON wire when
-    # empty. ``default_factory`` is used (not ``= []``) to keep
-    # Pydantic's parameterized-Generic + default handling well-behaved
-    # across Python versions.
+    # Per-op errors. Emitted by ``merge`` and ``append`` for validation
+    # rejections (path/value bounds, proto-pollution segments) and by
+    # ``append`` for the ``append.type_mismatch`` and
+    # ``append.target_not_object`` surfaces. Field is omitted from the
+    # JSON wire when empty. ``default_factory`` is used (not ``= []``)
+    # to keep Pydantic's parameterized-Generic + default handling
+    # well-behaved across Python versions.
     errors: list[UpdateOpError] = Field(default_factory=list)
 
 
@@ -156,12 +158,57 @@ class UpdateDecrement(BaseModel):
 
 
 class UpdateAppend(BaseModel):
-    """Append operation for stream update."""
+    """Append an element to an array, concatenate a string, or push at a nested path.
+
+    The target is the root (when ``path`` is omitted, an empty string,
+    or an empty list), a single first-level key (when ``path`` is a
+    non-empty string), or an arbitrary nested location (when ``path``
+    is a list of literal segments).
+
+    Path forms accepted (mirrors :class:`UpdateMerge` after #1547):
+      - ``None`` / ``""`` / ``[]``: append at the root.
+      - ``"foo"``: append at the first-level key ``foo``. A dotted
+        string like ``"a.b"`` is the literal key ``"a.b"``, *not*
+        traversed as ``a -> b``.
+      - ``["a", "b", "c"]``: nested path; each element is a literal
+        segment.
+
+    Engine semantics:
+      - Missing/non-object intermediates along a nested path are
+        auto-created/replaced with ``{}``.
+      - At the leaf:
+          - missing/null + nested path -> ``[value]`` (always an array)
+          - missing/null + single-string path -> string-as-string for
+            the string-concat tier, otherwise ``[value]``
+          - existing array -> push
+          - existing string + string value -> concatenate
+          - existing object/scalar at the leaf -> ``append.type_mismatch``
+
+    Validation: invalid paths (depth > 32 segments, segment > 256
+    bytes, or any ``__proto__`` / ``constructor`` / ``prototype``
+    segment) are rejected with a structured error in the ``errors``
+    field of the ``state::update`` / ``stream::update`` response. The
+    append does not apply when an error is returned for that op.
+    """
 
     type: str = "append"
-    path: str
+    # Optional. Accepts a single string (legacy / first-level key) or
+    # a list of literal segments (nested append). ``None`` / ``""`` /
+    # ``[]`` all route to root append.
+    path: str | list[str] | None = None
     value: Any
 
+    @model_serializer(mode="wrap")
+    def _omit_none_path(self, handler):  # type: ignore[no-untyped-def]
+        # Drop ``path: None`` from the wire so cross-SDK consumers see
+        # the field absent rather than ``null``. Mirrors the Rust
+        # ``#[serde(skip_serializing_if = "Option::is_none")]`` on
+        # ``UpdateOp::Append.path``.
+        data = handler(self)
+        if data.get("path") is None:
+            data.pop("path", None)
+        return data
+
 
 class UpdateRemove(BaseModel):
     """Remove operation for stream update."""
@@ -205,6 +252,16 @@ class UpdateMerge(BaseModel):
     path: str | list[str] | None = None
     value: Any
 
+    @model_serializer(mode="wrap")
+    def _omit_none_path(self, handler):  # type: ignore[no-untyped-def]
+        # Mirrors the same skip-when-none rule applied to
+        # ``UpdateOp::Merge.path`` in the Rust SDK so cross-SDK wire
+        # payloads are byte-identical for root merges.
+        data = handler(self)
+        if data.get("path") is None:
+            data.pop("path", None)
+        return data
+
 
 UpdateOp = UpdateSet | UpdateIncrement | UpdateDecrement | UpdateAppend | UpdateRemove | UpdateMerge
 

{iii_sdk-0.11.7.dev1 → iii_sdk-0.11.7.dev3}/src/iii/telemetry.py

@@ -107,6 +107,12 @@ def init_otel(
 
     span_exporter = EngineSpanExporter(_connection)
     provider = TracerProvider(resource=resource)
+    # BaggageSpanProcessor must register first: on_start fires in
+    # registration order, so baggage entries are materialized as span
+    # attributes before the batch exporter reads them.
+    from .baggage_span_processor import BaggageSpanProcessor
+
+    provider.add_span_processor(BaggageSpanProcessor())
     provider.add_span_processor(BatchSpanProcessor(span_exporter))  # type: ignore[arg-type]
     trace.set_tracer_provider(provider)
     _tracer = trace.get_tracer("iii-python-sdk")

{iii_sdk-0.11.7.dev1 → iii_sdk-0.11.7.dev3}/tests/test_api_triggers.py

@@ -87,6 +87,55 @@ async def test_post_endpoint_with_body(engine_http_url, iii_client: III):
     trigger.unregister()
 
 
+@pytest.mark.asyncio
+async def test_raw_json_request_body(engine_http_url, iii_client: III):
+    raw_json = '{"z":2, "a":1}'
+    function_id = "test::api::json::raw::py"
+
+    @http
+    async def handler(req: HttpRequest, response: HttpResponse):
+        raw = await req.request_body.read_all()
+
+        await response.status(200)
+        await response.headers({"content-type": "application/json"})
+        result = json.dumps(
+            {
+                "parsed_body": req.body,
+                "raw_body": raw.decode("utf-8"),
+            }
+        ).encode("utf-8")
+        await response.writer.write(result)
+        await response.writer.close_async()
+
+    fn_ref = iii_client.register_function(function_id, handler)
+    trigger = iii_client.register_trigger(
+        {
+            "type": "http",
+            "function_id": function_id,
+            "config": {
+                "api_path": "/test/py/json/raw",
+                "http_method": "POST",
+            },
+        }
+    )
+
+    time.sleep(0.3)
+
+    async with aiohttp.ClientSession() as session:
+        async with session.post(
+            f"{engine_http_url}/test/py/json/raw",
+            headers={"content-type": "application/json"},
+            data=raw_json,
+        ) as resp:
+            assert resp.status == 200
+            data = await resp.json()
+            assert data["parsed_body"] == {"z": 2, "a": 1}
+            assert data["raw_body"] == raw_json
+
+    fn_ref.unregister()
+    trigger.unregister()
+
+
 @pytest.mark.asyncio
 async def test_path_parameters(engine_http_url, iii_client: III):
     """Verify path parameters are extracted correctly."""

iii_sdk-0.11.7.dev3/tests/test_baggage_span_processor.py

@@ -0,0 +1,162 @@
+"""Unit tests for BaggageSpanProcessor."""
+
+from __future__ import annotations
+
+from opentelemetry import baggage, context
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import SimpleSpanProcessor
+from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
+    InMemorySpanExporter,
+)
+from opentelemetry.sdk.trace.sampling import ALWAYS_OFF
+
+from iii.baggage_span_processor import (
+    DEFAULT_ALLOWLIST,
+    BaggageSpanProcessor,
+)
+
+
+def _build_test_provider(
+    processor: BaggageSpanProcessor,
+) -> tuple[TracerProvider, InMemorySpanExporter]:
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider()
+    provider.add_span_processor(processor)
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    return provider, exporter
+
+
+def _attach_baggage(entries: dict[str, str]):
+    ctx = context.get_current()
+    for key, value in entries.items():
+        ctx = baggage.set_baggage(key, value, ctx)
+    return context.attach(ctx)
+
+
+def _first_span_attr(exporter: InMemorySpanExporter, key: str) -> object | None:
+    spans = exporter.get_finished_spans()
+    if not spans:
+        return None
+    return spans[0].attributes.get(key) if spans[0].attributes else None
+
+
+def test_copies_default_allowlist_from_baggage_to_attributes() -> None:
+    provider, exporter = _build_test_provider(BaggageSpanProcessor())
+    tracer = provider.get_tracer("test")
+
+    token = _attach_baggage(
+        {
+            "iii.session.id": "S-1",
+            "iii.message.id": "M-1",
+            "iii.function.id": "auth::set_token",
+        }
+    )
+    try:
+        with tracer.start_as_current_span("inner"):
+            pass
+    finally:
+        context.detach(token)
+
+    assert _first_span_attr(exporter, "iii.session.id") == "S-1"
+    assert _first_span_attr(exporter, "iii.message.id") == "M-1"
+    assert _first_span_attr(exporter, "iii.function.id") == "auth::set_token"
+
+
+def test_missing_baggage_entry_means_attribute_not_set() -> None:
+    provider, exporter = _build_test_provider(BaggageSpanProcessor())
+    tracer = provider.get_tracer("test")
+
+    token = _attach_baggage({"iii.message.id": "M-only"})
+    try:
+        with tracer.start_as_current_span("inner"):
+            pass
+    finally:
+        context.detach(token)
+
+    assert _first_span_attr(exporter, "iii.message.id") == "M-only"
+    assert _first_span_attr(exporter, "iii.session.id") is None
+    assert _first_span_attr(exporter, "iii.function.id") is None
+
+
+def test_baggage_entries_not_in_allowlist_are_dropped() -> None:
+    provider, exporter = _build_test_provider(BaggageSpanProcessor())
+    tracer = provider.get_tracer("test")
+
+    token = _attach_baggage(
+        {
+            "iii.message.id": "M",
+            "tenant.id": "t-42",
+            "debug.feature_flag": "on",
+        }
+    )
+    try:
+        with tracer.start_as_current_span("inner"):
+            pass
+    finally:
+        context.detach(token)
+
+    assert _first_span_attr(exporter, "iii.message.id") == "M"
+    assert _first_span_attr(exporter, "tenant.id") is None
+    assert _first_span_attr(exporter, "debug.feature_flag") is None
+
+
+def test_custom_allowlist_is_honored() -> None:
+    processor = BaggageSpanProcessor(allowlist=["tenant.id", "iii.message.id"])
+    provider, exporter = _build_test_provider(processor)
+    tracer = provider.get_tracer("test")
+
+    token = _attach_baggage(
+        {
+            "tenant.id": "t-1",
+            "iii.message.id": "M",
+            "iii.session.id": "S-not-copied",
+        }
+    )
+    try:
+        with tracer.start_as_current_span("inner"):
+            pass
+    finally:
+        context.detach(token)
+
+    assert _first_span_attr(exporter, "tenant.id") == "t-1"
+    assert _first_span_attr(exporter, "iii.message.id") == "M"
+    assert _first_span_attr(exporter, "iii.session.id") is None
+
+
+def test_empty_parent_context_produces_no_attributes() -> None:
+    provider, exporter = _build_test_provider(BaggageSpanProcessor())
+    tracer = provider.get_tracer("test")
+
+    with tracer.start_as_current_span("inner"):
+        pass
+
+    assert _first_span_attr(exporter, "iii.session.id") is None
+    assert _first_span_attr(exporter, "iii.message.id") is None
+
+
+def test_noop_guard_skips_processing_when_sampled_out() -> None:
+    exporter = InMemorySpanExporter()
+    provider = TracerProvider(sampler=ALWAYS_OFF)
+    provider.add_span_processor(BaggageSpanProcessor())
+    provider.add_span_processor(SimpleSpanProcessor(exporter))
+    tracer = provider.get_tracer("test")
+
+    token = _attach_baggage(
+        {"iii.session.id": "S-1", "iii.message.id": "M-1"}
+    )
+    try:
+        with tracer.start_as_current_span("inner"):
+            pass
+    finally:
+        context.detach(token)
+
+    assert exporter.get_finished_spans() == ()
+
+
+def test_default_allowlist_matches_other_sdks() -> None:
+    """DEFAULT_ALLOWLIST drift across languages would break worker chains."""
+    assert tuple(DEFAULT_ALLOWLIST) == (
+        "iii.session.id",
+        "iii.message.id",
+        "iii.function.id",
+    )