veil-api-kit 0.10.0__py3-none-any.whl

veil_kit/grpc.py

@@ -0,0 +1,525 @@
+"""gRPC: a channel for the stubs generated by ``grpc_tools.protoc``, and the server helpers of ``veil.grpc``.
+
+.. code-block:: python
+
+    import demo_pb2, demo_pb2_grpc                    # python -m grpc_tools.protoc ... --grpc_python_out=.
+    from veil_kit import grpc as vgrpc
+
+    channel = vgrpc.insecure_channel("127.0.0.1:50051")
+    stub = demo_pb2_grpc.DemoStub(channel)
+    reply = stub.SayHello(demo_pb2.HelloRequest(name="veil"), timeout=5)
+
+    # asyncio (the stubs of grpc.aio work the same way)
+    async with vgrpc.aio.insecure_channel("127.0.0.1:50051") as ch:
+        reply = await demo_pb2_grpc.DemoStub(ch).SayHello(demo_pb2.HelloRequest(name="veil"))
+
+The channel runs on veil's own HTTP/2 client (Rust, on a client thread of its own): grpcio is not needed (only
+protobuf for the messages). Errors raise :class:`RpcError` (a ``grpc.RpcError`` when grpcio is installed) with
+``code()``, ``details()`` and ``trailing_metadata()``. Servers: :class:`veil.grpc.Server` takes the generated
+``add_XxxServicer_to_server`` functions (re-exported here).
+"""
+
+# F-268: grpcio の Channel と同じ口（生成スタブがそのまま使える）。通信は Rust（veil::api::grpc::Channel）。
+
+import asyncio
+import os
+import tempfile
+
+from veil.grpc import Server, ServicerContext, StatusCode, add_health  # noqa: F401  再公開
+
+__all__ = [
+    "Channel",
+    "insecure_channel",
+    "secure_channel",
+    "ssl_channel_credentials",
+    "RpcError",
+    "StatusCode",
+    "Server",
+    "ServicerContext",
+    "add_health",
+    "aio",
+]
+
+try:  # grpcio があれば、その例外・状態コードの型に合わせる（except grpc.RpcError で捕まえられる）
+    import grpc as _grpcio
+
+    _RpcBase = _grpcio.RpcError
+    _CODES = {c.value[0]: c for c in _grpcio.StatusCode}
+except ImportError:  # pragma: no cover
+    _grpcio = None
+    _RpcBase = Exception
+    _CODES = {}
+
+
+def _code(n):
+    return _CODES.get(n) or StatusCode(n)
+
+
+class RpcError(_RpcBase):
+    """A call ended with a status other than OK."""
+
+    def __init__(self, code, details, initial=(), trailing=()):
+        super().__init__("%s: %s" % (_code(code).name, details))
+        self._code = code
+        self._details = details
+        self._initial = tuple(initial)
+        self._trailing = tuple(trailing)
+
+    def code(self):
+        """The status code."""
+        return _code(self._code)
+
+    def details(self):
+        """The status message."""
+        return self._details
+
+    def initial_metadata(self):
+        """The response headers."""
+        return self._initial
+
+    def trailing_metadata(self):
+        """The trailers."""
+        return self._trailing
+
+    def debug_error_string(self):
+        """Same as ``str(error)``."""
+        return str(self)
+
+
+class _CallInfo:
+    """What ``with_call`` returns next to the response (``grpc.Call``)."""
+
+    def __init__(self, code, details, initial, trailing):
+        self._code, self._details, self._initial, self._trailing = code, details, tuple(initial), tuple(trailing)
+
+    def code(self):
+        """The status code."""
+        return _code(self._code)
+
+    def details(self):
+        """The status message."""
+        return self._details
+
+    def initial_metadata(self):
+        """The response headers."""
+        return self._initial
+
+    def trailing_metadata(self):
+        """The trailers."""
+        return self._trailing
+
+
+class ChannelCredentials:
+    """TLS settings for :func:`secure_channel` (from :func:`ssl_channel_credentials`)."""
+
+    def __init__(self, ca=None, cert=None, key=None):
+        self.ca = ca
+        self.cert = cert
+        self.key = key
+
+
+def _to_file(pem, suffix):
+    if pem is None:
+        return None
+    if isinstance(pem, str) and not pem.lstrip().startswith("-----"):
+        return pem  # 既にパス
+    data = pem.encode() if isinstance(pem, str) else pem
+    fd, path = tempfile.mkstemp(suffix=suffix, prefix="veil-grpc-")
+    with os.fdopen(fd, "wb") as f:
+        f.write(data)
+    return path
+
+
+def ssl_channel_credentials(root_certificates=None, private_key=None, certificate_chain=None):
+    """TLS credentials (PEM ``bytes`` or file paths): trusted CAs (default: the system's) and a client certificate."""
+    return ChannelCredentials(_to_file(root_certificates, ".ca.pem"), _to_file(certificate_chain, ".crt.pem"),
+                              _to_file(private_key, ".key.pem"))
+
+
+def _url(target, secure):
+    if "://" in target:
+        return target
+    return ("https://" if secure else "http://") + target
+
+
+def _metadata(md):
+    out = []
+    for k, v in md or ():
+        k = str(k).lower()
+        out.append((k, v if isinstance(v, (bytes, bytearray)) else str(v)))
+    return out
+
+
+class Channel:
+    """A channel (``grpc.Channel``); prefer :func:`insecure_channel` / :func:`secure_channel`."""
+
+    def __init__(self, target, credentials=None, options=None, compression=None):
+        """Connect lazily to ``target`` (``host:port`` or a URL)."""
+        from veil import _veil
+
+        self.target = target
+        secure = credentials is not None
+        ca = [credentials.ca] if secure and credentials.ca else None
+        cert = (credentials.cert, credentials.key) if secure and credentials.cert else None
+        gzip = compression is not None and getattr(compression, "name", str(compression)).lower().endswith("gzip")
+        max_msg = None
+        for k, v in options or ():
+            if k in ("grpc.max_receive_message_length", "grpc.max_message_length"):
+                max_msg = int(v)
+        self._n = _veil.GrpcChannel(_url(target, secure), ca, cert, gzip, max_msg)
+
+    # ---- grpcio の Channel の口 ----
+
+    def unary_unary(self, method, request_serializer=None, response_deserializer=None, **_):
+        """A callable for a unary method."""
+        return _Unary(self, method, request_serializer, response_deserializer)
+
+    def unary_stream(self, method, request_serializer=None, response_deserializer=None, **_):
+        """A callable for a server-streaming method."""
+        return _UnaryStream(self, method, request_serializer, response_deserializer)
+
+    def stream_unary(self, method, request_serializer=None, response_deserializer=None, **_):
+        """A callable for a client-streaming method."""
+        return _StreamUnary(self, method, request_serializer, response_deserializer)
+
+    def stream_stream(self, method, request_serializer=None, response_deserializer=None, **_):
+        """A callable for a bidirectional method."""
+        return _StreamStream(self, method, request_serializer, response_deserializer)
+
+    def subscribe(self, callback, try_to_connect=False):
+        """Accepted for compatibility (connectivity is not reported)."""
+
+    def unsubscribe(self, callback):
+        """Accepted for compatibility."""
+
+    def close(self):
+        """Close the channel (connections close when idle)."""
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    # ---- 呼び出し ----
+
+    def _start(self, method, metadata, timeout):
+        return self._n.call(method, _metadata(metadata), timeout)
+
+
+def _ser(f, m):
+    return m if f is None else f(m)
+
+
+def _de(f, b):
+    return b if f is None else f(b)
+
+
+def _finish(call):
+    code, details, initial, trailing = call.status()
+    if code != 0:
+        raise RpcError(code, details, initial, trailing)
+    return _CallInfo(code, details, initial, trailing)
+
+
+class _Callable:
+    def __init__(self, ch, method, ser, de):
+        self._ch, self._method, self._ser, self._de = ch, method, ser, de
+
+
+class _Unary(_Callable):
+    def with_call(self, request, timeout=None, metadata=None, **_):
+        """Call and return ``(response, call)``."""
+        call = self._ch._start(self._method, metadata, timeout)
+        call.send(_ser(self._ser, request))
+        call.done_sending()
+        data = call.recv()
+        info = _finish(call)
+        if data is None:
+            raise RpcError(13, "the server sent no response message")
+        return _de(self._de, data), info
+
+    def __call__(self, request, timeout=None, metadata=None, **kw):
+        """Call and return the response."""
+        return self.with_call(request, timeout, metadata, **kw)[0]
+
+    def future(self, request, timeout=None, metadata=None, **kw):
+        """Call on a thread and return a ``concurrent.futures.Future``."""
+        import concurrent.futures
+
+        from veil._aio import _executor
+
+        f = _executor().submit(self, request, timeout, metadata)
+        assert isinstance(f, concurrent.futures.Future)
+        return f
+
+
+class _ResponseIterator:
+    def __init__(self, call, de):
+        self._call, self._de, self._info = call, de, None
+
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        data = self._call.recv()
+        if data is None:
+            self._info = _finish(self._call)
+            raise StopIteration
+        return _de(self._de, data)
+
+    def cancel(self):
+        """Cancel the call."""
+        self._call.cancel()
+
+    def code(self):
+        """The status code (after the last message)."""
+        return self._info.code() if self._info else None
+
+    def details(self):
+        """The status message."""
+        return self._info.details() if self._info else None
+
+    def trailing_metadata(self):
+        """The trailers (after the last message)."""
+        return self._info.trailing_metadata() if self._info else None
+
+    def initial_metadata(self):
+        """The response headers."""
+        return tuple(self._call.initial_metadata())
+
+
+class _UnaryStream(_Callable):
+    def __call__(self, request, timeout=None, metadata=None, **_):
+        """Call and return an iterator of responses."""
+        call = self._ch._start(self._method, metadata, timeout)
+        call.send(_ser(self._ser, request))
+        call.done_sending()
+        return _ResponseIterator(call, self._de)
+
+
+def _pump(call, ser, it):
+    try:
+        for m in it:
+            if not call.send(_ser(ser, m)):
+                break
+    finally:
+        call.done_sending()
+
+
+class _StreamUnary(_Callable):
+    def with_call(self, request_iterator, timeout=None, metadata=None, **_):
+        """Send the requests and return ``(response, call)``."""
+        call = self._ch._start(self._method, metadata, timeout)
+        _pump(call, self._ser, request_iterator)
+        data = call.recv()
+        info = _finish(call)
+        if data is None:
+            raise RpcError(13, "the server sent no response message")
+        return _de(self._de, data), info
+
+    def __call__(self, request_iterator, timeout=None, metadata=None, **kw):
+        """Send the requests and return the response."""
+        return self.with_call(request_iterator, timeout, metadata, **kw)[0]
+
+
+class _StreamStream(_Callable):
+    def __call__(self, request_iterator, timeout=None, metadata=None, **_):
+        """Send the requests (on a thread) and return an iterator of responses."""
+        import threading
+
+        call = self._ch._start(self._method, metadata, timeout)
+        threading.Thread(target=_pump, args=(call, self._ser, request_iterator), daemon=True).start()
+        return _ResponseIterator(call, self._de)
+
+
+def insecure_channel(target, options=None, compression=None):
+    """A channel over plain HTTP/2 (h2c)."""
+    return Channel(target, None, options, compression)
+
+
+def secure_channel(target, credentials=None, options=None, compression=None):
+    """A channel over TLS (``credentials`` from :func:`ssl_channel_credentials`; default: the system's CAs)."""
+    return Channel(target, credentials or ChannelCredentials(), options, compression)
+
+
+# ===================== asyncio（grpc.aio と同じ口） =====================
+
+
+def _future_of(register):
+    loop = asyncio.get_running_loop()
+    fut = loop.create_future()
+
+    def done(v):
+        loop.call_soon_threadsafe(lambda: fut.done() or fut.set_result(v))
+
+    register(done)
+    return fut
+
+
+async def _arecv(call):
+    return await _future_of(call.recv_cb)
+
+
+async def _astatus(call):
+    code, details, initial, trailing = await _future_of(call.status_cb)
+    if code != 0:
+        raise RpcError(code, details, initial, trailing)
+    return _CallInfo(code, details, initial, trailing)
+
+
+class _AioUnaryCall:
+    def __init__(self, coro):
+        self._coro = coro
+
+    def __await__(self):
+        return self._coro.__await__()
+
+
+class _AioStreamCall:
+    def __init__(self, call, de, pump=None, ser=None):
+        self._call, self._de, self._pump, self._ser, self._info = call, de, pump, ser, None
+
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        m = await self.read()
+        if m is None:
+            raise StopAsyncIteration
+        return m
+
+    async def read(self):
+        """The next response, or ``None`` at the end."""
+        data = await _arecv(self._call)
+        if data is None:
+            self._info = await _astatus(self._call)
+            return None
+        return _de(self._de, data)
+
+    async def write(self, request):
+        """Send one request (bidirectional calls created without a request iterator)."""
+        self._call.send(_ser(self._ser, request))
+
+    async def done_writing(self):
+        """Finish sending."""
+        self._call.done_sending()
+
+    def cancel(self):
+        """Cancel the call."""
+        self._call.cancel()
+        if self._pump is not None:
+            self._pump.cancel()
+
+    async def code(self):
+        """The status code."""
+        return self._info.code() if self._info else None
+
+    async def trailing_metadata(self):
+        """The trailers."""
+        return self._info.trailing_metadata() if self._info else None
+
+
+async def _apump(call, ser, it):
+    try:
+        if hasattr(it, "__aiter__"):
+            async for m in it:
+                if not call.send(_ser(ser, m)):
+                    break
+        else:
+            for m in it:
+                if not call.send(_ser(ser, m)):
+                    break
+    finally:
+        call.done_sending()
+
+
+class _AioChannel(Channel):
+    """An asyncio channel (``grpc.aio.Channel``)."""
+
+    def unary_unary(self, method, request_serializer=None, response_deserializer=None, **_):
+        """An awaitable callable for a unary method."""
+        ch = self
+
+        def call(request, timeout=None, metadata=None, **kw):
+            async def run():
+                c = ch._start(method, metadata, timeout)
+                c.send(_ser(request_serializer, request))
+                c.done_sending()
+                data = await _arecv(c)
+                await _astatus(c)
+                if data is None:
+                    raise RpcError(13, "the server sent no response message")
+                return _de(response_deserializer, data)
+
+            return _AioUnaryCall(run())
+
+        return call
+
+    def unary_stream(self, method, request_serializer=None, response_deserializer=None, **_):
+        """A callable returning an async iterator of responses."""
+        ch = self
+
+        def call(request, timeout=None, metadata=None, **kw):
+            c = ch._start(method, metadata, timeout)
+            c.send(_ser(request_serializer, request))
+            c.done_sending()
+            return _AioStreamCall(c, response_deserializer)
+
+        return call
+
+    def stream_unary(self, method, request_serializer=None, response_deserializer=None, **_):
+        """An awaitable callable taking an (async) iterator of requests."""
+        ch = self
+
+        def call(request_iterator, timeout=None, metadata=None, **kw):
+            async def run():
+                c = ch._start(method, metadata, timeout)
+                await _apump(c, request_serializer, request_iterator)
+                data = await _arecv(c)
+                await _astatus(c)
+                if data is None:
+                    raise RpcError(13, "the server sent no response message")
+                return _de(response_deserializer, data)
+
+            return _AioUnaryCall(run())
+
+        return call
+
+    def stream_stream(self, method, request_serializer=None, response_deserializer=None, **_):
+        """A callable taking an (async) iterator of requests and returning an async iterator of responses."""
+        ch = self
+
+        def call(request_iterator=None, timeout=None, metadata=None, **kw):
+            c = ch._start(method, metadata, timeout)
+            pump = None
+            if request_iterator is not None:
+                pump = asyncio.get_running_loop().create_task(_apump(c, request_serializer, request_iterator))
+            return _AioStreamCall(c, response_deserializer, pump, request_serializer)
+
+        return call
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc):
+        self.close()
+
+    async def channel_ready(self):
+        """Accepted for compatibility (connections are made on the first call)."""
+
+
+class aio:  # noqa: N801  grpc.aio と同じ名前
+    """``veil_kit.grpc.aio.insecure_channel`` / ``secure_channel`` (``grpc.aio`` style)."""
+
+    Channel = _AioChannel
+
+    @staticmethod
+    def insecure_channel(target, options=None, compression=None):
+        """An asyncio channel over plain HTTP/2 (h2c)."""
+        return _AioChannel(target, None, options, compression)
+
+    @staticmethod
+    def secure_channel(target, credentials=None, options=None, compression=None):
+        """An asyncio channel over TLS."""
+        return _AioChannel(target, credentials or ChannelCredentials(), options, compression)

veil_kit/redirects.py

@@ -0,0 +1,33 @@
+"""Redirects that only go to this site or to listed hosts (protection against open redirects)."""
+
+# F-268
+
+import urllib.parse
+
+import veil
+
+__all__ = ["is_safe_url", "safe_redirect"]
+
+
+def is_safe_url(url, allowed_hosts=(), require_https=False):
+    """True when ``url`` is a path on this site (``/x``, not ``//host`` or ``/\\host``) or an ``http(s)`` URL whose host
+    is in ``allowed_hosts`` (URLs with user information are refused)."""
+    if not url or any(c in url for c in "\r\n\t\x00") or "\\" in url:
+        return False
+    if url.startswith("/"):
+        return not url.startswith("//")
+    try:
+        u = urllib.parse.urlsplit(url)
+    except ValueError:
+        return False
+    if u.scheme not in (("https",) if require_https else ("http", "https")):
+        return False
+    if u.username is not None or u.password is not None:
+        return False
+    host = (u.hostname or "").lower()
+    return bool(host) and host in {h.lower() for h in allowed_hosts}
+
+
+def safe_redirect(url, allowed_hosts=(), fallback="/", status_code=303):
+    """A :class:`veil.RedirectResponse` to ``url`` when :func:`is_safe_url`, otherwise to ``fallback``."""
+    return veil.RedirectResponse(url if is_safe_url(url, allowed_hosts) else fallback, status_code)