pygrpc-native 0.2.0__tar.gz → 0.3.0__tar.gz

pygrpc_native-0.3.0/CHANGELOG.md

@@ -0,0 +1,62 @@
+# Changelog
+
+All notable changes are listed here. The project follows
+[semantic versioning](https://semver.org); see
+[Compatibility](README.md#compatibility) for what that covers.
+
+## 0.3.0 (2026-10-26)
+
+Everything here is an addition, so code written for 0.1 and 0.2 keeps working.
+
+### Added
+
+- `NativeGrpcFront(metrics=True)` and `metrics()`: call counts and latencies
+  per method and status, recorded in Rust without the GIL. The keys
+  `metrics()` returns are covered by the compatibility promise. (#29, #31)
+
+### Changed
+
+- The low-level API reference moved from the README to
+  [docs/low-level-api.md](docs/low-level-api.md). (#31)
+
+## 0.2.0 (2026-10-25)
+
+Everything here is an addition, so code written for 0.1 keeps working.
+
+### Added
+
+- `pygrpc_native.server()` and `pygrpc_native.aio.server()` take the same
+  arguments as `grpc.server()` and `grpc.aio.server()` and serve grpcio-tools
+  generated servicers unchanged. Status codes, metadata, deadlines and
+  cancellation behave as in grpcio, and the aio server runs on uvloop too.
+  (#17, #18, #20)
+- Methods the front doesn't serve itself, such as client-streaming and
+  bidirectional methods or server reflection, go to a grpcio server behind it.
+  (#19)
+- `NativeGrpcFront` can require a bearer token (`bearer_token_sha256`,
+  `unauthenticated_message`). Calls without one are rejected in Rust before
+  they reach Python. (#23)
+- `call_details` and `recv_batch_details()` report each call's request
+  metadata, peer and deadline. (#10)
+- `add_methods()` registers methods after the front is bound. (#11)
+- `stream_try_send()` for callers that can't block, such as an event loop.
+  (#12)
+- `respond()`, `fail()` and `stream_end()` take response metadata, and `fail()`
+  can send `grpc-status-details-bin`. (#13)
+- `delay_stream_headers` and `stream_send_initial_metadata()` hold a stream's
+  headers back until its first message. (#14)
+- With `call_details`, a cancelled unary call or one that misses its deadline
+  is reported as an `EVENT_CANCEL`. (#16)
+
+### Changed
+
+- The extension module moved to `pygrpc_native._native`, so the
+  `pygrpc_native.pygrpc_native` attribute is gone. Import names from
+  `pygrpc_native` as before. (#15)
+
+## 0.1.0 (2026-10-24)
+
+First release: `NativeGrpcFront`, a gRPC server whose HTTP/2 and gRPC work
+runs in Rust, outside the GIL. Unary and server-streaming methods, gzip
+requests, deadlines and batched calls to Python. abi3 wheels for CPython 3.10
+and later on Linux (x86_64, aarch64) and macOS (arm64, x86_64).

{pygrpc_native-0.2.0 → pygrpc_native-0.3.0}/CONTRIBUTING.md

@@ -59,20 +59,22 @@ commit without it.
 ## What a PR needs to merge
 
 The DCO, lint, rust and python checks have to pass, and a PR needs one
-approving review with every review thread resolved. `main` keeps a linear
-history: PRs are squash-merged with the PR title as the commit title, and
-force pushes and branch deletion are blocked. Issues and PRs with no activity
+approving review with every review thread resolved. While the project has a
+single maintainer, the maintainer's own PRs are merged once the checks pass.
+`main` keeps a linear history: PRs are squash-merged with the PR title as the
+commit title, and force pushes and branch deletion are blocked. Issues and PRs with no activity
 for 60 days are marked stale and closed 30 days later.
 
 ## Releases
 
 Releases follow semantic versioning. Existing users call the low-level API
 directly, so `tests/test_api.py` pins its names, signatures and event tuples;
-change it only together with a breaking release.
+change it only together with a new major version.
 
 Before a release:
 
-1. Bump the version in `Cargo.toml`.
+1. Bump the version in `Cargo.toml` and move the changes into a new section
+   of `CHANGELOG.md`.
 2. Build the wheel and run the tests of known downstream projects against it.
 3. Push a `vX.Y.Z` tag. The release workflow builds the wheels and publishes
    them to PyPI.

{pygrpc_native-0.2.0 → pygrpc_native-0.3.0}/Cargo.lock

@@ -392,7 +392,7 @@ dependencies = [
 
 [[package]]
 name = "pygrpc_native"
-version = "0.2.0"
+version = "0.3.0"
 dependencies = [
  "bytes",
  "crossbeam-channel",

{pygrpc_native-0.2.0 → pygrpc_native-0.3.0}/Cargo.toml

@@ -2,7 +2,7 @@
 
 [package]
 name = "pygrpc_native"
-version = "0.2.0"
+version = "0.3.0"
 edition = "2021"
 license = "Apache-2.0"
 description = "A gRPC server in Rust that hands calls to Python handlers in batches"

pygrpc_native-0.3.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: pygrpc-native
+Version: 0.3.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+License-File: LICENSE
+Summary: A gRPC server in Rust that hands calls to Python handlers in batches
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+Project-URL: Repository, https://github.com/theminjunchoi/pygrpc-native
+
+# pygrpc-native
+
+A gRPC server for Python whose HTTP/2 and gRPC work runs in Rust, outside the
+GIL. Your handlers stay in Python.
+
+grpcio runs its own Python code for every call, under the same GIL as your
+handlers. pygrpc-native does the framing, flow control, deadlines and
+cancellation on a tokio runtime instead, and gives Python each call as an
+event: an id, the method, the request bytes and who sent it. You decode the
+protobuf, run the handler and send back the encoded response. Clients and the
+wire format are the same as with grpcio.
+
+```
+grpc client ──HTTP/2──▶ tokio threads (no GIL)
+                          │ path → method id
+                          ▼
+                    event queue ──▶ recv_batch() in Python
+                          ◀── respond(call_id, bytes) from any thread
+```
+
+Calls reach Python in batches, so a burst takes one trip across the GIL
+rather than one per call.
+
+## Install
+
+```bash
+pip install pygrpc-native
+```
+
+Wheels are published for Linux (x86_64, aarch64) and macOS (arm64,
+x86_64) and work on CPython 3.10 and later. To build from a checkout:
+
+```bash
+pip install maturin
+maturin develop --release
+```
+
+## With grpcio servicers
+
+`pygrpc_native.server()` takes the same arguments as `grpc.server()` and
+serves servicers from grpcio-tools generated code (1.62 or later) unchanged:
+
+```python
+from concurrent import futures
+import pygrpc_native
+
+server = pygrpc_native.server(futures.ThreadPoolExecutor(16))
+greeter_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
+server.add_insecure_port("[::]:50051")
+server.start()
+server.wait_for_termination()
+```
+
+Status codes, error messages, metadata, deadlines, cancellation and
+`ServicerContext` behave as they do in grpcio.
+
+Unary and server-streaming methods are served natively on one insecure port.
+The rest, such as client-streaming and bidirectional methods, server
+reflection, or handlers added only with `add_generic_rpc_handlers`, go to a
+grpcio server on a Unix socket behind it. They work, but they aren't any
+faster, and `peer()` in them is the socket.
+
+Interceptors, `maximum_concurrent_rpcs`, TLS, response compression, and server
+options other than the message size limits and client ping settings raise an
+error rather than being ignored. There's one known difference: if a unary
+handler calls `send_initial_metadata()` and then fails, the metadata goes out
+with the status, so the client sees it as trailing metadata.
+
+`pygrpc_native.aio.server()` does the same for `grpc.aio.server()`:
+
+```python
+import pygrpc_native.aio
+
+server = pygrpc_native.aio.server()
+greeter_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
+server.add_insecure_port("[::]:50051")
+await server.start()
+await server.wait_for_termination()
+```
+
+Handlers run on the event loop that called `start()`, uvloop included.
+`abort()` raises `grpc.aio.AbortError`, and a handler whose client cancels or
+whose deadline passes gets `asyncio.CancelledError`, as in grpc.aio. Streams
+can yield from an async generator or call `context.write()`, and handlers
+that aren't coroutines run in `migration_thread_pool`. The fallback,
+the unsupported options and the unary metadata difference are the same as
+for the sync server.
+
+## Low-level API
+
+`NativeGrpcFront` is the layer under `server()`. Each call reaches Python as
+an event that you answer by id:
+
+```python
+import threading
+from pygrpc_native import EVENT_CALL, NativeGrpcFront
+
+front = NativeGrpcFront("0.0.0.0:50051", [("/echo.Echo/Say", False)])
+front.start()
+
+def serve():
+    while (events := front.recv_batch(64)) is not None:
+        for kind, call_id, method_id, payload, client_key in events:
+            if kind == EVENT_CALL:
+                front.respond(call_id, payload)
+
+threading.Thread(target=serve).start()
+```
+
+Streaming, call details, response metadata, bearer tokens and metrics are
+covered in [docs/low-level-api.md](https://github.com/theminjunchoi/pygrpc-native/blob/main/docs/low-level-api.md).
+
+## Compatibility
+
+pygrpc-native follows semantic versioning, and the low-level API stays
+compatible within 0.x as well. `tests/test_api.py` pins the 0.1 names,
+signatures and event tuples of `NativeGrpcFront`: they won't change or go
+away, and new parameters only come after the existing ones, with a default.
+The keys `metrics()` returns won't be renamed or removed within 0.x either,
+though new ones may be added. `server()` and `aio.server()` follow grpcio's
+API, and any difference from grpcio's behavior is a bug unless it is listed in
+this README. Changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+## Limitations
+
+- `NativeGrpcFront` serves unary and server-streaming methods only; other
+  kinds can go through the fallback server. `server()` and `aio.server()`
+  send them there on their own.
+- No TLS yet, and grpcio interceptors don't run on the listed methods. Bearer
+  tokens are the only authentication, and only on `NativeGrpcFront`.
+- Clients of a Unix socket server must set `grpc.default_authority`, since
+  the socket path grpc-core sends as `:authority` is not valid HTTP/2.
+- Like grpc-core, binding a Unix socket path replaces any socket file
+  already there.
+- Per connection: at most 1024 concurrent streams and 16 KiB of request
+  metadata. A connection that hasn't finished the HTTP/2 preface after 120 s
+  is dropped.
+
+## Benchmarks
+
+With an empty handler on an Apple M4 Pro, `pygrpc_native.server()` answers
+about 1.5x the calls per second of `grpc.server()` from one client thread and
+about 5x from 32. On a 40-vCPU Linux container the low-level API answered
+about 12x at 32 threads. See [benchmarks](https://github.com/theminjunchoi/pygrpc-native/blob/main/benchmarks/README.md) for the
+numbers and how they were measured.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Every commit needs a DCO sign-off
+(`git commit -s`).
+
+## License
+
+Apache-2.0
+

pygrpc_native-0.3.0/README.md

@@ -0,0 +1,154 @@
+# pygrpc-native
+
+A gRPC server for Python whose HTTP/2 and gRPC work runs in Rust, outside the
+GIL. Your handlers stay in Python.
+
+grpcio runs its own Python code for every call, under the same GIL as your
+handlers. pygrpc-native does the framing, flow control, deadlines and
+cancellation on a tokio runtime instead, and gives Python each call as an
+event: an id, the method, the request bytes and who sent it. You decode the
+protobuf, run the handler and send back the encoded response. Clients and the
+wire format are the same as with grpcio.
+
+```
+grpc client ──HTTP/2──▶ tokio threads (no GIL)
+                          │ path → method id
+                          ▼
+                    event queue ──▶ recv_batch() in Python
+                          ◀── respond(call_id, bytes) from any thread
+```
+
+Calls reach Python in batches, so a burst takes one trip across the GIL
+rather than one per call.
+
+## Install
+
+```bash
+pip install pygrpc-native
+```
+
+Wheels are published for Linux (x86_64, aarch64) and macOS (arm64,
+x86_64) and work on CPython 3.10 and later. To build from a checkout:
+
+```bash
+pip install maturin
+maturin develop --release
+```
+
+## With grpcio servicers
+
+`pygrpc_native.server()` takes the same arguments as `grpc.server()` and
+serves servicers from grpcio-tools generated code (1.62 or later) unchanged:
+
+```python
+from concurrent import futures
+import pygrpc_native
+
+server = pygrpc_native.server(futures.ThreadPoolExecutor(16))
+greeter_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
+server.add_insecure_port("[::]:50051")
+server.start()
+server.wait_for_termination()
+```
+
+Status codes, error messages, metadata, deadlines, cancellation and
+`ServicerContext` behave as they do in grpcio.
+
+Unary and server-streaming methods are served natively on one insecure port.
+The rest, such as client-streaming and bidirectional methods, server
+reflection, or handlers added only with `add_generic_rpc_handlers`, go to a
+grpcio server on a Unix socket behind it. They work, but they aren't any
+faster, and `peer()` in them is the socket.
+
+Interceptors, `maximum_concurrent_rpcs`, TLS, response compression, and server
+options other than the message size limits and client ping settings raise an
+error rather than being ignored. There's one known difference: if a unary
+handler calls `send_initial_metadata()` and then fails, the metadata goes out
+with the status, so the client sees it as trailing metadata.
+
+`pygrpc_native.aio.server()` does the same for `grpc.aio.server()`:
+
+```python
+import pygrpc_native.aio
+
+server = pygrpc_native.aio.server()
+greeter_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
+server.add_insecure_port("[::]:50051")
+await server.start()
+await server.wait_for_termination()
+```
+
+Handlers run on the event loop that called `start()`, uvloop included.
+`abort()` raises `grpc.aio.AbortError`, and a handler whose client cancels or
+whose deadline passes gets `asyncio.CancelledError`, as in grpc.aio. Streams
+can yield from an async generator or call `context.write()`, and handlers
+that aren't coroutines run in `migration_thread_pool`. The fallback,
+the unsupported options and the unary metadata difference are the same as
+for the sync server.
+
+## Low-level API
+
+`NativeGrpcFront` is the layer under `server()`. Each call reaches Python as
+an event that you answer by id:
+
+```python
+import threading
+from pygrpc_native import EVENT_CALL, NativeGrpcFront
+
+front = NativeGrpcFront("0.0.0.0:50051", [("/echo.Echo/Say", False)])
+front.start()
+
+def serve():
+    while (events := front.recv_batch(64)) is not None:
+        for kind, call_id, method_id, payload, client_key in events:
+            if kind == EVENT_CALL:
+                front.respond(call_id, payload)
+
+threading.Thread(target=serve).start()
+```
+
+Streaming, call details, response metadata, bearer tokens and metrics are
+covered in [docs/low-level-api.md](https://github.com/theminjunchoi/pygrpc-native/blob/main/docs/low-level-api.md).
+
+## Compatibility
+
+pygrpc-native follows semantic versioning, and the low-level API stays
+compatible within 0.x as well. `tests/test_api.py` pins the 0.1 names,
+signatures and event tuples of `NativeGrpcFront`: they won't change or go
+away, and new parameters only come after the existing ones, with a default.
+The keys `metrics()` returns won't be renamed or removed within 0.x either,
+though new ones may be added. `server()` and `aio.server()` follow grpcio's
+API, and any difference from grpcio's behavior is a bug unless it is listed in
+this README. Changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+## Limitations
+
+- `NativeGrpcFront` serves unary and server-streaming methods only; other
+  kinds can go through the fallback server. `server()` and `aio.server()`
+  send them there on their own.
+- No TLS yet, and grpcio interceptors don't run on the listed methods. Bearer
+  tokens are the only authentication, and only on `NativeGrpcFront`.
+- Clients of a Unix socket server must set `grpc.default_authority`, since
+  the socket path grpc-core sends as `:authority` is not valid HTTP/2.
+- Like grpc-core, binding a Unix socket path replaces any socket file
+  already there.
+- Per connection: at most 1024 concurrent streams and 16 KiB of request
+  metadata. A connection that hasn't finished the HTTP/2 preface after 120 s
+  is dropped.
+
+## Benchmarks
+
+With an empty handler on an Apple M4 Pro, `pygrpc_native.server()` answers
+about 1.5x the calls per second of `grpc.server()` from one client thread and
+about 5x from 32. On a 40-vCPU Linux container the low-level API answered
+about 12x at 32 threads. See [benchmarks](https://github.com/theminjunchoi/pygrpc-native/blob/main/benchmarks/README.md) for the
+numbers and how they were measured.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Every commit needs a DCO sign-off
+(`git commit -s`).
+
+## License
+
+Apache-2.0

{pygrpc_native-0.2.0 → pygrpc_native-0.3.0}/benchmarks/README.md

@@ -15,7 +15,8 @@ payload bytes. The server and the clients share the machine.
 
 Median of three runs, calls/s with the client CPU per call in brackets.
 
-Apple M4 Pro (14 cores), Python 3.12.13, grpcio 1.84.1, pygrpc-native main:
+Apple M4 Pro (14 cores), Python 3.12.13, grpcio 1.84.1, pygrpc-native 0.2.0
+(measured at #20):
 
 | server | 1x1 | 4x4 | 8x4 |
 |---|---|---|---|

{pygrpc_native-0.2.0 → pygrpc_native-0.3.0}/benchmarks/echo.py

@@ -7,7 +7,7 @@ pygrpc_native.server() and pygrpc_native.aio.server(), or native for the
 low-level API.
 
 DUR sets the seconds measured (default 5) and SIZE the payload bytes
-(default 64).
+(default 64). METRICS=1 turns on the native front's metrics.
 """
 
 import multiprocessing as mp
@@ -33,7 +33,9 @@ def serve(kind: str, port: int) -> None:
     if kind == "native":
         from pygrpc_native import EVENT_CALL, NativeGrpcFront
 
-        front = NativeGrpcFront(target, [(METHOD, False)])
+        # Only when asked, so the script still runs against older releases.
+        extra = {"metrics": True} if os.environ.get("METRICS") == "1" else {}
+        front = NativeGrpcFront(target, [(METHOD, False)], **extra)
         front.start()
         while (events := front.recv_batch(256)) is not None:
             for ev_kind, call_id, _, payload, _ in events:

pygrpc_native-0.2.0/README.md → pygrpc_native-0.3.0/docs/low-level-api.md

@@ -1,90 +1,11 @@
-# pygrpc-native
+# Low-level API
 
-A gRPC server for Python whose HTTP/2 and gRPC work runs in Rust, outside the
-GIL. Your handlers stay in Python.
+`NativeGrpcFront` is the layer under `pygrpc_native.server()`. Each call
+reaches Python as an event, and you answer it by id, so you choose how calls
+are batched, which threads run the handlers, and how calls from the same
+client are routed.
 
-grpcio runs its own Python code for every call, under the same GIL as your
-handlers. pygrpc-native does the framing, flow control, deadlines and
-cancellation on a tokio runtime instead, and gives Python each call as an
-event: an id, the method, the request bytes and who sent it. You decode the
-protobuf, run the handler and send back the encoded response. Clients and the
-wire format are the same as with grpcio.
-
-```
-grpc client ──HTTP/2──▶ tokio threads (no GIL)
-                          │ path → method id
-                          ▼
-                    event queue ──▶ recv_batch() in Python
-                          ◀── respond(call_id, bytes) from any thread
-```
-
-Calls reach Python in batches, so a burst takes one trip across the GIL
-rather than one per call.
-
-## Install
-
-```bash
-pip install pygrpc-native
-```
-
-Wheels are published for Linux (x86_64, aarch64) and macOS (arm64,
-x86_64) and work on CPython 3.10 and later. To build from a checkout:
-
-```bash
-pip install maturin
-maturin develop --release
-```
-
-## With grpcio servicers
-
-`pygrpc_native.server()` takes the same arguments as `grpc.server()` and
-serves servicers from grpcio-tools generated code (1.62 or later) unchanged:
-
-```python
-from concurrent import futures
-import pygrpc_native
-
-server = pygrpc_native.server(futures.ThreadPoolExecutor(16))
-greeter_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
-server.add_insecure_port("[::]:50051")
-server.start()
-server.wait_for_termination()
-```
-
-Status codes, error messages, metadata, deadlines, cancellation and
-`ServicerContext` behave as they do in grpcio. Unary and server-streaming
-methods are served natively on one insecure port. Everything else, such as
-client-streaming and bidirectional methods, server reflection or handlers
-added only with `add_generic_rpc_handlers`, is passed to a grpcio server on a
-Unix socket behind it, so it works but doesn't get faster, and `peer()` there
-is the socket. Interceptors, `maximum_concurrent_rpcs`, TLS, response
-compression and server options other than the message size limits and client
-ping settings raise an error instead of being ignored. One difference
-remains: a unary handler that calls `send_initial_metadata()` and then fails
-sends the metadata with the status instead of before it, so the client sees
-it as trailing metadata.
-
-`pygrpc_native.aio.server()` does the same for `grpc.aio.server()`:
-
-```python
-import pygrpc_native.aio
-
-server = pygrpc_native.aio.server()
-greeter_pb2_grpc.add_GreeterServicer_to_server(Greeter(), server)
-server.add_insecure_port("[::]:50051")
-await server.start()
-await server.wait_for_termination()
-```
-
-Handlers run on the event loop that called `start()`, uvloop included.
-`abort()` raises `grpc.aio.AbortError`, and a handler whose client cancels or
-whose deadline passes gets `asyncio.CancelledError`, as in grpc.aio. Streams
-can yield from an async generator or call `context.write()`, and handlers
-that aren't coroutines run in `migration_thread_pool`. The fallback,
-the unsupported options and the unary metadata difference are the same as
-for the sync server.
-
-## Low-level example
+## Example
 
 ```python
 import threading
@@ -115,9 +36,9 @@ In a real server `payload` is a serialized protobuf message: decode it with
 the generated class, run the handler (in a thread pool, if it blocks) and
 pass the serialized reply to `respond`.
 
-## API
+## Reference
 
-`NativeGrpcFront(target, methods, io_threads=2, client_key_metadata=None, call_details=False, delay_stream_headers=False, bearer_token_sha256=None, unauthenticated_message="Unauthenticated")`
+`NativeGrpcFront(target, methods, io_threads=2, client_key_metadata=None, call_details=False, delay_stream_headers=False, bearer_token_sha256=None, unauthenticated_message="Unauthenticated", metrics=False)`
 binds `host:port` (every address the host resolves to), `unix:path` or
 `unix:///path`. Port 0 picks a free port. `methods` lists
 `(path, server_streaming)` pairs, where a path is `/package.Service/Method`
@@ -139,6 +60,7 @@ before `start()`, so the port can be bound before the methods are known.
 | `stream_send_initial_metadata(call_id, metadata)` | send a held-back stream's headers now |
 | `stream_end(call_id, trailing_metadata=None)` | finish a stream with OK; a stream cut short by `close()` ends with UNAVAILABLE |
 | `stream_open(call_id)` | whether the client is still reading a stream |
+| `metrics()` | call counts and latencies per method and status; `None` without `metrics=True` |
 | `close()` | stop without waiting for calls in flight; their clients get UNAVAILABLE |
 
 `recv_batch` returns `(kind, call_id, method_id, payload, client_key)`
@@ -188,39 +110,39 @@ front = NativeGrpcFront(
 `grpc.Server` on a Unix socket and its methods are proxied there, with its
 interceptors.
 
-## Limitations
+## Metrics
 
-- Unary and server-streaming methods only. Other kinds can go through the
-  fallback server.
-- No TLS yet, and grpcio interceptors don't run on the listed methods. Bearer
-  tokens are the only authentication, and only on `NativeGrpcFront`.
-- Clients of a Unix socket server must set `grpc.default_authority`, since
-  the socket path grpc-core sends as `:authority` is not valid HTTP/2.
-- Like grpc-core, binding a Unix socket path replaces any socket file
-  already there.
-- Per connection: at most 1024 concurrent streams and 16 KiB of request
-  metadata. A connection that hasn't finished the HTTP/2 preface after 120 s
-  is dropped.
+With `metrics=True`, the front counts calls like gRFC A66's
+`grpc.server.call.started` and `grpc.server.call.duration`. It counts each
+call when it starts, and records its status and duration when the trailers go
+out. A call the client resets counts as CANCELLED, so one the client drops at
+its deadline can show up as CANCELLED or DEADLINE_EXCEEDED, depending on which
+side notices first. Calls to paths you didn't list count under `"other"`, so
+unknown paths can't add entries. Calls forwarded to the fallback aren't
+counted here; the fallback server counts them. Each tokio thread keeps its own
+counters, which costs about 70 ns per call, and `metrics()` adds them up when
+you call it:
 
-## Benchmarks
-
-With an empty handler, pygrpc-native answers about 1.6x the calls per second
-of grpcio's servers from one client thread, and 4x to 12x from 16 or 32. See
-[benchmarks](benchmarks/README.md).
-
-## Tests
-
-```bash
-cargo test --locked --no-default-features
-maturin develop --release
-pytest tests
+```python
+{
+    "start_time_unix_nano": 1761436800000000000,
+    "bounds": [0.0, 1e-05, ..., 100.0],  # A66's latency buckets, in seconds
+    "methods": {
+        "/echo.Echo/Say": {
+            "started": 1042,  # still running: started minus the counts
+            "status": {
+                0: {"count": 1040, "sum": 0.21, "min": 0.00009, "max": 0.0031,
+                    "buckets": [0, 0, 0, 12, ...]},  # one more than bounds
+            },
+        },
+    },
+}
 ```
 
-## Contributing
-
-See [CONTRIBUTING.md](CONTRIBUTING.md). Every commit needs a DCO sign-off
-(`git commit -s`).
-
-## License
-
-Apache-2.0
+Each entry in `buckets` is the number of calls in that bucket, not a running
+total. A call goes in the first bucket whose bound is at least its duration,
+and the last bucket holds anything slower than the last bound. OpenTelemetry
+histograms use the same layout, while Prometheus `le` buckets are cumulative,
+so add them up from the first one. Nothing resets: the totals count up from
+`start_time_unix_nano`. The status keys are gRPC status code numbers, with 0
+for OK. A66 labels statuses by name instead.

{pygrpc_native-0.2.0 → pygrpc_native-0.3.0}/python/pygrpc_native/_native.pyi

@@ -1,4 +1,5 @@
 from collections.abc import Sequence
+from typing import Any
 
 Metadata = Sequence[tuple[str, str | bytes]]
 
@@ -30,6 +31,7 @@ class NativeGrpcFront:
         delay_stream_headers: bool = False,
         bearer_token_sha256: Sequence[bytes] | None = None,
         unauthenticated_message: str = "Unauthenticated",
+        metrics: bool = False,
     ) -> None: ...
     @property
     def bound_port(self) -> int: ...
@@ -65,4 +67,5 @@ class NativeGrpcFront:
         self, call_id: int, trailing_metadata: Metadata | None = None
     ) -> None: ...
     def stream_open(self, call_id: int) -> bool: ...
+    def metrics(self) -> dict[str, Any] | None: ...
     def close(self) -> None: ...