Home /Modules/http-3.0/sleeuum.py

sleeuum.py

http-3.0/sleeuum.py · 255 line(s) · py

"""sleeuum.py -- Sleeuum(TM), the packet ledger client for SLeeLa executables.

Sleeuum(TM) is the client-side module a SLeeLa executable uses to KEEP TRACK of
the HTTP 3.0 / HTTP 2.0+ packets it sends and receives -- together with their
DATES and their NUMBERS. It does not move bytes itself; it observes the bytes
that the packet builder (http3_transport.py) and the H3 pipeline (http3_flow.py)
already produce, and records a durable, queryable ledger of them.

What Sleeuum(TM) tracks, per the request:

  * PACKETS -- one ledger entry per observed H3 packet, tagged with its HTTP
        carrier (HTTP/1.1, HTTP/2, or raw H3), direction (sent / received),
        service-id, op-id, request-id, wire form (text / binary), and byte size.
  * DATES   -- an ISO-8601 UTC timestamp on every entry, plus the session's
        first-seen and last-seen instants and total duration.
  * NUMBERS -- a monotonic Sleeuum sequence number per entry, the H3 NONCE and
        DIGEST, request-ids, running byte counters, per-status tallies, and the
        BASKET NUMERALS (atomic-number item ids) carried in each packet.

Design stance matches the rest of the stack: observe, don't misrepresent. The
ledger never alters a packet, never forges an integrity field, and reports the
H3 status exactly as the pipeline returned it.

Trademark: "Sleeuum(TM)" -- rendered SLEEUUM_TM below; use the unicode mark
where the display supports it.
"""
from __future__ import annotations

import json
from dataclasses import dataclass, field, asdict
from datetime import datetime, timezone
from typing import Dict, List, Optional

from http3_flow import Envelope, Response, Status, basket_parse
import http3_transport as transport

# Trademark rendering. Prefer the unicode symbol; the ASCII form is a fallback.
SLEEUUM_TM = "Sleeuum\u2122"          # Sleeuum™
SLEEUUM_TM_ASCII = "Sleeuum(TM)"
MODULE_NAME = SLEEUUM_TM


def _now_iso() -> str:
    """Current instant as an ISO-8601 UTC string with a trailing 'Z'."""
    return datetime.now(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z")


# --------------------------------------------------------------------------
# Ledger entry -- one observed packet
# --------------------------------------------------------------------------

@dataclass
class PacketRecord:
    """A single tracked HTTP 3.0 / HTTP 2.0+ packet: its dates and its numbers."""

    # --- Sleeuum numbering ---
    seq: int                       # monotonic Sleeuum sequence number (1-based)
    # --- date ---
    at: str                        # ISO-8601 UTC timestamp of observation
    # --- packet identity ---
    direction: str                 # "sent" | "received"
    carrier: str                   # "http/1.1" | "http/2" | "h3-raw"
    kind: str                      # "request" | "response"
    wire_form: str                 # "text" | "binary"
    # --- H3 numbers (request packets) ---
    service_id: Optional[int] = None
    op_id: Optional[int] = None
    request_id: Optional[int] = None
    nonce: Optional[int] = None
    digest: Optional[int] = None
    intactx: Optional[int] = None
    # --- H3 numbers (response packets) ---
    status: Optional[int] = None
    status_name: Optional[str] = None
    # --- sizes ---
    payload_bytes: int = 0
    wire_bytes: int = 0
    # --- basket numerals carried in this packet (atomic-number item ids) ---
    numerals: List[int] = field(default_factory=list)

    def to_dict(self) -> dict:
        return {k: v for k, v in asdict(self).items() if v is not None}


# --------------------------------------------------------------------------
# The Sleeuum ledger
# --------------------------------------------------------------------------

@dataclass
class SleeuumStats:
    """Rolled-up NUMBERS across everything the ledger has seen."""
    packets: int = 0
    sent: int = 0
    received: int = 0
    requests: int = 0
    responses: int = 0
    total_payload_bytes: int = 0
    total_wire_bytes: int = 0
    by_carrier: Dict[str, int] = field(default_factory=dict)
    by_status: Dict[str, int] = field(default_factory=dict)
    first_seen: Optional[str] = None
    last_seen: Optional[str] = None

    def duration_seconds(self) -> float:
        if not self.first_seen or not self.last_seen:
            return 0.0
        a = datetime.fromisoformat(self.first_seen.replace("Z", "+00:00"))
        b = datetime.fromisoformat(self.last_seen.replace("Z", "+00:00"))
        return (b - a).total_seconds()


class Sleeuum:
    """Sleeuum(TM) -- client ledger of HTTP 3.0 / HTTP 2.0+ packets for a SLeeLa exe.

    Usage:

        led = Sleeuum(name="my-exe")
        wire = transport.build_http2(env, key, include_preface=True)
        led.track_sent(env, carrier=transport.Carrier.HTTP2, wire=wire)
        ...
        led.track_received_wire(response_wire, carrier="http/2")
        print(led.report())
    """

    def __init__(self, name: str = "sleela-exe") -> None:
        self.name = name
        self._records: List[PacketRecord] = []
        self._seq = 0
        self.stats = SleeuumStats()

    # ---- numbering / dating helpers -------------------------------------
    def _next_seq(self) -> int:
        self._seq += 1
        return self._seq

    def _stamp(self, rec: PacketRecord) -> PacketRecord:
        self._records.append(rec)
        s = self.stats
        s.packets += 1
        s.total_payload_bytes += rec.payload_bytes
        s.total_wire_bytes += rec.wire_bytes
        s.by_carrier[rec.carrier] = s.by_carrier.get(rec.carrier, 0) + 1
        if rec.direction == "sent":
            s.sent += 1
        else:
            s.received += 1
        if rec.kind == "request":
            s.requests += 1
        else:
            s.responses += 1
            if rec.status_name:
                s.by_status[rec.status_name] = s.by_status.get(rec.status_name, 0) + 1
        if s.first_seen is None:
            s.first_seen = rec.at
        s.last_seen = rec.at
        return rec

    @staticmethod
    def _numerals_of(env: Envelope) -> List[int]:
        """Basket numerals (atomic-number item ids) carried in this packet.

        basket_parse() returns (iso_numeric, [(number, value), ...]); the numeral
        is each item's `number` (its atomic-number id, per NUMERAL.md).
        """
        try:
            _iso, items = basket_parse(env.basket)
            return [int(number) for (number, _value) in items]
        except Exception:
            return []

    # ---- tracking API ----------------------------------------------------
    def track_sent(self, env: Envelope, *, carrier: str, wire: bytes) -> PacketRecord:
        """Record a request packet the executable is sending."""
        return self._stamp(PacketRecord(
            seq=self._next_seq(), at=_now_iso(), direction="sent", carrier=carrier,
            kind="request",
            wire_form=("binary" if (env.flags & 0x01) else "text"),
            service_id=env.service_id, op_id=env.op_id, request_id=env.request_id,
            nonce=env.nonce, digest=env.digest, intactx=env.intactx,
            payload_bytes=len(env.payload), wire_bytes=len(wire),
            numerals=self._numerals_of(env),
        ))

    def track_received_wire(self, wire: bytes, *, carrier: str = "h3-raw") -> PacketRecord:
        """Record a response packet received (raw H3R bytes or HTTP-wrapped)."""
        raw = wire
        # If it looks like an HTTP message, extract the embedded H3 bytes first.
        if wire[:5] == b"HTTP/" or wire[:3] in (b"GET", b"POS", b"PRI") or b" HTTP/1." in wire[:64]:
            try:
                raw = transport.unwrap(wire)
            except Exception:
                raw = wire
        status_val = None
        status_name = None
        rid = None
        rlen = 0
        try:
            resp = Response.unpack_text(raw)
            status_val = int(resp.status)
            status_name = Status(resp.status).name
            rid = resp.request_id
            rlen = len(resp.result)
        except Exception:
            pass
        return self._stamp(PacketRecord(
            seq=self._next_seq(), at=_now_iso(), direction="received", carrier=carrier,
            kind="response",
            wire_form=("text" if raw[:3] == b"H3R" else "binary"),
            request_id=rid, status=status_val, status_name=status_name,
            payload_bytes=rlen, wire_bytes=len(wire),
        ))

    # ---- reporting -------------------------------------------------------
    def records(self) -> List[PacketRecord]:
        return list(self._records)

    def to_json(self, *, indent: int = 2) -> str:
        """Serialize the full ledger (dates + numbers + packets) to JSON."""
        doc = {
            "module": SLEEUUM_TM,
            "trademark": SLEEUUM_TM,
            "client": self.name,
            "generated": _now_iso(),
            "stats": {
                **asdict(self.stats),
                "duration_seconds": round(self.stats.duration_seconds(), 6),
            },
            "packets": [r.to_dict() for r in self._records],
        }
        return json.dumps(doc, indent=indent, sort_keys=False)

    def report(self) -> str:
        """Short human-readable summary line."""
        s = self.stats
        return (
            f"{SLEEUUM_TM} [{self.name}] "
            f"packets={s.packets} (sent={s.sent} recv={s.received}) "
            f"bytes={s.total_wire_bytes} "
            f"carriers={s.by_carrier or '{}'} statuses={s.by_status or '{}'} "
            f"window={s.first_seen}..{s.last_seen}"
        )


if __name__ == "__main__":
    # Tiny self-demonstration (no network): build a couple of packets and track.
    import http3_flow as f
    key = b"\x11" * f.MAC_KEY_BYTES
    led = Sleeuum(name="demo")
    e = f.Envelope(service_id=7, op_id=3, request_id=1, payload=b"hi", nonce=1)
    e.seal(key)
    w = transport.build_http2(e, key, include_preface=True)
    led.track_sent(e, carrier=transport.Carrier.HTTP2, wire=w)
    led.track_received_wire(f.Response(status=f.Status.OK, request_id=1, result=b"ok").pack_text())
    print(led.report())