forgeintel-sdk 0.1.0b1__py3-none-any.whl

forgeintel/__init__.py

@@ -0,0 +1,7 @@
+"""Forge SDK for Python x402 merchants."""
+
+from .asgi import ForgeMiddleware
+from .core import AgentContextOptions, Forge, ForgeOptions, OpenAPIOptions
+
+__version__ = "0.1.0b1"
+__all__ = ["AgentContextOptions", "Forge", "ForgeMiddleware", "ForgeOptions", "OpenAPIOptions"]

forgeintel/asgi.py

@@ -0,0 +1,303 @@
+"""Pure ASGI adapter; no FastAPI/Starlette dependency and no BaseHTTPMiddleware.
+
+Install outside payment middleware. Streamed, compressed and binary responses are
+passed through; bounded JSON bodies can carry feedback alongside the merchant's data.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections import deque
+from urllib.parse import parse_qs
+
+from .core import Forge, Reply
+from .signals import take_query
+from .wire import json_bytes
+
+BODY_LIMIT = 1024 * 1024
+SPEC_LIMIT = 5 * BODY_LIMIT
+RATING_LIMIT = 16 * 1024
+JSON_MEDIA = re.compile(r"^application/(?:[\w.+-]+\+)?json(?:\s*;|$)", re.I)
+INVALIDATED = {
+    b"content-length",
+    b"etag",
+    b"content-md5",
+    b"digest",
+    b"content-digest",
+    b"repr-digest",
+}
+
+
+def header_map(headers: list) -> dict[str, str]:
+    # Preserve the first field, like Starlette Headers.get(). Raw lists are kept when forwarding.
+    result = {}
+    for key, value in headers:
+        result.setdefault(key.decode("latin-1").lower(), value.decode("latin-1"))
+    return result
+
+
+def update_headers(headers: list, changes: dict[str, str], *, body: bytes | None = None) -> list:
+    remove = {key.encode("ascii") for key in changes}
+    if body is not None:
+        remove |= INVALIDATED
+    result = [(key, value) for key, value in headers if key.lower() not in remove]
+    result.extend((key.encode("ascii"), value.encode("latin-1")) for key, value in changes.items())
+    if body is not None:
+        result.append((b"content-length", str(len(body)).encode()))
+    return result
+
+
+async def send_reply(reply: Reply, method: str, send) -> None:
+    body = b"" if reply.body is None else json_bytes(reply.body)
+    headers = {
+        "content-type": "application/json; charset=utf-8",
+        **reply.headers,
+        "content-length": str(len(body)),
+    }
+    await send(
+        {
+            "type": "http.response.start",
+            "status": reply.status,
+            "headers": [(k.encode(), v.encode("latin-1")) for k, v in headers.items()],
+        }
+    )
+    await send({"type": "http.response.body", "body": b"" if method == "HEAD" else body})
+
+
+class ForgeMiddleware:
+    def __init__(self, app, *, forge: Forge):
+        self.app, self.forge = app, forge
+
+    async def __call__(self, scope, receive, send):
+        forge = self.forge
+        if not forge.enabled:
+            return await self.app(scope, receive, send)
+        if scope["type"] == "lifespan":
+
+            async def lifespan_send(message):
+                if message["type"] == "lifespan.shutdown.complete":
+                    await forge.shutdown()
+                await send(message)
+
+            try:
+                await self.app(scope, receive, lifespan_send)
+            finally:
+                await forge.shutdown()
+            return
+        if scope["type"] != "http":
+            return await self.app(scope, receive, send)
+        method, path = scope["method"], scope["path"]
+        # ASGI servers differ on whether path retains root_path. Use the public path
+        # for telemetry, configured Forge routes and OpenAPI response-schema matching.
+        root = scope.get("root_path", "").rstrip("/")
+        local_path = (
+            path[len(root) :] if root and (path == root or path.startswith(root + "/")) else path
+        )
+        public_path = root + local_path
+        request_headers = header_map(scope.get("headers", []))
+        pending = deque()
+
+        async def replay():
+            return pending.popleft() if pending else await receive()
+
+        async def bounded_body(limit: int):
+            parts, total = [], 0
+            while True:
+                message = await receive()
+                pending.append(message)
+                if message["type"] != "http.request":
+                    raise ValueError("request disconnected")
+                part = message.get("body", b"")
+                total += len(part)
+                if total > limit:
+                    raise ValueError("body_too_large")
+                parts.append(part)
+                if not message.get("more_body", False):
+                    return b"".join(parts)
+
+        async def read_rating():
+            return json.loads(await bounded_body(RATING_LIMIT))
+
+        try:
+            query = {
+                key: values[0]
+                for key, values in parse_qs(
+                    scope.get("query_string", b"").decode("latin-1"), keep_blank_values=True
+                ).items()
+            }
+            own = await forge.route(method, public_path, request_headers, query, read_rating)
+        except Exception as error:
+            forge.on_error(error)
+            own = (
+                Reply(503, {"error": "feedback_unavailable"})
+                if forge.options.feedback
+                and public_path in (forge.base_path, forge.rate_path, forge.summary_path)
+                else None
+            )
+        if own is not None:
+            return await send_reply(own, method, send)
+
+        # Keep the original request replayable. Never catch exceptions from or retry the merchant app.
+        try:
+            call = forge.call(method, public_path, request_headers)
+            query_string, raw = take_query(scope.get("query_string", b""))
+            call.remember(raw)
+            forwarded = {**scope, "query_string": query_string}
+        except Exception as error:
+            forge.on_error(error)
+            return await self.app(scope, replay, send)
+        if JSON_MEDIA.match(request_headers.get("content-type", "")):
+            try:
+                if request_headers.get("content-encoding", "identity").lower() != "identity":
+                    raise ValueError("encoded JSON is not inspected")
+                length = int(request_headers.get("content-length", "0"))
+                if length > BODY_LIMIT:
+                    raise ValueError("body_too_large")
+                original = await bounded_body(BODY_LIMIT)
+                if original:
+                    parsed = json.loads(original)
+                    stripped = call.request_body(parsed)
+                    if stripped is not parsed:
+                        body = json_bytes(stripped)
+                        forwarded["headers"] = update_headers(
+                            scope.get("headers", []), {}, body=body
+                        )
+                        pending.clear()
+                        pending.append({"type": "http.request", "body": body, "more_body": False})
+            except (ValueError, UnicodeError):
+                if call.context_required:
+                    return await send_reply(
+                        Reply(
+                            400,
+                            {
+                                "error": "agent_context_invalid",
+                                "message": "Required agent context could not be read. Send valid JSON up to 1 MiB, or use agent_type and agent_search_query query parameters with a non-JSON body.",
+                            },
+                        ),
+                        method,
+                        send,
+                    )
+                # Optional context on unreadable/large bodies is skipped. Every consumed byte is replayed.
+            except Exception as error:
+                forge.on_error(error)
+                if call.context_required:
+                    return await send_reply(
+                        Reply(400, {"error": "agent_context_invalid"}), method, send
+                    )
+        error = call.context_error()
+        if error:
+            return await send_reply(error, method, send)
+
+        start = None
+        buffered = []
+        size = 0
+        should_buffer = False
+        sent_start = False
+        status = 0
+        response_headers = {}
+        spec = forge.is_spec(method, public_path)
+
+        async def response_send(message):
+            nonlocal start, size, should_buffer, sent_start, status, response_headers
+            kind = message["type"]
+            if kind == "http.response.start":
+                status = message["status"]
+                response_headers = header_map(message.get("headers", []))
+                start = {**message}
+                try:
+                    changes = call.response_headers(status, response_headers)
+                    start["headers"] = update_headers(message.get("headers", []), changes)
+                    media = response_headers.get("content-type", "")
+                    can_edit = bool(JSON_MEDIA.match(media)) or (
+                        forge.options.inject_text and media.split(";", 1)[0].lower() == "text/plain"
+                    )
+                    limit = SPEC_LIMIT if spec else BODY_LIMIT
+                    length = int(response_headers.get("content-length", "0"))
+                    should_buffer = (
+                        method != "HEAD"
+                        and status not in (204, 205, 206, 304)
+                        and response_headers.get("content-encoding", "identity").lower()
+                        == "identity"
+                        and "content-range" not in response_headers
+                        and can_edit
+                        and 0 <= length <= limit
+                        and (
+                            spec
+                            and status == 200
+                            or status == 402
+                            or bool(call.feedback_id)
+                            and 200 <= status < 300
+                        )
+                    )
+                except Exception as error:
+                    forge.on_error(error)
+                    should_buffer = False
+                if not should_buffer:
+                    await send(start)
+                    sent_start = True
+                return
+            if kind != "http.response.body":
+                if start and not sent_start:
+                    await send(start)
+                    sent_start = True
+                    for chunk in buffered:
+                        await send(chunk)
+                    buffered.clear()
+                    should_buffer = False
+                return await send(message)
+            if should_buffer:
+                buffered.append(message)
+                size += len(message.get("body", b""))
+                limit = SPEC_LIMIT if spec else BODY_LIMIT
+                # Unknown-length streams must keep their streaming behavior.
+                if size > limit or (
+                    message.get("more_body", False) and "content-length" not in response_headers
+                ):
+                    should_buffer = False
+                    await send(start)
+                    sent_start = True
+                    for chunk in buffered:
+                        await send(chunk)
+                    buffered.clear()
+                elif not message.get("more_body", False):
+                    original = b"".join(chunk.get("body", b"") for chunk in buffered)
+                    body = original
+                    try:
+                        media = response_headers.get("content-type", "")
+                        if JSON_MEDIA.match(media):
+                            parsed = json.loads(original)
+                            decorated = (
+                                forge.enrich_openapi(parsed)
+                                if spec and status == 200
+                                else call.response_json(status, parsed)
+                            )
+                            if decorated != parsed:
+                                body = json_bytes(decorated)
+                        elif call.feedback_id and forge.options.inject_text and 200 <= status < 300:
+                            text = original.decode("utf-8")
+                            body = (
+                                text
+                                + ("" if text.endswith("\n") else "\n")
+                                + f"\nfeedback_id: {call.feedback_id}\nfeedback_url: {call.feedback_url}\n"
+                            ).encode()
+                        if body != original:
+                            start["headers"] = update_headers(
+                                start.get("headers", []), {}, body=body
+                            )
+                    except Exception as error:
+                        forge.on_error(error)
+                        body = original
+                    await send(start)
+                    sent_start = True
+                    await send({**message, "body": body})
+                    buffered.clear()
+            else:
+                await send(message)
+            if not message.get("more_body", False):
+                try:
+                    call.finish(status)
+                except Exception as error:
+                    forge.on_error(error)
+
+        await self.app(forwarded, replay, response_send)