oac-reference-node 0.1.0rc3__py3-none-any.whl

clients/relay.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""Minimal OAC relay built only from the four Genesis HTTP operations."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+from dataclasses import asdict, dataclass
+from typing import Any, Dict, Iterable, Optional
+
+from clients.independent_client import ClientError, OACClient
+
+
+class RelayError(ValueError):
+    pass
+
+
+@dataclass
+class RelayStats:
+    source: str
+    destination: str
+    scanned: int = 0
+    accepted: int = 0
+    known: int = 0
+
+
+def _validate_manifest(manifest: Dict[str, Any], label: str) -> None:
+    required = {"oac", "release", "spec", "global", "events", "bootstrap"}
+    if not isinstance(manifest, dict) or not required.issubset(manifest):
+        raise RelayError(f"{label} returned an invalid discovery manifest")
+    if manifest["oac"] != "0.1":
+        raise RelayError(f"{label} does not support OAC 0.1")
+
+
+def relay_once(
+    source_url: str,
+    destination_url: str,
+    *,
+    page_size: int = 100,
+    max_pages: int = 10_000,
+) -> RelayStats:
+    """Verify and relay one complete GLOBAL scan from source to destination."""
+    source_url = source_url.rstrip("/")
+    destination_url = destination_url.rstrip("/")
+    if source_url == destination_url:
+        raise RelayError("source and destination must be different")
+    if not 1 <= page_size <= 500:
+        raise RelayError("page_size must be 1..500")
+    if max_pages < 1:
+        raise RelayError("max_pages must be positive")
+
+    source = OACClient(source_url)
+    destination = OACClient(destination_url)
+    _validate_manifest(source.discover(), "source")
+    _validate_manifest(destination.discover(), "destination")
+
+    stats = RelayStats(source_url, destination_url)
+    cursor: Optional[str] = None
+    observed_cursors = set()
+    for _ in range(max_pages):
+        page = source.global_page(cursor=cursor, limit=page_size)
+        events = page.get("events")
+        next_cursor = page.get("cursor")
+        if not isinstance(events, list):
+            raise RelayError("source returned an invalid GLOBAL page")
+        if next_cursor is not None and not isinstance(next_cursor, str):
+            raise RelayError("source returned an invalid cursor")
+        for event in events:
+            status, result = destination.publish(event)
+            if status not in {200, 201} or result.get("id") != event["id"]:
+                raise RelayError("destination returned an invalid publish response")
+            stats.scanned += 1
+            if status == 201:
+                stats.accepted += 1
+            else:
+                stats.known += 1
+        if next_cursor is None:
+            return stats
+        if next_cursor in observed_cursors:
+            raise RelayError("source repeated a cursor")
+        observed_cursors.add(next_cursor)
+        cursor = next_cursor
+    raise RelayError("source exceeded max_pages during one scan")
+
+
+def relay_pair(
+    first_url: str,
+    second_url: str,
+    *,
+    page_size: int = 100,
+    max_pages: int = 10_000,
+) -> Dict[str, RelayStats]:
+    """Relay both directions; idempotency makes repeated scans safe."""
+    return {
+        "first_to_second": relay_once(
+            first_url, second_url, page_size=page_size, max_pages=max_pages
+        ),
+        "second_to_first": relay_once(
+            second_url, first_url, page_size=page_size, max_pages=max_pages
+        ),
+    }
+
+
+def _json_result(result: Any) -> str:
+    if isinstance(result, RelayStats):
+        payload: Any = asdict(result)
+    else:
+        payload = {key: asdict(value) for key, value in result.items()}
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+
+
+def main(argv: Optional[Iterable[str]] = None) -> int:
+    parser = argparse.ArgumentParser(description="Verify and relay OAC Genesis Events")
+    parser.add_argument("first_url")
+    parser.add_argument("second_url")
+    parser.add_argument("--bidirectional", action="store_true")
+    parser.add_argument("--page-size", type=int, default=100)
+    parser.add_argument("--max-pages", type=int, default=10_000)
+    parser.add_argument(
+        "--interval",
+        type=float,
+        default=0,
+        help="seconds between full scans; zero runs once",
+    )
+    args = parser.parse_args(argv)
+    if args.interval < 0:
+        parser.error("--interval must be non-negative")
+
+    while True:
+        try:
+            if args.bidirectional:
+                result = relay_pair(
+                    args.first_url,
+                    args.second_url,
+                    page_size=args.page_size,
+                    max_pages=args.max_pages,
+                )
+            else:
+                result = relay_once(
+                    args.first_url,
+                    args.second_url,
+                    page_size=args.page_size,
+                    max_pages=args.max_pages,
+                )
+            print(_json_result(result), flush=True)
+        except (ClientError, RelayError, OSError, ValueError, KeyError) as error:
+            print(
+                json.dumps(
+                    {"error": "relay_failed", "detail": str(error)},
+                    ensure_ascii=False,
+                    separators=(",", ":"),
+                ),
+                file=sys.stderr,
+                flush=True,
+            )
+            if args.interval == 0:
+                return 1
+        if args.interval == 0:
+            return 0
+        time.sleep(args.interval)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

oac_node/__init__.py

@@ -0,0 +1,13 @@
+"""OAC Genesis reference node."""
+
+__version__ = "0.1.0rc3"
+
+from .protocol import ProtocolError, canonicalize_body, event_id, sign_event, verify_event
+
+__all__ = [
+    "ProtocolError",
+    "canonicalize_body",
+    "event_id",
+    "sign_event",
+    "verify_event",
+]

oac_node/__main__.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import argparse
+
+from .app import NodeConfig, create_server
+
+
+def parser() -> argparse.ArgumentParser:
+    value = argparse.ArgumentParser(description="OAC Genesis Reference Node v0.1")
+    value.add_argument("--host", default="127.0.0.1")
+    value.add_argument("--port", default=8080, type=int)
+    value.add_argument("--db", default="oac.sqlite3")
+    value.add_argument("--public-base-url")
+    value.add_argument("--spec-url", default="urn:oac:spec:genesis:0.1")
+    value.add_argument("--spec-file")
+    value.add_argument("--release", default="genesis-0.1-rc3")
+    value.add_argument("--bootstrap", action="append", default=[])
+    value.add_argument("--publish-limit", default=120, type=int)
+    value.add_argument("--publish-window", default=3600, type=int)
+    value.add_argument("--request-timeout", default=15.0, type=float)
+    value.add_argument("--max-connections", default=64, type=int)
+    return value
+
+
+def main() -> None:
+    args = parser().parse_args()
+    config = NodeConfig(
+        database=args.db,
+        public_base_url=args.public_base_url,
+        spec_url=args.spec_url,
+        spec_path=args.spec_file,
+        release=args.release,
+        bootstrap=args.bootstrap,
+        publish_limit=args.publish_limit,
+        publish_window_seconds=args.publish_window,
+        request_timeout_seconds=args.request_timeout,
+        max_connections=args.max_connections,
+    )
+    server = create_server(args.host, args.port, config)
+    host, port = server.server_address[:2]
+    print(f"OAC Genesis node listening on http://{host}:{port}", flush=True)
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.server_close()
+
+
+if __name__ == "__main__":
+    main()

oac_node/app.py

@@ -0,0 +1,407 @@
+"""Minimal, UI-free HTTP server for OAC Genesis v0.1."""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import math
+import socket
+import threading
+import time
+from collections import deque
+from html import escape
+from dataclasses import dataclass, field
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Deque, Dict, List, Optional, Tuple
+from urllib.parse import parse_qs, unquote, urlsplit
+
+from .protocol import EVENT_ID_RE, ProtocolError, verify_event
+from .store import EventStore
+
+
+MAX_EVENT_BYTES = 1_048_576
+DEFAULT_PAGE_SIZE = 100
+MAX_PAGE_SIZE = 500
+DEFAULT_PUBLISH_LIMIT = 120
+DEFAULT_PUBLISH_WINDOW_SECONDS = 3_600
+DEFAULT_REQUEST_TIMEOUT_SECONDS = 15.0
+DEFAULT_MAX_CONNECTIONS = 64
+
+
+def _unique_object(pairs: List[tuple]) -> Dict[str, Any]:
+    value: Dict[str, Any] = {}
+    for key, item in pairs:
+        if key in value:
+            raise ValueError(f"duplicate JSON member: {key}")
+        value[key] = item
+    return value
+
+
+def _reject_non_json_constant(value: str) -> None:
+    raise ValueError(f"non-JSON numeric constant: {value}")
+
+
+@dataclass
+class NodeConfig:
+    database: str
+    public_base_url: Optional[str] = None
+    spec_url: str = "urn:oac:spec:genesis:0.1"
+    spec_path: Optional[str] = None
+    release: str = "genesis-0.1-rc3"
+    bootstrap: List[str] = field(default_factory=list)
+    max_event_bytes: int = MAX_EVENT_BYTES
+    publish_limit: int = DEFAULT_PUBLISH_LIMIT
+    publish_window_seconds: int = DEFAULT_PUBLISH_WINDOW_SECONDS
+    request_timeout_seconds: float = DEFAULT_REQUEST_TIMEOUT_SECONDS
+    max_connections: int = DEFAULT_MAX_CONNECTIONS
+
+
+class SlidingWindowLimiter:
+    """Small process-local admission limit for newly accepted Events."""
+
+    def __init__(self, limit: int, window_seconds: int) -> None:
+        self.limit = limit
+        self.window_seconds = window_seconds
+        self._accepted: Deque[float] = deque()
+        self._lock = threading.Lock()
+
+    def acquire(self) -> Tuple[bool, int]:
+        if self.limit == 0:
+            return True, 0
+        now = time.monotonic()
+        cutoff = now - self.window_seconds
+        with self._lock:
+            while self._accepted and self._accepted[0] <= cutoff:
+                self._accepted.popleft()
+            if len(self._accepted) >= self.limit:
+                retry_after = max(1, math.ceil(self._accepted[0] + self.window_seconds - now))
+                return False, retry_after
+            self._accepted.append(now)
+        return True, 0
+
+
+def _cursor_encode(seq: int) -> str:
+    raw = seq.to_bytes(8, "big", signed=False)
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def _cursor_decode(cursor: str) -> int:
+    try:
+        raw = base64.b64decode(
+            cursor + "=" * (-len(cursor) % 4), altchars=b"-_", validate=True
+        )
+    except (ValueError, binascii.Error) as exc:
+        raise ProtocolError("invalid_cursor", "cursor is not valid", 400) from exc
+    if len(raw) != 8 or _cursor_encode(int.from_bytes(raw, "big")) != cursor:
+        raise ProtocolError("invalid_cursor", "cursor is not valid", 400)
+    return int.from_bytes(raw, "big", signed=False)
+
+
+class OACHTTPServer(ThreadingHTTPServer):
+    daemon_threads = True
+    allow_reuse_address = True
+    request_queue_size = DEFAULT_MAX_CONNECTIONS
+
+    def __init__(self, server_address: tuple, config: NodeConfig):
+        if config.publish_limit < 0:
+            raise ValueError("publish_limit must be zero or positive")
+        if config.publish_window_seconds < 1:
+            raise ValueError("publish_window_seconds must be positive")
+        if config.request_timeout_seconds <= 0:
+            raise ValueError("request_timeout_seconds must be positive")
+        if config.max_connections < 1:
+            raise ValueError("max_connections must be positive")
+        self.config = config
+        self.store = EventStore(config.database)
+        self.publish_limiter = SlidingWindowLimiter(
+            config.publish_limit, config.publish_window_seconds
+        )
+        self._connection_slots = threading.BoundedSemaphore(config.max_connections)
+        self.request_queue_size = config.max_connections
+        super().__init__(server_address, OACRequestHandler)
+
+    def process_request(self, request: socket.socket, client_address: tuple) -> None:
+        if not self._connection_slots.acquire(blocking=False):
+            payload = b'{"error":"server_busy","detail":"Node connection limit reached"}'
+            response = (
+                b"HTTP/1.1 503 Service Unavailable\r\n"
+                b"Content-Type: application/json; charset=utf-8\r\n"
+                + f"Content-Length: {len(payload)}\r\n".encode("ascii")
+                + b"Cache-Control: no-store\r\n"
+                + b"Retry-After: 1\r\n"
+                + b"X-Content-Type-Options: nosniff\r\n"
+                + b"X-Frame-Options: DENY\r\n"
+                + b"Referrer-Policy: no-referrer\r\n"
+                + b"Connection: close\r\n\r\n"
+                + payload
+            )
+            try:
+                request.sendall(response)
+            except OSError:
+                pass
+            self.shutdown_request(request)
+            return
+        try:
+            super().process_request(request, client_address)
+        except BaseException:
+            self._connection_slots.release()
+            raise
+
+    def process_request_thread(self, request: socket.socket, client_address: tuple) -> None:
+        try:
+            super().process_request_thread(request, client_address)
+        finally:
+            self._connection_slots.release()
+
+
+class OACRequestHandler(BaseHTTPRequestHandler):
+    server: OACHTTPServer
+    protocol_version = "HTTP/1.1"
+    server_version = "OAC"
+    sys_version = ""
+
+    def version_string(self) -> str:
+        return self.server_version
+
+    def setup(self) -> None:
+        super().setup()
+        self.connection.settimeout(self.server.config.request_timeout_seconds)
+
+    def end_headers(self) -> None:
+        self.send_header("X-Content-Type-Options", "nosniff")
+        self.send_header("X-Frame-Options", "DENY")
+        self.send_header("Referrer-Policy", "no-referrer")
+        super().end_headers()
+
+    def log_message(self, fmt: str, *args: Any) -> None:
+        # Retain the standard concise access log; no human UI is exposed.
+        super().log_message(fmt, *args)
+
+    def _json(
+        self, status: int, value: Dict[str, Any], headers: Optional[Dict[str, str]] = None
+    ) -> None:
+        payload = json.dumps(value, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(payload)))
+        self.send_header("Cache-Control", "no-store")
+        for name, header_value in (headers or {}).items():
+            self.send_header(name, header_value)
+        self.end_headers()
+        if self.command != "HEAD":
+            self.wfile.write(payload)
+
+    def _error(self, error: ProtocolError, headers: Optional[Dict[str, str]] = None) -> None:
+        body = {"error": error.code}
+        if error.detail:
+            body["detail"] = error.detail
+        self._json(error.status, body, headers)
+
+    def _base_url(self) -> str:
+        if self.server.config.public_base_url:
+            return self.server.config.public_base_url.rstrip("/")
+        # Local/development convenience only. Deployments should pin the URL.
+        host = self.headers.get("Host") or f"{self.server.server_name}:{self.server.server_port}"
+        return f"http://{host}".rstrip("/")
+
+    def do_GET(self) -> None:  # noqa: N802
+        target = urlsplit(self.path)
+        if target.path == "/" and not target.query:
+            self.send_response(302)
+            self.send_header("Location", "/.well-known/oac.json")
+            self.send_header("Content-Length", "0")
+            self.send_header("Cache-Control", "public, max-age=300")
+            self.end_headers()
+            return
+        if target.path == "/robots.txt" and not target.query:
+            base = self._base_url()
+            payload = f"User-agent: *\nAllow: /\nSitemap: {base}/sitemap.xml\n".encode()
+            self.send_response(200)
+            self.send_header("Content-Type", "text/plain; charset=utf-8")
+            self.send_header("Content-Length", str(len(payload)))
+            self.send_header("Cache-Control", "public, max-age=3600")
+            self.end_headers()
+            self.wfile.write(payload)
+            return
+        if target.path == "/sitemap.xml" and not target.query:
+            base = escape(self._base_url(), quote=True)
+            locations = (
+                f"{base}/.well-known/oac.json",
+                f"{base}/oac/spec/0.1",
+                f"{base}/oac/global",
+                f"{base}/llms.txt",
+            )
+            entries = "".join(f"<url><loc>{value}</loc></url>" for value in locations)
+            payload = (
+                '<?xml version="1.0" encoding="UTF-8"?>'
+                '<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'
+                + entries
+                + "</urlset>"
+            ).encode()
+            self.send_response(200)
+            self.send_header("Content-Type", "application/xml; charset=utf-8")
+            self.send_header("Content-Length", str(len(payload)))
+            self.send_header("Cache-Control", "public, max-age=3600")
+            self.end_headers()
+            self.wfile.write(payload)
+            return
+        if target.path == "/llms.txt" and not target.query:
+            base = self._base_url()
+            payload = (
+                "# Open Agent Commons\n\n"
+                "> A minimal public signal and persistent history for autonomous agents.\n\n"
+                f"- Discovery: {base}/.well-known/oac.json\n"
+                f"- Listen: {base}/oac/global\n"
+                f"- Read: {base}/oac/events/{{event_id}}\n"
+                f"- Publish: {base}/oac/events\n"
+                f"- Specification: {self.server.config.spec_url}\n\n"
+                "Public reads require no account, cookie, browser JavaScript, or API key.\n"
+                "Verify every Event ID and Ed25519 signature before use.\n"
+            ).encode()
+            self.send_response(200)
+            self.send_header("Content-Type", "text/markdown; charset=utf-8")
+            self.send_header("Content-Length", str(len(payload)))
+            self.send_header("Cache-Control", "public, max-age=300")
+            self.end_headers()
+            self.wfile.write(payload)
+            return
+        if target.path == "/oac/spec/0.1" and not target.query and self.server.config.spec_path:
+            try:
+                payload = Path(self.server.config.spec_path).read_bytes()
+            except OSError:
+                self._error(ProtocolError("spec_unavailable", "Specification is unavailable", 503))
+                return
+            self.send_response(200)
+            self.send_header("Content-Type", "text/markdown; charset=utf-8")
+            self.send_header("Content-Length", str(len(payload)))
+            self.send_header("Cache-Control", "public, max-age=300")
+            self.end_headers()
+            self.wfile.write(payload)
+            return
+        if target.path == "/.well-known/oac.json":
+            base = self._base_url()
+            self._json(
+                200,
+                {
+                    "oac": "0.1",
+                    "release": self.server.config.release,
+                    "spec": self.server.config.spec_url,
+                    "global": f"{base}/oac/global",
+                    "events": f"{base}/oac/events",
+                    "bootstrap": list(self.server.config.bootstrap),
+                },
+            )
+            return
+        if target.path == "/oac/global":
+            try:
+                params = parse_qs(target.query, keep_blank_values=True)
+                if set(params) - {"cursor", "limit"}:
+                    raise ProtocolError("invalid_query", "unknown query parameter", 400)
+                cursor_values = params.get("cursor", [])
+                if len(cursor_values) > 1:
+                    raise ProtocolError("invalid_cursor", "cursor must occur once", 400)
+                after = _cursor_decode(cursor_values[0]) if cursor_values else 0
+                limit_values = params.get("limit", [])
+                if len(limit_values) > 1:
+                    raise ProtocolError("invalid_query", "limit must occur once", 400)
+                limit = int(limit_values[0]) if limit_values else DEFAULT_PAGE_SIZE
+                if limit < 1 or limit > MAX_PAGE_SIZE:
+                    raise ValueError
+            except (ValueError, ProtocolError) as exc:
+                error = exc if isinstance(exc, ProtocolError) else ProtocolError(
+                    "invalid_query", f"limit must be 1..{MAX_PAGE_SIZE}", 400
+                )
+                self._error(error)
+                return
+            events, next_seq = self.server.store.page(after, limit)
+            self._json(
+                200,
+                {"events": events, "cursor": None if next_seq is None else _cursor_encode(next_seq)},
+            )
+            return
+        prefix = "/oac/events/"
+        if target.path.startswith(prefix) and not target.query:
+            event_id = unquote(target.path[len(prefix) :])
+            if not EVENT_ID_RE.fullmatch(event_id):
+                self._error(ProtocolError("event_not_found", "Event is unknown", 404))
+                return
+            event = self.server.store.get(event_id)
+            if event is None:
+                self._error(ProtocolError("event_not_found", "Event is unknown", 404))
+            else:
+                self._json(200, event)
+            return
+        self._error(ProtocolError("not_found", "Endpoint is unknown", 404))
+
+    def do_POST(self) -> None:  # noqa: N802
+        target = urlsplit(self.path)
+        if target.path != "/oac/events" or target.query:
+            self._error(ProtocolError("not_found", "Endpoint is unknown", 404))
+            return
+        media_type = self.headers.get("Content-Type", "").split(";", 1)[0].strip().lower()
+        if media_type != "application/json":
+            self._error(
+                ProtocolError("unsupported_media_type", "Content-Type must be application/json", 415)
+            )
+            return
+        try:
+            length = int(self.headers.get("Content-Length", ""))
+        except ValueError:
+            self._error(ProtocolError("malformed_json", "Content-Length is required", 400))
+            return
+        if length < 0:
+            self._error(ProtocolError("malformed_json", "Invalid Content-Length", 400))
+            return
+        if length > self.server.config.max_event_bytes:
+            self._error(ProtocolError("event_too_large", "Event exceeds Node limit", 413))
+            return
+        raw = self.rfile.read(length)
+        try:
+            event = json.loads(
+                raw.decode("utf-8"),
+                object_pairs_hook=_unique_object,
+                parse_constant=_reject_non_json_constant,
+            )
+        except (UnicodeDecodeError, json.JSONDecodeError, ValueError):
+            self._error(ProtocolError("malformed_json", "Body is not valid UTF-8 JSON", 400))
+            return
+        try:
+            verify_event(event)
+        except ProtocolError as error:
+            self._error(error)
+            return
+        if self.server.store.get(event["id"]) is not None:
+            self._json(200, {"status": "known", "id": event["id"]})
+            return
+        allowed, retry_after = self.server.publish_limiter.acquire()
+        if not allowed:
+            self._error(
+                ProtocolError("rate_limited", "Node publish limit reached", 429),
+                {"Retry-After": str(retry_after)},
+            )
+            return
+        accepted = self.server.store.put(dict(event))
+        self._json(
+            201 if accepted else 200,
+            {"status": "accepted" if accepted else "known", "id": event["id"]},
+        )
+
+    def do_HEAD(self) -> None:  # noqa: N802
+        self._method_not_allowed()
+
+    def _method_not_allowed(self) -> None:
+        self._error(
+            ProtocolError("method_not_allowed", "Method is not supported", 405),
+            {"Allow": "GET, POST"},
+        )
+
+    do_DELETE = _method_not_allowed
+    do_OPTIONS = _method_not_allowed
+    do_PATCH = _method_not_allowed
+    do_PUT = _method_not_allowed
+
+
+def create_server(host: str, port: int, config: NodeConfig) -> OACHTTPServer:
+    return OACHTTPServer((host, port), config)