@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/hkp-python/src/hkp/services/http_client.py

@@ -0,0 +1,444 @@
+from __future__ import annotations
+
+# Service Documentation
+# Service ID: http-client
+# Service Name: HTTP Client
+# Runtime: hkp-python
+# Modes: none (method is configuration, not a mode)
+# Key Config: url, __hkpMount (target), path, query, method, headers, userAgent,
+#             body
+# IO: in=body to send (str | dict | bytes | {meta, body|binary})
+#     out=None immediately; the response is pushed through the rest of the
+#     pipeline when it arrives, shaped {meta, body?, binary?}
+#
+# The python implementation of the http-client concept hkp-node and hkp-rt also
+# provide, sharing their state contract (url, method, headers, userAgent, body)
+# and therefore the same UI panel.
+#
+# What it adds, like hkp-node's, is the ability to call a mount. url may hold a
+# hkp-mount://<runtimeId>/<serviceUuid> reference instead of an address: it names
+# the service that owns the endpoint, which is what a board can know when an
+# address is only assigned at load. The board's coordinator — the only instance
+# that can see across runtimes — resolves it and configures __hkpMount with the
+# address, which then takes precedence.
+#
+# So url is what a person writes and __hkpMount is what the run produced, and
+# neither overwrites the other. An unresolved reference in either means the owner
+# has not published yet: a normal state while a board comes up, and a reason to
+# wait rather than to dial anything.
+#
+# query holds the request's parameters as a map, encoded onto the target when it
+# is called — the same shape http-server-subservices reports an incoming
+# request's parameters in, and what a board has instead of escaping them into
+# the URL by hand. Unlike path it applies to every target, because escaping is a
+# service a map performs and a written URL cannot.
+#
+# path is the sub-path of a mount, and applies to nothing else: a typed url is a
+# whole URL and carries its own path. A mount's address is assigned by a runtime
+# and resolved by the coordinator, so it is not the board's to write — which
+# leaves a sub-path of it nowhere else to go.
+#
+# The response shape mirrors what http-server-subservices produces for an
+# incoming request, so a pipeline that handles one handles the other — metadata
+# including the response headers, then the body in whichever form its content
+# type explains.
+
+import asyncio
+import json
+from typing import Any
+from urllib.parse import urlencode
+
+import aiohttp
+
+from ..egress import client_session, failure_reason
+from ..mount import MOUNT_FIELD, is_mount_reference, join_mount_path
+from ..secrets import resolve_credential
+from ..types import (
+    JsonRecord,
+    NotifyCallback,
+    ProcessContext,
+    ServiceConfiguration,
+    ServiceRegistryEntry,
+)
+
+HTTP_CLIENT_DESCRIPTOR = ServiceRegistryEntry(
+    service_id="http-client",
+    service_name="HTTP Client",
+    version="v1",
+    capabilities=[],
+)
+
+# Lower case, as hkp-rt's http-client stores them and the shared UI sends them.
+_METHODS = ("get", "post", "put", "patch", "delete")
+
+
+def _as_parameter(value: str | int | float | bool) -> str:
+    """A query parameter's value as the text it is sent as."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)
+
+
+def _media_type(content_type: str | None) -> str:
+    """Content type with any parameters (``; charset=…``) stripped, lower-cased."""
+    return (content_type or "").split(";")[0].strip().lower()
+
+
+def _is_textual(media_type: str) -> bool:
+    """Whether a response of this type is worth decoding rather than kept as bytes."""
+    return (
+        media_type.startswith("text/")
+        or media_type == "application/json"
+        or media_type.endswith("+json")
+        or media_type == "application/x-www-form-urlencoded"
+    )
+
+
+class HttpClientService:
+    service_id = HTTP_CLIENT_DESCRIPTOR.service_id
+    service_name = HTTP_CLIENT_DESCRIPTOR.service_name
+    version = HTTP_CLIENT_DESCRIPTOR.version
+    capabilities = HTTP_CLIENT_DESCRIPTOR.capabilities
+
+    def __init__(self, config: ServiceConfiguration, _create_service: Any = None) -> None:
+        self.uuid = config.uuid
+        self._host: Any = None
+        self._url = ""
+        self._mount = ""
+        self._path = ""
+        self._query: dict[str, str] = {}
+        self._method = "get"
+        self._headers: dict[str, str] = {}
+        self._user_agent = ""
+        self._body = ""
+        self._timeout_ms = 10000
+        self._bypass = False
+        self._in_flight = 0
+
+        if config.state:
+            self.configure(config.state)
+
+    def set_host(self, host: Any) -> None:
+        self._host = host
+
+    def get_state(self) -> JsonRecord:
+        return {
+            "url": self._url,
+            # Reserved name: the coordinator reads and rewrites it. Holds the
+            # address to call, or a reference to the service that owns it while
+            # unresolved.
+            MOUNT_FIELD: self._mount,
+            "path": self._path,
+            "query": self._query,
+            "method": self._method,
+            "headers": self._headers,
+            "userAgent": self._user_agent,
+            "body": self._body,
+            "timeoutMs": self._timeout_ms,
+            "bypass": self._bypass,
+        }
+
+    def configure(self, config: JsonRecord) -> JsonRecord:
+        if isinstance(config.get("url"), str):
+            self._url = config["url"]
+        if isinstance(config.get(MOUNT_FIELD), str):
+            self._mount = config[MOUNT_FIELD]
+        if isinstance(config.get("path"), str):
+            self._path = config["path"]
+        query = config.get("query")
+        if isinstance(query, dict):
+            # A parameter is sent as text whatever it was written as, so a number
+            # or a flag typed in an editor arrives as the value it reads as — and
+            # a flag as the word the wire uses, not Python's.
+            self._query = {
+                key: _as_parameter(value)
+                for key, value in query.items()
+                if isinstance(value, (str, int, float, bool))
+            }
+        method = config.get("method")
+        if isinstance(method, str) and method.lower() in _METHODS:
+            self._method = method.lower()
+        headers = config.get("headers")
+        if isinstance(headers, dict):
+            self._headers = {
+                key: value for key, value in headers.items() if isinstance(value, str)
+            }
+        if isinstance(config.get("userAgent"), str):
+            self._user_agent = config["userAgent"]
+        if isinstance(config.get("body"), str):
+            self._body = config["body"]
+        timeout = config.get("timeoutMs")
+        if isinstance(timeout, (int, float)) and timeout > 0:
+            self._timeout_ms = int(timeout)
+        if isinstance(config.get("bypass"), bool):
+            self._bypass = config["bypass"]
+        return self.get_state()
+
+    def process(self, input: Any, notify: NotifyCallback) -> Any:
+        """Start the request and stop the synchronous push.
+
+        The runtime calls services one after another without awaiting, so a
+        response cannot be returned from here — it does not exist yet. Returning
+        None stops the push, and the rest of the pipeline is called with the
+        response once it arrives (the inversion-of-control path a cache or a
+        fetching service takes).
+        """
+        if self._bypass:
+            return input
+
+        target = self._target_url()
+        if not target:
+            # Either nothing is configured, or the mount's owner has not
+            # published an address yet. Say so and stop; the next input tries
+            # again, by which time the coordinator has usually handed it over.
+            pending = next(
+                (
+                    value
+                    for value in (self._mount, self._url)
+                    if is_mount_reference(value)
+                ),
+                "",
+            )
+            notify(
+                {
+                    "error": (
+                        f'Waiting for "{pending}" to publish an endpoint'
+                        if pending
+                        else "No target configured"
+                    )
+                }
+            )
+            return None
+
+        # Captured here, while still inside the call this request belongs to.
+        # By the time the response arrives the pass has long returned, so this
+        # is the only moment at which the run that asked for it can be named.
+        context = self._host.current_context() if self._host else None
+
+        # A pass runs on a worker thread, so there is no loop here to schedule
+        # on — the runtime knows the server's and schedules through it. Without
+        # a host there is none to ask, which is a unit test calling process
+        # directly rather than anything a board can reach.
+        coro = self._send(target, input, notify, context)
+        if self._host is None or not self._host.spawn(coro):
+            if self._host is None:
+                coro.close()
+            notify({"error": "No event loop to run the request on"})
+            return None
+        return None
+
+    def destroy(self) -> None:
+        self._host = None
+
+    # ── Private ────────────────────────────────────────────────────────────────
+
+    def _target_url(self) -> str | None:
+        """The URL to call, or None while there is nothing callable.
+
+        A resolved mount address wins over a typed URL — a board that names a
+        service is being explicit about which endpoint it means, and the address
+        is not knowable when the board is written.
+
+        A reference in either field is "not ready yet" rather than something to
+        dial: it names a service whose address nobody has published, and falling
+        back past it would silently call something else. Boards written before
+        the split carry the reference in ``__hkpMount``; both read the same way.
+        """
+        if self._mount:
+            if is_mount_reference(self._mount):
+                return None
+            return self._with_query(join_mount_path(self._mount, self._path))
+        if not self._url or is_mount_reference(self._url):
+            return None
+        return self._with_query(self._url)
+
+    def _with_query(self, target: str) -> str:
+        """Append the configured parameters, encoded.
+
+        Appended rather than replacing what the target already carries: a url or
+        a path may have been written with parameters of its own, and a mount
+        address is not the board's to rewrite.
+        """
+        if not self._query:
+            return target
+        params = urlencode(self._query)
+        separator = "&" if "?" in target else "?"
+        return f"{target}{separator}{params}"
+
+    async def _send(
+        self,
+        url: str,
+        input: Any,
+        notify: NotifyCallback,
+        context: ProcessContext | None = None,
+    ) -> None:
+        body, content_type = self._request_body(input)
+        # Headers are a free-form map, and a credential is as likely to be part
+        # of one — ``Bearer <token>`` — as to be a field of its own. Resolved
+        # against the address being called, so a header bound to one host cannot
+        # be sent to another by repointing this service. What comes back is used
+        # for this request and dropped; nothing resolved goes back into state.
+        credential = resolve_credential(
+            self._host.secrets() if self._host else None, self._headers, url
+        )
+        if credential.problem:
+            notify(
+                {
+                    "requesting": False,
+                    "method": self._method,
+                    "url": url,
+                    "status": 0,
+                    "error": credential.problem,
+                }
+            )
+            return
+        headers = dict(credential.value)
+        if content_type and "content-type" not in {k.lower() for k in headers}:
+            headers["content-type"] = content_type
+        if self._user_agent and "user-agent" not in {k.lower() for k in headers}:
+            headers["user-agent"] = self._user_agent
+
+        self._in_flight += 1
+        notify(
+            {
+                "requesting": True,
+                "method": self._method,
+                "url": url,
+                "inFlight": self._in_flight,
+            }
+        )
+
+        try:
+            timeout = aiohttp.ClientTimeout(total=self._timeout_ms / 1000)
+            async with client_session(timeout=timeout) as session:
+                async with session.request(
+                    self._method.upper(), url, data=body, headers=headers
+                ) as response:
+                    result = await self._read_response(url, response)
+                    notify(
+                        {
+                            "requesting": False,
+                            "method": self._method,
+                            "url": url,
+                            "status": response.status,
+                            # Said on every outcome, so what a panel shows is
+                            # this request's and not the last failure's still
+                            # standing.
+                            "error": "",
+                            "inFlight": self._in_flight - 1,
+                        }
+                    )
+            self._push(result, notify, context)
+        except Exception as err:  # noqa: BLE001 - reported, not swallowed
+            # Status 0: there was no response to have one, so the status of the
+            # request before this stops standing as if it were this one's.
+            notify(
+                {
+                    "requesting": False,
+                    "method": self._method,
+                    "url": url,
+                    "status": 0,
+                    "error": failure_reason(err),
+                }
+            )
+            # A failed request produces no result to pass on: the pipeline behind
+            # this service is not called, rather than called with a fabricated
+            # one.
+        finally:
+            self._in_flight -= 1
+
+    def _request_body(self, input: Any) -> tuple[Any, str | None]:
+        """Turn pipeline input into a request body.
+
+        Accepts what an upstream ``http-server-subservices`` produces, so a
+        request received on one runtime can be forwarded from another unchanged.
+        """
+        if self._method == "get":
+            return None, None
+
+        if input is None:
+            # Nothing came down the pipeline, so send the configured body — which
+            # is how the shared UI's body field is meant to be used.
+            return (self._body, "text/plain; charset=utf-8") if self._body else (None, None)
+
+        if isinstance(input, str):
+            return input, "text/plain; charset=utf-8"
+        if isinstance(input, (bytes, bytearray)):
+            return bytes(input), "application/octet-stream"
+
+        if isinstance(input, dict):
+            meta = input.get("meta")
+            declared = meta.get("contentType") if isinstance(meta, dict) else None
+            binary = input.get("binary")
+            if isinstance(binary, (bytes, bytearray)):
+                return bytes(binary), declared or "application/octet-stream"
+            if meta is not None and "body" in input:
+                body = input["body"]
+                if isinstance(body, str):
+                    return body, declared or "text/plain; charset=utf-8"
+                return json.dumps(body), declared or "application/json"
+
+        return json.dumps(input), "application/json"
+
+    async def _read_response(
+        self, url: str, response: aiohttp.ClientResponse
+    ) -> JsonRecord:
+        """Shape a response the way ``http-server-subservices`` shapes a request:
+        metadata always, a decoded body when the content type says what the bytes
+        mean, the bytes themselves when it does not.
+        """
+        content_type = response.headers.get("content-type")
+        media_type = _media_type(content_type)
+        meta: JsonRecord = {
+            "url": url,
+            "status": response.status,
+            "statusText": response.reason or "",
+            # Lower-cased as HTTP names compare, the way the request shape
+            # reports the headers a caller sent.
+            "headers": {key.lower(): value for key, value in response.headers.items()},
+        }
+        if content_type:
+            meta["contentType"] = content_type
+
+        raw = await response.read()
+        if not raw:
+            return {"meta": meta}
+
+        if _is_textual(media_type):
+            text = raw.decode("utf-8", errors="replace")
+            if media_type == "application/json" or media_type.endswith("+json"):
+                try:
+                    return {"meta": meta, "body": json.loads(text)}
+                except json.JSONDecodeError:
+                    # Declared JSON that is not JSON: hand over the text rather
+                    # than dropping the response.
+                    return {"meta": meta, "body": text}
+            return {"meta": meta, "body": text}
+
+        return {"meta": meta, "binary": raw}
+
+    def _push(
+        self,
+        result: JsonRecord,
+        notify: NotifyCallback,
+        context: ProcessContext | None = None,
+    ) -> None:
+        """Run the rest of the pipeline with the response, then emit the runtime's
+        result. A service that produces data outside the push has to emit it
+        itself; nothing else will, and running the remaining services alone would
+        leave the chain dead from here on.
+        """
+        if not self._host:
+            return
+        output = self._host.process_from(
+            self.uuid,
+            result,
+            # No-op: the runtime already fans these out to its notification
+            # targets. Re-notifying through the host would deliver each twice.
+            lambda _n: None,
+            context,
+        )
+        # A downstream service returning None means "stop" — honour it rather
+        # than forwarding a dead result to the next runtime.
+        if output is not None:
+            self._host.emit_result(output)