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

{pygrpc_native-0.2.0 → pygrpc_native-0.4.0}/.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,5 @@
 blank_issues_enabled: true
 contact_links:
   - name: Report a security vulnerability
-    url: https://github.com/theminjunchoi/pygrpc-native/security/advisories/new
+    url: https://github.com/pygrpc/pygrpc-native/security/advisories/new
     about: Please report security issues privately, not as a public issue.

{pygrpc_native-0.2.0 → pygrpc_native-0.4.0}/.github/workflows/ci.yml

@@ -48,6 +48,8 @@ jobs:
       - name: Build and install
         run: |
           python -m pip install maturin pytest grpcio grpcio-tools grpcio-health-checking grpcio-reflection uvloop
+          # Interceptor libraries that downstream servers use, for tests/test_downstream.py.
+          python -m pip install grpc-interceptor opentelemetry-instrumentation-grpc
           maturin build --release --locked --out dist
           python -m pip install dist/*.whl
       - run: pytest -q tests

{pygrpc_native-0.2.0 → pygrpc_native-0.4.0}/.pre-commit-config.yaml

@@ -1,3 +1,4 @@
+exclude: ^vendor/
 repos:
 - repo: https://github.com/astral-sh/ruff-pre-commit
   rev: v0.11.7

pygrpc_native-0.4.0/CHANGELOG.md

@@ -0,0 +1,110 @@
+# 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.4.0 (2026-10-27)
+
+`server()` and `aio.server()` now take the interceptors and options grpcio
+servers commonly pass. Code written for 0.3 keeps working; the changes in
+behavior below bring the servers closer to grpcio.
+
+### Added
+
+- `server()` and `aio.server()` take grpcio server interceptors. (#39)
+- `server()` and `aio.server()` take the `grpc.keepalive_time_ms`,
+  `grpc.keepalive_timeout_ms` and `grpc.keepalive_permit_without_calls`
+  options, and `NativeGrpcFront` the matching `keepalive_*` arguments. (#47)
+- `server()` and `aio.server()` take `grpc.max_concurrent_streams`, and
+  `NativeGrpcFront` a matching `max_concurrent_streams` argument. (#51)
+- `server()` and `aio.server()` take `grpc.max_metadata_size` and
+  `grpc.absolute_max_metadata_size`, and `NativeGrpcFront` a matching
+  `max_metadata_size` argument. (#51)
+- `server()` and `aio.server()` ignore options they don't take, as grpcio
+  does, such as options only clients read, `grpc.max_message_length` and
+  `grpc.http2.max_frame_size`, and values that aren't integers. Only options
+  asking for something the server can't do, such as closing connections by
+  age or compressing responses, still raise an error. (#47, #51)
+- `metrics()` also reports each call's sent and received message bytes,
+  like gRFC A66's `grpc.server.call.sent_total_compressed_message_size` and
+  `rcvd_total_compressed_message_size`, under the new keys `size_bounds`,
+  `sent` and `rcvd`. (#37)
+
+### Changed
+
+- Like grpc-core, the keepalive ping now waits until a connection has
+  received nothing for the keepalive time, so busy connections aren't
+  pinged. (#47)
+
+### Fixed
+
+- Handlers that aren't coroutines get grpcio's sync context on
+  `aio.server()`, so calling `abort()` from them ends the call with that
+  status instead of INTERNAL. (#51)
+- `aio.server()` encodes responses as grpc.aio does: a handler's `None` goes
+  out as an empty message when there's no serializer, and a response that
+  fails to serialize ends the call with UNKNOWN, like any other error in the
+  handler, instead of INTERNAL. (#51)
+- `server()` and `aio.server()` ignore a message size limit that isn't an
+  integer, as grpcio does, instead of converting it. (#47)
+- grpcio clients can call a Unix socket server without setting
+  `grpc.default_authority`. This uses a patched copy of the `http` crate
+  until hyperium/http#836 is fixed upstream. (#35)
+
+## 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.4.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.4.0}/Cargo.lock

@@ -31,11 +31,11 @@ checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
 [[package]]
 name = "block-buffer"
-version = "0.10.4"
+version = "0.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+checksum = "d2f6c7dbe95a6ed67ad9f18e57daf93a2f034c524b99fd2b76d18fdfeb6660aa"
 dependencies = [
- "generic-array",
+ "hybrid-array",
 ]
 
 [[package]]
@@ -50,11 +50,17 @@ version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"
 
+[[package]]
+name = "const-oid"
+version = "0.10.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c"
+
 [[package]]
 name = "cpufeatures"
-version = "0.2.17"
+version = "0.3.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566"
 dependencies = [
  "libc",
 ]
@@ -85,21 +91,21 @@ checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
 
 [[package]]
 name = "crypto-common"
-version = "0.1.7"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453"
 dependencies = [
- "generic-array",
- "typenum",
+ "hybrid-array",
 ]
 
 [[package]]
 name = "digest"
-version = "0.10.7"
+version = "0.11.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2"
 dependencies = [
  "block-buffer",
+ "const-oid",
  "crypto-common",
 ]
 
@@ -165,16 +171,6 @@ dependencies = [
  "slab",
 ]
 
-[[package]]
-name = "generic-array"
-version = "0.14.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
-dependencies = [
- "typenum",
- "version_check",
-]
-
 [[package]]
 name = "h2"
 version = "0.4.20"
@@ -209,8 +205,6 @@ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
 [[package]]
 name = "http"
 version = "1.5.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0"
 dependencies = [
  "bytes",
  "itoa",
@@ -251,6 +245,15 @@ version = "1.0.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
 
+[[package]]
+name = "hybrid-array"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27f864f10dfb56725ce5ce5472bc52252c8f93a4ab86327122cebf62c5f59a17"
+dependencies = [
+ "typenum",
+]
+
 [[package]]
 name = "hyper"
 version = "1.12.0"
@@ -392,7 +395,7 @@ dependencies = [
 
 [[package]]
 name = "pygrpc_native"
-version = "0.2.0"
+version = "0.4.0"
 dependencies = [
  "bytes",
  "crossbeam-channel",
@@ -496,9 +499,9 @@ checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"
 
 [[package]]
 name = "sha2"
-version = "0.10.9"
+version = "0.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+checksum = "47d7069beb7d6ac7b9acd1039986e73443f24234f41074da099d6f994ac9ad19"
 dependencies = [
  "cfg-if",
  "cpufeatures",
@@ -729,12 +732,6 @@ version = "1.0.27"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
 
-[[package]]
-name = "version_check"
-version = "0.9.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
-
 [[package]]
 name = "want"
 version = "0.3.2"

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

@@ -2,11 +2,11 @@
 
 [package]
 name = "pygrpc_native"
-version = "0.2.0"
+version = "0.4.0"
 edition = "2021"
 license = "Apache-2.0"
 description = "A gRPC server in Rust that hands calls to Python handlers in batches"
-repository = "https://github.com/theminjunchoi/pygrpc-native"
+repository = "https://github.com/pygrpc/pygrpc-native"
 # tonic 0.14 needs rustc 1.88.
 rust-version = "1.88"
 readme = "README.md"
@@ -32,7 +32,7 @@ hyper-util = { version = "0.1", features = ["tokio"] }
 log = "0.4"
 pyo3 = { version = "0.29", features = ["abi3-py310"] }
 pyo3-log = "0.13"
-sha2 = "0.10"
+sha2 = "0.11"
 subtle = "2.6"
 tokio = { version = "1", features = ["rt-multi-thread", "net", "sync", "time", "macros"] }
 tonic = { version = "0.14", default-features = false, features = ["server", "gzip"] }
@@ -41,3 +41,9 @@ tonic = { version = "0.14", default-features = false, features = ["server", "gzi
 [profile.release]
 lto = "thin"
 codegen-units = 1
+
+# grpc-core sends a Unix socket path, percent-encoded, as :authority, which
+# http 1.5 rejects (hyperium/http#836). The copy allows valid escapes in the
+# host. Drop it once upstream does.
+[patch.crates-io]
+http = { path = "vendor/http" }

pygrpc_native-0.4.0/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: pygrpc-native
+Version: 0.4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Rust
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+License-File: LICENSE
+Summary: A drop-in grpcio server whose HTTP/2 and gRPC work runs in Rust, outside the GIL
+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/pygrpc/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.
+
+When a Python gRPC server runs out of CPU, the usual fixes are running more
+server processes or rewriting the servicers in another language. pygrpc-native
+instead moves the gRPC work itself (framing, flow control, deadlines and
+cancellation) onto a tokio runtime outside the GIL, and leaves your servicers,
+interceptors and generated code alone, so Python spends its time on your code.
+`pygrpc_native.server()` and `pygrpc_native.aio.server()` take the same
+arguments as grpcio's servers, so switching is usually a one-line change, and
+nothing changes for clients.
+
+Underneath, each call reaches Python as an event: an id, the method, the
+request bytes and who sent it.
+
+```
+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.64 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`, as code
+generated by grpcio-tools before 1.64 does, 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 run as in grpcio, on the methods served here and on the fallback
+server. Of the server options, the message size limits, the keepalive
+settings (`grpc.keepalive_time_ms`, `grpc.keepalive_timeout_ms` and
+`grpc.keepalive_permit_without_calls`), `grpc.max_concurrent_streams` and the
+metadata size limits (`grpc.max_metadata_size` and
+`grpc.absolute_max_metadata_size`) work as in grpcio. Options that ask for
+something this server can't do raise an error: closing connections by age or
+idleness (`grpc.max_connection_age_ms`, `grpc.max_connection_age_grace_ms`,
+`grpc.max_connection_idle_ms`), `grpc.max_allowed_incoming_connections`,
+response compression and `grpc.so_reuseport`, as do `maximum_concurrent_rpcs`
+and TLS. Any other option is ignored, as grpcio ignores the many that only
+clients read. That covers the limits on client pings, which are accepted but
+not enforced, and `grpc.http2.max_frame_size`, which grpc-core's flow control
+overrides anyway. Values that aren't integers are ignored too, as in grpcio.
+
+There are two known differences. 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. And a connection whose
+client doesn't answer a keepalive ping is closed after
+`grpc.keepalive_timeout_ms`, as gRPC's keepalive documentation describes,
+while grpcio waits for `grpc.http2.ping_timeout_ms`, a minute by default.
+
+`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` with grpcio's sync
+context, where `abort()` returns instead of raising. The fallback,
+the unsupported options and the known differences 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/pygrpc/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. `NativeGrpcFront` checks bearer tokens itself; `server()` and
+  `aio.server()` run grpcio interceptors instead.
+- Like grpc-core, binding a Unix socket path replaces any socket file
+  already there.
+- The server never sets `SO_REUSEPORT`, so binding a port another server is
+  using fails, where grpcio's default lets both bind it. `grpc.so_reuseport`
+  set to 0 is accepted; other integers raise an error.
+- Per connection: at most 1024 concurrent streams unless
+  `grpc.max_concurrent_streams` says otherwise. A connection that hasn't
+  finished the HTTP/2 preface after 120 s is dropped.
+- A call with more request metadata than the limit (16 KiB unless set) is
+  refused. grpcio also refuses some calls at random between
+  `grpc.max_metadata_size` and that limit; this server doesn't.
+
+## 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/pygrpc/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
+