Skip to content

0.3.0

Choose a tag to compare

@zystem zystem released this 09 Nov 00:51
· 73 commits to main since this release
v0.3.0
4fbdb15

Security

  • nghttp2 1.61.0 or later is required (was 1.57.0), which limits the CONTINUATION flood (CVE-2024-28182); the build fails with an #error against an older header. The limits that nghttp2 applies by default to CONTINUATION frames (8 after a HEADERS frame) and to RST_STREAM (a burst of 1000, then 33 a second: Rapid Reset, CVE-2023-44487) are now set by the library itself, and tests/th2session.nim feeds a server the frames of a flood.

Added

  • Happy Eyeballs (RFC 8305) in dial, blocking and chronos: the addresses of a name are tried in the order of the resolver's first family, then the families alternating, and when an attempt has not answered within 250 ms (or has failed) the next address is tried alongside it; the first to connect wins. A dead IPv6 route no longer costs a whole connectTimeoutMs before IPv4 is tried. Tests: tests/teyeballs.nim.
  • unaryCall (blocking and chronos) sends a call again, up to twice within its deadline (20 ms, then 40 ms apart), when the server refused it without starting on it: REFUSED_STREAM, which is also what nghttp2 reports for a stream a GOAWAY left unprocessed (a draining server, a connection rotated by maxConnectionAgeMs, the first burst before SETTINGS). The error of the last attempt has the new GrpcError.unprocessed set. Calls that may have run are never repeated, and streaming calls are not retried (newCall already tries a fresh connection once). Tests: tests/tretry.nim.
  • nimgrpc/reflection: server reflection (grpc.reflection.v1 and v1alpha) for both servers, so that grpcurl and grpc_cli can list the services of a server (always) and describe them (with their descriptors): newReflection(), addFileDescriptor, srv.register(refl). protoc-gen-nim writes the serialized FileDescriptorProto (without the source info protoc adds) into a module when it runs with --nim_opt=descriptor, as the constant fileDescriptorProto; the well-known types are built in (tools/gen_wkt_descriptors.py). file_by_filename, file_containing_symbol (messages, nested types, enums and their values, fields, services, methods) answer with the file and the imports the reflection holds; extensions are not supported. Servers gain serviceNames. Checked against grpc-go's own reflection client (tests/interop/reflection_interop.sh: it builds the descriptors it gets). Tests: tests/treflection.nim.
  • nimgrpc/healthclient: the asking side of the health service, on blocking and chronos channels: checkHealth (NOT_FOUND is hsServiceUnknown), isServing, waitServing and watchHealth / next / close. Test: tests/thealthclient.nim. The health service is checked against grpc-go's own client (tests/interop/health_interop.sh: Check, NOT_FOUND, List, Watch; all pass with grpc-go 1.84.0).
  • nimgrpc/health: the gRPC health checking service (grpc.health.v1.Health: Check, Watch, List) for both servers, which is what the native gRPC probe of Kubernetes, Envoy and grpc_health_probe call. newHealth(), srv.register(health), health.setStatus(service, hsNotServing), health.shutdown() before stop. Health is a handle to memory shared by all threads (copy it, hand it to threads, close frees it). Message bytes checked against protoc and the official health.proto. Test: tests/thealth.nim.
  • Rotation of server connections: Limits.maxConnectionAgeMs (age, give or take 10%) and Limits.maxConnectionIdleMs (no call for that long), both off by default, drain a connection: an advisory GOAWAY, the final one a moment later, the calls in progress finish, then the connection closes; Limits.maxConnectionAgeGraceMs (30 s) is how long they get. Behind a load balancer this spreads long-lived clients over new instances and makes them resolve names again (connections are balanced, not calls, in Kubernetes); clients of this library dial a new connection for the next call on their own. Blocking and chronos servers. Tests: tests/tconnage.nim, tests/tconnageasync.nim.
  • TCP keepalive and a limit for the handshake. Every connection, client and server, blocking and chronos, gets the system's TCP keepalive (Keepalive.tcpSecs, 15 seconds by default, 0 turns it off): a peer that has vanished is found and a NAT or load balancer does not forget a quiet connection. A server closes a connection whose peer has not completed the TLS handshake and sent its preface and first SETTINGS within Limits.handshakeTimeoutMs (120 seconds by default, 0 for no limit); until now such a connection, which holds two threads on the blocking server, stayed until the peer left. Test: tests/thandshake.nim (it reads the keepalive timers of the sockets from /proc/net/tcp). See docs/threat-model.md.
  • IPv6. A server listens on an IPv6 address (address = "::1"), or on both families (address = "::", dual-stack); the blocking dial takes IPv6 literals ("::1", "[::1]") and tries every address a name resolves to, IPv6 ones included, in the resolver's order, each with connectTimeoutMs. The :authority of an IPv6 host is bracketed. Until now the sockets were IPv4 only: a server could not bind ::1 and a host with only an AAAA record could not be reached. The chronos adapter already resolved both families and now has tests. Test: tests/tipv6.nim (skipped without an IPv6 loopback).
  • shutdown(GrpcChannel): closes every connection of the channel and frees nothing. Calls in progress, on any thread, fail at once, and new calls are refused. A program whose threads wait in calls can stop them with it, join them, and only then close the channel. Safe from any thread and more than once.
  • nimble coverage / tools/coverage.sh: statement coverage of src/nimgrpc from gcov (the Nim compiler's #line directives make it report .nim lines); 88.8% now, CI fails under 80% (job tests (coverage, Nim 2.2.12)). See docs/building.md.
  • The builds of this repository honour CC, CFLAGS and LDFLAGS from the environment (added to the flags in use); see docs/building.md, which also says how debug information, repeatable builds and installation are handled.

Fixed

  • Deadlines and timed waits of the blocking adapter counted on CLOCK_REALTIME, so a step of the system clock (NTP, a resumed virtual machine) shortened or stretched a timeout. They count on CLOCK_MONOTONIC now (Linux; other systems keep the wall clock). Test: tests/tblocking.nim, which fails with the old pairing of clocks.
  • close(GrpcChannel) from one thread while a call of another thread was waiting in recv freed the connection under that call: the call that then failed touched freed memory (found with AddressSanitizer in a program that closed its channel to end its reader thread; the corrupted heap ended in a thread spinning for ever in the allocator). close now waits (up to ten seconds) for the calls that are inside a procedure of the library on another thread to leave it, and does not free the channel if one does not. A call that has not entered the library yet cannot be waited for: do not start calls on a channel that is being closed. Test: tests/tchannelclose.nim.

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