[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"pDQXj0T5sa":3},"# lean-grpc\n\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Lean](https://img.shields.io/badge/Lean-4.32-purple.svg)](lean-toolchain)\n[![Docs](https://img.shields.io/badge/docs-rileybetts.ai-0B3D2E.svg)](https://rileybetts.ai/oss/lean-grpc)\n\nGeneral-purpose **Lean 4 gRPC library**: HPACK + HTTP/2 + gRPC framing on `Std.Async.TCP`.\n\nStandalone Lake package (**1.1.0**). Consumers depend via git tag or, after indexing, [Reservoir](https://reservoir.lean-lang.org/).\n\n**Docs:** [rileybetts.ai/oss/lean-grpc](https://rileybetts.ai/oss/lean-grpc) (curated) · [docs/](docs/README.md) (full in-repo index)\n\n**Public libraries:** `Bytes`, `Hpack`, `H2`, `Proto`, `Grpc` (umbrella `LeanGrpc`). Tests, examples, and the compile-time `Proofs` library are not consumer API.\n\n## Install / depend\n\n**System deps:** OpenSSL (`libssl-dev` / Homebrew `openssl` + `pkg-config`). If headers are missing: `./scripts/fetch-openssl-headers.sh`. On macOS, set `LIBRARY_PATH` for Homebrew OpenSSL (see [docs/packaging.md](docs/packaging.md)).\n\nIn your `lakefile.lean`:\n\n```lean\nrequire «lean-grpc» from git\n  \"https://github.com/RileyBetts/lean-grpc.git\" @ \"v1.1.0\"\n```\n\nThen `import Grpc`. After Reservoir lists the package you can use `require «lean-grpc»` without a git URL. Packaging details and the maintainer release checklist: [docs/packaging.md](docs/packaging.md).\n\n## Documentation\n\n| Doc | Description |\n|---|---|\n| [Hosted docs](https://rileybetts.ai/oss/lean-grpc) | Curated guides on rileybetts.ai |\n| [docs/README.md](docs/README.md) | Full documentation index (source of truth) |\n| [Getting started](docs/getting-started.md) | Typed unary helloworld, TLS, Lake dependency |\n| [Cookbooks](docs/cookbook-unary.md) | Unary · [streaming](docs/cookbook-streaming.md) · [interceptors / mTLS](docs/cookbook-interceptors.md) |\n| [Packaging](docs/packaging.md) | Lake/Reservoir layout, consumer contract, release checklist |\n| [Provenance](docs/provenance.md) | Independent protocol implementation; third-party interop protos |\n| [Architecture](docs/architecture.md) | Layering and data flow |\n| [API reference](docs/api-reference.md) | Module catalogue |\n| [Protocol mapping](docs/protocol-mapping.md) | gRPC-over-HTTP/2 mapping for this stack |\n| [Conformance](docs/conformance.md) | Scorecard, interop matrix, allowlists |\n| [Formal proofs](docs/proofs.md) | Compile-time theorems for pure codecs |\n| [TLS / Envoy](docs/tls-envoy.md) | In-process OpenSSL and sidecars |\n| [CHANGELOG](CHANGELOG.md) | Version history |\n| [ROADMAP](ROADMAP.md) | What v1.1.0 shipped vs open proof/hardening follow-ups |\n| [CONTRIBUTING](CONTRIBUTING.md) | Dev setup and PR expectations |\n| [SECURITY](SECURITY.md) | Vulnerability reporting (`security@rileybetts.ai`) |\n| [Code of Conduct](CODE_OF_CONDUCT.md) | Community standards |\n\n## Status\n\nNear **grpc-go / official interop** parity for general-purpose use. Core wire + Go/Python/Rust interop and stress/framing gates are CI-gated. Cloud-edge items (live Google ADC, ALTS) remain mock/allowlisted.\n\nRough estimates (see [conformance.md](docs/conformance.md) for detail):\n\n| Axis | Implemented | Tested |\n|---|---:|---:|\n| Official gRPC standard | ~95% | ~90% |\n| vs grpc-go surface | ~93% | ~88% |\n| vs Python (grpcio) peer | ~92% | ~82% |\n| vs Rust (tonic) peer | ~92% | ~82% |\n\n| Layer | Package | Notes |\n|---|---|---|\n| Bytes / slices | `Bytes` | Hot-path slice views, BE helpers, buffer pool |\n| HPACK | `Hpack` | Static + dynamic table, Huffman encode/decode |\n| HTTP/2 h2c | `H2` | Full h2spec hard gate; flow control; CONTINUATION; §8.1 |\n| Protobuf (minimal) | `Proto` | Enums, nested, repeated, Any/map/oneof helpers |\n| gRPC | `Grpc` | Duplex streams, deadlines, compression, dial/LB/retry, health/reflection/channelz |\n| TLS | `Grpc.Native.Tls` + `Grpc.Tls` | **In-process** OpenSSL ALPN `h2` (sidecar optional); mTLS |\n| ADC / xDS | `Grpc.Adc`, `Grpc.XdsAds` | SA/metadata Bearer; ADS LDS→EDS chain |\n| Codegen | `protoc-gen-lean4-grpc` | Text path + real `CodeGeneratorRequest` path |\n\n**Allowlist:** ALTS / GCE channel credentials (see `Grpc.Gcp`).\n\n## Build\n\n```bash\n./scripts/fetch-openssl-headers.sh   # if libssl-dev is unavailable\nlake build\nlake build Proofs                    # compile-time pure-codec theorems\nlake build bytesTests hpackTests h2Tests grpcTests trailersLoopback\n./.lake/build/bin/grpcTests\n./scripts/build_native.sh            # optional zlib_helper for peer gzip (+ tls_proxy)\n```\n\nFormal proofs of high-leverage pure codecs (status codes, BE ints, gRPC framing, varints, HPACK integers, …): [docs/proofs.md](docs/proofs.md).\n\n## Quick start\n\n```bash\n./scripts/gen-helloworld.sh   # typed stubs → Examples/Helloworld/Generated.lean\nlake build helloworldServer helloworldClient\n./.lake/build/bin/helloworldServer &\n./.lake/build/bin/helloworldClient 127.0.0.1 50051 World\n```\n\nFull walkthrough: [docs/getting-started.md](docs/getting-started.md). Cookbooks: [unary](docs/cookbook-unary.md), [streaming](docs/cookbook-streaming.md), [interceptors / mTLS](docs/cookbook-interceptors.md).\n\n## Interop\n\n```bash\n./scripts/run-go-to-lean.sh                 # Go client → Lean server\nGRPC_PORT=10001 ./scripts/interop-go-lean.sh\n./scripts/run-python-to-lean.sh             # Python client → Lean\nGRPC_PORT=10001 ./scripts/interop-lean-python.sh\n./scripts/run-rust-to-lean.sh               # Rust (tonic) client → Lean\nGRPC_PORT=10001 ./scripts/interop-lean-rust.sh\n./scripts/interop-compress-go-lean.sh       # gzip both directions (Go gzip server)\n./scripts/interop-tls-go-lean.sh            # in-process TLS Lean → Go\n./scripts/run-adc-smoke.sh                  # ADC against local mock\n./scripts/run-xds-ads-smoke.sh              # Fake ADS chain → unary\n./scripts/run-codegen-fixture.sh\n./scripts/run-soak.sh\n./scripts/h2spec.sh\n```\n\n## Helloworld / RouteGuide / soak\n\n```bash\nlake build helloworldServer helloworldClient benchSoak\n./.lake/build/bin/helloworldServer &\n./.lake/build/bin/helloworldClient 127.0.0.1 50051 World\n./.lake/build/bin/benchSoak 127.0.0.1 50051 30\n```\n\n## License\n\nSPDX **Apache-2.0** — see [LICENSE](LICENSE) (full terms) and [NOTICE](NOTICE) (copyright + third-party interop protos). Independent protocol implementation note: [docs/provenance.md](docs/provenance.md).\n",1786349532634]