constellation-node-sdk 1.2.0__tar.gz → 1.3.2__tar.gz

{constellation_node_sdk-1.2.0 → constellation_node_sdk-1.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: constellation-node-sdk
-Version: 1.2.0
+Version: 1.3.2
 Summary: L9 Constellation Node SDK — TransportPacket runtime, Gate client, and node factory
 License: Proprietary
 Requires-Python: >=3.12

{constellation_node_sdk-1.2.0 → constellation_node_sdk-1.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "constellation-node-sdk"
-version = "1.2.0"
+version = "1.3.2"
 description = "L9 Constellation Node SDK — TransportPacket runtime, Gate client, and node factory"
 readme = "README.md"
 requires-python = ">=3.12"

{constellation_node_sdk-1.2.0 → constellation_node_sdk-1.3.2}/src/constellation_node_sdk/__init__.py

@@ -56,6 +56,13 @@ from constellation_node_sdk.security import (
     validate_transport_packet,
     verify_transport_packet_signature,
 )
+from constellation_node_sdk.trace_context import (
+    TraceContext,
+    TraceContextError,
+    create_root_trace_context,
+    inject_trace_context,
+    parse_trace_context,
+)
 from constellation_node_sdk.transport import (
     DelegationLink,
     RoutingProvenance,
@@ -126,6 +133,8 @@ __all__ = [
     "TransportPacket",
     "TransportSecurity",
     "TransportValidationError",
+    "TraceContext",
+    "TraceContextError",
     "assert_gate_only_destination",
     "assert_local_node_identity",
     "assert_node_origin_packet",
@@ -137,6 +146,7 @@ __all__ = [
     "compute_transport_hash",
     "create_error_transport_packet",
     "create_node_app",
+    "create_root_trace_context",
     "create_transport_packet",
     "ensure_tenant_context",
     "execute_transport_packet",
@@ -144,7 +154,9 @@ __all__ = [
     "get_gate_registration_config_from_env",
     "get_handler",
     "get_runtime_config",
+    "inject_trace_context",
     "load_node_spec",
+    "parse_trace_context",
     "recompute_transport_core",
     "register_from_env",
     "register_handler",

{constellation_node_sdk-1.2.0 → constellation_node_sdk-1.3.2}/src/constellation_node_sdk/gate_authority/dispatch.py

@@ -17,6 +17,7 @@ from constellation_node_sdk._packet_http import (
 from constellation_node_sdk.runtime.inbound_policy import validate_execute_ingress_packet
 from constellation_node_sdk.security.signing import sign_transport_packet
 from constellation_node_sdk.security.validation import validate_transport_packet
+from constellation_node_sdk.trace_context import TraceContext, inject_trace_context
 from constellation_node_sdk.transport.errors import TransportError
 from constellation_node_sdk.transport.packet import TransportPacket
 
@@ -144,6 +145,7 @@ class GateDispatchTransport:
         packet: TransportPacket,
         target_node: str,
         worker_base_url: str,
+        trace_context: TraceContext | None = None,
     ) -> TransportPacket:
         """
         Send a Gate-authored dispatch packet to the worker Gate resolved.
@@ -168,6 +170,10 @@ class GateDispatchTransport:
             target_node: The node name Gate resolved.
             worker_base_url: That node's base URL from Gate's registry. The
                 canonical ``/v1/execute`` endpoint is appended by the SDK.
+            trace_context: Optional validated W3C context authored by Gate.
+                It is transported only as strict ``traceparent`` and optional
+                ``tracestate`` headers; baggage and arbitrary headers are not
+                accepted on this authority boundary.
 
         Returns:
             The validated canonical ``TransportPacket`` the worker returned.
@@ -197,6 +203,13 @@ class GateDispatchTransport:
         signed_packet = self._maybe_sign(packet)
         self._validate_outbound_transport(signed_packet)
         timeout_seconds = self._network_timeout_seconds(signed_packet)
+        trace_headers: dict[str, str] | None = None
+        if trace_context is not None:
+            injected = inject_trace_context({}, trace_context)
+            trace_headers = {"traceparent": str(injected["traceparent"])}
+            tracestate = injected.get("tracestate")
+            if isinstance(tracestate, str):
+                trace_headers["tracestate"] = tracestate
 
         response = await post_packet_json(
             url=execute_url,
@@ -206,6 +219,7 @@ class GateDispatchTransport:
             what=f"worker {normalized_target!r}",
             client=self._client,
             transport=self._transport if self._client is None else None,
+            headers=trace_headers,
         )
         raise_for_status(
             response,

constellation_node_sdk-1.3.2/src/constellation_node_sdk/trace_context.py

@@ -0,0 +1,278 @@
+"""Packet-neutral utilities for W3C Trace Context version 00 headers."""
+
+from __future__ import annotations
+
+import re
+import secrets
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass
+from typing import NoReturn
+
+__all__ = [
+    "TraceContext",
+    "TraceContextError",
+    "create_root_trace_context",
+    "inject_trace_context",
+    "parse_trace_context",
+]
+
+_ERROR_MESSAGE = "invalid W3C trace context"
+_TRACEPARENT_RE = re.compile(
+    r"00-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}\Z",
+    re.ASCII,
+)
+_TRACESTATE_KEY_RE = re.compile(
+    r"(?:[a-z][a-z0-9_*/-]{0,255}|[a-z0-9][a-z0-9_*/-]{0,240}@[a-z][a-z0-9_*/-]{0,13})\Z",
+    re.ASCII,
+)
+_CONTEXT_HEADER_NAMES = frozenset({"traceparent", "tracestate", "baggage"})
+_MAX_SCANNED_HEADER_FIELDS = 64
+_MAX_TRACEPARENT_VALUES = 1
+_MAX_TRACESTATE_FIELD_VALUES = 32
+_MAX_TRACESTATE_LENGTH = 512
+_MAX_TRACESTATE_MEMBERS = 32
+_MAX_TRACESTATE_VALUE_LENGTH = 256
+
+
+class TraceContextError(ValueError):
+    """Raised when W3C trace-context input is malformed or unsafe."""
+
+
+def _raise_invalid() -> NoReturn:
+    raise TraceContextError(_ERROR_MESSAGE) from None
+
+
+def create_root_trace_context() -> TraceContext:
+    """Create a fresh valid, unsampled W3C v00 root context.
+
+    This establishes correlation only. It carries no caller identity, routing
+    authority, packet state, or sampling policy beyond the conservative
+    unsampled default. Deployment-specific sampling remains outside this
+    packet-neutral utility.
+    """
+    while True:
+        trace_id = secrets.token_hex(16)
+        parent_id = secrets.token_hex(8)
+        if trace_id != "0" * 32 and parent_id != "0" * 16:
+            return TraceContext(f"00-{trace_id}-{parent_id}-00")
+
+
+@dataclass(frozen=True, slots=True, repr=False)
+class TraceContext:
+    """Validated W3C version 00 trace headers without packet coupling."""
+
+    traceparent: str
+    tracestate: str | None = None
+
+    def __post_init__(self) -> None:
+        try:
+            traceparent = _validate_traceparent(self.traceparent)
+            tracestate = (
+                None if self.tracestate is None else _normalize_tracestate((self.tracestate,))
+            )
+        except Exception:
+            pass
+        else:
+            object.__setattr__(self, "traceparent", traceparent)
+            object.__setattr__(self, "tracestate", tracestate)
+            return
+        _raise_invalid()
+
+    def __repr__(self) -> str:
+        tracestate = "None" if self.tracestate is None else "<redacted>"
+        return f"TraceContext(traceparent=<redacted>, tracestate={tracestate})"
+
+
+def parse_trace_context(
+    headers: Mapping[str, str | Sequence[str]],
+) -> TraceContext | None:
+    """Parse strict W3C v00 context from case-insensitive HTTP-style headers.
+
+    Baggage is intentionally ignored and never becomes part of ``TraceContext``.
+    A malformed ``tracestate`` is discarded when its ``traceparent`` is valid, as
+    required for receiver interoperability.
+    """
+    try:
+        if not isinstance(headers, Mapping):
+            _raise_invalid()
+
+        traceparent_values: tuple[str, ...] = ()
+        raw_tracestate_fields: list[object] = []
+        traceparent_fields = 0
+        tracestate_fields = 0
+
+        for header_name, header_value in _bounded_mapping_items(headers):
+            if not isinstance(header_name, str):
+                _raise_invalid()
+            normalized_name = header_name.lower()
+            if normalized_name == "traceparent":
+                traceparent_fields += 1
+                if traceparent_fields > 1:
+                    _raise_invalid()
+                traceparent_values = _header_values(
+                    header_value,
+                    maximum=_MAX_TRACEPARENT_VALUES,
+                )
+            elif normalized_name == "tracestate":
+                tracestate_fields += 1
+                raw_tracestate_fields.append(header_value)
+
+        if traceparent_fields == 0:
+            if tracestate_fields:
+                _raise_invalid()
+            return None
+        if len(traceparent_values) != _MAX_TRACEPARENT_VALUES:
+            _raise_invalid()
+
+        traceparent = _validate_traceparent(traceparent_values[0])
+        tracestate: str | None = None
+        if tracestate_fields:
+            try:
+                tracestate_values = _tracestate_header_values(raw_tracestate_fields)
+                tracestate = _normalize_tracestate(
+                    tracestate_values,
+                    allow_empty_members=True,
+                )
+            except Exception:
+                tracestate = None
+
+        return TraceContext(traceparent=traceparent, tracestate=tracestate)
+    except Exception:
+        pass
+    _raise_invalid()
+
+
+def inject_trace_context(headers: Mapping[str, object], context: TraceContext) -> dict[str, object]:
+    """Copy headers, replace trace context, and deliberately drop baggage."""
+    try:
+        if not isinstance(headers, Mapping) or not isinstance(context, TraceContext):
+            _raise_invalid()
+        validated_context = TraceContext(
+            traceparent=context.traceparent,
+            tracestate=context.tracestate,
+        )
+        injected: dict[str, object] = {}
+        for header_name, header_value in _bounded_mapping_items(headers):
+            if not isinstance(header_name, str):
+                _raise_invalid()
+            if header_name.lower() not in _CONTEXT_HEADER_NAMES:
+                injected[header_name] = header_value
+        injected["traceparent"] = validated_context.traceparent
+        if validated_context.tracestate is not None:
+            injected["tracestate"] = validated_context.tracestate
+        return injected
+    except Exception:
+        pass
+    _raise_invalid()
+
+
+def _bounded_mapping_items[HeaderName, HeaderValue](
+    headers: Mapping[HeaderName, HeaderValue],
+) -> Iterator[tuple[HeaderName, HeaderValue]]:
+    """Yield at most a fixed number of mapping fields without using ``items()``."""
+    header_names = iter(headers)
+    for _ in range(_MAX_SCANNED_HEADER_FIELDS):
+        try:
+            header_name = next(header_names)
+        except StopIteration:
+            return
+        yield header_name, headers[header_name]
+    _raise_invalid()
+
+
+def _header_values(value: object, *, maximum: int) -> tuple[str, ...]:
+    """Read a bounded HTTP header value sequence using indexed access only."""
+    if isinstance(value, str):
+        return (value,)
+    if isinstance(value, (bytes, bytearray)) or not isinstance(value, Sequence):
+        _raise_invalid()
+
+    value_count = len(value)
+    if value_count > maximum:
+        _raise_invalid()
+
+    values: list[str] = []
+    for index in range(value_count):
+        item = value[index]
+        if not isinstance(item, str):
+            _raise_invalid()
+        values.append(item)
+    return tuple(values)
+
+
+def _tracestate_header_values(raw_values: Sequence[object]) -> tuple[str, ...]:
+    """Collect bounded tracestate fields without splitting an oversized value."""
+    values: list[str] = []
+    for raw_value in raw_values:
+        remaining = _MAX_TRACESTATE_FIELD_VALUES - len(values)
+        if remaining <= 0:
+            _raise_invalid()
+        for value in _header_values(raw_value, maximum=remaining):
+            if len(value) > _MAX_TRACESTATE_LENGTH:
+                _raise_invalid()
+            values.append(value)
+    return tuple(values)
+
+
+def _validate_traceparent(value: object) -> str:
+    if not isinstance(value, str) or not _TRACEPARENT_RE.fullmatch(value):
+        _raise_invalid()
+    trace_id = value[3:35]
+    parent_id = value[36:52]
+    if trace_id == "0" * 32 or parent_id == "0" * 16:
+        _raise_invalid()
+    return value
+
+
+def _normalize_tracestate(
+    values: Sequence[str],
+    *,
+    allow_empty_members: bool = False,
+) -> str | None:
+    if any(not isinstance(value, str) for value in values):
+        _raise_invalid()
+
+    raw_length = max(len(values) - 1, 0)
+    for value in values:
+        if len(value) > _MAX_TRACESTATE_LENGTH:
+            _raise_invalid()
+        raw_length += len(value)
+        if raw_length > _MAX_TRACESTATE_LENGTH:
+            _raise_invalid()
+
+    members: list[str] = []
+    seen_keys: set[str] = set()
+    for raw_value in values:
+        for raw_member in raw_value.split(","):
+            member = raw_member.strip(" \t")
+            if not member:
+                if allow_empty_members:
+                    continue
+                _raise_invalid()
+            if member.count("=") != 1:
+                _raise_invalid()
+
+            key, value = member.split("=", 1)
+            if not key or not value or key[-1] in " \t" or value[0] in " \t":
+                _raise_invalid()
+            if not _TRACESTATE_KEY_RE.fullmatch(key) or key in seen_keys:
+                _raise_invalid()
+            if len(value) > _MAX_TRACESTATE_VALUE_LENGTH:
+                _raise_invalid()
+            if any(character in ",=" or not 0x20 <= ord(character) <= 0x7E for character in value):
+                _raise_invalid()
+
+            seen_keys.add(key)
+            members.append(f"{key}={value}")
+            if len(members) > _MAX_TRACESTATE_MEMBERS:
+                _raise_invalid()
+
+    if not members:
+        if allow_empty_members:
+            return None
+        _raise_invalid()
+
+    normalized = ",".join(members)
+    if len(normalized) > _MAX_TRACESTATE_LENGTH:
+        _raise_invalid()
+    return normalized

{constellation_node_sdk-1.2.0 → constellation_node_sdk-1.3.2}/src/constellation_node_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: constellation-node-sdk
-Version: 1.2.0
+Version: 1.3.2
 Summary: L9 Constellation Node SDK — TransportPacket runtime, Gate client, and node factory
 License: Proprietary
 Requires-Python: >=3.12

{constellation_node_sdk-1.2.0 → constellation_node_sdk-1.3.2}/src/constellation_node_sdk.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ pyproject.toml
 src/constellation_node_sdk/__init__.py
 src/constellation_node_sdk/_packet_http.py
 src/constellation_node_sdk/py.typed
+src/constellation_node_sdk/trace_context.py
 src/constellation_node_sdk.egg-info/PKG-INFO
 src/constellation_node_sdk.egg-info/SOURCES.txt
 src/constellation_node_sdk.egg-info/dependency_links.txt