iCode-TUI 0.29.1__py3-none-any.whl

chrys/foundation/net/route_probe.py

@@ -0,0 +1,94 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Whether this machine's routing table has a way out at all.
+
+Only adds a "seems offline" hint to a network error the classifier already
+named; it never changes a kind or a retry verdict.  A UDP ``connect()`` asks
+the kernel for a route and sends nothing, so the probe costs two syscalls
+and may run on the event loop.
+"""
+
+from __future__ import annotations
+
+import logging
+import socket
+import sys
+from typing import Literal
+
+from chrys.foundation.errors.network import NetworkCodes, codes_for
+
+from .address_class import is_restricted_address, literal_address, names_this_host
+
+logger = logging.getLogger(__name__)
+
+# RFC 5737 and RFC 3849 documentation addresses: routed like any public
+# address, owned by no one.
+_PROBES: tuple[tuple[socket.AddressFamily, tuple[str, int]], ...] = (
+    (socket.AF_INET, ("192.0.2.1", 9)),
+    (socket.AF_INET6, ("2001:db8::1", 9)),
+)
+
+
+# A family this machine has no stack for (IPv6 on a host without it) says
+# nothing about the network.
+type _Verdict = bool | Literal["absent"] | None
+
+
+def _no_route_codes(codes: NetworkCodes) -> frozenset[int]:
+    found = {codes.enetunreach, codes.enetdown, codes.ehostunreach, codes.eaddrnotavail}
+    if codes.windows:
+        found |= {codes.win_netunreach, codes.win_hostunreach}
+    return frozenset(found)
+
+
+def _family_has_route(family: socket.AddressFamily, address: tuple[str, int], codes: NetworkCodes) -> _Verdict:
+    try:
+        with socket.socket(family, socket.SOCK_DGRAM) as probe:
+            probe.connect(address)
+    except OSError as exc:
+        answered = {exc.errno, getattr(exc, "winerror", None)}
+        if codes.eafnosupport in answered:
+            return "absent"
+        return False if answered & _no_route_codes(codes) else None
+    return True
+
+
+def default_route_available() -> bool | None:
+    """Return whether either address family has a route to the internet; None when that can't be told.
+
+    False needs every family this machine has to answer "no route" (network
+    or host unreachable, network down, no usable source address); a family
+    it has no stack for doesn't count, and with none left the answer is
+    None.  Any other failure, including one from a test's egress guard, is
+    None.  A full
+    tunnel (VPN, TUN-mode proxy) makes this True while offline: the hint is
+    then missing, never wrong.
+    """
+    try:
+        codes = codes_for(sys.platform)
+        if codes is None:
+            return None
+        verdicts: list[_Verdict] = []
+        for family, address in _PROBES:
+            verdict = _family_has_route(family, address, codes)
+            if verdict is True:
+                return True
+            verdicts.append(verdict)
+    except Exception:
+        logger.debug("Default route probe failed", exc_info=True)
+        return None
+    present = [verdict for verdict in verdicts if verdict != "absent"]
+    return False if present and all(verdict is False for verdict in present) else None
+
+
+def is_local_target(host: str) -> bool:
+    """Return whether *host* is this machine or on a private network, where the internet's route says nothing.
+
+    Covers ``localhost`` names, mDNS ``.local`` names, and loopback, private,
+    link-local, ULA and other non-global address literals.
+    """
+    name = host.rstrip(".").lower()
+    if names_this_host(name) or name.endswith(".local"):
+        return True
+    address = literal_address(name)
+    return address is not None and is_restricted_address(address)

chrys/foundation/net/url.py

@@ -0,0 +1,107 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Strict URL and hostname normalization for web egress and its settings.
+
+The settings validators and the web tools share these functions, so a value
+the settings panel accepts is exactly a value the tools can dial.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import unicodedata
+from urllib.parse import quote, urlsplit, urlunsplit
+
+import idna
+
+# DNS permits underscores (service records, docker-compose names, some bucket
+# hosts) and browsers accept them; IDNA's STD3 rules do not.
+_UNDERSCORE_LABEL = re.compile(r"(?!-)[a-z0-9_-]{1,63}(?<!-)\Z")
+# Format characters (bidi overrides, zero-width spaces) and non-ASCII spaces
+# reorder or hide part of a URL wherever it is shown or linked. Encoding them
+# changes nothing on the wire, where the client percent-encodes them anyway.
+_INVISIBLE_CATEGORIES = frozenset({"Cf", "Zs", "Zl", "Zp"})
+
+
+def _encode_invisible(text: str) -> str:
+    if text.isascii():
+        return text
+    return "".join(quote(c, safe="") if unicodedata.category(c) in _INVISIBLE_CATEGORIES else c for c in text)
+
+
+def hostname(value: str) -> str:
+    """Normalize an exact DNS hostname or IP literal; never accept URL syntax."""
+    if not isinstance(value, str) or not value or any(c.isspace() for c in value):
+        raise ValueError("Invalid hostname")
+    if any(c in value for c in "/@?#\\%*"):
+        raise ValueError("Invalid hostname")
+    value = value.rstrip(".").lower()
+    try:
+        return str(ipaddress.ip_address(value))
+    except ValueError:
+        pass
+    if "_" not in value:
+        return idna.encode(value, uts46=True, std3_rules=True).decode("ascii").rstrip(".")
+    if not value.isascii():
+        raise ValueError("Invalid hostname")
+    labels = []
+    for label in value.split("."):
+        if "_" in label:
+            if _UNDERSCORE_LABEL.fullmatch(label) is None:
+                raise ValueError("Invalid hostname")
+            labels.append(label)
+        else:
+            labels.append(idna.encode(label, uts46=True, std3_rules=True).decode("ascii"))
+    result = ".".join(labels)
+    if len(result) > 253:
+        raise ValueError("Invalid hostname")
+    return result
+
+
+def normalize_url(value: str, *, limit: int = 2048, endpoint: bool = False) -> str:
+    """Keep path/query spelling, normalize the authority, and remove fragments."""
+    if not isinstance(value, str) or not value or len(value) > limit:
+        raise ValueError("Invalid URL length")
+    # C1 controls are rejected with C0: a URL reaches terminal hyperlinks and
+    # display text, where U+0080-U+009F act as escape sequences.
+    if any(ord(c) <= 32 or 127 <= ord(c) <= 159 for c in value) or "\\" in value:
+        raise ValueError("Invalid URL characters")
+    parts = urlsplit(value)
+    if parts.scheme.lower() not in {"http", "https"} or not parts.hostname or parts.username is not None:
+        raise ValueError("An absolute HTTP(S) URL without credentials is required")
+    host = hostname(parts.hostname)
+    port = parts.port
+    if port is not None and not 1 <= port <= 65535:
+        raise ValueError("Invalid port")
+    if endpoint and (parts.query or parts.fragment):
+        raise ValueError("Endpoints cannot contain query strings or fragments")
+    authority = f"[{host}]" if ":" in host else host
+    if port is not None and port != (443 if parts.scheme.lower() == "https" else 80):
+        authority += f":{port}"
+    path, query = _encode_invisible(parts.path), _encode_invisible(parts.query)
+    return urlunsplit((parts.scheme.lower(), authority, path or "/", query, ""))
+
+
+def origin(url: str) -> str:
+    """Return the normalized scheme/authority identity."""
+    parts = urlsplit(normalize_url(url, limit=16384))
+    return f"{parts.scheme}://{parts.netloc}"
+
+
+def normalize_origin(value: str) -> str:
+    """Validate an exact origin, without paths, query strings or fragments."""
+    url = normalize_url(value, endpoint=True)
+    if urlsplit(url).path != "/":
+        raise ValueError("An origin cannot contain a path")
+    return origin(url)
+
+
+def same_site(left: str, right: str) -> bool:
+    """Permit only same scheme/port and an optional www prefix change."""
+    a, b = urlsplit(left), urlsplit(right)
+    return (a.scheme, a.port, (a.hostname or "").removeprefix("www.")) == (
+        b.scheme,
+        b.port,
+        (b.hostname or "").removeprefix("www."),
+    )

chrys/foundation/observability/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Telemetry — logging, metrics, and data collection."""

chrys/foundation/observability/exporters.py

@@ -0,0 +1,174 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""SDK-dependent OpenTelemetry exporters and span processor for Chrys.
+
+This module imports from ``opentelemetry.sdk.*`` at module level and is
+ONLY loaded by :func:`chrys.foundation.observability.setup.setup_otel` after confirming
+the SDK is available.  Engine code must not import this module directly
+— use :func:`chrys.foundation.observability.sink.get_otel_sink` instead, which
+has no SDK dependency.
+
+Provides:
+
+* :class:`SessionJsonlSpanExporter` — serialises spans to JSONL and
+  hands them to :meth:`OtelSessionSink.write_spans`.
+* :class:`SessionJsonlLogExporter` — same for log records.
+* :class:`SessionContextSpanProcessor` — stamps ``chrys.session_id``
+  and ``gen_ai.conversation.id`` on every span at ``on_start``.  The
+  kernel's ``_get_span_attributes`` omits ``None`` values, so the later
+  attribute setter preserves injected conversation ids when the provider
+  supplies none (the Anthropic / OpenAI Chat Completions path).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+from opentelemetry.sdk._logs.export import LogRecordExporter, LogRecordExportResult
+from opentelemetry.sdk.trace import SpanProcessor
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from opentelemetry.context import Context
+    from opentelemetry.sdk._logs import ReadableLogRecord
+    from opentelemetry.sdk.trace import ReadableSpan, Span
+
+    from chrys.foundation.observability.sink import OtelSessionSink
+
+logger = logging.getLogger(__name__)
+
+
+# --- Exporters ----------------------------------------------------------------
+
+
+class SessionJsonlSpanExporter(SpanExporter):
+    """Writes exported spans as one JSONL line each via the session sink."""
+
+    def __init__(self, sink: OtelSessionSink) -> None:
+        self._sink = sink
+
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        try:
+            lines = [json.dumps(_span_to_dict(s), default=str, ensure_ascii=False) + "\n" for s in spans]
+            self._sink.write_spans(lines)
+        except Exception:
+            logger.exception("SessionJsonlSpanExporter.export failed")
+            return SpanExportResult.FAILURE
+        return SpanExportResult.SUCCESS
+
+    def shutdown(self) -> None:
+        """No-op — files are opened/closed per write by the sink."""
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True
+
+
+class SessionJsonlLogExporter(LogRecordExporter):
+    """Writes exported log records as one JSONL line each via the sink."""
+
+    def __init__(self, sink: OtelSessionSink) -> None:
+        self._sink = sink
+
+    def export(self, batch: Sequence[ReadableLogRecord]) -> LogRecordExportResult:
+        try:
+            lines = [json.dumps(_log_to_dict(d), default=str, ensure_ascii=False) + "\n" for d in batch]
+            self._sink.write_logs(lines)
+        except Exception:
+            logger.exception("SessionJsonlLogExporter.export failed")
+            return LogRecordExportResult.FAILURE
+        return LogRecordExportResult.SUCCESS
+
+    def shutdown(self) -> None:
+        """No-op."""
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True
+
+
+# --- Attribute injection ------------------------------------------------------
+
+
+class SessionContextSpanProcessor(SpanProcessor):
+    """Stamp the active session id and a fallback conversation id on each span.
+
+    Injection must run in ``on_start``, before kernel instrumentation calls
+    ``span.set_attributes(...)``. ``_get_span_attributes`` omits ``None`` values,
+    so the later setter preserves our fallback when the provider supplies no
+    conversation id. An explicit provider conversation id overwrites it.
+    """
+
+    def __init__(self, sink: OtelSessionSink) -> None:
+        self._sink = sink
+
+    def on_start(self, span: Span, parent_context: Context | None = None) -> None:
+        sid = self._sink.session_id
+        if sid:
+            span.set_attribute("chrys.session_id", sid)
+            span.set_attribute("gen_ai.conversation.id", sid)
+
+    def on_end(self, span: ReadableSpan) -> None:
+        """No-op — attribute injection happens at start."""
+
+
+# --- Serialization helpers ----------------------------------------------------
+
+
+def _span_to_dict(span: ReadableSpan) -> dict[str, Any]:
+    """Convert a ReadableSpan to a JSON-safe dict with GenAI fields promoted."""
+    ctx = span.get_span_context()
+    parent = span.parent
+    status = span.status
+    return {
+        "timestamp": datetime.now(UTC).isoformat(),
+        "name": span.name,
+        "kind": span.kind.name if span.kind else None,
+        "trace_id": f"{ctx.trace_id:032x}" if ctx else None,
+        "span_id": f"{ctx.span_id:016x}" if ctx else None,
+        "parent_span_id": f"{parent.span_id:016x}" if parent else None,
+        "start_time_ns": span.start_time,
+        "end_time_ns": span.end_time,
+        "duration_ns": (span.end_time - span.start_time) if (span.start_time and span.end_time) else None,
+        "status": {
+            "code": status.status_code.name if status else None,
+            "description": status.description if status else None,
+        },
+        "attributes": dict(span.attributes) if span.attributes else {},
+        "events": [
+            {
+                "name": e.name,
+                "timestamp_ns": e.timestamp,
+                "attributes": dict(e.attributes) if e.attributes else {},
+            }
+            for e in (span.events or [])
+        ],
+        "resource": dict(span.resource.attributes) if span.resource else {},
+    }
+
+
+def _log_to_dict(data: ReadableLogRecord) -> dict[str, Any]:
+    """Convert a ReadableLogRecord to a JSON-safe dict.
+
+    ``ReadableLogRecord`` wraps a ``LogRecord`` and an ``InstrumentationScope``;
+    we flatten the bits that matter for debugging.
+    """
+    rec = data.log_record
+    return {
+        "timestamp": datetime.now(UTC).isoformat(),
+        "observed_timestamp_ns": rec.observed_timestamp,
+        "timestamp_ns": rec.timestamp,
+        "severity_text": rec.severity_text,
+        "severity_number": rec.severity_number.value if rec.severity_number else None,
+        "body": rec.body,
+        "attributes": dict(rec.attributes) if rec.attributes else {},
+        "trace_id": f"{rec.trace_id:032x}" if rec.trace_id else None,
+        "span_id": f"{rec.span_id:016x}" if rec.span_id else None,
+        "scope": {
+            "name": data.instrumentation_scope.name if data.instrumentation_scope else None,
+            "version": data.instrumentation_scope.version if data.instrumentation_scope else None,
+        },
+    }

chrys/foundation/observability/gate.py

@@ -0,0 +1,31 @@
+# Copyright (c) Huawei Technologies Co., Ltd. 2026. All rights reserved.
+
+"""Process-wide telemetry gate shared by foundation setup and kernel spans."""
+
+from __future__ import annotations
+
+
+class TelemetryGate:
+    """Process-wide switch shared by Chrys telemetry emitters.
+
+    Both flags default off. ``configure_telemetry`` sets them during provider
+    setup; the gate itself reads no environment variables.
+    """
+
+    def __init__(self) -> None:
+        self.enabled: bool = False
+        self.sensitive_data: bool = False
+
+    @property
+    def sensitive_enabled(self) -> bool:
+        """Allow sensitive capture only when telemetry and sensitive data are both enabled."""
+        return self.enabled and self.sensitive_data
+
+
+TELEMETRY_GATE = TelemetryGate()
+
+
+def configure_telemetry(*, enabled: bool, sensitive_data: bool = False) -> None:
+    """Flip the telemetry gate (``setup_otel`` closes it at entry, reopens on success)."""
+    TELEMETRY_GATE.enabled = enabled
+    TELEMETRY_GATE.sensitive_data = sensitive_data