rbek 0.2.1__py3-none-any.whl

rbek/adoption/__init__.py

@@ -0,0 +1,17 @@
+"""Privacy-preserving adoption measurement primitives.
+
+This package contains no HTTP listener, route registration, service startup,
+or public activation authority.
+"""
+
+from rbek.adoption.intake import (
+    AdoptionIntake,
+    AppendOnlyJsonlAdoptionStore,
+    IntakeResult,
+)
+
+__all__ = [
+    "AdoptionIntake",
+    "AppendOnlyJsonlAdoptionStore",
+    "IntakeResult",
+]

rbek/adoption/http_adapter.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+from typing import Final
+
+from rbek.adoption.intake import AdoptionIntake, MAX_PAYLOAD_BYTES
+
+JSON_CONTENT_TYPE: Final[str] = "application/json"
+
+
+@dataclass(frozen=True, slots=True)
+class AdoptionHttpResponse:
+    status_code: int
+    body: bytes
+    content_type: str = JSON_CONTENT_TYPE
+
+    def __post_init__(self) -> None:
+        if type(self.status_code) is not int:
+            raise TypeError("status_code must be int")
+        if type(self.body) is not bytes:
+            raise TypeError("body must be bytes")
+        if type(self.content_type) is not str:
+            raise TypeError("content_type must be str")
+
+
+def _response(status_code: int, code: str) -> AdoptionHttpResponse:
+    return AdoptionHttpResponse(
+        status_code=status_code,
+        body=json.dumps(
+            {"status": code},
+            sort_keys=True,
+            separators=(",", ":"),
+        ).encode("utf-8"),
+    )
+
+
+class AdoptionIntakeHttpAdapter:
+    __slots__ = ("_intake",)
+
+    def __init__(self, intake: AdoptionIntake) -> None:
+        if not isinstance(intake, AdoptionIntake):
+            raise TypeError("intake must be AdoptionIntake")
+        self._intake = intake
+
+    def handle(
+        self,
+        *,
+        method: str,
+        content_type: str | None,
+        body: bytes,
+    ) -> AdoptionHttpResponse:
+        if type(method) is not str:
+            return _response(400, "invalid_request")
+
+        if method.upper() != "POST":
+            return _response(405, "method_not_allowed")
+
+        if type(content_type) is not str:
+            return _response(415, "unsupported_media_type")
+
+        media_type = content_type.split(";", 1)[0].strip().lower()
+
+        if media_type != JSON_CONTENT_TYPE:
+            return _response(415, "unsupported_media_type")
+
+        if type(body) is not bytes:
+            return _response(400, "invalid_body")
+
+        if len(body) > MAX_PAYLOAD_BYTES:
+            return _response(413, "payload_too_large")
+
+        try:
+            decoded = body.decode("utf-8")
+            json.loads(decoded)
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return _response(422, "unprocessable_event")
+
+        try:
+            result = self._intake.receive(body)
+        except (TypeError, ValueError, UnicodeError, json.JSONDecodeError):
+            return _response(422, "unprocessable_event")
+        except Exception:
+            return _response(500, "internal_error")
+
+        return _response(
+            result.status_code,
+            result.reason,
+        )

rbek/adoption/http_listener.py

@@ -0,0 +1,147 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from io import BytesIO
+from typing import Callable, Final, TypeAlias
+
+from rbek.adoption.http_adapter import (
+    AdoptionHttpResponse,
+    AdoptionIntakeHttpAdapter,
+)
+
+DEFAULT_HOST: Final[str] = "127.0.0.1"
+DEFAULT_PORT: Final[int] = 8766
+EVENT_PATH: Final[str] = "/api/v1/adoption/events"
+MAX_REQUEST_BODY_BYTES: Final[int] = 4096
+
+ServerFactory: TypeAlias = Callable[
+    [tuple[str, int], type[BaseHTTPRequestHandler]],
+    ThreadingHTTPServer,
+]
+
+
+def _write_response(
+    handler: BaseHTTPRequestHandler,
+    response: AdoptionHttpResponse,
+) -> None:
+    handler.send_response(response.status_code)
+    handler.send_header("Content-Type", response.content_type)
+    handler.send_header("Content-Length", str(len(response.body)))
+    handler.send_header("Cache-Control", "no-store")
+    handler.end_headers()
+    handler.wfile.write(response.body)
+
+
+def build_request_handler(
+    adapter: AdoptionIntakeHttpAdapter,
+) -> type[BaseHTTPRequestHandler]:
+    class AdoptionRequestHandler(BaseHTTPRequestHandler):
+        server_version = "RBEKAdoption/1"
+        sys_version = ""
+
+        def log_message(self, format: str, *args: object) -> None:
+            return None
+
+        def _dispatch(self) -> None:
+            if self.path != EVENT_PATH:
+                response = AdoptionHttpResponse(
+                    status_code=404,
+                    body=b'{"status":"not_found"}',
+                )
+                _write_response(self, response)
+                return
+
+            content_length_raw = self.headers.get("Content-Length")
+
+            if content_length_raw is None:
+                response = AdoptionHttpResponse(
+                    status_code=411,
+                    body=b'{"status":"length_required"}',
+                )
+                _write_response(self, response)
+                return
+
+            try:
+                content_length = int(content_length_raw)
+            except ValueError:
+                response = AdoptionHttpResponse(
+                    status_code=400,
+                    body=b'{"status":"invalid_content_length"}',
+                )
+                _write_response(self, response)
+                return
+
+            if content_length < 0:
+                response = AdoptionHttpResponse(
+                    status_code=400,
+                    body=b'{"status":"invalid_content_length"}',
+                )
+                _write_response(self, response)
+                return
+
+            if content_length > MAX_REQUEST_BODY_BYTES:
+                response = AdoptionHttpResponse(
+                    status_code=413,
+                    body=b'{"status":"payload_too_large"}',
+                )
+                _write_response(self, response)
+                return
+
+            body = self.rfile.read(content_length)
+
+            response = adapter.handle(
+                method=self.command,
+                content_type=self.headers.get("Content-Type"),
+                body=body,
+            )
+
+            _write_response(self, response)
+
+        def do_POST(self) -> None:
+            self._dispatch()
+
+        def do_GET(self) -> None:
+            response = AdoptionHttpResponse(
+                status_code=405,
+                body=b'{"status":"method_not_allowed"}',
+            )
+            _write_response(self, response)
+
+        def do_PUT(self) -> None:
+            self.do_GET()
+
+        def do_DELETE(self) -> None:
+            self.do_GET()
+
+        def do_PATCH(self) -> None:
+            self.do_GET()
+
+    return AdoptionRequestHandler
+
+
+@dataclass(frozen=True, slots=True)
+class LocalAdoptionHttpListener:
+    adapter: AdoptionIntakeHttpAdapter
+    host: str = DEFAULT_HOST
+    port: int = DEFAULT_PORT
+    server_factory: ServerFactory = ThreadingHTTPServer
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.adapter, AdoptionIntakeHttpAdapter):
+            raise TypeError("adapter must be AdoptionIntakeHttpAdapter")
+
+        if self.host != DEFAULT_HOST:
+            raise ValueError("local adoption listener must bind to 127.0.0.1")
+
+        if type(self.port) is not int or not (1 <= self.port <= 65535):
+            raise ValueError("port must be an integer in range 1..65535")
+
+    def serve_forever(self) -> None:
+        handler = build_request_handler(self.adapter)
+
+        with self.server_factory(
+            (self.host, self.port),
+            handler,
+        ) as server:
+            server.serve_forever()

rbek/adoption/intake.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timezone
+import json
+from pathlib import Path
+from typing import Mapping, Protocol
+
+from rbek.cli.adoption_remote_contract import (
+    AdoptionEventValidationError,
+    validate_event_mapping,
+)
+
+MAX_PAYLOAD_BYTES = 4096
+
+
+class AdoptionStore(Protocol):
+    def append(
+        self,
+        event: Mapping[str, str],
+        *,
+        received_at_server: str,
+    ) -> None:
+        """Persist one already validated non-identifying event."""
+
+
+@dataclass(frozen=True, slots=True)
+class IntakeResult:
+    accepted: bool
+    status_code: int
+    reason: str
+
+
+@dataclass(frozen=True, slots=True)
+class AppendOnlyJsonlAdoptionStore:
+    path: Path
+
+    def append(
+        self,
+        event: Mapping[str, str],
+        *,
+        received_at_server: str,
+    ) -> None:
+        self.path.parent.mkdir(
+            parents=True,
+            exist_ok=True,
+        )
+
+        row = dict(event)
+        row["received_at_server"] = received_at_server
+
+        encoded = (
+            json.dumps(
+                row,
+                sort_keys=True,
+                separators=(",", ":"),
+            )
+            + "\n"
+        ).encode("utf-8")
+
+        with self.path.open("ab") as handle:
+            handle.write(encoded)
+            handle.flush()
+
+
+@dataclass(frozen=True, slots=True)
+class AdoptionIntake:
+    store: AdoptionStore
+
+    def receive(
+        self,
+        body: bytes,
+        *,
+        received_at_server: str | None = None,
+    ) -> IntakeResult:
+        if type(body) is not bytes:
+            return IntakeResult(
+                accepted=False,
+                status_code=400,
+                reason="body_must_be_bytes",
+            )
+
+        if len(body) == 0:
+            return IntakeResult(
+                accepted=False,
+                status_code=400,
+                reason="empty_payload",
+            )
+
+        if len(body) > MAX_PAYLOAD_BYTES:
+            return IntakeResult(
+                accepted=False,
+                status_code=413,
+                reason="payload_too_large",
+            )
+
+        try:
+            decoded = json.loads(body.decode("utf-8"))
+        except (UnicodeDecodeError, json.JSONDecodeError):
+            return IntakeResult(
+                accepted=False,
+                status_code=400,
+                reason="invalid_json",
+            )
+
+        if not isinstance(decoded, dict):
+            return IntakeResult(
+                accepted=False,
+                status_code=422,
+                reason="payload_must_be_object",
+            )
+
+        try:
+            event = validate_event_mapping(decoded)
+        except AdoptionEventValidationError:
+            return IntakeResult(
+                accepted=False,
+                status_code=422,
+                reason="invalid_event_contract",
+            )
+
+        timestamp = received_at_server
+
+        if timestamp is None:
+            timestamp = (
+                datetime.now(timezone.utc)
+                .replace(microsecond=0)
+                .isoformat()
+                .replace("+00:00", "Z")
+            )
+
+        self.store.append(
+            event,
+            received_at_server=timestamp,
+        )
+
+        return IntakeResult(
+            accepted=True,
+            status_code=202,
+            reason="accepted",
+        )

rbek/adoption/retention.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+from datetime import (
+    datetime,
+    timedelta,
+    timezone,
+)
+import fcntl
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+DEFAULT_STATE_ROOT = Path(
+    "/var/lib/rbek-adoption"
+)
+
+DEFAULT_EVENT_LOG = (
+    DEFAULT_STATE_ROOT
+    / "events.jsonl"
+)
+
+DEFAULT_RECEIPT_LOG = (
+    DEFAULT_STATE_ROOT
+    / "events.receipts.jsonl"
+)
+
+DEFAULT_LOCK_FILE = (
+    DEFAULT_STATE_ROOT
+    / "events.write.lock"
+)
+
+RETENTION_DAYS = 30
+
+
+def _parse_server_time(
+    value: str,
+) -> datetime:
+    parsed = datetime.fromisoformat(
+        value.replace(
+            "Z",
+            "+00:00",
+        )
+    )
+
+    if parsed.tzinfo is None:
+        raise ValueError(
+            "received_at_server must be timezone-aware"
+        )
+
+    return parsed.astimezone(
+        timezone.utc
+    )
+
+
+def _rewrite(
+    path: Path,
+    lines: list[str],
+) -> None:
+    temporary = path.with_name(
+        path.name
+        + ".retention.tmp"
+    )
+
+    payload = "".join(
+        line + "\n"
+        for line in lines
+    ).encode(
+        "utf-8"
+    )
+
+    fd = os.open(
+        temporary,
+        os.O_WRONLY
+        | os.O_CREAT
+        | os.O_TRUNC,
+        0o640,
+    )
+
+    try:
+        written = 0
+
+        while written < len(payload):
+            count = os.write(
+                fd,
+                payload[written:],
+            )
+
+            if count <= 0:
+                raise OSError(
+                    "retention rewrite failed"
+                )
+
+            written += count
+
+        os.fsync(fd)
+
+    finally:
+        os.close(fd)
+
+    os.replace(
+        temporary,
+        path,
+    )
+
+
+def prune_expired_events(
+    *,
+    event_log: Path = DEFAULT_EVENT_LOG,
+    receipt_log: Path = DEFAULT_RECEIPT_LOG,
+    lock_file: Path = DEFAULT_LOCK_FILE,
+    now: datetime | None = None,
+    retention_days: int = RETENTION_DAYS,
+) -> dict[str, int]:
+
+    if retention_days != 30:
+        raise ValueError(
+            "retention_days must be exactly 30"
+        )
+
+    current = (
+        now
+        or datetime.now(
+            timezone.utc
+        )
+    )
+
+    if current.tzinfo is None:
+        raise ValueError(
+            "now must be timezone-aware"
+        )
+
+    cutoff = (
+        current.astimezone(
+            timezone.utc
+        )
+        - timedelta(
+            days=30
+        )
+    )
+
+    event_log = Path(
+        event_log
+    )
+
+    receipt_log = Path(
+        receipt_log
+    )
+
+    lock_file = Path(
+        lock_file
+    )
+
+    lock_file.parent.mkdir(
+        mode=0o750,
+        parents=True,
+        exist_ok=True,
+    )
+
+    lock_fd = os.open(
+        lock_file,
+        os.O_WRONLY
+        | os.O_CREAT,
+        0o640,
+    )
+
+    try:
+        fcntl.flock(
+            lock_fd,
+            fcntl.LOCK_EX,
+        )
+
+        events = (
+            event_log.read_text(
+                encoding="utf-8"
+            ).splitlines()
+            if event_log.exists()
+            else []
+        )
+
+        receipts = (
+            receipt_log.read_text(
+                encoding="utf-8"
+            ).splitlines()
+            if receipt_log.exists()
+            else []
+        )
+
+        if len(events) != len(receipts):
+            raise RuntimeError(
+                "event/receipt "
+                "line-count mismatch: "
+                f"{len(events)} != "
+                f"{len(receipts)}"
+            )
+
+        kept_events: list[str] = []
+        kept_receipts: list[str] = []
+
+        removed = 0
+
+        for event_line, receipt_line in zip(
+            events,
+            receipts,
+        ):
+            receipt: Any = json.loads(
+                receipt_line
+            )
+
+            received_value = receipt.get(
+                "received_at_server"
+            )
+
+            if not isinstance(
+                received_value,
+                str,
+            ):
+                raise RuntimeError(
+                    "receipt metadata missing "
+                    "received_at_server"
+                )
+
+            received = _parse_server_time(
+                received_value
+            )
+
+            if received < cutoff:
+                removed += 1
+                continue
+
+            kept_events.append(
+                event_line
+            )
+
+            kept_receipts.append(
+                receipt_line
+            )
+
+        if removed:
+            _rewrite(
+                event_log,
+                kept_events,
+            )
+
+            _rewrite(
+                receipt_log,
+                kept_receipts,
+            )
+
+        return {
+            "before":
+                len(events),
+
+            "removed":
+                removed,
+
+            "after":
+                len(kept_events),
+        }
+
+    finally:
+        try:
+            fcntl.flock(
+                lock_fd,
+                fcntl.LOCK_UN,
+            )
+        finally:
+            os.close(
+                lock_fd
+            )
+
+
+def prune_default_retention() -> dict[str, int]:
+    return prune_expired_events()