muad-skill-http 0.1.0__tar.gz

muad_skill_http-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: muad-skill-http
+Version: 0.1.0
+Summary: Trace-aware HTTP helpers and platform request client for muad skills
+Author: muad-openclaw maintainers
+Project-URL: Homepage, https://github.com/Michaelxwb/muad-openclaw
+Project-URL: Source, https://github.com/Michaelxwb/muad-openclaw/tree/main/tools/muad-skill-sdk
+Keywords: http,requests,tracing,skills
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests<3,>=2.31
+
+# muad-skill-http
+
+Trace-aware HTTP helpers and a platform request client for muad skills.
+
+`platform_request()` sends business-platform requests through a platform session
+managed by `session-manager`. It assembles the browser defaults, platform host
+header, platform static headers, cookies, CSRF header and a fresh `Traceid`
+UUID v4 for every request, and re-asserts the mandatory headers last so caller
+headers cannot override them. Cookie and CSRF values never reach the trace
+spool.
+
+## Install
+
+```bash
+pip install muad-skill-http
+```
+
+## Usage
+
+```python
+from muad_skill_http import get, platform_request
+
+# Plain HTTP with trace accounting.
+response = get("https://example.com/api/v1/items")
+
+# Business-platform request: headers and Traceid are built by the SDK.
+response = platform_request("demo", "GET", "/api/v1/targets")
+```
+
+`get` / `post` / `put` / `patch` / `delete` / `head` / `options` / `request`
+wrap `requests` and record request counts for the current skill execution.
+
+### Runtime requirements for `platform_request`
+
+`platform_request` resolves the platform session from the skill runtime, not
+from the local machine. It needs:
+
+- `MUAD_SKILL_NAME` set to the running skill name;
+- a `session-manager` executable on `PATH` that answers
+  `session-manager get-state --skill-name <name>` with
+  `{"sessionStateFile": "..."}`;
+- a session state file containing the requested platform's credentials.
+
+Outside that environment it raises `muad_skill_http.PlatformSessionError`.
+Plain `get` / `post` calls work anywhere.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `MUAD_SKILL_NAME` | Skill name used to resolve the platform session. |
+| `MUAD_TRACE_SPOOL` | Optional JSONL trace spool path; paired with `MUAD_EXECUTION_ID`. |
+| `MUAD_EXECUTION_ID` | Execution id written to the trace spool. |
+| `MUAD_SKILL_REQUEST_LIMIT` | Per-execution interface request limit; unset or `0` means unlimited. Exceeding the limit exits with code `86`. |
+
+I/O failures while writing the trace spool are swallowed: auditing never breaks
+a skill request.
+
+## Development
+
+```bash
+python -m pytest test
+```
+
+Releases are published by pushing an `sdk-v*` tag; the tag must match
+`project.version` in `pyproject.toml`.

muad_skill_http-0.1.0/README.md

@@ -0,0 +1,66 @@
+# muad-skill-http
+
+Trace-aware HTTP helpers and a platform request client for muad skills.
+
+`platform_request()` sends business-platform requests through a platform session
+managed by `session-manager`. It assembles the browser defaults, platform host
+header, platform static headers, cookies, CSRF header and a fresh `Traceid`
+UUID v4 for every request, and re-asserts the mandatory headers last so caller
+headers cannot override them. Cookie and CSRF values never reach the trace
+spool.
+
+## Install
+
+```bash
+pip install muad-skill-http
+```
+
+## Usage
+
+```python
+from muad_skill_http import get, platform_request
+
+# Plain HTTP with trace accounting.
+response = get("https://example.com/api/v1/items")
+
+# Business-platform request: headers and Traceid are built by the SDK.
+response = platform_request("demo", "GET", "/api/v1/targets")
+```
+
+`get` / `post` / `put` / `patch` / `delete` / `head` / `options` / `request`
+wrap `requests` and record request counts for the current skill execution.
+
+### Runtime requirements for `platform_request`
+
+`platform_request` resolves the platform session from the skill runtime, not
+from the local machine. It needs:
+
+- `MUAD_SKILL_NAME` set to the running skill name;
+- a `session-manager` executable on `PATH` that answers
+  `session-manager get-state --skill-name <name>` with
+  `{"sessionStateFile": "..."}`;
+- a session state file containing the requested platform's credentials.
+
+Outside that environment it raises `muad_skill_http.PlatformSessionError`.
+Plain `get` / `post` calls work anywhere.
+
+## Environment variables
+
+| Variable | Purpose |
+| --- | --- |
+| `MUAD_SKILL_NAME` | Skill name used to resolve the platform session. |
+| `MUAD_TRACE_SPOOL` | Optional JSONL trace spool path; paired with `MUAD_EXECUTION_ID`. |
+| `MUAD_EXECUTION_ID` | Execution id written to the trace spool. |
+| `MUAD_SKILL_REQUEST_LIMIT` | Per-execution interface request limit; unset or `0` means unlimited. Exceeding the limit exits with code `86`. |
+
+I/O failures while writing the trace spool are swallowed: auditing never breaks
+a skill request.
+
+## Development
+
+```bash
+python -m pytest test
+```
+
+Releases are published by pushing an `sdk-v*` tag; the tag must match
+`project.version` in `pyproject.toml`.

muad_skill_http-0.1.0/muad_skill_http/__init__.py

@@ -0,0 +1,47 @@
+"""muad_skill_http: trace-aware requests helper and platform request client.
+
+Usage in skills::
+
+    import muad_skill_http
+
+    response = muad_skill_http.get("http://service/api")
+    response = muad_skill_http.platform_request("mssw", "GET", "/api/v1/targets")
+
+Without importing this module, existing skills keep their original behavior:
+``requests`` is never patched and no trace spool is written.
+"""
+
+from __future__ import annotations
+
+from . import _platform, _trace
+from ._http import delete, get, head, options, patch, post, put, request, session
+from ._platform import PlatformClient, PlatformSessionError, platform, platform_request
+from ._trace import EXIT_REQUEST_LIMIT
+
+__all__ = [
+    "EXIT_REQUEST_LIMIT",
+    "PlatformClient",
+    "PlatformSessionError",
+    "delete",
+    "get",
+    "head",
+    "options",
+    "patch",
+    "platform",
+    "platform_request",
+    "post",
+    "put",
+    "request",
+    "session",
+]
+
+
+def _reset_for_tests():
+    """Drop the process-wide recorder and session cache (tests only)."""
+    _trace.reset()
+    _platform.reset_cache()
+
+
+def _flush_summary():
+    """Write the trace summary early (tests and one-shot scripts)."""
+    _trace.flush_summary()

muad_skill_http-0.1.0/muad_skill_http/_http.py

@@ -0,0 +1,109 @@
+"""Thin requests pass-through that records every helper request."""
+
+from __future__ import annotations
+
+import time
+
+import requests
+
+from . import _trace
+from ._normalize import split_target
+
+
+def _duration_ms(started):
+    return int((time.monotonic() - started) * 1000)
+
+
+def _send(call, method, url, **kwargs):
+    method = str(method).upper()
+    extra = kwargs.pop("_trace_extra", None)
+    recorder = _trace.get_recorder()
+    host, path = split_target(url)
+    recorder.admit(host, method, path)
+    started = time.monotonic()
+    try:
+        response = call(method, url, **kwargs)
+    except requests.RequestException as exc:
+        recorder.complete(host, method, path, None, _duration_ms(started), type(exc).__name__, extra)
+        raise
+    status = response.status_code
+    error_class = "http_%d" % status if status >= 400 else ""
+    recorder.complete(host, method, path, status, _duration_ms(started), error_class, extra)
+    return response
+
+
+def request(method, url, **kwargs):
+    """requests.request with trace + per-interface limit accounting."""
+    return _send(requests.request, method, url, **kwargs)
+
+
+def get(url, **kwargs):
+    return request("GET", url, **kwargs)
+
+
+def head(url, **kwargs):
+    return request("HEAD", url, **kwargs)
+
+
+def options(url, **kwargs):
+    return request("OPTIONS", url, **kwargs)
+
+
+def post(url, **kwargs):
+    return request("POST", url, **kwargs)
+
+
+def put(url, **kwargs):
+    return request("PUT", url, **kwargs)
+
+
+def patch(url, **kwargs):
+    return request("PATCH", url, **kwargs)
+
+
+def delete(url, **kwargs):
+    return request("DELETE", url, **kwargs)
+
+
+class _TrackedSession:
+    def __init__(self):
+        self._session = requests.Session()
+
+    def request(self, method, url, **kwargs):
+        return _send(self._session.request, method, url, **kwargs)
+
+    def get(self, url, **kwargs):
+        return self.request("GET", url, **kwargs)
+
+    def head(self, url, **kwargs):
+        return self.request("HEAD", url, **kwargs)
+
+    def options(self, url, **kwargs):
+        return self.request("OPTIONS", url, **kwargs)
+
+    def post(self, url, **kwargs):
+        return self.request("POST", url, **kwargs)
+
+    def put(self, url, **kwargs):
+        return self.request("PUT", url, **kwargs)
+
+    def patch(self, url, **kwargs):
+        return self.request("PATCH", url, **kwargs)
+
+    def delete(self, url, **kwargs):
+        return self.request("DELETE", url, **kwargs)
+
+    def close(self):
+        self._session.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, tb):
+        self.close()
+        return False
+
+
+def session():
+    """A requests.Session wrapper (supports ``with``) that traces each call."""
+    return _TrackedSession()

muad_skill_http-0.1.0/muad_skill_http/_normalize.py

@@ -0,0 +1,49 @@
+"""Path and target normalization for interface counting."""
+
+from __future__ import annotations
+
+import re
+from urllib.parse import urlsplit
+
+_UUID_RE = re.compile(
+    r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
+)
+_HEX_RE = re.compile(r"^[0-9a-fA-F]{8,}$")
+_DIGITS_RE = re.compile(r"^\d+$")
+
+
+def normalize_path(path):
+    """Collapse volatile path segments and drop query/fragment.
+
+    Numeric, UUID and long hex segments become ``{id}`` so one business
+    interface is counted once regardless of object ids.
+    """
+    if not isinstance(path, str):
+        path = str(path or "")
+    if path.startswith(("http://", "https://")):
+        raw = urlsplit(path).path or "/"
+    else:
+        raw = path.split("?", 1)[0].split("#", 1)[0]
+    if not raw:
+        return "/"
+    segments = ["{id}" if _is_volatile(segment) else segment for segment in raw.split("/")]
+    return "/".join(segments) or "/"
+
+
+def split_target(url):
+    """Return (host:port, normalized path) for a request URL."""
+    parts = urlsplit(str(url))
+    host = (parts.hostname or "").lower()
+    try:
+        port = parts.port
+    except ValueError:
+        port = None
+    if port:
+        host = "%s:%d" % (host, port)
+    return host, normalize_path(parts.path or "/")
+
+
+def _is_volatile(segment):
+    if not segment:
+        return False
+    return bool(_DIGITS_RE.match(segment) or _UUID_RE.match(segment) or _HEX_RE.match(segment))