Skip to content

0.5.1

Choose a tag to compare

@zystem zystem released this 15 Nov 22:42
· 32 commits to main since this release
v0.5.1
3b8fa66

Added

  • Examples: examples/hello.nim (a server and a client in one process, no generated code), examples/greeter/ (a service from hello.proto through 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 into deps/nghttp2 of the clone, without root. Builds inside the repository find it there, or where NGHTTP2_PREFIX points; -d:nghttp2Prefix on the command line still wins. A program that uses the installed library is not affected.
  • tests/texamples.nim: builds and runs every nim c -r examples/... shown in README.md and examples/README.md and compares the output with the document; where protoc is installed it also checks that hello_pb.nim is 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 with nimgrpc.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): a bytes or string field 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 by tests/tdocs.nim in 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 (maxConnections and maxConnectionsPerIp exist since 0.2.0 and 0.4.0); it and SECURITY.md called the version 0.0.x.
  • README: the health snippet let health = newHealth() does not compile beside import nimgrpc/health (the name is the module's); it is let h = newHealth().

Upgrade notes: docs/upgrading.md (section 0.5.1).