nativerelay 0.1.0__py3-none-any.whl

collectors/__init__.py

@@ -0,0 +1 @@
+"""Native platform collectors."""

collectors/linux/__init__.py

@@ -0,0 +1,3 @@
+"""Linux kernel telemetry collector."""
+from .collector import LinuxCollector
+__all__ = ["LinuxCollector"]

collectors/linux/collector.py

@@ -0,0 +1,319 @@
+"""Linux process connector and fanotify collectors (Linux only, stdlib only).
+
+Process lifecycle uses NETLINK_CONNECTOR/CN_PROC. File events use a fanotify
+mount mark, filtered to one requested directory in userspace. No polling is
+used; permission and queue errors are surfaced in capabilities/health.
+"""
+from __future__ import annotations
+import ctypes
+import errno
+from dataclasses import replace
+import os
+import platform
+import re
+import select
+import socket
+import struct
+import threading
+import time
+from pathlib import Path
+
+from nativerelay.collector import Collector
+from nativerelay.model import Capability, CollectorStatus, Event, EventType, Process, Resource
+from nativerelay.stream import EventStream
+
+NETLINK_CONNECTOR = 11
+CN_IDX_PROC = 1
+CN_VAL_PROC = 1
+NLMSG_DONE = 3
+NLMSG_OVERRUN = 4
+PROC_EVENT_FORK = 0x00000001
+PROC_EVENT_EXIT = 0x80000000
+PROC_CN_MCAST_LISTEN = 1
+FAN_CLOEXEC = 0x00000001
+FAN_CLASS_NOTIF = 0x00000000
+FAN_NONBLOCK = 0x00000002
+FAN_MARK_ADD = 0x00000001
+FAN_MARK_MOUNT = 0x00000010
+FAN_MODIFY = 0x00000002
+FAN_OPEN = 0x00000020
+FAN_Q_OVERFLOW = 0x00004000
+FANOTIFY_METADATA_VERSION = 3
+FANOTIFY_METADATA_LEN = 24
+FAN_EVENT_METADATA_FMT = "=IBBHQii"
+
+class LinuxCollector(Collector):
+    name = "linux-kernel"
+    def __init__(self, scope: str, *, include_command: bool = False):
+        if platform.system() != "Linux":
+            raise OSError("LinuxCollector is available only on Linux")
+        self.scope = Path(scope).resolve(strict=True)
+        if not self.scope.is_dir(): raise ValueError("scope must be an existing directory")
+        self.include_command = include_command
+        self._stream = None
+        self._sockets = []
+        self._threads = []
+        self._stop = threading.Event()
+        self._publish_lock = threading.Lock()
+        self._sequence = 0
+        self.health = {"process": "not_started", "filesystem": "not_started", "dropped": 0, "errors": []}
+        self._caps = self._initial_capabilities()
+
+    def _initial_capabilities(self):
+        return tuple(Capability(t, CollectorStatus.SUPPORTED if t in (EventType.PROCESS_STARTED, EventType.PROCESS_EXITED, EventType.FILE_OPENED, EventType.FILE_MODIFIED) else CollectorStatus.UNSUPPORTED,
+                 "collector has not started" if t in (EventType.PROCESS_STARTED, EventType.PROCESS_EXITED, EventType.FILE_OPENED, EventType.FILE_MODIFIED) else
+                 "This collector does not infer namespace changes from file content notifications",
+                 "host process table" if t.value.startswith("process") else str(self.scope),
+                 "kernel PID/TGID" if t.value.startswith("process") else "fanotify event PID") for t in EventType)
+
+    @property
+    def capabilities(self): return self._caps
+
+    @property
+    def status(self):
+        losses = self._stream.losses if self._stream is not None else getattr(self, "_last_stream_losses", {})
+        generation = self._stream.loss_generation if self._stream is not None else getattr(self, "_last_loss_generation", 0)
+        return {**self.health, "errors": list(self.health["errors"]), "losses": losses, "loss_generation": generation}
+
+    def start(self, stream: EventStream):
+        if self._stream is not None: raise RuntimeError("collector already started")
+        self._stop = threading.Event()
+        self._publish_lock = threading.Lock()
+        self._sequence = 0
+        self.health = {"process": "not_started", "filesystem": "not_started", "dropped": 0, "errors": []}
+        self._caps = self._initial_capabilities()
+        self._stream = stream
+        self._last_stream_losses = {}
+        self._start_process()
+        self._start_filesystem()
+
+    def stop(self):
+        if self._stream is None: return
+        self._stop.set()
+        for sock in self._sockets:
+            try:
+                if isinstance(sock, int): os.close(sock)
+                else: sock.close()
+            except OSError: pass
+        for thread in self._threads: thread.join(timeout=2)
+        self._last_stream_losses = self._stream.losses
+        self._last_loss_generation = self._stream.loss_generation
+        self._stream.close()
+        self._sockets.clear(); self._threads.clear(); self._stream = None
+
+    def _failure(self, subsystem, exc):
+        status = CollectorStatus.PERMISSION_DENIED if isinstance(exc, PermissionError) or getattr(exc, "errno", None) in (errno.EPERM, errno.EACCES) else CollectorStatus.UNAVAILABLE
+        self.health[subsystem] = status.value
+        self.health["errors"].append(f"{subsystem}: {exc}")
+        affected = (EventType.PROCESS_STARTED, EventType.PROCESS_EXITED) if subsystem == "process" else (EventType.FILE_OPENED, EventType.FILE_MODIFIED)
+        self._caps = tuple(Capability(c.event_type, status if c.event_type in affected else c.status,
+                         str(exc) if c.event_type in affected else c.reason, c.scope, c.attribution) for c in self._caps)
+
+    def _start_process(self):
+        try:
+            sock = socket.socket(socket.AF_NETLINK, socket.SOCK_DGRAM, NETLINK_CONNECTOR)
+            sock.bind((os.getpid(), CN_IDX_PROC))
+            payload = struct.pack("=IIIIHHI", CN_IDX_PROC, CN_VAL_PROC, 0, 0, 4, 0, PROC_CN_MCAST_LISTEN)
+            header = struct.pack("=IHHII", 16 + len(payload), NLMSG_DONE, 0, 1, os.getpid())
+            sock.send(header + payload)
+            self._sockets.append(sock)
+            # CN_PROC may silently ignore subscribers outside the initial PID/user namespaces.
+            # Require its connector acknowledgement before claiming process coverage.
+            deadline = time.monotonic() + 2.0
+            while self.health["process"] != "available":
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise TimeoutError("CN_PROC sent no subscription acknowledgement; process events may be disabled or this PID namespace may not be the kernel's initial namespace")
+                sock.settimeout(remaining)
+                packet = sock.recv(65536)
+                try: self._parse_proc_packet(packet)
+                except (ValueError, struct.error, OSError) as exc:
+                    self.health["errors"].append(f"malformed process event during startup: {exc}")
+                    self._record_native_loss("cn_proc_malformed_packet", count=None)
+                if self.health["process"] in (CollectorStatus.PERMISSION_DENIED.value, CollectorStatus.UNAVAILABLE.value): break
+            if self.health["process"] != "available":
+                sock.close()
+                self._sockets.remove(sock)
+                return
+            sock.settimeout(.5)
+            thread = threading.Thread(target=self._process_loop, args=(sock,), daemon=True, name="nativerelay-proc")
+            thread.start(); self._threads.append(thread)
+        except OSError as exc:
+            self._failure("process", exc)
+
+    def _process_loop(self, sock):
+        while not self._stop.is_set():
+            try: packet = sock.recv(65536)
+            except socket.timeout: continue
+            except OSError:
+                if not self._stop.is_set(): self._failure("process", OSError("process connector socket closed"))
+                break
+            try: self._parse_proc_packet(packet)
+            except (ValueError, struct.error, OSError) as exc:
+                self.health["errors"].append(f"malformed process event: {exc}")
+                self._record_native_loss("cn_proc_malformed_packet", count=None)
+
+    def _parse_proc_packet(self, packet):
+        # Netlink header (16), connector header (20), then proc_event data.
+        offset = 0
+        while offset < len(packet):
+            if len(packet) - offset < 16: raise ValueError("truncated netlink header")
+            nl_len, nl_type, _, _, _ = struct.unpack_from("=IHHII", packet, offset)
+            if nl_len < 16 or offset + nl_len > len(packet): raise ValueError("invalid netlink message length")
+            if nl_type == NLMSG_OVERRUN:
+                self._record_native_loss("cn_proc_netlink_overrun", count=None)
+                offset += (nl_len + 3) & ~3
+                continue
+            if len(packet) - offset < 36 or nl_len < 36: raise ValueError("truncated netlink connector message")
+            cn = offset + 16
+            idx, val = struct.unpack_from("=II", packet, cn)
+            payload_len = struct.unpack_from("=H", packet, cn + 16)[0]
+            if payload_len > nl_len - 36: raise ValueError("connector payload exceeds netlink message")
+            if idx == CN_IDX_PROC and val == CN_VAL_PROC and payload_len >= 16:
+                body = cn + 20
+                what = struct.unpack_from("=I", packet, body)[0]
+                data = body + 16
+                if what == 0 and payload_len >= 20:
+                    error = struct.unpack_from("=i", packet, data)[0]
+                    if error:
+                        code = abs(error)
+                        self._failure("process", OSError(code, os.strerror(code)))
+                    else:
+                        self.health["process"] = "available"
+                        self._set_status((EventType.PROCESS_STARTED, EventType.PROCESS_EXITED), CollectorStatus.AVAILABLE, "Linux NETLINK_CONNECTOR/CN_PROC notifications acknowledged")
+                elif what == PROC_EVENT_FORK and payload_len >= 32:
+                    _, parent_tgid, child_pid, child_tgid = struct.unpack_from("=IIII", packet, data)
+                    if child_pid == child_tgid:
+                        self._emit_process(EventType.PROCESS_STARTED, child_tgid, parent_tgid)
+                elif what == PROC_EVENT_EXIT and payload_len >= 32:
+                    pid, tgid, code, sig = struct.unpack_from("=IIII", packet, data)
+                    if pid == tgid:
+                        self._emit_process(EventType.PROCESS_EXITED, tgid, None,
+                                           {"exitStatus": code, "exitSignal": sig, "leaderThreadExit": True})
+            offset += nl_len
+    def _process_info(self, pid, parent_pid):
+        proc = Path("/proc") / str(pid)
+        try:
+            stat = (proc / "stat").read_text()
+            # comm may contain spaces and ')' characters; fields after final ')' are stable.
+            tail = stat[stat.rfind(")") + 2:].split()
+            parent_pid = int(tail[1]) if parent_pid is None and len(tail) > 1 else parent_pid
+        except (OSError, ValueError, IndexError): pass
+        try: executable = os.readlink(proc / "exe")
+        except OSError: executable = None
+        command = None
+        if self.include_command:
+            try: command = tuple((proc / "cmdline").read_bytes().decode(errors="replace").rstrip("\0").split("\0"))
+            except OSError: pass
+        return Process(pid=pid, parent_pid=parent_pid, executable=executable, command=command)
+
+    def _emit_process(self, typ, pid, ppid, metadata=None):
+        self._publish(Event(typ, "linux", self.name, self._process_info(pid, ppid), metadata=metadata or {}))
+
+    def _start_filesystem(self):
+        try:
+            libc = ctypes.CDLL(None, use_errno=True)
+            init = libc.fanotify_init
+            init.argtypes = [ctypes.c_uint, ctypes.c_uint]
+            init.restype = ctypes.c_int
+            fd = init(FAN_CLOEXEC | FAN_CLASS_NOTIF | FAN_NONBLOCK, os.O_RDONLY | os.O_LARGEFILE if hasattr(os, "O_LARGEFILE") else os.O_RDONLY)
+            if fd < 0: self._raise_errno()
+            self._fanotify_fd = fd
+            mark = libc.fanotify_mark
+            mark.argtypes = [ctypes.c_int, ctypes.c_uint, ctypes.c_uint64, ctypes.c_int, ctypes.c_char_p]
+            mark.restype = ctypes.c_int
+            mountpoint = self._mountpoint(self.scope)
+            if mark(fd, FAN_MARK_ADD | FAN_MARK_MOUNT, FAN_OPEN | FAN_MODIFY, -100, os.fsencode(mountpoint)) < 0:
+                os.close(fd); self._raise_errno()
+            self._sockets.append(fd)
+            self.health["filesystem"] = "available"
+            self._set_status((EventType.FILE_OPENED, EventType.FILE_MODIFIED), CollectorStatus.AVAILABLE, f"fanotify mount notifications filtered to {self.scope}")
+            thread = threading.Thread(target=self._fanotify_loop, daemon=True, name="nativerelay-fanotify")
+            thread.start(); self._threads.append(thread)
+        except OSError as exc:
+            self._failure("filesystem", exc)
+
+    @staticmethod
+    def _raise_errno():
+        code = ctypes.get_errno()
+        raise OSError(code, os.strerror(code))
+
+    @staticmethod
+    def _mountpoint(path):
+        best = Path("/")
+        for line in Path("/proc/self/mountinfo").read_text().splitlines():
+            fields = line.split()
+            if len(fields) > 4:
+                decoded = re.sub(r"\\([0-7]{3})", lambda match: chr(int(match.group(1), 8)), fields[4])
+                try: mount = Path(decoded).resolve()
+                except OSError: continue
+                if path == mount or mount in path.parents:
+                    if len(str(mount)) > len(str(best)): best = mount
+        return best
+
+    def _fanotify_loop(self):
+        poller = select.poll()
+        poller.register(self._fanotify_fd, select.POLLIN | select.POLLERR | select.POLLHUP)
+        while not self._stop.is_set():
+            ready = poller.poll(500)
+            if not ready: continue
+            try: data = os.read(self._fanotify_fd, 65536)
+            except BlockingIOError: continue
+            except OSError:
+                if not self._stop.is_set(): self._failure("filesystem", OSError("fanotify descriptor closed"))
+                return
+            self._parse_fanotify_data(data)
+
+    def _parse_fanotify_data(self, data):
+        offset = 0
+        while offset + FANOTIFY_METADATA_LEN <= len(data):
+            try:
+                length, version, _, metadata_len, mask, event_fd, pid = struct.unpack_from(FAN_EVENT_METADATA_FMT, data, offset)
+                if length < FANOTIFY_METADATA_LEN or offset + length > len(data): raise ValueError("invalid fanotify event length")
+                if version != FANOTIFY_METADATA_VERSION or metadata_len < FANOTIFY_METADATA_LEN or metadata_len > length: raise ValueError("unsupported fanotify metadata version")
+                if mask & FAN_Q_OVERFLOW:
+                    self._record_native_loss("fanotify_queue_overflow", count=None)
+                elif event_fd >= 0:
+                    self._handle_file_event(mask, event_fd, pid)
+                offset += length
+            except (ValueError, struct.error) as exc:
+                self.health["errors"].append(f"malformed fanotify event: {exc}")
+                self._record_native_loss("fanotify_malformed_event", count=None)
+                break
+        if offset < len(data) and len(data) - offset < FANOTIFY_METADATA_LEN:
+            self.health["errors"].append("truncated fanotify metadata")
+            self._record_native_loss("fanotify_truncated_metadata", count=None)
+    def _handle_file_event(self, mask, fd, pid):
+        try:
+            path = Path(os.readlink(f"/proc/self/fd/{fd}")).resolve(strict=False)
+            if path != self.scope and self.scope not in path.parents: return
+            if mask & FAN_OPEN:
+                self._publish(Event(EventType.FILE_OPENED, "linux", self.name, self._process_info(pid, None), Resource("file", str(path))))
+            if mask & FAN_MODIFY:
+                self._publish(Event(EventType.FILE_MODIFIED, "linux", self.name, self._process_info(pid, None), Resource("file", str(path))))
+        except (OSError, ValueError) as exc:
+            self.health["errors"].append(f"file event resolution: {exc}")
+            lost = int(bool(mask & FAN_OPEN)) + int(bool(mask & FAN_MODIFY))
+            if lost: self._record_native_loss("fanotify_path_resolution", count=lost)
+        finally:
+            try: os.close(fd)
+            except OSError: pass
+
+    def _record_native_loss(self, reason, *, count):
+        """Record detected native loss and reserve a collector sequence marker."""
+        with self._publish_lock:
+            sequence = self._sequence
+            self._sequence += 1
+            if self._stream is not None:
+                self._stream.report_loss(self.name, reason, count=count, sequence=sequence)
+
+    def _publish(self, event):
+        with self._publish_lock:
+            sequenced = replace(event, sequence=self._sequence)
+            self._sequence += 1
+            if self._stream is not None and not self._stream.publish(sequenced):
+                self.health["dropped"] += 1
+
+    def _set_status(self, event_types, status, reason):
+        self._caps = tuple(Capability(c.event_type, status if c.event_type in event_types else c.status,
+                         reason if c.event_type in event_types else c.reason, c.scope, c.attribution) for c in self._caps)

nativerelay/__init__.py

@@ -0,0 +1,4 @@
+"""NativeRelay platform-neutral event API."""
+from .model import Capability, CollectorStatus, Event, EventType, Process, Resource
+from .stream import EventStream, StreamClosed
+__all__ = ["Capability", "CollectorStatus", "Event", "EventType", "Process", "Resource", "EventStream", "StreamClosed"]

nativerelay/build.py

@@ -0,0 +1,49 @@
+"""Tiny offline PEP 517 wheel builder; runtime remains standard-library only."""
+from pathlib import Path
+import base64
+import csv
+import hashlib
+import io
+from zipfile import ZIP_DEFLATED, ZipFile
+
+NAME = "nativerelay"
+VERSION = "0.1.0"
+
+def get_requires_for_build_wheel(config_settings=None):
+    return []
+
+def build_wheel(wheel_directory, config_settings=None, metadata_directory=None):
+    output = Path(wheel_directory)
+    output.mkdir(parents=True, exist_ok=True)
+    filename = f"{NAME}-{VERSION}-py3-none-any.whl"
+    dist = f"{NAME}-{VERSION}.dist-info"
+    files = []
+    for package in (Path("nativerelay"), Path("collectors")):
+        for path in package.rglob("*.py"):
+            if "__pycache__" not in path.parts:
+                files.append(path)
+    record = []
+    with ZipFile(output / filename, "w", ZIP_DEFLATED) as wheel:
+        for path in files:
+            content = path.read_bytes()
+            wheel.writestr(path.as_posix(), content)
+            record.append(_record_row(path.as_posix(), content))
+        metadata = f"{dist}/METADATA"
+        content = b"Metadata-Version: 2.1\nName: nativerelay\nVersion: 0.1.0\nRequires-Python: >=3.11\nSummary: Local-first normalized native OS telemetry\n\n"
+        wheel.writestr(metadata, content); record.append(_record_row(metadata, content))
+        wheel_file = f"{dist}/WHEEL"
+        content = b"Wheel-Version: 1.0\nGenerator: nativerelay.build\nRoot-Is-Purelib: true\nTag: py3-none-any\n"
+        wheel.writestr(wheel_file, content); record.append(_record_row(wheel_file, content))
+        entrypoints = f"{dist}/entry_points.txt"
+        content = b"[console_scripts]\nnativerelay = nativerelay.cli:main\n"
+        wheel.writestr(entrypoints, content); record.append(_record_row(entrypoints, content))
+        record_path = f"{dist}/RECORD"
+        record.append((record_path, "", ""))
+        stream = io.StringIO(newline="")
+        csv.writer(stream, lineterminator="\n").writerows(record)
+        wheel.writestr(record_path, stream.getvalue())
+    return filename
+
+def _record_row(path, content):
+    digest = base64.urlsafe_b64encode(hashlib.sha256(content).digest()).rstrip(b"=").decode("ascii")
+    return (path, f"sha256={digest}", str(len(content)))

nativerelay/cli.py

@@ -0,0 +1,62 @@
+"""NativeRelay local development CLI."""
+import argparse
+import json
+import sys
+from dataclasses import asdict
+from collectors.linux import LinuxCollector
+from .stream import EventStream
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="nativerelay", description="Observe local Linux kernel events")
+    commands = parser.add_subparsers(dest="command", required=True)
+    observe = commands.add_parser("observe", help="stream process events and scoped file open/write events")
+    observe.add_argument("--scope", required=True, help="existing directory to include in file events")
+    observe.add_argument("--json", action="store_true", help="emit one JSON event per line")
+    observe.add_argument("--include-command", action="store_true", help="include argv (may contain sensitive data)")
+    commands.add_parser("capabilities", help="show collector capabilities for a scope")
+    capabilities = commands.choices["capabilities"]
+    capabilities.add_argument("--scope", required=True)
+    args = parser.parse_args(argv)
+    try: collector = LinuxCollector(args.scope, include_command=getattr(args, "include_command", False))
+    except (OSError, ValueError) as exc:
+        print(f"nativerelay: {exc}", file=sys.stderr); return 2
+    if args.command == "capabilities":
+        collector.start(EventStream(1))
+        try:
+            print(json.dumps({"platform": "linux", "collector": collector.name,
+                              "scope": str(collector.scope), "health": collector.status,
+                              "capabilities": [
+                                  {**asdict(c), "event_type": c.event_type.value, "status": c.status.value}
+                                  for c in collector.capabilities]}, indent=2))
+        finally: collector.stop()
+        return 0
+    stream = EventStream()
+    try:
+        collector.start(stream)
+        print("NativeRelay Linux observe (Ctrl-C to stop)", file=sys.stderr)
+        last_dropped = -1
+        last_loss_generation = -1
+        while True:
+            try: event = stream.receive(timeout=1)
+            except TimeoutError:
+                status = collector.status
+                if status["errors"] or status["dropped"] != last_dropped or status["loss_generation"] != last_loss_generation:
+                    print(json.dumps({"collector_status": status}), file=sys.stderr)
+                    collector.health["errors"].clear()
+                    last_dropped = status["dropped"]
+                    last_loss_generation = status["loss_generation"]
+                continue
+            print(event.to_json() if args.json else _human(event), flush=True)
+    except KeyboardInterrupt:
+        return 0
+    finally: collector.stop()
+
+def _human(event):
+    proc = f"pid={event.process.pid}"
+    if event.process.parent_pid is not None: proc += f" ppid={event.process.parent_pid}"
+    if event.process.executable: proc += f" exe={event.process.executable}"
+    resource = f" {event.resource.path}" if event.resource else ""
+    metadata = " " + json.dumps(event.metadata) if event.metadata else ""
+    return f"{event.timestamp} {event.type.value} {proc}{resource}{metadata}"
+
+if __name__ == "__main__": raise SystemExit(main())

nativerelay/collector.py

@@ -0,0 +1,13 @@
+"""Platform-neutral collector contract."""
+from abc import ABC, abstractmethod
+from .model import Capability
+from .stream import EventStream
+
+class Collector(ABC):
+    @property
+    @abstractmethod
+    def capabilities(self) -> tuple[Capability, ...]: ...
+    @abstractmethod
+    def start(self, stream: EventStream) -> None: ...
+    @abstractmethod
+    def stop(self) -> None: ...

nativerelay/model.py

@@ -0,0 +1,113 @@
+"""Version 1 normalized event and capability model.
+
+Timestamps are timezone-aware ISO-8601 instants. ``sequence`` is optional and, when a
+collector supplies it, orders events as normalized by that collector only.
+"""
+from __future__ import annotations
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from enum import Enum
+import hashlib
+import json
+import uuid
+from typing import Any
+
+class EventType(str, Enum):
+    PROCESS_STARTED = "process.started"
+    PROCESS_EXITED = "process.exited"
+    FILE_OPENED = "file.opened"
+    FILE_CREATED = "file.created"
+    FILE_MODIFIED = "file.modified"
+    FILE_DELETED = "file.deleted"
+    FILE_RENAMED = "file.renamed"
+
+class CollectorStatus(str, Enum):
+    SUPPORTED = "supported"
+    AVAILABLE = "available"
+    DEGRADED = "degraded"
+    PERMISSION_DENIED = "permission_denied"
+    UNAVAILABLE = "unavailable"
+    UNSUPPORTED = "unsupported"
+
+@dataclass(frozen=True)
+class Process:
+    pid: int
+    parent_pid: int | None = None
+    executable: str | None = None
+    command: tuple[str, ...] | None = None
+    def __post_init__(self):
+        if not isinstance(self.pid, int) or self.pid <= 0 or (self.parent_pid is not None and (not isinstance(self.parent_pid, int) or self.parent_pid < 0)):
+            raise ValueError("process IDs must be positive (parent may be zero)")
+        if self.executable is not None and not isinstance(self.executable, str): raise ValueError("executable must be a string")
+        if self.command is not None and not all(isinstance(x, str) for x in self.command):
+            raise ValueError("command must contain strings")
+
+@dataclass(frozen=True)
+class Resource:
+    type: str
+    path: str
+    def __post_init__(self):
+        if not isinstance(self.type, str) or not isinstance(self.path, str) or not self.type or not self.path:
+            raise ValueError("resource type and path are required")
+
+@dataclass(frozen=True)
+class Event:
+    type: EventType
+    platform: str
+    collector: str
+    process: Process
+    resource: Resource | None = None
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    metadata: dict[str, Any] = field(default_factory=dict)
+    evidence: str = "observed"
+    id: str = field(default_factory=lambda: str(uuid.uuid4()))
+    sequence: int | None = None
+    def __post_init__(self):
+        if not isinstance(self.type, EventType): object.__setattr__(self, "type", EventType(self.type))
+        if not isinstance(self.process, Process): raise ValueError("process must be a Process")
+        if self.resource is not None and not isinstance(self.resource, Resource): raise ValueError("resource must be a Resource")
+        if not all(isinstance(value, str) and value for value in (self.platform, self.collector, self.id)):
+            raise ValueError("platform, collector, and id are required")
+        if self.evidence not in ("observed", "derived"): raise ValueError("evidence must be observed or derived")
+        try:
+            parsed_timestamp = datetime.fromisoformat(self.timestamp.replace("Z", "+00:00"))
+            if parsed_timestamp.utcoffset() is None: raise ValueError("timezone required")
+        except (ValueError, AttributeError) as exc: raise ValueError("timestamp must be ISO-8601 with timezone") from exc
+        if self.sequence is not None and (not isinstance(self.sequence, int) or self.sequence < 0):
+            raise ValueError("sequence must be a non-negative integer or None")
+        if not isinstance(self.metadata, dict): raise ValueError("metadata must be an object")
+        try: json.dumps(self.metadata)
+        except (TypeError, ValueError) as exc: raise ValueError("metadata must be JSON serializable") from exc
+    @staticmethod
+    def stable_id(collector: str, boot_id: str, sequence: int) -> str:
+        raw = f"{collector}\0{boot_id}\0{sequence}".encode()
+        return hashlib.sha256(raw).hexdigest()
+    def to_dict(self):
+        return {"id": self.id, "timestamp": self.timestamp, "type": self.type.value,
+                "platform": self.platform, "collector": self.collector, "process": asdict(self.process),
+                "resource": asdict(self.resource) if self.resource else None,
+                "metadata": self.metadata, "evidence": self.evidence, "sequence": self.sequence, "schema_version": 1}
+    def to_json(self): return json.dumps(self.to_dict(), separators=(",", ":"), ensure_ascii=True)
+
+@dataclass(frozen=True)
+class Capability:
+    event_type: EventType
+    status: CollectorStatus
+    reason: str
+    scope: str
+    attribution: str
+    def __post_init__(self):
+        if not isinstance(self.event_type, EventType): object.__setattr__(self, "event_type", EventType(self.event_type))
+        if not isinstance(self.status, CollectorStatus): object.__setattr__(self, "status", CollectorStatus(self.status))
+        if not self.reason or not self.scope or not self.attribution: raise ValueError("capability reason, scope, and attribution are required")
+
+def decode_event(data: str) -> Event:
+    try:
+        raw = json.loads(data)
+        return Event(type=EventType(raw["type"]), platform=raw["platform"], collector=raw["collector"],
+                     process=Process(**{**raw["process"], "command": tuple(raw["process"]["command"]) if raw["process"].get("command") is not None else None}),
+                     resource=Resource(**raw["resource"]) if raw.get("resource") else None,
+                     timestamp=raw["timestamp"], metadata=raw.get("metadata", {}), evidence=raw["evidence"], id=raw["id"],
+                     sequence=raw.get("sequence"))
+    except (ValueError, TypeError, KeyError, json.JSONDecodeError) as exc:
+        raise ValueError(f"invalid NativeRelay event: {exc}") from exc

nativerelay/stream.py

@@ -0,0 +1,111 @@
+"""Bounded synchronous event stream shared by collectors."""
+from queue import Queue, Full, Empty
+from threading import Lock
+from .model import Event
+
+
+class StreamClosed(RuntimeError):
+    """Raised after a producer has closed the stream and queued events drain."""
+
+
+class EventStream:
+    def __init__(self, capacity=1024):
+        if capacity <= 0: raise ValueError("capacity must be positive")
+        self._queue = Queue(maxsize=capacity)
+        self.dropped = 0
+        self._closed = False
+        self._lock = Lock()
+        self._close_error = None
+        self._loss_generation = 0
+        self._losses = {}
+
+    @property
+    def closed(self):
+        with self._lock: return self._closed
+
+    @property
+    def error(self):
+        with self._lock: return self._close_error
+
+    @property
+    def loss_generation(self):
+        """Monotonic counter; changes whenever a producer reports detected loss."""
+        with self._lock: return self._loss_generation
+
+    @property
+    def losses(self):
+        """Copy of loss totals grouped by source and reason."""
+        with self._lock:
+            return {source: {reason: dict(totals) for reason, totals in reasons.items()}
+                    for source, reasons in self._losses.items()}
+
+    def _record_loss_locked(self, source, reason, count, sequence):
+        totals = self._losses.setdefault(source, {}).setdefault(reason, {
+            "occurrences": 0, "known_dropped": 0, "unknown_count": False,
+            "last_sequence": None,
+        })
+        totals["occurrences"] += 1
+        if count is None:
+            totals["unknown_count"] = True
+        else:
+            totals["known_dropped"] += count
+        if sequence is not None: totals["last_sequence"] = sequence
+        self._loss_generation += 1
+
+    def report_loss(self, source, reason, *, count=None, sequence=None):
+        """Report an observed loss; count=None means the lost-event count is unknown."""
+        if not isinstance(source, str) or not source: raise ValueError("loss source is required")
+        if not isinstance(reason, str) or not reason: raise ValueError("loss reason is required")
+        if count is not None and (not isinstance(count, int) or count < 0):
+            raise ValueError("loss count must be a non-negative integer or None")
+        if sequence is not None and (not isinstance(sequence, int) or sequence < 0):
+            raise ValueError("loss sequence must be a non-negative integer or None")
+        with self._lock:
+            self._record_loss_locked(source, reason, count, sequence)
+
+    def publish(self, event: Event):
+        if not isinstance(event, Event): raise TypeError("event must be a NativeRelay Event")
+        with self._lock:
+            if self._closed:
+                self.dropped += 1
+                self._record_loss_locked(event.collector, "event_stream_closed", 1, event.sequence)
+                return False
+            try: self._queue.put_nowait(event); return True
+            except Full:
+                self.dropped += 1
+                self._record_loss_locked(event.collector, "event_stream_full", 1, event.sequence)
+                return False
+
+    def close(self, error: BaseException | None = None):
+        """Stop accepting events; buffered events remain available to consumers."""
+        with self._lock:
+            if self._closed: return
+            self._closed = True
+            self._close_error = error
+            # Wake a blocked receiver if the queue is empty. A full queue already
+            # guarantees that no receiver can be blocked waiting for an event.
+            try: self._queue.put_nowait(_CLOSED)
+            except Full: pass
+
+    def receive(self, timeout=None):
+        with self._lock:
+            if self._closed and self._queue.empty():
+                raise StreamClosed("NativeRelay event stream is closed")
+        try: item = self._queue.get(timeout=timeout)
+        except Empty as exc:
+            if self.closed: raise StreamClosed("NativeRelay event stream is closed") from exc
+            raise TimeoutError("no NativeRelay event available") from exc
+        if item is _CLOSED:
+            # Keep closure visible to every later receive call.
+            try: self._queue.put_nowait(_CLOSED)
+            except Full: pass
+            raise StreamClosed("NativeRelay event stream is closed")
+        return item
+
+    def __iter__(self):
+        while True:
+            try: yield self.receive()
+            except StreamClosed: return
+
+
+_CLOSED = object()

nativerelay-0.1.0.dist-info/METADATA

@@ -0,0 +1,6 @@
+Metadata-Version: 2.1
+Name: nativerelay
+Version: 0.1.0
+Requires-Python: >=3.11
+Summary: Local-first normalized native OS telemetry
+

nativerelay-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+nativerelay/collector.py,sha256=jPDHfzCnDK7hZlrRUijUBuwY1pKrgqEpH-j3arHQAWs,382
+nativerelay/cli.py,sha256=nJ4DErru3tYf6nAbvzGUAkb6Nfj2aDBCcRBkTYlPp9E,3211
+nativerelay/model.py,sha256=B2877ueYtHhffLldFd_7J-BdoSyY-uP5ognPVdG442Q,5773
+nativerelay/stream.py,sha256=uHixaWvliAufV0kwbSz7r1rh4eUOnzwYlXJhquSsSR8,4514
+nativerelay/build.py,sha256=i3HGOBGNBrUEXamSFgMwvPW-P-S6y1xdZygkoD-yjXQ,2243
+nativerelay/__init__.py,sha256=ybvXpAmxt80upZF6drELWZRem-8iXa9YIZC4C9_mMw0,296
+collectors/__init__.py,sha256=QXgA7aS-PUeEorvGCuQe96rSHIE730bEpPPzN9r0XJc,34
+collectors/linux/collector.py,sha256=43_nm9KPeTa-I8gd8rwE0t6gosDFeltIXHnns2UcO8c,16789
+collectors/linux/__init__.py,sha256=IuTIryxNWK1r16SJlZNvwIzcMhQoqsishl3-cqZVt-Y,107
+nativerelay-0.1.0.dist-info/METADATA,sha256=PCBP-mQfNdL80H0e6fNzXeGduc9mcIv9UXtV2H60JrQ,132
+nativerelay-0.1.0.dist-info/WHEEL,sha256=z2Hx0MKflNlZIAkP5GUTPqUXXNrsUKmC72d9FVdGwY0,88
+nativerelay-0.1.0.dist-info/entry_points.txt,sha256=FDtVrUt_aeMn4jVO4p67jYka9krFId8KR21ooTfEn9s,53
+nativerelay-0.1.0.dist-info/RECORD,,

nativerelay-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: nativerelay.build
+Root-Is-Purelib: true
+Tag: py3-none-any

nativerelay-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nativerelay = nativerelay.cli:main