twirpy 0.1.0.dev3__tar.gz

twirpy-0.1.0.dev3/.gitignore

@@ -0,0 +1,2 @@
+__pycache__/
+dist/

twirpy-0.1.0.dev3/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright 2024, [pafin Inc.](https://www.pafin.com)
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

twirpy-0.1.0.dev3/PKG-INFO

@@ -0,0 +1,81 @@
+Metadata-Version: 2.3
+Name: twirpy
+Version: 0.1.0.dev3
+Summary: Twirp runtime library for Python
+Project-URL: repository, https://github.com/cryptact/twirpy
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: protobuf,rpc,twirp
+Requires-Python: >=3.10
+Requires-Dist: protobuf
+Requires-Dist: requests
+Requires-Dist: structlog
+Provides-Extra: async
+Requires-Dist: aiohttp; extra == 'async'
+Description-Content-Type: text/markdown
+
+# Twirpy
+
+> Twirp is a framework for service-to-service communication emphasizing simplicity and minimalism.
+> It generates routing and serialization from API definition files and lets you focus on your application's logic
+> instead of thinking about folderol like HTTP methods and paths and JSON.
+>
+> -- <cite>[Twirp's README](https://github.com/twitchtv/twirp/blob/main/README.md)</cite>
+
+Twirpy is a Python implementation of the Twirp framework.
+It currently supports [Twirp Wire Protocol v7](https://twitchtv.github.io/twirp/docs/spec_v7.html).
+
+This repository contains:
+* a protoc (aka the Protocol Compiler) plugin that generates sever and client code;
+* a Python package with common implementation details.
+
+## Installation
+
+### Runtime Library
+
+The runtime library package contains common types like `TwirpServer` and `TwirpClient` that are used by the generated code.
+
+Add the Twirp package to your Python project with:
+```
+pip install twirpy
+```
+
+### Code Generator
+
+You need to install `protoc`, the Protocol Buffers compiler, and the `protoc-gen-twirpy` protoc plugin to generate code.
+
+First, install the [Protocol Buffers](https://developers.google.com/protocol-buffers) compiler.
+For installation instructions, see [Protocol Buffer Compiler Installation documentation](https://github.com/protocolbuffers/protobuf#protobuf-compiler-installation).
+You can also use your package manager (e.g. `brew install protobuf` on macOS).
+
+Go the [releases page](https://github.com/Cryptact/twirpy/releases/latest), and download the `protoc-gen-twirpy` binary for your platform.
+Unzip the archive and move the binary to a directory in your PATH.
+
+On macOS, you can use the following commands:
+```sh
+curl -L -o- \
+  https://github.com/Cryptact/twirpy/releases/latest/download/protoc-gen-twirpy_Darwin_arm64.tar.gz \
+  | tar xz -C ~/.local/bin protoc-gen-twirpy
+````
+
+## Generate and run
+
+Use the protoc plugin to generate twirp server and client code.
+```sh
+protoc --python_out=. --pyi_out=. --twirpy_out=. example/rpc/haberdasher/service.proto
+```
+
+For more information on how to generate code, see the [example](example/README.md).
+
+## Development
+
+We use [`hatch`](https://hatch.pypa.io/latest/) to manage the development process.
+
+To open a shell with the development environment, run: `hatch shell`.
+To run the linter, run: `hatch fmt --check` or `hatch fmt` to fix the issues.
+
+## Standing on the shoulders of giants
+
+- The initial version of twirpy was made from an internal copy of https://github.com/daroot/protoc-gen-twirp_python_srv
+- The work done by [Verloop](https://verloop.io/) on [the initial versions of Twirpy](https://github.com/verloop/twirpy).
+- The `run_in_threadpool` method comes from https://github.com/encode/starlette

twirpy-0.1.0.dev3/README.md

@@ -0,0 +1,65 @@
+# Twirpy
+
+> Twirp is a framework for service-to-service communication emphasizing simplicity and minimalism.
+> It generates routing and serialization from API definition files and lets you focus on your application's logic
+> instead of thinking about folderol like HTTP methods and paths and JSON.
+>
+> -- <cite>[Twirp's README](https://github.com/twitchtv/twirp/blob/main/README.md)</cite>
+
+Twirpy is a Python implementation of the Twirp framework.
+It currently supports [Twirp Wire Protocol v7](https://twitchtv.github.io/twirp/docs/spec_v7.html).
+
+This repository contains:
+* a protoc (aka the Protocol Compiler) plugin that generates sever and client code;
+* a Python package with common implementation details.
+
+## Installation
+
+### Runtime Library
+
+The runtime library package contains common types like `TwirpServer` and `TwirpClient` that are used by the generated code.
+
+Add the Twirp package to your Python project with:
+```
+pip install twirpy
+```
+
+### Code Generator
+
+You need to install `protoc`, the Protocol Buffers compiler, and the `protoc-gen-twirpy` protoc plugin to generate code.
+
+First, install the [Protocol Buffers](https://developers.google.com/protocol-buffers) compiler.
+For installation instructions, see [Protocol Buffer Compiler Installation documentation](https://github.com/protocolbuffers/protobuf#protobuf-compiler-installation).
+You can also use your package manager (e.g. `brew install protobuf` on macOS).
+
+Go the [releases page](https://github.com/Cryptact/twirpy/releases/latest), and download the `protoc-gen-twirpy` binary for your platform.
+Unzip the archive and move the binary to a directory in your PATH.
+
+On macOS, you can use the following commands:
+```sh
+curl -L -o- \
+  https://github.com/Cryptact/twirpy/releases/latest/download/protoc-gen-twirpy_Darwin_arm64.tar.gz \
+  | tar xz -C ~/.local/bin protoc-gen-twirpy
+````
+
+## Generate and run
+
+Use the protoc plugin to generate twirp server and client code.
+```sh
+protoc --python_out=. --pyi_out=. --twirpy_out=. example/rpc/haberdasher/service.proto
+```
+
+For more information on how to generate code, see the [example](example/README.md).
+
+## Development
+
+We use [`hatch`](https://hatch.pypa.io/latest/) to manage the development process.
+
+To open a shell with the development environment, run: `hatch shell`.
+To run the linter, run: `hatch fmt --check` or `hatch fmt` to fix the issues.
+
+## Standing on the shoulders of giants
+
+- The initial version of twirpy was made from an internal copy of https://github.com/daroot/protoc-gen-twirp_python_srv
+- The work done by [Verloop](https://verloop.io/) on [the initial versions of Twirpy](https://github.com/verloop/twirpy).
+- The `run_in_threadpool` method comes from https://github.com/encode/starlette

twirpy-0.1.0.dev3/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = [
+    "hatchling",
+    "hatch-semver"
+]
+build-backend = "hatchling.build"
+
+[project]
+name = "twirpy"
+dynamic = ["version"]
+description = "Twirp runtime library for Python"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "BSD-3-Clause"
+keywords = [
+  "protobuf",
+  "rpc",
+  "twirp",
+]
+dependencies = [
+    "protobuf",
+    "requests",
+    "structlog",
+]
+
+[project.urls]
+repository = "https://github.com/cryptact/twirpy"
+
+[project.optional-dependencies]
+async = [
+    "aiohttp",
+]
+
+[tool.hatch.version]
+path = "twirp/__init__.py"
+validate-bump = true
+scheme = "semver"
+
+[tool.hatch.build.targets.sdist]
+include = ["/twirp"]
+[tool.hatch.build.targets.wheel]
+packages = ["twirp"]
+
+[tool.hatch.envs.default]
+python = "3.12"
+dependencies = [
+    "aiohttp",
+]
+
+[tool.ruff]
+line-length = 120
+lint.select = [
+  "F",   # pyflakes
+  "PLE", # pylint errors
+  "UP",  # pyupgrade
+]
+lint.fixable = [
+  "F",   # pyflakes
+  "PLE", # pylint errors
+  "UP",  # pyupgrade
+]
+exclude = ["example/rpc"]

twirpy-0.1.0.dev3/twirp/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0-dev.3"

twirpy-0.1.0.dev3/twirp/asgi.py

@@ -0,0 +1,178 @@
+import asyncio
+import functools
+import typing
+import traceback
+
+from . import base
+from . import exceptions
+from . import errors
+from . import ctxkeys
+
+try:
+    import contextvars  # Python 3.7+ only.
+except ImportError:  # pragma: no cover
+    contextvars = None  # type: ignore
+
+
+# Lifted from starlette.concurrency
+async def run_in_threadpool(func: typing.Callable, *args: typing.Any, **kwargs: typing.Any) -> typing.Any:
+    loop = asyncio.get_event_loop()
+    if contextvars is not None:  # pragma: no cover
+        # Ensure we run in the same context
+        child = functools.partial(func, *args, **kwargs)
+        context = contextvars.copy_context()
+        func = context.run
+        args = (child,)
+    elif kwargs:  # pragma: no cover
+        # loop.run_in_executor doesn't accept 'kwargs', so bind them in here
+        func = functools.partial(func, **kwargs)
+    return await loop.run_in_executor(None, func, *args)
+
+
+def thread_pool_runner(func):
+    async def run(ctx, request):
+        return await run_in_threadpool(func, ctx, request)
+
+    return run
+
+
+class TwirpASGIApp(base.TwirpBaseApp):
+    async def __call__(self, scope, receive, send):
+        assert scope["type"] == "http"
+        ctx = self._ctx_class()
+        try:
+            http_method = scope["method"]
+            if http_method != "POST":
+                raise exceptions.TwirpServerException(
+                    code=errors.Errors.BadRoute,
+                    message="unsupported method " + http_method + " (only POST is allowed)",
+                    meta={"twirp_invalid_route": http_method + " " + scope["path"]},
+                )
+
+            headers = {k.decode("utf-8"): v.decode("utf-8") for (k, v) in scope["headers"]}
+            ctx.set(ctxkeys.RAW_REQUEST_PATH, scope["path"])
+            ctx.set(ctxkeys.RAW_HEADERS, headers)
+            self._hook.request_received(ctx=ctx)
+
+            endpoint = self._get_endpoint(scope["path"])
+            headers = {k.decode("utf-8"): v.decode("utf-8") for (k, v) in scope["headers"]}
+            self.validate_content_length(headers=headers)
+            encoder, decoder = self._get_encoder_decoder(endpoint, headers)
+
+            # add headers from request into context
+            ctx.set(ctxkeys.SERVICE_NAME, endpoint.service_name)
+            ctx.set(ctxkeys.METHOD_NAME, endpoint.name)
+            ctx.set(ctxkeys.RESPONSE_STATUS, 200)
+            self._hook.request_routed(ctx=ctx)
+            raw_receive = await self._recv_all(receive)
+            request = decoder(raw_receive)
+            response_data = await self._with_middlewares(func=endpoint.function, ctx=ctx, request=request)
+            self._hook.response_prepared(ctx=ctx)
+
+            body_bytes, headers = encoder(response_data)
+            headers = dict(ctx.get_response_headers(), **headers)
+            # Todo: middleware
+            await self._respond(send=send, status=200, headers=headers, body_bytes=body_bytes)
+            self._hook.response_sent(ctx=ctx)
+        except Exception as e:
+            await self.handle_error(ctx, e, scope, receive, send)
+
+    def _with_middlewares(self, *args, func, ctx, request):
+        chain = iter(self._middlewares + (func,))
+
+        def bind(fn):
+            if not asyncio.iscoroutinefunction(fn):
+                fn = thread_pool_runner(fn)
+
+            async def nxt(ctx, request):
+                try:
+                    cur = next(chain)
+                    return await fn(ctx, request, bind(cur))
+                except StopIteration:
+                    pass
+                return await fn(ctx, request)
+
+            return nxt
+
+        return bind(next(chain))(ctx, request)
+
+    async def handle_error(self, ctx, exc, scope, receive, send):
+        status = 500
+        body_bytes = b"{}"
+        logger = ctx.get_logger()
+        error_data = {}
+        ctx.set(ctxkeys.ORIGINAL_EXCEPTION, exc)
+        try:
+            if not isinstance(exc, exceptions.TwirpServerException):
+                error_data["raw_error"] = str(exc)
+                error_data["raw_trace"] = traceback.format_exc()
+                logger.exception("got non-twirp exception while processing request", **error_data)
+                exc = exceptions.TwirpServerException(code=errors.Errors.Internal, message="Internal non-Twirp Error")
+
+            body_bytes = exc.to_json_bytes()
+            status = errors.Errors.get_status_code(exc.code)
+        except Exception:
+            exc = exceptions.TwirpServerException(
+                code=errors.Errors.Internal, message="There was an error but it could not be serialized into JSON"
+            )
+            error_data["raw_error"] = str(exc)
+            error_data["raw_trace"] = traceback.format_exc()
+            logger.exception("got exception while processing request", **error_data)
+            body_bytes = exc.to_json_bytes()
+
+        ctx.set_logger(logger.bind(**error_data))
+        ctx.set(ctxkeys.RESPONSE_STATUS, status)
+        self._hook.error(ctx=ctx, exc=exc)
+        await self._respond(
+            send=send, status=status, headers={"Content-Type": "application/json"}, body_bytes=body_bytes
+        )
+        self._hook.response_sent(ctx=ctx)
+
+    async def _respond(self, *args, send, status, headers, body_bytes):
+        headers["Content-Length"] = str(len(body_bytes))
+        resp_headers = [(k.encode("utf-8"), v.encode("utf-8")) for (k, v) in headers.items()]
+        await send(
+            {
+                "type": "http.response.start",
+                "status": status,
+                "headers": resp_headers,
+            }
+        )
+        await send(
+            {
+                "type": "http.response.body",
+                "body": body_bytes,
+            }
+        )
+
+    async def _recv_all(self, receive):
+        body = b""
+        more_body = True
+        while more_body:
+            message = await receive()
+            body += message.get("body", b"")
+            more_body = message.get("more_body", False)
+
+            # the body length exceeded than the size set, raise a valid exception
+            # so that proper error is returned to the client
+            if self._max_receive_message_length < len(body):
+                raise exceptions.TwirpServerException(
+                    code=errors.Errors.InvalidArgument,
+                    message=f"message body exceeds the specified length of {self._max_receive_message_length} bytes",
+                )
+
+        return body
+
+    # we will check content-length header value and make sure it is
+    # below the limit set
+    def validate_content_length(self, headers):
+        try:
+            content_length = int(headers.get("content-length"))
+        except (ValueError, TypeError):
+            return
+
+        if self._max_receive_message_length < content_length:
+            raise exceptions.TwirpServerException(
+                code=errors.Errors.InvalidArgument,
+                message=f"message body exceeds the specified length of {self._max_receive_message_length} bytes",
+            )

twirpy-0.1.0.dev3/twirp/async_client.py

@@ -0,0 +1,50 @@
+import asyncio
+import json
+
+import aiohttp
+
+from . import exceptions
+from . import errors
+
+
+class AsyncTwirpClient:
+    def __init__(self, address: str, session: aiohttp.ClientSession | None = None) -> None:
+        self._address = address
+        self._session = session
+
+    async def _make_request(self, *, url, ctx, request, response_obj, session=None, **kwargs):
+        headers = ctx.get_headers()
+        if "headers" in kwargs:
+            headers.update(kwargs["headers"])
+        kwargs["headers"] = headers
+        kwargs["headers"]["Content-Type"] = "application/protobuf"
+
+        if session is None:
+            session = self._session
+        if not isinstance(session, aiohttp.ClientSession):
+            raise TypeError(f"invalid session type '{type(session).__name__}'")
+
+        try:
+            async with await session.post(url=url, data=request.SerializeToString(), **kwargs) as resp:
+                if resp.status == 200:
+                    response = response_obj()
+                    response.ParseFromString(await resp.read())
+                    return response
+                try:
+                    raise exceptions.TwirpServerException.from_json(await resp.json())
+                except (aiohttp.ContentTypeError, json.JSONDecodeError):
+                    raise exceptions.twirp_error_from_intermediary(
+                        resp.status, resp.reason, resp.headers, await resp.text()
+                    ) from None
+        except asyncio.TimeoutError as e:
+            raise exceptions.TwirpServerException(
+                code=errors.Errors.DeadlineExceeded,
+                message=str(e) or "request timeout",
+                meta={"original_exception": e},
+            )
+        except aiohttp.ServerConnectionError as e:
+            raise exceptions.TwirpServerException(
+                code=errors.Errors.Unavailable,
+                message=str(e),
+                meta={"original_exception": e},
+            )

twirpy-0.1.0.dev3/twirp/base.py

@@ -0,0 +1,108 @@
+import functools
+from collections import namedtuple
+
+from google.protobuf import json_format
+from google.protobuf import message
+from google.protobuf import symbol_database as _symbol_database
+
+
+from . import context
+
+from . import server
+from . import exceptions
+from . import errors
+from . import hook as vtwirp_hook
+
+_sym_lookup = _symbol_database.Default().GetSymbol
+
+Endpoint = namedtuple("Endpoint", ["service_name", "name", "function", "input", "output"])
+
+
+class TwirpBaseApp:
+    def __init__(self, *middlewares, hook=None, prefix="", max_receive_message_length=1024 * 100 * 100, ctx_class=None):
+        self._prefix = prefix
+        self._services = {}
+        self._max_receive_message_length = max_receive_message_length
+        if ctx_class is None:
+            ctx_class = context.Context
+        assert issubclass(ctx_class, context.Context)
+        self._ctx_class = ctx_class
+        self._middlewares = middlewares
+        if hook is None:
+            hook = vtwirp_hook.TwirpHook()
+        assert isinstance(hook, vtwirp_hook.TwirpHook)
+        self._hook = hook
+
+    def add_service(self, svc: server.TwirpServer):
+        self._services[self._prefix + svc.prefix] = svc
+
+    def _get_endpoint(self, path):
+        svc = self._services.get(path.rsplit("/", 1)[0], None)
+        if svc is None:
+            raise exceptions.TwirpServerException(code=errors.Errors.NotFound, message="not found")
+
+        return svc.get_endpoint(path[len(self._prefix) :])
+
+    @staticmethod
+    def json_decoder(body, data_obj=None):
+        data = data_obj()
+        try:
+            json_format.Parse(body, data)
+        except json_format.ParseError as exc:
+            raise exceptions.TwirpServerException(
+                code=errors.Errors.Malformed,
+                message="the json request could not be decoded",
+            ) from exc
+        return data
+
+    @staticmethod
+    def json_encoder(value, data_obj=None):
+        if not isinstance(value, data_obj):
+            raise exceptions.TwirpServerException(
+                code=errors.Errors.Internal,
+                message=(
+                    "bad service response type " + str(type(value)) + ", expecting: " + data_obj.DESCRIPTOR.full_name
+                ),
+            )
+
+        return json_format.MessageToJson(value, preserving_proto_field_name=True).encode("utf-8"), {
+            "Content-Type": "application/json"
+        }
+
+    @staticmethod
+    def proto_decoder(body, data_obj=None):
+        data = data_obj()
+        try:
+            data.ParseFromString(body)
+        except message.DecodeError as exc:
+            raise exceptions.TwirpServerException(
+                code=errors.Errors.Malformed,
+                message="the protobuf request could not be decoded",
+            ) from exc
+        return data
+
+    @staticmethod
+    def proto_encoder(value, data_obj=None):
+        if not isinstance(value, data_obj):
+            raise exceptions.TwirpServerException(
+                code=errors.Errors.Internal,
+                message=(
+                    "bad service response type " + str(type(value)) + ", expecting: " + data_obj.DESCRIPTOR.full_name
+                ),
+            )
+
+        return value.SerializeToString(), {"Content-Type": "application/protobuf"}
+
+    def _get_encoder_decoder(self, endpoint, headers):
+        ctype = headers.get("content-type", None)
+        if "application/json" == ctype:
+            decoder = functools.partial(self.json_decoder, data_obj=endpoint.input)
+            encoder = functools.partial(self.json_encoder, data_obj=endpoint.output)
+        elif "application/protobuf" == ctype:
+            decoder = functools.partial(self.proto_decoder, data_obj=endpoint.input)
+            encoder = functools.partial(self.proto_encoder, data_obj=endpoint.output)
+        else:
+            raise exceptions.TwirpServerException(
+                code=errors.Errors.BadRoute, message="unexpected Content-Type: " + str(ctype)
+            )
+        return encoder, decoder

twirpy-0.1.0.dev3/twirp/client.py

@@ -0,0 +1,44 @@
+import requests
+
+from . import exceptions
+from . import errors
+
+
+class TwirpClient:
+    def __init__(self, address, timeout=5):
+        self._address = address
+        self._timeout = timeout
+
+    def _make_request(self, *args, url, ctx, request, response_obj, **kwargs):
+        if "timeout" not in kwargs:
+            kwargs["timeout"] = self._timeout
+        headers = ctx.get_headers()
+        if "headers" in kwargs:
+            headers.update(kwargs["headers"])
+        kwargs["headers"] = headers
+        kwargs["headers"]["Content-Type"] = "application/protobuf"
+        try:
+            resp = requests.post(url=self._address + url, data=request.SerializeToString(), **kwargs)
+            if resp.status_code == 200:
+                response = response_obj()
+                response.ParseFromString(resp.content)
+                return response
+            try:
+                raise exceptions.TwirpServerException.from_json(resp.json())
+            except requests.JSONDecodeError:
+                raise exceptions.twirp_error_from_intermediary(
+                    resp.status_code, resp.reason, resp.headers, resp.text
+                ) from None
+            # Todo: handle error
+        except requests.exceptions.Timeout as e:
+            raise exceptions.TwirpServerException(
+                code=errors.Errors.DeadlineExceeded,
+                message=str(e),
+                meta={"original_exception": e},
+            )
+        except requests.exceptions.ConnectionError as e:
+            raise exceptions.TwirpServerException(
+                code=errors.Errors.Unavailable,
+                message=str(e),
+                meta={"original_exception": e},
+            )

twirpy-0.1.0.dev3/twirp/context.py

@@ -0,0 +1,78 @@
+from . import logging
+
+
+class Context:
+    """Context object for storing context information of
+    request currently being processed.
+    """
+
+    def __init__(self, *args, logger=None, headers=None):
+        """Create a new Context object
+
+        Keyword arguments:
+        logger: Logger that will be used for logging.
+        headers: Headers for the request.
+        """
+        self._values = {}
+        if logger is None:
+            logger = logging.get_logger()
+        self._logger = logger
+        if headers is None:
+            headers = {}
+        self._headers = headers
+        self._response_headers = {}
+
+    def set(self, key, value):
+        """Set a Context value
+
+        Arguments:
+        key: Key for the context key-value pair.
+        value: Value to be stored.
+        """
+        self._values[key] = value
+
+    def get(self, key):
+        """Get a Context value
+
+        Arguments:
+        key: Key for the context key-value pair.
+        """
+        return self._values[key]
+
+    def get_logger(self):
+        """Get current logger used by Context."""
+        return self._logger
+
+    def set_logger(self, logger):
+        """Set logger for this Context
+
+        Arguments:
+        logger: Logger object to be used.
+        """
+        self._logger = logger
+
+    def get_headers(self):
+        """Get request headers that are currently stored."""
+        return self._headers
+
+    def set_header(self, key, value):
+        """Set a request header
+
+        Arguments:
+        key: Key for the header.
+        value: Value for the header.
+        """
+        self._headers[key] = value
+
+    def get_response_headers(self):
+        """Get response headers that are currently stored."""
+        return self._response_headers
+
+    def set_response_header(self, key, value):
+        """Set a response header
+
+        Arguments:
+        key: Key for the header.
+        value: Value for the header.
+        """
+        self._response_headers[key] = value

twirpy-0.1.0.dev3/twirp/ctxkeys.py

@@ -0,0 +1,9 @@
+SERVICE_NAME = "service_name"
+METHOD_NAME = "method_name"
+
+RAW_HEADERS = "raw_headers"
+RAW_REQUEST_PATH = "raw_request_path"
+
+RESPONSE_STATUS = "response_status"
+
+ORIGINAL_EXCEPTION = "original_exception"

twirpy-0.1.0.dev3/twirp/errors.py

@@ -0,0 +1,47 @@
+from enum import Enum
+
+
+class Errors(Enum):
+    Canceled = "canceled"
+    Unknown = "unknown"
+    InvalidArgument = "invalid_argument"
+    DeadlineExceeded = "deadline_exceeded"
+    NotFound = "not_found"
+    BadRoute = "bad_route"
+    AlreadyExists = "already_exists"
+    PermissionDenied = "permission_denied"
+    Unauthenticated = "unauthenticated"
+    ResourceExhausted = "resource_exhausted"
+    FailedPrecondition = "failed_precondition"
+    Aborted = "aborted"
+    OutOfRange = "out_of_range"
+    Unimplemented = "unimplemented"
+    Internal = "internal"
+    Unavailable = "unavailable"
+    DataLoss = "data_loss"
+    Malformed = "malformed"
+    NoError = ""
+
+    @staticmethod
+    def get_status_code(code):
+        return {
+            Errors.Canceled: 408,
+            Errors.Unknown: 500,
+            Errors.InvalidArgument: 400,
+            Errors.Malformed: 400,
+            Errors.DeadlineExceeded: 408,
+            Errors.NotFound: 404,
+            Errors.BadRoute: 404,
+            Errors.AlreadyExists: 409,
+            Errors.PermissionDenied: 403,
+            Errors.Unauthenticated: 401,
+            Errors.ResourceExhausted: 429,
+            Errors.FailedPrecondition: 412,
+            Errors.Aborted: 409,
+            Errors.OutOfRange: 400,
+            Errors.Unimplemented: 501,
+            Errors.Internal: 500,
+            Errors.Unavailable: 503,
+            Errors.DataLoss: 500,
+            Errors.NoError: 200,
+        }.get(code, 500)

twirpy-0.1.0.dev3/twirp/exceptions.py

@@ -0,0 +1,96 @@
+import json
+from http.client import HTTPException
+from typing import Any
+
+from . import errors
+
+
+class TwirpServerException(HTTPException):
+    def __init__(self, *args, code, message, meta: dict[str, Any] | None = None):
+        try:
+            self._code = errors.Errors(code)
+        except ValueError:
+            self._code = errors.Errors.Unknown
+        self._message = message
+        self._meta = meta or {}
+        super().__init__(message)
+
+    @property
+    def code(self):
+        if isinstance(self._code, errors.Errors):
+            return self._code
+        return errors.Errors.Unknown
+
+    @property
+    def message(self):
+        return self._message
+
+    @property
+    def meta(self):
+        return self._meta
+
+    def to_dict(self):
+        err = {"code": self._code.value, "msg": self._message, "meta": {}}
+        for k, v in self._meta.items():
+            err["meta"][k] = str(v)
+        return err
+
+    def to_json_bytes(self):
+        return json.dumps(self.to_dict()).encode("utf-8")
+
+    @staticmethod
+    def from_json(err_dict):
+        return TwirpServerException(
+            code=err_dict.get("code", errors.Errors.Unknown),
+            message=err_dict.get("msg", ""),
+            meta=err_dict.get("meta", {}),
+        )
+
+
+def InvalidArgument(*args, argument, error):
+    return TwirpServerException(
+        code=errors.Errors.InvalidArgument, message=f"{argument} {error}", meta={"argument": argument}
+    )
+
+
+def RequiredArgument(*args, argument):
+    return InvalidArgument(argument=argument, error="is required")
+
+
+def twirp_error_from_intermediary(status, reason, headers, body):
+    # see https://twitchtv.github.io/twirp/docs/errors.html#http-errors-from-intermediary-proxies
+    meta = {
+        "http_error_from_intermediary": "true",
+        "status_code": str(status),
+    }
+
+    if 300 <= status < 400:
+        # twirp uses POST which should not redirect
+        code = errors.Errors.Internal
+        location = headers.get("location")
+        message = 'unexpected HTTP status code %d "%s" received, Location="%s"' % (
+            status,
+            reason,
+            location,
+        )
+        meta["location"] = location
+
+    else:
+        code = {
+            400: errors.Errors.Internal,  # JSON response should have been returned
+            401: errors.Errors.Unauthenticated,
+            403: errors.Errors.PermissionDenied,
+            404: errors.Errors.BadRoute,
+            429: errors.Errors.ResourceExhausted,
+            502: errors.Errors.Unavailable,
+            503: errors.Errors.Unavailable,
+            504: errors.Errors.Unavailable,
+        }.get(status, errors.Errors.Unknown)
+
+        message = 'Error from intermediary with HTTP status code %d "%s"' % (
+            status,
+            reason,
+        )
+        meta["body"] = body
+
+    return TwirpServerException(code=code, message=message, meta=meta)

twirpy-0.1.0.dev3/twirp/hook.py

@@ -0,0 +1,47 @@
+class TwirpHook:
+    # Called as soon as a request is received, always called
+    def request_received(self, *args, ctx):
+        pass
+
+    # Called once the request is routed, service name known, only called if request is routable
+    def request_routed(self, *args, ctx):
+        pass
+
+    # Called once the response is prepared, not called for error cases
+    def response_prepared(self, *args, ctx):
+        pass
+
+    # Called if an error occurs
+    def error(self, *args, ctx, exc):
+        pass
+
+    # Called after error is sent, always called
+    def response_sent(self, *args, ctx):
+        pass
+
+
+class ChainHooks(TwirpHook):
+    def __init__(self, *hooks):
+        for hook in hooks:
+            assert isinstance(hook, TwirpHook)
+        self._hooks = hooks
+
+    def request_received(self, *args, ctx):
+        for hook in self._hooks:
+            hook.request_received(ctx=ctx)
+
+    def request_routed(self, *args, ctx):
+        for hook in self._hooks:
+            hook.request_routed(ctx=ctx)
+
+    def response_prepared(self, *args, ctx):
+        for hook in self._hooks:
+            hook.response_prepared(ctx=ctx)
+
+    def error(self, *args, ctx, exc):
+        for hook in self._hooks:
+            hook.error(ctx=ctx, exc=exc)
+
+    def response_sent(self, *args, ctx):
+        for hook in self._hooks:
+            hook.response_sent(ctx=ctx)

twirpy-0.1.0.dev3/twirp/logging.py

@@ -0,0 +1,62 @@
+import os
+import logging
+
+import structlog
+from structlog.stdlib import LoggerFactory, add_log_level
+
+_configured = False
+
+
+def configure(force=False):
+    """
+    Configures logging & structlog modules
+
+    Keyword Arguments:
+    force: Force to reconfigure logging.
+    """
+
+    global _configured
+    if _configured and not force:
+        return
+
+    # Check whether debug flag is set
+    debug = os.environ.get("DEBUG_MODE", False)
+    # Set appropriate log level
+    if debug:
+        log_level = logging.DEBUG
+    else:
+        log_level = logging.INFO
+
+    # Set logging config
+    logging.basicConfig(
+        level=log_level,
+        format="%(message)s",
+    )
+
+    # Configure structlog
+    structlog.configure(
+        logger_factory=LoggerFactory(),
+        processors=[
+            add_log_level,
+            # Add timestamp
+            structlog.processors.TimeStamper("iso"),
+            # Add stack information
+            structlog.processors.StackInfoRenderer(),
+            # Set exception field using exec info
+            structlog.processors.format_exc_info,
+            # Render event_dict as JSON
+            structlog.processors.JSONRenderer(),
+        ],
+    )
+
+    _configured = True
+
+
+def get_logger(**kwargs):
+    """
+    Get the structlog logger
+    """
+    # Configure logging modules
+    configure()
+    # Return structlog
+    return structlog.get_logger(**kwargs)

twirpy-0.1.0.dev3/twirp/server.py

@@ -0,0 +1,32 @@
+from . import exceptions
+from . import errors
+
+
+class TwirpServer:
+    def __init__(self, *args, service):
+        self.service = service
+        self._endpoints = {}
+        self._prefix = ""
+
+    @property
+    def prefix(self):
+        return self._prefix
+
+    def get_endpoint(self, path):
+        (_, url_pre, rpc_method) = path.rpartition(self._prefix + "/")
+        if not url_pre or not rpc_method:
+            raise exceptions.TwirpServerException(
+                code=errors.Errors.BadRoute,
+                message="no handler for path " + path,
+                meta={"twirp_invalid_route": "POST " + path},
+            )
+
+        endpoint = self._endpoints.get(rpc_method, None)
+        if not endpoint:
+            raise exceptions.TwirpServerException(
+                code=errors.Errors.Unimplemented,
+                message="service has no endpoint " + rpc_method,
+                meta={"twirp_invalide_route": "POST " + path},
+            )
+
+        return endpoint