Metadata-Version: 2.4
Name: ingot-grpcio
Version: 0.10.0
Summary: Integration of grpcio, the gRPC library of Google, into Ingots.
Keywords: ingots,grpc,grpcio
Author: Aliaksandr Karotki
Author-email: Aliaksandr Karotki <abkarotki@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: 3.15
Classifier: Typing :: Typed
Requires-Dist: googleapis-common-protos>=1.70,<2
Requires-Dist: grpcio>=1.84,<2
Requires-Dist: grpcio-status>=1.84,<2
Requires-Dist: ingots>=0.31.0,<0.32
Requires-Dist: protobuf>=6.31,<8
Requires-Dist: grpcio-reflection>=1.84,<2 ; extra == 'reflection'
Requires-Python: >=3.14
Project-URL: repository, https://github.com/ak-ingots/ingot-grpcio
Project-URL: changelog, https://github.com/ak-ingots/ingot-grpcio/blob/main/CHANGELOG.md
Provides-Extra: reflection
Description-Content-Type: text/markdown

# ingot-grpcio

[![ci](https://github.com/ak-ingots/ingot-grpcio/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/ak-ingots/ingot-grpcio/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/ak-ingots/ingot-grpcio/blob/main/LICENSE)

<!-- Links must be absolute: this README also renders on PyPI. -->

Integration of grpcio, the gRPC library of Google, into Ingots applications:
gRPC servers and clients on its API. An addon of
[Ingots](https://github.com/ak-ingots/ingots).

## Install

```sh
uv add ingot-grpcio
```

```python
import ingot_grpcio


class AppProject(ingot_grpcio.GrpcProject):
    env_configs_prefix = "APP"
```

An application with other addons joins the configs, the settings and the
logging instead: `class AppConfigs(HttpConfigs, GrpcConfigs)` with `GrpcConfigs`
from `ingot_grpcio.settings.configs`, and so on, as the addon guide of Ingots
shows. The configs of the addon are named
`GRPC_*`: `GRPC_LOGGING_LEVEL` sets the level of its logger, `ingot_grpcio`.

## Servers

`GrpcProject` holds `grpc`, a unit of three: `grpc.errors`, how the
exceptions reach a client; `grpc.servers` and `grpc.clients`, the servers
and their clients, each a component. A binding declares the services of
a server, each a contract in a `.proto` file with the class implementing
it, a servicer; the server and its client extend the binding. The
contract:

```proto
// app/proto/demo.proto
syntax = "proto3";

package demo;

service Echo {
  rpc Say (EchoMessage) returns (EchoMessage);
}

message EchoMessage {
  string text = 1;
}
```

Its code, generated by `grpcio-tools`
([mypy-protobuf](https://github.com/nipunn1313/mypy-protobuf) adds the
stubs for mypy with `--mypy_out=. --mypy_grpc_out=.`):

```sh
uv add --dev grpcio-tools
uv run python -m grpc_tools.protoc -I . --python_out=. --grpc_python_out=. app/proto/demo.proto
```

The application:

```python
# app/project.py
import typing as t

from ingot_grpcio import GrpcProject
from ingot_grpcio.grpc import GrpcUnit
from ingot_grpcio.grpc.clients import DefaultGrpcClient, GrpcClients
from ingot_grpcio.grpc.servers import DefaultGrpcServer, GrpcServers
from ingot_grpcio.grpc.services import GrpcService, GrpcServicer
from ingots.puer import Slot
from ingots.puer.cli import BaseCommand

from .proto import demo_pb2, demo_pb2_grpc


class Echo(GrpcServicer, demo_pb2_grpc.EchoServicer):
    @t.override
    async def Say(self, request, context):
        return request


class AppGrpcBinding:
    echo = GrpcService(demo_pb2_grpc.EchoStub, Echo)


class AppGrpcServer(AppGrpcBinding, DefaultGrpcServer):
    pass


class AppGrpcClient(AppGrpcBinding, DefaultGrpcClient):
    pass


class AppGrpcServers(GrpcServers):
    default = Slot(AppGrpcServer)


class AppGrpcClients(GrpcClients):
    default = Slot(AppGrpcClient)


class AppGrpc(GrpcUnit):
    servers = Slot(AppGrpcServers)
    clients = Slot(AppGrpcClients)


class Say(BaseCommand):
    cli_description = "Says ingots to the server."
    project: "AppProject"

    @t.override
    async def _run(self) -> None:
        client = await self.project.grpc.clients.default
        reply = await client.echo.Say(demo_pb2.EchoMessage(text="ingots"))
        print(reply.text)


class AppProject(GrpcProject):
    env_configs_prefix = "APP"
    grpc = Slot(AppGrpc)
    say = Slot(Say)
```

It runs through its own `__main__.py`, which hands `AppProject` to
`CommandRunner`:

```python
# app/__main__.py
import sys

from ingots.defaults.logging import configure_startup_logging
from ingots.puer.cli import CommandRunner

from .project import AppProject

configure_startup_logging()
sys.exit(CommandRunner(AppProject).run())
```

```sh
uv run python -m app components run-forever --component grpc.servers.default
```

From the stub a `GrpcService` finds, by the names grpcio generates, the
rest of the code of the service: its descriptor, the servicer base, the
function adding a servicer to a server. The servicer extends that
generated base, so that mypy checks its RPCs. The same attribute gives
each side its own: `server.echo` is the servicer of the server, created
once with the project, and `client.echo` the stub on the channel of the
client. A server serves the services of the bindings it extends, in the
order of its bases, and nothing else; a binding is a plain class, and a
server may extend several. A subclass replacing a service keeps its
contract and refines its servicer, as a slot does: `echo =
GrpcService(demo_pb2_grpc.EchoStub, LoudEcho)` with `LoudEcho(Echo)`.

The default server is configured
by `GRPC_DEFAULT_LISTEN_HOST` (`[::]`), `GRPC_DEFAULT_PORT` (50051),
`GRPC_DEFAULT_MAX_CONCURRENT_RPCS` (100, 0 for no limit),
`GRPC_DEFAULT_SHUTDOWN_GRACE` (30 seconds for the calls in progress),
`GRPC_DEFAULT_IS_SEND_DEBUG_INFO` (off, see below) and
`GRPC_DEFAULT_IS_REFLECTION` (off, see below). Another server in the
same process extends `BaseGrpcServer` with configs and bindings of its
own.

The interceptors of a server, the middleware of gRPC, come from its hook
`_iter_interceptors()`, the outermost first. The default server yields
`ServerGrpcErrorsInterceptor`, which encodes the errors; a subclass adding
its own yields those of its base first:

```python
class AppGrpcServer(AppGrpcBinding, DefaultGrpcServer):
    @t.override
    def _iter_interceptors(self):
        yield from super()._iter_interceptors()
        yield AuthInterceptor()
```

Reflection, the service of gRPC describing a server, lets visual clients
such as grpcurl, grpcui or Postman find its RPCs and messages without the
`.proto` files. `GRPC_DEFAULT_IS_REFLECTION` turns it on, with the extra
`reflection` (`uv add "ingot-grpcio[reflection]"`): the server describes
exactly what it serves, as `grpc export` writes it. It is off by default,
as it tells the API to anyone who can call the server: a development
build turns it on, `APP_GRPC_DEFAULT_IS_REFLECTION=on`.

A server is created in its hook `_create_server()` and prepared in
`_prepare_server()`: its services added, its port bound, the reflection
added when it is on. Another addition goes there, after `super()`.

## Clients

A client is a component too: `grpc.clients.default` calls the default
server, the command `say` above for one, while the server runs:

```sh
uv run python -m app say
```

It calls `GRPC_DEFAULT_HOST` (`localhost`) on `GRPC_DEFAULT_PORT`, the
port the server listens on, and the services of the bindings it extends,
those of its server. Awaited, the client opens its channel and creates a
stub for each service, once: `client.echo`, typed by mypy-protobuf as the
async stub. The project closes the channel when it shuts down, before the
servers. A client of another server, of the project or written in
anything, extends `BaseGrpcClient` with its target (`_get_target()`) and
bindings of its own: a contract alone, `GrpcService(EchoStub)` with no
servicer, is enough for a client, and a server refuses it. A service the
server does not serve fails as `UNIMPLEMENTED`.

A failed call raises a `GrpcError`, the `AioRpcError` of grpcio as its
cause, at the `await` of a unary call or at the failing read of a stream;
the call stays a call of grpcio, with its metadata and code. The
interceptors of a client come from `_iter_interceptors()` too, the
outermost first; the default client yields `ClientGrpcErrorsInterceptor`.
grpcio takes an interceptor of several kinds of RPCs for the first of
them only, so a client splits one into a part for each.

## Export

Client SDKs, in any language, are generated from the services a server
serves: `grpc export` writes them to a `FileDescriptorSet`, complete with
the files they import, as `protoc --include_imports` writes one. A file
keeps only the services the servers serve, and every message it declares.
`--server default` chooses a server of `grpc.servers`, repeated for more;
every server by default:

```sh
uv run python -m app grpc export --server default --output demo.binpb
```

`protoc`, or buf, generates an SDK from the export, without the `.proto`
files:

```sh
mkdir sdk
uv run python -m grpc_tools.protoc --descriptor_set_in=demo.binpb --python_out=sdk --grpc_python_out=sdk app/proto/demo.proto
```

## Errors

The RPCs raise the exceptions of the business logic and see no protobuf. A
policy in `grpc.errors` tells how the server answers an exception of its
class, and of its subclasses: the status of the call, with a code, a
message and an `ErrorInfo` of a domain, a reason and metadata, as
[AIP-193](https://google.aip.dev/193) describes, and more
[details](https://github.com/googleapis/googleapis/blob/master/google/rpc/error_details.proto)
if it gives them; and how the server logs it. A client raises the status
as a `GrpcError`. A static policy declares its status in constants:

```python
import grpc
from ingot_grpcio.grpc.errors import BaseStaticGrpcErrorPolicy, GrpcErrors


class InsufficientFundsPolicy(BaseStaticGrpcErrorPolicy):
    EXCEPTION = InsufficientFunds
    CODE = grpc.StatusCode.FAILED_PRECONDITION
    DOMAIN = "shop.example.com"
    REASON = "INSUFFICIENT_FUNDS"

    @t.override
    def _get_metadata(self, error):
        return {"account": error.account}


class AppGrpcErrors(GrpcErrors):
    insufficient_funds = Slot(InsufficientFundsPolicy)
```

`AppGrpc` declares `errors = Slot(AppGrpcErrors)`. An exception takes the
policy of its class or of its nearest base class with one. The server logs
it at the `LOG_LEVEL` of the policy, `logging.INFO` by default, for an
answer of the API, or `logging.WARNING` and up; `LOG_EXC_INFO = True` adds
the traceback. Every other exception is logged at `ERROR` with its
traceback and reaches the client as `INTERNAL`, "internal error". Only
when `GRPC_DEFAULT_IS_SEND_DEBUG_INFO` is on, for development, the server
adds the text and traceback of an exception to its status in a
`DebugInfo`; a policy cannot. A policy of its own, on
`BaseGrpcErrorPolicy`, may choose the status by the exception.

A client catches the `GrpcError` of a failed call: the code, the message,
the domain, reason and metadata of the `ErrorInfo`, and `find_detail()`
for the rest. The classes of the exceptions stay on the server:

```python
try:
    await shop.Pay(request)
except GrpcError as error:
    if error.reason != "INSUFFICIENT_FUNDS":
        raise
    account = error.metadata["account"]
```

Two handlers apply it all: `ServerGrpcErrorHandler` the policies on a
server, `ClientGrpcErrorHandler` the decoding of a failed call on a
client, which logs it at `DEBUG`. A subclass in
`server_handler = Slot(...)` or `client_handler = Slot(...)` changes how,
its logging for one (`_log()`).

**Status:** pre-alpha: the servers, the clients, the errors and the
export of the services.

## Development

Requires [uv](https://docs.astral.sh/uv/) and `make`; uv fetches the
interpreters it needs.

```sh
make                 # the target list
make check           # everything CI runs: lint, test, coverage, wheel-test, cl-check
make format          # black
make all             # build the sdist and the wheel into dist/
```

- Every change users should know about adds a news fragment to `changelog.d/`
  (see [its README](https://github.com/ak-ingots/ingot-grpcio/blob/main/changelog.d/README.md)).
- A release is a pull request setting the version (`uv version X.Y.Z`) and
  collating the changelog (`make cl-build VERSION=X.Y.Z`), then the tag
  `vX.Y.Z` on `main`: the `release` workflow publishes the tested build to
  TestPyPI, then to PyPI. Run by hand, it rehearses on TestPyPI only.

## License

[Apache 2.0](https://github.com/ak-ingots/ingot-grpcio/blob/main/LICENSE).
