Repository navigation
0.5.1
Added
- Examples:
examples/hello.nim(a server and a client in one process, no generated code),examples/greeter/(a service fromhello.protothrough generated code: a server with health and reflection, a client, and both on chronos), and examples/README.md, a tutorial with what every command prints. tools/build-nghttp2.sh: downloads nghttp2 1.68.1, checks its SHA-256 and builds it intodeps/nghttp2of the clone, without root. Builds inside the repository find it there, or whereNGHTTP2_PREFIXpoints;-d:nghttp2Prefixon the command line still wins. A program that uses the installed library is not affected.tests/texamples.nim: builds and runs everynim c -r examples/...shown inREADME.mdandexamples/README.mdand compares the output with the document; whereprotocis installed it also checks thathello_pb.nimis what the plugin generates.- docs/README.md: an index of the documents with the kind of each page.
- docs/troubleshooting.md: every message of the library with its meaning and what to do; docs/faq.md; docs/production.md, a checklist before a server faces real clients; docs/supported-versions.md.
tests/tdocs.nim: fails when a message the library can raise has no line in the troubleshooting page, makes 17 common failures happen (a closed port, TLS against plaintext, a wrong CA or name, a missing client certificate, a full server, a message over the limit and others) and compares their text with the page, compares the supported-versions page withnimgrpc.nimble, the CI workflow and the source, and checks that the index lists every page.
Changed
- README: starts with what the library is, when to use it and when not, a picture of the parts, a first run with its output, a table of ways to install, a glossary and the documents by purpose; the description of the API follows unchanged, the status went below it.
- Encoder (
nimgrpc/protobuf, used by generated code): abytesorstringfield of 64 KiB or more is copied once into a buffer of the size of the message. Before, the buffer was reallocated when the field went in and again when the length in front of it needed more than one byte, so a message with one 4 MiB field cost about 10 MiB while it was encoded. The wire form is the same and generated code does not have to be regenerated. This was the library's part of the pentest's finding 4 (responses a client asks for and never reads): 200 such calls asking for 4 MB responses held 2.53 GB before and 1.76 GB after (measured locally on 2026-11-15, blocking server, release build). What is left is the handler's own message and one encoded copy per waiting handler; docs/threat-model.md says how to bound it. Tests:tests/tcodec.nim(suite "large values").
Fixed
- Blocking server: a unary request much larger than
maxMessage(6 MB and more against the default 4 MiB) left the client waiting until its deadline, and without a deadline for ever. The server answered RESOURCE_EXHAUSTED when the limit was passed and read no more, so the window of the stream stayed shut and the client could not finish sending to see the answer. The server now resets such a stream with NO_ERROR once its response is complete, as the chronos server already did and as other gRPC servers do; the client gets RESOURCE_EXHAUSTED at once. Found bytests/tdocs.nimin CI. Tests:tests/thostile.nim. - Documents that said what the code does not do: docs/threat-model.md said a handler gets the peer's certificate (it gets the metadata only; mutual TLS admits a client, it does not name it); docs/security-requirements.md said there are no connection quotas (
maxConnectionsandmaxConnectionsPerIpexist since 0.2.0 and 0.4.0); it andSECURITY.mdcalled the version 0.0.x. - README: the health snippet
let health = newHealth()does not compile besideimport nimgrpc/health(the name is the module's); it islet h = newHealth().
Upgrade notes: docs/upgrading.md (section 0.5.1).