fastgrpc2 0.2.0__py3-none-any.whl

fastgrpc2/__init__.py

@@ -0,0 +1,39 @@
+"""fastgrpc2 — FastAPI-подобная эргономика для gRPC.
+
+Pydantic на входе и выходе, вся механика grpc.aio — внутри. Юзер пишет
+голые pydantic-модели и async-функции и не трогает grpc/_pb2/ServicerContext.
+"""
+from .app import GrpcApp
+from .service import GrpcService
+from .context import Context
+from .dependencies import Depends
+from .client import Channel, GrpcClient
+from .config import Compression, Keepalive, RetryPolicy
+from .errors import BadRequest, ErrorInfo, FieldViolation, GrpcError, StatusCode, register_detail
+from .metadata import Metadata
+from .security import BearerToken, Insecure, MTLS, TLS
+
+__all__ = [
+    "GrpcApp",
+    "GrpcService",
+    "Context",
+    "Depends",
+    "Channel",
+    "GrpcClient",
+    "GrpcError",
+    "StatusCode",
+    "Metadata",
+    "TLS",
+    "MTLS",
+    "Insecure",
+    "BearerToken",
+    "ErrorInfo",
+    "BadRequest",
+    "FieldViolation",
+    "register_detail",
+    "Compression",
+    "RetryPolicy",
+    "Keepalive",
+]
+
+__version__ = "0.2.0"

fastgrpc2/app.py

@@ -0,0 +1,110 @@
+"""GrpcApp — приложение/сервер (аналог KafkaApp в fastkafka2, FastAPI в REST).
+
+Сервисы, grpc.aio.server, lifespan, graceful-stop, health, интерсепторы.
+TLS/mTLS — tls=TLS(...)/MTLS(...); по умолчанию insecure (dev).
+Ручки: max_send_bytes/max_recv_bytes, compression, keepalive.
+add_interceptor(fn) — pre-hook (auth/logging) перед каждым хендлером.
+dependency_overrides — подмена Depends (тесты). export_proto() — .proto-контракт.
+"""
+from __future__ import annotations
+
+from typing import Awaitable, Callable
+
+import grpc
+import grpc.aio
+
+from . import codec, config, security
+from .context import Context
+from .health import HealthService
+from .service import GrpcService
+
+
+class GrpcApp:
+    def __init__(
+        self,
+        title: str = "",
+        description: str = "",
+        *,
+        address: str = "0.0.0.0:50051",
+        tls=None,
+        compression=None,
+        max_send_bytes: int | None = None,
+        max_recv_bytes: int | None = None,
+        keepalive=None,
+        lifespan: Callable[["GrpcApp"], object] | None = None,
+    ) -> None:
+        self.title = title
+        self.description = description
+        self.address = address
+        self.tls = tls
+        self.compression = compression
+        self.max_send_bytes = max_send_bytes
+        self.max_recv_bytes = max_recv_bytes
+        self.keepalive = keepalive
+        self.dependency_overrides: dict = {}
+        self.bound_port: int | None = None
+        self._interceptors: list[Callable[[Context], Awaitable[None]]] = []
+        self._lifespan_func = lifespan
+        self._lifespan_cm = None
+        self._services: list[GrpcService] = []
+        self._health: HealthService | None = None
+        self._server: grpc.aio.Server | None = None
+
+    def add_service(self, service: GrpcService) -> None:
+        self._services.append(service)
+
+    include_service = add_service  # alias под доктрину include_*
+
+    def add_interceptor(self, interceptor: Callable[[Context], Awaitable[None]]) -> None:
+        """Pre-hook перед каждым хендлером (любого типа): auth/логирование.
+        Бросает GrpcError -> отказ. Порядок = порядок добавления."""
+        self._interceptors.append(interceptor)
+
+    def enable_health(self) -> HealthService:
+        """grpc.health.v1.Health (k8s/LB-пробы). overall=SERVING после старта."""
+        self._health = HealthService()
+        return self._health
+
+    def export_proto(self) -> str:
+        return codec.render_proto(self._services)
+
+    async def start(self) -> None:
+        if self._lifespan_func is not None:
+            self._lifespan_cm = self._lifespan_func(self)
+            await self._lifespan_cm.__aenter__()
+
+        options = config.channel_options(self.max_send_bytes, self.max_recv_bytes, None, self.keepalive) or None
+        self._server = grpc.aio.server(options=options, compression=self.compression)
+
+        interceptors = tuple(self._interceptors)
+        for svc in self._services:
+            self._server.add_generic_rpc_handlers([svc._generic_handler(self.dependency_overrides, interceptors)])
+        if self._health is not None:
+            self._server.add_generic_rpc_handlers([self._health._generic_handler()])
+
+        if security.is_secure(self.tls):
+            self.bound_port = self._server.add_secure_port(self.address, security.server_credentials(self.tls))
+        else:
+            self.bound_port = self._server.add_insecure_port(self.address)
+
+        await self._server.start()
+        if self._health is not None:
+            self._health.set_serving("")
+
+    async def stop(self, grace: float | None = None) -> None:
+        if self._server is not None:
+            await self._server.stop(grace)
+            self._server = None
+        if self._lifespan_cm is not None:
+            await self._lifespan_cm.__aexit__(None, None, None)
+            self._lifespan_cm = None
+
+    async def run(self) -> None:
+        await self.start()
+        try:
+            await self._server.wait_for_termination()
+        finally:
+            await self.stop()
+
+
+__all__ = ["GrpcApp"]

fastgrpc2/client.py

@@ -0,0 +1,177 @@
+"""Клиент: Channel (переиспользуемое соединение) + типизированный GrpcClient.
+
+Все 4 типа вызова как дескрипторы-методы:
+    get_order = GrpcClient.unary("GetOrder", Req, Resp)          await -> Resp
+    watch     = GrpcClient.unary_stream("Watch", Req, Ev)        async for ev in ...
+    upload    = GrpcClient.stream_unary("Upload", Sample, Sum)   await(aiter) -> Sum
+    chat      = GrpcClient.stream_stream("Chat", In, Out)        async for out in ...(aiter)
+
+Канал держим один и шарим между вызовами. v0.1: insecure. TLS/mTLS, .call()
+с доступом к metadata/трейлерам, write()/done_writing() для bidi — later.
+"""
+from __future__ import annotations
+
+import grpc
+import grpc.aio
+
+from . import codec, config, security
+from .deadline import get_budget
+from .errors import TRAILER_KEY, GrpcError, unpack_details
+from .metadata import Metadata
+
+
+def _to_grpc_error(e: grpc.aio.AioRpcError) -> GrpcError:
+    details: list = []
+    try:
+        for k, v in e.trailing_metadata() or ():
+            if k == TRAILER_KEY:
+                details = unpack_details(v if isinstance(v, (bytes, bytearray)) else bytes(v))
+    except Exception:
+        pass
+    return GrpcError(e.code(), e.details(), details)
+
+
+class Channel:
+    def __init__(
+        self,
+        target: str,
+        *,
+        default_timeout: float | None = None,
+        tls=None,
+        auth=None,
+        compression=None,
+        max_send_bytes: int | None = None,
+        max_recv_bytes: int | None = None,
+        retry=None,
+        keepalive=None,
+    ) -> None:
+        self.target = target
+        self.default_timeout = default_timeout
+        self.auth = auth
+        options = config.channel_options(max_send_bytes, max_recv_bytes, retry, keepalive) or None
+        if security.is_secure(tls):
+            self._channel = grpc.aio.secure_channel(
+                target, security.channel_credentials(tls), options=options, compression=compression
+            )
+        else:
+            self._channel = grpc.aio.insecure_channel(target, options=options, compression=compression)
+
+    async def close(self, grace: float | None = None) -> None:
+        await self._channel.close(grace)
+
+    async def __aenter__(self) -> "Channel":
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.close()
+
+
+async def _aiter_wrap(call):
+    try:
+        async for item in call:
+            yield item
+    except grpc.aio.AioRpcError as e:
+        raise _to_grpc_error(e) from e
+
+
+class _Method:
+    """Дескриптор метода клиента; kind = unary|unary_stream|stream_unary|stream_stream."""
+
+    def __init__(self, kind: str, rpc_name: str, request_model: type, response_model: type) -> None:
+        self.kind = kind
+        self.rpc_name = rpc_name
+        self.request_model = request_model
+        self.response_model = response_model
+
+    def __set_name__(self, owner, name: str) -> None:
+        self.attr = name
+
+    def __get__(self, instance, owner):
+        if instance is None:
+            return self
+        return _Bound(instance, self)
+
+
+class _Bound:
+    def __init__(self, client: "GrpcClient", method: _Method) -> None:
+        self._client = client
+        self._m = method
+
+    def _make_callable(self):
+        ch = self._client._channel._channel
+        path = f"/{self._client.full_service_name}/{self._m.rpc_name}"
+        ser = codec.serializer(self._m.request_model)
+        de = codec.deserializer(self._m.response_model)
+        factory = {
+            "unary": ch.unary_unary,
+            "unary_stream": ch.unary_stream,
+            "stream_unary": ch.stream_unary,
+            "stream_stream": ch.stream_stream,
+        }[self._m.kind]
+        return factory(path, request_serializer=ser, response_deserializer=de)
+
+    def __call__(self, request, *, timeout: float | None = None, metadata=None):
+        callable_ = self._make_callable()
+        ch = self._client._channel
+        pairs: list = []
+        if ch.auth is not None:
+            pairs.extend(ch.auth.metadata())
+        if isinstance(metadata, Metadata):
+            pairs.extend(metadata.to_grpc())
+        elif metadata:
+            pairs.extend(metadata)
+        md = pairs or None
+        to = timeout
+        if to is None:
+            to = get_budget()  # наследуем дедлайн-бюджет цепочки, если он есть
+        if to is None:
+            to = ch.default_timeout
+        if self._m.kind in ("unary_stream", "stream_stream"):
+            # стрим на выходе -> возвращаем async-итератор (его НЕ await-им, его итерируем)
+            return _aiter_wrap(callable_(request, timeout=to, metadata=md))
+        # одиночный ответ -> возвращаем корутину под await
+        return self._await(callable_, request, to, md)
+
+    async def _await(self, callable_, request, to, md):
+        try:
+            return await callable_(request, timeout=to, metadata=md)
+        except grpc.aio.AioRpcError as e:
+            raise _to_grpc_error(e) from e
+
+
+class GrpcClient:
+    """Базовый типизированный клиент. Наследник задаёт service и методы:
+
+        class OrderClient(GrpcClient):
+            service = "Orders"
+            get_order = GrpcClient.unary("GetOrder", GetOrderRequest, OrderReply)
+    """
+
+    package: str = "fastgrpc2"
+    service: str = ""
+
+    def __init__(self, channel: Channel) -> None:
+        self._channel = channel
+
+    @property
+    def full_service_name(self) -> str:
+        return f"{self.package}.{self.service}"
+
+    @staticmethod
+    def unary(rpc_name: str, request_model: type, response_model: type) -> _Method:
+        return _Method("unary", rpc_name, request_model, response_model)
+
+    @staticmethod
+    def unary_stream(rpc_name: str, request_model: type, response_model: type) -> _Method:
+        return _Method("unary_stream", rpc_name, request_model, response_model)
+
+    @staticmethod
+    def stream_unary(rpc_name: str, request_model: type, response_model: type) -> _Method:
+        return _Method("stream_unary", rpc_name, request_model, response_model)
+
+    @staticmethod
+    def stream_stream(rpc_name: str, request_model: type, response_model: type) -> _Method:
+        return _Method("stream_stream", rpc_name, request_model, response_model)
+
+
+__all__ = ["Channel", "GrpcClient"]

fastgrpc2/codec.py

@@ -0,0 +1,267 @@
+"""Codec — pydantic <-> protobuf, динамические дескрипторы.
+
+Сигнатура хендлера = контракт. По pydantic-модели на лету строим protobuf-
+дескриптор (FileDescriptorProto -> DescriptorPool -> message class) и держим
+его в кэше. На проводе — настоящий protobuf (интероп с любым gRPC-клиентом),
+а юзер видит только pydantic-модель.
+
+v0.1 поддерживает: bool/int/float/str/bytes, вложенные BaseModel, list[...],
+Optional[...] (разворачивается в singular). Остальное (enum, dict/map, Union-
+oneof, datetime, рекурсия) бросает явный TypeError — это later, не заглушка.
+
+model_construct() при декоде осознанно пропускает ре-валидацию: данные пришли
+из типобезопасного protobuf, форма уже гарантирована проводом.
+"""
+from __future__ import annotations
+
+import types as _types
+from dataclasses import dataclass
+from typing import Any, Union, get_args, get_origin
+
+from google.protobuf import descriptor_pb2, descriptor_pool, message_factory
+from pydantic import BaseModel
+
+_PACKAGE = "fastgrpc2"
+_POOL = descriptor_pool.DescriptorPool()
+
+_FD = descriptor_pb2.FieldDescriptorProto
+_SCALAR: dict[type, int] = {
+    bool: _FD.TYPE_BOOL,     # bool раньше int — он его подтип
+    int: _FD.TYPE_INT64,
+    float: _FD.TYPE_DOUBLE,
+    str: _FD.TYPE_STRING,
+    bytes: _FD.TYPE_BYTES,
+}
+
+
+@dataclass
+class _Field:
+    repeated: bool
+    is_message: bool
+    scalar_type: int | None = None
+    model: type | None = None
+    optional: bool = False  # proto3 presence для скаляра (Optional[...] -> None различимо)
+
+
+@dataclass
+class _Registered:
+    message_class: type
+    full_name: str
+    file_name: str
+    fields: dict[str, _Field]
+
+
+_CACHE: dict[type, _Registered] = {}
+_IN_PROGRESS: set[type] = set()
+
+
+def _field_of(annotation: Any) -> _Field:
+    origin = get_origin(annotation)
+    if origin in (Union, _types.UnionType):
+        non_none = [a for a in get_args(annotation) if a is not type(None)]
+        if len(non_none) == 1:
+            inner = _field_of(non_none[0])  # Optional[X] -> singular X
+            if not inner.repeated and not inner.is_message:
+                inner.optional = True  # presence для скаляра через proto3 optional
+            return inner
+        raise TypeError(f"fastgrpc2 v0.1: Union/oneof пока не поддержан: {annotation!r}")
+    if origin is list:
+        (inner,) = get_args(annotation)
+        f = _field_of(inner)
+        if f.repeated:
+            raise TypeError("fastgrpc2 v0.1: вложенные списки не поддержаны")
+        return _Field(repeated=True, is_message=f.is_message, scalar_type=f.scalar_type, model=f.model)
+    if isinstance(annotation, type) and issubclass(annotation, BaseModel):
+        return _Field(repeated=False, is_message=True, model=annotation)
+    if annotation in _SCALAR:
+        return _Field(repeated=False, is_message=False, scalar_type=_SCALAR[annotation])
+    raise TypeError(
+        f"fastgrpc2 v0.1: тип поля не поддержан: {annotation!r}. "
+        "Поддержано: bool/int/float/str/bytes, BaseModel, list[...], Optional[...]."
+    )
+
+
+def register_model(model: type) -> _Registered:
+    """Строит (и кэширует) protobuf message class для pydantic-модели."""
+    cached = _CACHE.get(model)
+    if cached is not None:
+        return cached
+    if model in _IN_PROGRESS:
+        raise TypeError(f"fastgrpc2 v0.1: рекурсивные модели не поддержаны: {model.__name__}")
+
+    _IN_PROGRESS.add(model)
+    try:
+        fields: dict[str, _Field] = {}
+        deps: list[str] = []
+        for fname, finfo in model.model_fields.items():
+            f = _field_of(finfo.annotation)
+            fields[fname] = f
+            if f.is_message:
+                child = register_model(f.model)  # вложенные регистрируем первыми
+                if child.file_name not in deps:
+                    deps.append(child.file_name)
+
+        name = model.__name__
+        file_name = f"{_PACKAGE}/{name}.proto"
+        full_name = f"{_PACKAGE}.{name}"
+
+        fdp = descriptor_pb2.FileDescriptorProto()
+        fdp.name = file_name
+        fdp.package = _PACKAGE
+        fdp.syntax = "proto3"
+        for d in deps:
+            fdp.dependency.append(d)
+
+        msg = fdp.message_type.add()
+        msg.name = name
+        for number, (fname, f) in enumerate(fields.items(), start=1):
+            pf = msg.field.add()
+            pf.name = fname
+            pf.number = number
+            pf.label = _FD.LABEL_REPEATED if f.repeated else _FD.LABEL_OPTIONAL
+            if f.is_message:
+                pf.type = _FD.TYPE_MESSAGE
+                pf.type_name = f".{_PACKAGE}.{f.model.__name__}"
+            else:
+                pf.type = f.scalar_type
+                if f.optional:
+                    # синтетический oneof -> presence для proto3-скаляра (HasField работает)
+                    oneof = msg.oneof_decl.add()
+                    oneof.name = f"_{fname}"
+                    pf.oneof_index = len(msg.oneof_decl) - 1
+                    pf.proto3_optional = True
+
+        _POOL.Add(fdp)
+        descriptor = _POOL.FindMessageTypeByName(full_name)
+        message_class = _build_class(descriptor)
+        reg = _Registered(message_class, full_name, file_name, fields)
+        _CACHE[model] = reg
+        return reg
+    finally:
+        _IN_PROGRESS.discard(model)
+
+
+def _build_class(descriptor) -> type:
+    # protobuf >= 4.22
+    get_cls = getattr(message_factory, "GetMessageClass", None)
+    if get_cls is not None:
+        return get_cls(descriptor)
+    return message_factory.MessageFactory(_POOL).GetPrototype(descriptor)  # legacy fallback
+
+
+def encode(instance: BaseModel, reg: _Registered | None = None):
+    if reg is None:
+        reg = register_model(type(instance))
+    msg = reg.message_class()
+    for fname, f in reg.fields.items():
+        value = getattr(instance, fname)
+        if value is None:
+            continue
+        if f.repeated:
+            target = getattr(msg, fname)
+            if f.is_message:
+                child = register_model(f.model)
+                for item in value:
+                    target.add().CopyFrom(encode(item, child))
+            else:
+                target.extend(value)
+        elif f.is_message:
+            getattr(msg, fname).CopyFrom(encode(value, register_model(f.model)))
+        else:
+            setattr(msg, fname, value)
+    return msg
+
+
+def decode(msg, model: type) -> BaseModel:
+    reg = register_model(model)
+    data: dict[str, Any] = {}
+    for fname, f in reg.fields.items():
+        if f.repeated:
+            raw = getattr(msg, fname)
+            data[fname] = [decode(x, f.model) for x in raw] if f.is_message else list(raw)
+        elif f.is_message:
+            data[fname] = decode(getattr(msg, fname), f.model) if msg.HasField(fname) else None
+        elif f.optional:
+            data[fname] = getattr(msg, fname) if msg.HasField(fname) else None
+        else:
+            data[fname] = getattr(msg, fname)
+    return model.model_construct(**data)
+
+
+def serializer(model: type):
+    """obj -> bytes (request_serializer на клиенте / response_serializer на сервере)."""
+    reg = register_model(model)
+
+    def _ser(instance: BaseModel) -> bytes:
+        return encode(instance, reg).SerializeToString()
+
+    return _ser
+
+
+def deserializer(model: type):
+    """bytes -> obj (request_deserializer на сервере / response_deserializer на клиенте)."""
+    reg = register_model(model)
+
+    def _de(data: bytes) -> BaseModel:
+        msg = reg.message_class()
+        msg.ParseFromString(data)
+        return decode(msg, model)
+
+    return _de
+
+
+_PROTO_NAME = {
+    _FD.TYPE_BOOL: "bool",
+    _FD.TYPE_INT64: "int64",
+    _FD.TYPE_DOUBLE: "double",
+    _FD.TYPE_STRING: "string",
+    _FD.TYPE_BYTES: "bytes",
+}
+
+
+def _render_message(model: type) -> str:
+    reg = register_model(model)
+    lines = [f"message {model.__name__} {{"]
+    for number, (fname, f) in enumerate(reg.fields.items(), start=1):
+        prefix = "repeated " if f.repeated else ("optional " if f.optional else "")
+        tname = f.model.__name__ if f.is_message else _PROTO_NAME[f.scalar_type]
+        lines.append(f"  {prefix}{tname} {fname} = {number};")
+    lines.append("}")
+    return "\n".join(lines)
+
+
+def render_proto(services) -> str:
+    """Собирает .proto-текст из pydantic-моделей сервисов (доктрина: сигнатура = контракт)."""
+    models: list[type] = []
+    seen: set[type] = set()
+
+    def add(model: type) -> None:
+        reg = register_model(model)
+        for f in reg.fields.values():
+            if f.is_message:
+                add(f.model)
+        if model not in seen:
+            seen.add(model)
+            models.append(model)
+
+    for svc in services:
+        for spec in svc._methods.values():
+            add(spec.request_model)
+            add(spec.response_model)
+
+    parts = ['syntax = "proto3";', "", f"package {_PACKAGE};", ""]
+    for model in models:
+        parts.append(_render_message(model))
+        parts.append("")
+    for svc in services:
+        parts.append(f"service {svc.name} {{")
+        for spec in svc._methods.values():
+            req = ("stream " if spec.input_stream else "") + spec.request_model.__name__
+            resp = ("stream " if spec.output_stream else "") + spec.response_model.__name__
+            parts.append(f"  rpc {spec.rpc_name}({req}) returns ({resp});")
+        parts.append("}")
+        parts.append("")
+    return "\n".join(parts).rstrip() + "\n"
+
+
+__all__ = ["register_model", "encode", "decode", "serializer", "deserializer", "render_proto"]

fastgrpc2/config.py

@@ -0,0 +1,75 @@
+"""Типизированные ручки канала/сервера: сжатие, лимиты размера, ретраи, keepalive.
+
+Скрывают сырые grpc.* опции-кортежи и service_config JSON за нормальными типами.
+"""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+
+import grpc
+
+
+class Compression:
+    NoCompression = grpc.Compression.NoCompression
+    Gzip = grpc.Compression.Gzip
+    Deflate = grpc.Compression.Deflate
+
+
+@dataclass
+class RetryPolicy:
+    """Сериализуется в grpc service_config (юзер не пишет JSON руками)."""
+    max_attempts: int = 3
+    initial_backoff: str = "0.1s"
+    max_backoff: str = "1s"
+    backoff_multiplier: float = 2.0
+    retryable_status_codes: tuple[str, ...] = ("UNAVAILABLE",)
+
+    def _service_config_json(self) -> str:
+        return json.dumps(
+            {
+                "methodConfig": [
+                    {
+                        "name": [{}],  # все методы
+                        "retryPolicy": {
+                            "maxAttempts": self.max_attempts,
+                            "initialBackoff": self.initial_backoff,
+                            "maxBackoff": self.max_backoff,
+                            "backoffMultiplier": self.backoff_multiplier,
+                            "retryableStatusCodes": list(self.retryable_status_codes),
+                        },
+                    }
+                ]
+            }
+        )
+
+
+@dataclass
+class Keepalive:
+    time_ms: int = 60000
+    timeout_ms: int = 20000
+    permit_without_calls: bool = False
+
+    def _options(self) -> list[tuple[str, int]]:
+        return [
+            ("grpc.keepalive_time_ms", self.time_ms),
+            ("grpc.keepalive_timeout_ms", self.timeout_ms),
+            ("grpc.keepalive_permit_without_calls", 1 if self.permit_without_calls else 0),
+        ]
+
+
+def channel_options(max_send_bytes, max_recv_bytes, retry, keepalive) -> list[tuple]:
+    options: list[tuple] = []
+    if max_send_bytes is not None:
+        options.append(("grpc.max_send_message_length", max_send_bytes))
+    if max_recv_bytes is not None:
+        options.append(("grpc.max_receive_message_length", max_recv_bytes))
+    if keepalive is not None:
+        options.extend(keepalive._options())
+    if retry is not None:
+        options.append(("grpc.enable_retries", 1))
+        options.append(("grpc.service_config", retry._service_config_json()))
+    return options
+
+
+__all__ = ["Compression", "RetryPolicy", "Keepalive", "channel_options"]