@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-python/src/hkp/data.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+"""HKP shared data types for the Python runtime.
+
+These mirror the cross-runtime data model:
+  hkp-frontend/src/runtime/rest/Data.ts   (TypeScript)
+  hkp-rt/lib/include/types/data.h         (C++)
+
+Plain ``dict`` / ``list`` values represent the JSON data type, so existing
+services keep working untouched. The classes below cover the non-JSON types
+that travel over the YAS binary wire format.
+"""
+
+from array import array
+from dataclasses import dataclass, field
+from typing import Any
+import time
+
+
+class DataTypeId:
+    """Wire-format type ids — in sync with data.h / Data.ts."""
+
+    UNDEFINED = 0
+    FLOAT_RING_BUFFER = 1
+    JSON = 2
+    BINARY = 3
+    STRING = 4
+    NULL = 5
+    CONTROL_FLOW = 6
+    CUSTOM = 7
+
+
+@dataclass
+class FloatRingBuffer:
+    """Contiguous float32 samples with id + timestamp (the audio type)."""
+
+    samples: bytes  # raw little-endian float32 samples
+    id: int = 0
+    ts: int = field(default_factory=lambda: int(time.time() * 1000))
+
+    @classmethod
+    def from_floats(cls, values: list[float] | array, id: int = 0, ts: int | None = None) -> "FloatRingBuffer":
+        arr = values if isinstance(values, array) else array("f", values)
+        if arr.typecode != "f":
+            raise ValueError("FloatRingBuffer.from_floats requires float32 ('f') values")
+        kwargs = {} if ts is None else {"ts": ts}
+        return cls(samples=arr.tobytes(), id=id, **kwargs)
+
+    def to_floats(self) -> array:
+        arr = array("f")
+        arr.frombytes(self.samples)
+        return arr
+
+    @property
+    def num_samples(self) -> int:
+        return len(self.samples) // 4
+
+
+@dataclass
+class TextData:
+    text: str
+
+
+@dataclass
+class BinaryData:
+    data: bytes
+
+
+@dataclass
+class ControlFlowData:
+    """Early-return signal: skips the remaining services in the runtime and
+    makes `result` the runtime's output (see the shared data-types table)."""
+
+    result: Any
+
+
+class NullData:
+    """Signals stop / no output."""
+
+    _instance: "NullData | None" = None
+
+    def __new__(cls) -> "NullData":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "NullData()"
+
+
+class UndefinedData:
+    """Uninitialized / not yet set."""
+
+    _instance: "UndefinedData | None" = None
+
+    def __new__(cls) -> "UndefinedData":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __repr__(self) -> str:
+        return "UndefinedData()"
+
+
+def get_data_type_id(data: object) -> int:
+    if isinstance(data, FloatRingBuffer):
+        return DataTypeId.FLOAT_RING_BUFFER
+    if isinstance(data, (dict, list)):
+        return DataTypeId.JSON
+    if isinstance(data, BinaryData):
+        return DataTypeId.BINARY
+    if isinstance(data, (TextData, str)):
+        return DataTypeId.STRING
+    if isinstance(data, NullData) or data is None:
+        return DataTypeId.NULL
+    if isinstance(data, UndefinedData):
+        return DataTypeId.UNDEFINED
+    raise TypeError(f"get_data_type_id: unsupported data type: {type(data)!r}")

package/bundle/hkp-python/src/hkp/egress.py

@@ -0,0 +1,310 @@
+"""Where a board may make this server connect to.
+
+A board names destinations — an HTTP Client's URL, an asset, a model's base
+URL — and the server dials them. On a person's own machine that is the point.
+On a server several people's boards run on it is not: this server's loopback,
+its private network and a cloud provider's metadata endpoint
+(``169.254.169.254``, which hands out the instance's credentials) are reachable
+from here and are not a board's to reach.
+
+So a server can be told it is hosted: with ``HKP_EGRESS=public``, a destination
+is reached only when every address its name resolves to is a public internet
+address. Unset, nothing is refused.
+
+**Judged where the socket opens, on the address it opens to** — not on the
+name a board wrote, which may resolve to something else by the time it is
+dialled. That covers every hop of a redirect and every spelling of an address
+too.
+
+Services reach the network through what is here: ``client_session`` for
+aiohttp, ``urlopen`` for urllib. ``tests/test_egress_sources.py`` fails on any
+other way out. Connections the operator configured rather than a board — the
+coordinator link, a model download from a fixed release address — are not a
+board's destinations and are not judged here.
+
+The same rule, range for range, is in hkp-node (``src/egress.ts``) and hkp-rt
+(``lib/include/egress.h``).
+"""
+
+from __future__ import annotations
+
+import http.client
+import ipaddress
+import socket
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any, Mapping
+
+import aiohttp
+
+# What is not the public internet: this host, private networks, link-local
+# (where the metadata endpoints are), shared address space, and what is not an
+# address one connects to at all. ``::/96`` is the deprecated IPv4-compatible
+# form (``::127.0.0.1``); ``64:ff9b:1::/48`` is a network's own NAT64 prefix,
+# which may translate to private IPv4 and puts the IPv4 address where that
+# network chose, so the whole range is refused rather than judged by what it
+# carries.
+_NOT_PUBLIC = [
+    ipaddress.ip_network(text)
+    for text in (
+        "0.0.0.0/8",
+        "127.0.0.0/8",
+        "10.0.0.0/8",
+        "172.16.0.0/12",
+        "192.168.0.0/16",
+        "100.64.0.0/10",
+        "169.254.0.0/16",
+        "192.0.0.0/24",
+        "198.18.0.0/15",
+        "224.0.0.0/4",
+        "240.0.0.0/4",
+        "::/96",
+        "::1/128",
+        "fe80::/10",
+        "fc00::/7",
+        "ff00::/8",
+        "64:ff9b:1::/48",
+    )
+]
+
+_NAT64 = ipaddress.ip_network("64:ff9b::/96")
+
+
+@dataclass(frozen=True)
+class EgressPolicy:
+    mode: str = "open"
+    #: Addresses and ranges reached anyway, as the operator listed them.
+    allow: tuple[ipaddress.IPv4Network | ipaddress.IPv6Network, ...] = field(
+        default_factory=tuple
+    )
+
+
+OPEN = EgressPolicy()
+
+
+def _address(text: str) -> ipaddress.IPv4Address | ipaddress.IPv6Address | None:
+    try:
+        return ipaddress.ip_address(text.strip("[]").split("%", 1)[0])
+    except ValueError:
+        return None
+
+
+def _carried(
+    address: ipaddress.IPv4Address | ipaddress.IPv6Address,
+) -> ipaddress.IPv4Address | ipaddress.IPv6Address:
+    """An IPv6 address that carries an IPv4 one is that IPv4 address:
+    ``::ffff:127.0.0.1`` is loopback."""
+    if isinstance(address, ipaddress.IPv6Address):
+        if address.ipv4_mapped is not None:
+            return address.ipv4_mapped
+        if address.sixtofour is not None:
+            return address.sixtofour
+        if address in _NAT64:
+            return ipaddress.IPv4Address(int(address) & 0xFFFFFFFF)
+    return address
+
+
+def is_public_address(text: str) -> bool:
+    """Whether ``text`` is a public internet address. Not an address: False."""
+    address = _address(text)
+    if address is None:
+        return False
+    address = _carried(address)
+    return not any(address in network for network in _NOT_PUBLIC)
+
+
+def read_egress_policy(env: Mapping[str, str]) -> EgressPolicy:
+    """Reads ``HKP_EGRESS`` and ``HKP_EGRESS_ALLOW``.
+
+    An entry of the list that is not an address or a range is an error rather
+    than skipped: an operator who meant to allow something should learn now
+    that nothing was. Names are not accepted, since an allowed name could be
+    repointed.
+    """
+    mode = (env.get("HKP_EGRESS") or "").strip().lower()
+    if mode in ("", "open"):
+        return OPEN
+    if mode != "public":
+        raise ValueError(f'HKP_EGRESS must be "public" or unset, not "{env.get("HKP_EGRESS")}"')
+    allow = []
+    for entry in (env.get("HKP_EGRESS_ALLOW") or "").split(","):
+        entry = entry.strip()
+        if not entry:
+            continue
+        try:
+            allow.append(ipaddress.ip_network(entry, strict=False))
+        except ValueError:
+            raise ValueError(
+                f'HKP_EGRESS_ALLOW: "{entry}" is not an address or a range '
+                "(names are not accepted: an allowed name could be repointed)"
+            ) from None
+    return EgressPolicy(mode="public", allow=tuple(allow))
+
+
+def may_reach(policy: EgressPolicy, text: str) -> bool:
+    """Whether a destination at address ``text`` may be reached under ``policy``."""
+    if policy.mode == "open":
+        return True
+    address = _address(text)
+    if address is not None and any(
+        address.version == network.version and address in network for network in policy.allow
+    ):
+        return True
+    return is_public_address(text)
+
+
+class EgressRefused(OSError):
+    """A destination this server will not connect to, and why.
+
+    An ``OSError``, so that the clients that report a failed connection report
+    this one the same way — and keep it as the cause.
+    """
+
+    def __init__(self, host: str, address: str) -> None:
+        message = (
+            f"This server does not reach private addresses ({address})"
+            if host == address
+            else f"This server does not reach private addresses ({host} is {address})"
+        )
+        super().__init__(message)
+        self.host = host
+        self.address = address
+
+    def __str__(self) -> str:
+        return self.args[0]
+
+
+_active: EgressPolicy = OPEN
+
+
+def egress_policy() -> EgressPolicy:
+    return _active
+
+
+def set_egress_policy(policy: EgressPolicy) -> None:
+    global _active
+    _active = policy
+
+
+def failure_reason(error: BaseException) -> str:
+    """What to say about a failed connection: the refusal when this was one.
+
+    The clients wrap what went wrong — aiohttp in a ``ClientConnectorError``,
+    urllib in a ``URLError`` — and keep it as the cause or the reason.
+    """
+    refused = refusal_in(error)
+    return str(refused) if refused else str(error)
+
+
+def refusal_in(error: BaseException | None) -> EgressRefused | None:
+    """The refusal an error is, or was caused by."""
+    seen = 0
+    current: Any = error
+    while current is not None and seen < 6:
+        if isinstance(current, EgressRefused):
+            return current
+        current = (
+            getattr(current, "os_error", None)
+            or getattr(current, "reason", None)
+            or current.__cause__
+            or current.__context__
+        )
+        if not isinstance(current, BaseException):
+            return None
+        seen += 1
+    return None
+
+
+def _check(host: str, addresses: list[str]) -> None:
+    for address in addresses:
+        if not may_reach(_active, address):
+            raise EgressRefused(host, address)
+
+
+# ── aiohttp ──────────────────────────────────────────────────────────────────
+
+
+class _EgressConnector(aiohttp.TCPConnector):
+    """A connector that refuses a destination any of whose addresses may not be
+    reached.
+
+    ``_resolve_host`` is where aiohttp turns a host — a name or an address
+    literal — into the addresses it will connect to, for every connection and
+    every redirect hop. It is private: ``tests/test_egress.py`` pins that a
+    private address is refused through it, so an aiohttp that renamed it would
+    fail there rather than let everything through.
+    """
+
+    async def _resolve_host(self, host: str, port: int, traces: Any = None) -> Any:
+        resolved = await super()._resolve_host(host, port, traces=traces)
+        _check(host, [entry["host"] for entry in resolved])
+        return resolved
+
+
+def client_session(**kwargs: Any) -> aiohttp.ClientSession:
+    """An ``aiohttp.ClientSession`` for a board's destinations. Open: the
+    default session. Hosted: one whose connector checks every connection."""
+    if _active.mode != "open" and "connector" not in kwargs:
+        kwargs["connector"] = _EgressConnector()
+    return aiohttp.ClientSession(**kwargs)
+
+
+# ── urllib ───────────────────────────────────────────────────────────────────
+
+
+def _checked_connection(address, timeout=socket._GLOBAL_DEFAULT_TIMEOUT, source_address=None, **kwargs):
+    """``socket.create_connection``, to an address the policy allows.
+
+    Resolved here and connected to what was checked, so a second lookup cannot
+    answer differently. TLS is wrapped around the socket afterwards by
+    ``http.client``, against the name, so the certificate is still checked
+    for the host that was asked for.
+    """
+    host, port = address
+    infos = socket.getaddrinfo(host, port, type=socket.SOCK_STREAM)
+    _check(host, [info[4][0] for info in infos])
+    last: OSError | None = None
+    for family, kind, proto, _, sockaddr in infos:
+        sock = socket.socket(family, kind, proto)
+        try:
+            if timeout is not socket._GLOBAL_DEFAULT_TIMEOUT:
+                sock.settimeout(timeout)
+            if source_address:
+                sock.bind(source_address)
+            sock.connect(sockaddr)
+            return sock
+        except OSError as error:
+            last = error
+            sock.close()
+    raise last or OSError(f"could not connect to {host}")
+
+
+class _CheckedHTTPConnection(http.client.HTTPConnection):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._create_connection = _checked_connection
+
+
+class _CheckedHTTPSConnection(http.client.HTTPSConnection):
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._create_connection = _checked_connection
+
+
+class _CheckedHTTPHandler(urllib.request.HTTPHandler):
+    def http_open(self, req):  # noqa: D102 - urllib's own hook
+        return self.do_open(_CheckedHTTPConnection, req)
+
+
+class _CheckedHTTPSHandler(urllib.request.HTTPSHandler):
+    def https_open(self, req):  # noqa: D102 - urllib's own hook
+        return self.do_open(_CheckedHTTPSConnection, req, context=self._context)
+
+
+def urlopen(request: Any, timeout: Any = socket._GLOBAL_DEFAULT_TIMEOUT) -> Any:
+    """``urllib.request.urlopen`` for a board's destinations. Open: exactly
+    that. Hosted: every connection, redirects included, through the check."""
+    if _active.mode == "open":
+        return urllib.request.urlopen(request, timeout=timeout)
+    opener = urllib.request.build_opener(_CheckedHTTPHandler, _CheckedHTTPSHandler)
+    return opener.open(request, timeout=timeout)

package/bundle/hkp-python/src/hkp/mount.py

@@ -0,0 +1,46 @@
+"""Mount vocabulary.
+
+A service that needs to be reachable from outside is assigned an address by its
+runtime and publishes it in its own state. Both sides use one reserved field::
+
+    __hkpMount says where a mount is.
+
+A service that *owns* a mount publishes its address there, as an absolute
+``http(s)://`` URL. A service that *consumes* one points at the owner there, as
+``hkp-mount://<runtimeId>/<serviceUuid>``. The two forms are told apart by
+scheme; a bare ``<runtimeId>/<serviceUuid>`` is not accepted, because it is
+indistinguishable from a relative URL.
+
+Resolving a reference into an address needs a view of the whole board, which
+only the board's coordinator has. A service therefore never resolves one
+itself: it is configured with the address once the coordinator has it, and a
+reference still sitting here means "not ready yet".
+
+Mirrors hkp-node's src/coordinator/mount.ts, hkp-rt's lib/src/mount.h and the
+frontend's runtime/board/mount.ts; the four must agree, since they read the same
+boards.
+"""
+from __future__ import annotations
+
+#: State field holding a mount address, on both the owner and the consumer.
+MOUNT_FIELD = "__hkpMount"
+
+#: Scheme marking a value as a reference to a mount-owning service.
+MOUNT_SCHEME = "hkp-mount://"
+
+
+def is_mount_reference(value: str | None) -> bool:
+    """Whether a ``__hkpMount`` value still names a service rather than an
+    address — i.e. whether the coordinator has yet to resolve it.
+    """
+    return bool(value) and value.startswith(MOUNT_SCHEME)
+
+
+def join_mount_path(address: str, path: str) -> str:
+    """Join a mount address and a path, without doubling or dropping the
+    separator.
+    """
+    if not path:
+        return address
+    stem = address[:-1] if address.endswith("/") else address
+    return stem + path if path.startswith("/") else f"{stem}/{path}"