harp-proxy 0.5.0b3__py3-none-any.whl

harp/__init__.py

@@ -0,0 +1,101 @@
+"""
+The Core (:mod:`harp`) package is the root namespace of the Harp framework.
+
+It mostly contains a reference to the :class:`Config` class, because it's the only object you need to start using Harp
+using the python API (you don't *need* to use this API, configuration files should be enough for most use cases, but
+if you want to, this is the starting point).
+
+For convenience, the :func:`run` function is also available, which is a simple way to start the default server
+implementation for your configuration object.
+
+Example usage:
+
+.. code-block:: python
+
+    from harp import Config, run
+
+    config = Config()
+    config.add_defaults()
+
+    if __name__ == "__main__":
+        run(config)
+
+You can find more information about how configuration works in the :mod:`harp.config` module.
+
+Contents
+--------
+
+"""
+
+import os
+from subprocess import check_output
+
+from packaging.version import InvalidVersion, Version
+
+ROOT_DIR = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+
+def _parse_version(version: str, /, *, default=None) -> Version:
+    try:
+        return Version(version)
+    except InvalidVersion:
+        if "-" in version:
+            return _parse_version(version.rsplit("-", 1)[0], default=default)
+        return default
+
+
+# last release
+__title__ = "Core"
+__version__ = "0.5.0b3"
+__revision__ = __version__  # we can't commit the not yet known revision
+
+# override with version.txt if available (after docker build for example)
+if os.path.exists(os.path.join(ROOT_DIR, "version.txt")):
+    with open(os.path.join(ROOT_DIR, "version.txt")) as f:
+        __version__ = f.read().strip()
+
+__parsed_version__ = _parse_version(__version__)
+
+# override with current development version/revision if available (disabled in CI, for docs)
+if not os.environ.get("CI", False) and os.path.exists(os.path.join(ROOT_DIR, ".git")):
+    __revision__ = check_output(["git", "rev-parse", "HEAD"], cwd=ROOT_DIR).decode("utf-8").strip()
+    try:
+        __version__ = (
+            check_output(["git", "describe", "--tags", "--always", "--dirty"], cwd=ROOT_DIR).decode("utf-8").strip()
+        )
+        __parsed_version__ = _parse_version(__version__, default=__parsed_version__)
+    except Exception:
+        __version__ = __revision__[:7]
+
+from ._logging import get_logger  # noqa: E402, isort: skip
+from harp.config import Config  # noqa: E402, isort: skip
+
+
+def run(config: Config):
+    """
+    Run the default server using provided configuration.
+
+    :param config: Config
+    :return:
+    """
+    import asyncio
+    import sys
+
+    from harp.config.adapters.hypercorn import HypercornAdapter
+    from harp.config.factories.kernel_factory import KernelFactory
+
+    config.read_env(sys.argv[1:])
+    factory = KernelFactory(config)
+    server = HypercornAdapter(factory)
+    asyncio.run(server.serve())
+
+
+__all__ = [
+    "Config",
+    "ROOT_DIR",
+    "__revision__",
+    "__version__",
+    "__parsed_version__",
+    "get_logger",
+    "run",
+]

harp/__main__.py

@@ -0,0 +1,4 @@
+if __name__ == "__main__":
+    from .commandline import entrypoint
+
+    entrypoint()

harp/_logging.py

@@ -0,0 +1,87 @@
+import logging.config
+import os
+from typing import Any
+
+import structlog
+
+processors = [
+    structlog.stdlib.filter_by_level,
+    structlog.contextvars.merge_contextvars,
+    structlog.stdlib.add_logger_name,
+    structlog.stdlib.add_log_level,
+    structlog.processors.TimeStamper(fmt="iso"),
+    structlog.dev.set_exc_info,
+    structlog.stdlib.PositionalArgumentsFormatter(),
+    structlog.processors.StackInfoRenderer(),
+    structlog.processors.UnicodeDecoder(),
+    structlog.stdlib.ProcessorFormatter.wrap_for_formatter,
+]
+
+structlog.configure(
+    logger_factory=structlog.stdlib.LoggerFactory(),
+    wrapper_class=structlog.stdlib.BoundLogger,
+    processors=processors,
+    cache_logger_on_first_use=True,
+)
+
+LOGGING_FORMATTERS = {
+    "json": {
+        "()": structlog.stdlib.ProcessorFormatter,
+        "processor": structlog.processors.JSONRenderer(),
+    },
+    "plain": {
+        "()": structlog.stdlib.ProcessorFormatter,
+        "processor": structlog.dev.ConsoleRenderer(exception_formatter=structlog.dev.plain_traceback, colors=False),
+    },
+    "pretty": {
+        "()": structlog.stdlib.ProcessorFormatter,
+        "processor": structlog.dev.ConsoleRenderer(exception_formatter=structlog.dev.plain_traceback),
+    },
+    "keyvalue": {
+        "()": structlog.stdlib.ProcessorFormatter,
+        "processor": structlog.processors.KeyValueRenderer(key_order=["timestamp", "level", "event", "logger"]),
+    },
+}
+
+LOGGING_DEFAULT_FORMATTER = "pretty"
+LOGGING_FORMATTER = os.environ.get("LOGGING_FORMATTER", LOGGING_DEFAULT_FORMATTER)
+if LOGGING_FORMATTER not in LOGGING_FORMATTERS:
+    LOGGING_FORMATTER = LOGGING_DEFAULT_FORMATTER
+
+logging_config = {
+    "version": 1,
+    "disable_existing_loggers": True,
+    "formatters": LOGGING_FORMATTERS,
+    "handlers": {
+        "console": {
+            "class": "logging.StreamHandler",
+            "formatter": LOGGING_FORMATTER,
+        },
+    },
+    "root": {
+        "handlers": ["console"],
+        "level": logging.INFO,
+    },
+    "loggers": {
+        "harp": {"level": os.environ.get("LOGGING_HARP", "INFO")},
+        "harp.event_dispatcher": {"level": os.environ.get("LOGGING_HARP_EVENTS", "WARNING")},
+        "httpcore": {"level": os.environ.get("LOGGING_HTTPCORE", "INFO")},  # todo wrap in structlog
+        "httpx": {"level": os.environ.get("LOGGING_HTTPX", "WARNING")},  # todo wrap in structlog
+        "hypercorn.access": {"level": os.environ.get("LOGGING_HYPERCORN_ACCESS", "WARNING")},
+        "hypercorn.error": {"level": os.environ.get("LOGGING_HYPERCORN_ERROR", "INFO")},
+    },
+}
+
+
+logging.config.dictConfig(logging_config)
+
+
+def get_logger(name, *args: Any, **initial_values: Any) -> Any:
+    pkg, mod = name.rsplit(".", 1)
+    if mod in ("__init__", "__main__", "__app__"):
+        name = pkg
+
+    return structlog.get_logger(name, *args, **initial_values)
+
+
+__all__ = ["get_logger"]

harp/asgi/__init__.py

@@ -0,0 +1,7 @@
+from .kernel import ASGIKernel
+
+__title__ = "ASGI"
+
+__all__ = [
+    "ASGIKernel",
+]

harp/asgi/bridge/requests.py

@@ -0,0 +1,71 @@
+from typing import AsyncIterator, Optional, cast
+from urllib.parse import parse_qsl
+
+from asgiref.typing import ASGIReceiveCallable, HTTPScope
+from multidict import CIMultiDict, MultiDict
+
+from harp.http import HttpRequestBridge
+
+_default_host = (None, None)
+
+
+class HttpRequestAsgiBridge(HttpRequestBridge):
+    """Actually implements the getters required by HttpRequest using the asgi scope and receive callable. It is still
+    an early implementation and will need to support streaming requests in the future."""
+
+    def __init__(self, scope: HTTPScope, receive: ASGIReceiveCallable):
+        """
+        :param scope: see https://asgi.readthedocs.io/en/latest/specs/www.html#http-connection-scope
+        :param receive:
+        """
+        self.asgi_scope = scope
+        self.asgi_receive = receive
+
+        self._closed = False
+
+    def get_server_ipaddr(self) -> Optional[str]:
+        """Get the server IP address from asgi scope."""
+        try:
+            return (self.asgi_scope.get("server", _default_host) or _default_host)[0]
+        except IndexError:
+            return None
+
+    def get_server_port(self) -> Optional[int]:
+        """Get the server port from asgi scope."""
+        try:
+            return (self.asgi_scope.get("server", _default_host) or _default_host)[1]
+        except IndexError:
+            return None
+
+    def get_method(self) -> str:
+        """Get the HTTP method from asgi scope."""
+        return self.asgi_scope.get("method", None)
+
+    def get_path(self) -> str:
+        """Get the HTTP path from asgi scope (/foo/bar), without the query string part."""
+        if "raw_path" in self.asgi_scope:
+            return self.asgi_scope["raw_path"].decode("utf-8")
+        return self.asgi_scope.get("path", "/")
+
+    def get_query(self) -> MultiDict:
+        """Get the query string from asgi scope, as a multidict."""
+        return MultiDict(parse_qsl(self.asgi_scope.get("query_string", b"").decode("utf-8"), keep_blank_values=True))
+
+    def get_headers(self) -> CIMultiDict:
+        """Get the headers from asgi scope, as a case-insensitive multidict."""
+        headers = CIMultiDict()
+        for name, value in self.asgi_scope.get("headers", []):
+            headers.add(name.decode("utf-8"), value.decode("utf-8"))
+        return headers
+
+    async def stream(self) -> AsyncIterator[bytes]:
+        """Returns an async iterator that reads the request body chunks. This can only be used once, as it delegates to
+        the ASGI receive callable."""
+        if self._closed:
+            raise RuntimeError("Request body has already been read.")
+
+        # TODO max iter  to avoid infinite loop on erroneous proto content?
+        while not self._closed:
+            message = await self.asgi_receive()
+            self._closed = not message.get("more_body", False)
+            yield cast(bytes, message.get("body", b""))

harp/asgi/bridge/responses.py

@@ -0,0 +1,42 @@
+from typing import TYPE_CHECKING
+
+from asgiref.typing import ASGISendCallable
+from multidict import CIMultiDictProxy
+
+from harp.utils.bytes import ensure_bytes
+
+if TYPE_CHECKING:
+    from harp.http import HttpResponse
+
+
+class HttpResponseAsgiBridge:  # todo protocol HttpResponseBridge
+    """Implements the ability of sending our HttpResponse object over the asgi protocol. This is still early impl. and
+    it will need to support streaming responses in the future."""
+
+    def __init__(self, response: "HttpResponse", send: ASGISendCallable):
+        self.response = response
+        self.asgi_send = send
+
+    async def send(self):
+        # set the headers as read only
+        self.response._headers = CIMultiDictProxy(self.response._headers)
+
+        # prepare headers for asgi
+        headers = tuple((ensure_bytes(k), ensure_bytes(v)) for k, v in self.response.headers.items())
+
+        # start the response
+        await self.asgi_send(
+            {
+                "type": "http.response.start",
+                "status": self.response.status,
+                "headers": headers,
+            }
+        )
+
+        # send the body
+        await self.asgi_send(
+            {
+                "type": "http.response.body",
+                "body": ensure_bytes(self.response.body),
+            }
+        )

harp/asgi/events.py

@@ -0,0 +1,91 @@
+from functools import cached_property
+from typing import TYPE_CHECKING, Any, Optional
+
+from whistle import Event
+
+from harp.http import BaseMessage, HttpRequest
+from harp.models.transactions import Transaction
+
+if TYPE_CHECKING:
+    from harp.http import HttpResponse
+
+EVENT_CORE_STARTED = "core.started"
+
+
+class RequestEvent(Event):
+    name = "core.request"
+
+    def __init__(self, request: HttpRequest):
+        self._request = request
+        self._controller = None
+
+    @cached_property
+    def request(self):
+        return self._request
+
+    @property
+    def controller(self):
+        return self._controller
+
+    def set_controller(self, controller):
+        self._controller = controller
+
+
+EVENT_CORE_REQUEST = RequestEvent.name
+
+
+class ControllerEvent(RequestEvent):
+    name = "core.controller"
+
+    def __init__(self, request: HttpRequest, controller):
+        super().__init__(request)
+        self._controller = controller
+
+
+EVENT_CORE_CONTROLLER = ControllerEvent.name
+
+
+class ResponseEvent(RequestEvent):
+    name = "core.response"
+
+    def __init__(self, request: HttpRequest, response):
+        super().__init__(request)
+        self.response = response
+
+
+EVENT_CORE_RESPONSE = ResponseEvent.name
+
+
+class ControllerViewEvent(RequestEvent):
+    """
+    The view event allows to transform controller return values into response objects.
+    """
+
+    name = "controller.view"
+
+    value: Any
+    response: Optional["HttpResponse"]
+
+    def __init__(self, request: HttpRequest, value: Any):
+        super().__init__(request)
+
+        self.value = value
+        self.response = None
+
+    def set_response(self, response: "HttpResponse"):
+        self.response = response
+        self.stop_propagation()
+
+
+EVENT_CONTROLLER_VIEW = ControllerViewEvent.name
+
+
+class TransactionEvent(Event):
+    def __init__(self, transaction: Transaction):
+        self.transaction = transaction
+
+
+class MessageEvent(TransactionEvent):
+    def __init__(self, transaction: Transaction, message: BaseMessage):
+        super().__init__(transaction)
+        self.message = message

harp/asgi/kernel.py

@@ -0,0 +1,164 @@
+import traceback
+from inspect import signature
+
+from asgiref.typing import ASGIReceiveCallable, ASGISendCallable, Scope
+from whistle import AsyncEventDispatcher, Event, IAsyncEventDispatcher
+
+from harp import get_logger
+from harp.controllers import DefaultControllerResolver
+from harp.http import AlreadyHandledHttpResponse, HttpRequest, HttpResponse
+
+from .bridge.requests import HttpRequestAsgiBridge
+from .bridge.responses import HttpResponseAsgiBridge
+from .events import (
+    EVENT_CONTROLLER_VIEW,
+    EVENT_CORE_CONTROLLER,
+    EVENT_CORE_REQUEST,
+    EVENT_CORE_RESPONSE,
+    EVENT_CORE_STARTED,
+    ControllerEvent,
+    ControllerViewEvent,
+    RequestEvent,
+    ResponseEvent,
+)
+
+logger = get_logger(__name__)
+
+
+class ASGIKernel:
+    dispatcher: IAsyncEventDispatcher
+
+    def __init__(self, *, dispatcher=None, resolver=None, debug=False, handle_errors=True):
+        self.dispatcher = dispatcher or AsyncEventDispatcher()
+        # TODO IControllerResolver ? What contract do we expect ?
+        self.resolver = resolver or DefaultControllerResolver()
+        self.started = False
+        self.debug = debug
+        self.handle_errors = handle_errors
+
+    async def __call__(self, scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable):
+        asgi_type = scope.get("type", None)
+
+        if asgi_type == "http":
+            response = await self.handle_http(scope, receive, send)
+            if isinstance(response, AlreadyHandledHttpResponse):
+                return
+            return await HttpResponseAsgiBridge(response, send).send()
+
+        if asgi_type == "lifespan":
+            await receive()
+            await self.dispatcher.adispatch(EVENT_CORE_STARTED, Event())
+            self.started = True
+            return
+
+        if asgi_type == "websocket":
+            # NOT IMPLEMENTED YET!
+            # This is ignored here to avoid huge errors in the console.
+            return
+
+        raise RuntimeError(f'Unable to handle request, invalid type "{asgi_type}".')
+
+    def _resolve_arguments(self, subject, **candidates):
+        """
+        Dynamicaly resolve arguments by names in prototype, looking at a "candidates" dictionary that
+        contains the possible arguments used.
+        """
+
+        while hasattr(subject, "_mock_wraps"):
+            subject = subject._mock_wraps
+
+        try:
+            return [
+                candidates[name] if name in candidates or param.default is param.empty else param.default
+                for name, param in signature(subject).parameters.items()
+                if param.kind is not param.KEYWORD_ONLY
+            ], {}
+        except KeyError as exc:
+            raise TypeError(f"Unable to resolve arguments: {exc}")
+
+    async def _resolve_http_controller(self, request: HttpRequest):
+        """
+        Resolves the controller for the given request, aka the callable that will handle the request. If we fail to do
+        so, we will have hard time building a response for the user, and thus we raise an error.
+
+        Resolving the controller involves two steps:
+        - first, we use `self.resolver` to find a controller for the request.
+          See `harp.controllers.ControllerResolver`
+
+        :param request:
+        :return:
+        """
+        controller = await self.resolver.resolve(request)
+        if not controller:
+            raise RuntimeError("Unable to find request controller using resolver.")
+
+        event = ControllerEvent(request, controller)
+        await self.dispatcher.adispatch(EVENT_CORE_CONTROLLER, event)
+
+        if not event.controller:
+            raise RuntimeError("Unable to find request controller after controller event dispatch.")
+
+        return event.controller
+
+    async def _execute_http_controller(self, controller, request: HttpRequest, send: ASGISendCallable):
+        """Executes the given controller and make all efforts to build a http response."""
+        args, kwargs = self._resolve_arguments(controller, request=request, asgi_send=send)
+        response = await controller(*args, **kwargs)
+
+        # if the controller returned anything that is not a response, maybe some view listener can create one from this
+        # value (for example for json data, etc.).
+        if not isinstance(response, HttpResponse):
+            event = ControllerViewEvent(request, response)
+            await self.dispatcher.adispatch(EVENT_CONTROLLER_VIEW, event)
+            response = event.response
+
+        # if after the view event has been dispatched we still don't have a response, we have to raise an error.
+        if not isinstance(response, HttpResponse):
+            raise RuntimeError(
+                f"Response did not start despite the efforts made (controller return value is "
+                f"{type(response).__name__} after controller view event was dispatched)."
+            )
+
+        # the core response event may want to filter the response, for example to add some headers, etc.
+        await self.dispatcher.adispatch(EVENT_CORE_RESPONSE, ResponseEvent(request, response))
+
+        return response
+
+    async def handle_http(self, scope: Scope, receive: ASGIReceiveCallable, send: ASGISendCallable):
+        request = HttpRequest(HttpRequestAsgiBridge(scope, receive))
+
+        if not self.started:
+            return HttpResponse(
+                "Unhandled server error: Cannot access service provider, the lifespan.startup asgi event "
+                "probably never went through.",
+                status=500,
+                content_type="text/plain",
+            )
+
+        try:
+            return await self.do_handle_http(request, send)
+
+        except Exception as exc:
+            if not self.handle_errors:
+                raise
+
+            # todo refactor this
+            logger.exception()
+            if self.debug:
+                return HttpResponse(
+                    f"<h1>Internal Server Error</h1><h2>{type(exc).__name__}: {exc}</h2> "
+                    f"<pre>{traceback.format_exc()}</pre>",
+                    status=500,
+                    content_type="text/html",
+                )
+            return HttpResponse("Internal Server Error", status=500, content_type="text/plain")
+
+    async def do_handle_http(self, request: HttpRequest, send: ASGISendCallable):
+        event = RequestEvent(request)
+        await self.dispatcher.adispatch(EVENT_CORE_REQUEST, event)
+
+        if event.controller:
+            return await self._execute_http_controller(event.controller, request, send)
+
+        controller = await self._resolve_http_controller(request)
+        return await self._execute_http_controller(controller, request, send)