v1.1.7

This release of libpaf adds support for Pathfinder protocol version 3, in addition to the existing version 2 support.

Pathfinder protocol version 3 moves the keepalive/heartbeat functionality from the transport protocol (e.g., TCP) into the Pathfinder application-layer protocol itself. See the v3 protocol specification for details.

When protocol version 3 is in used, libpaf uses a notion of a per-connection maximum idle time. When nothing has been heard from the server for about ~50% of the max idle time, libpaf will send a track query to the server. If the server fails to respond for the remaining half of the max idle time, the connection will be considered down, and libpaf will close it and reopen a new connection. A server will behave in a similar manner.

libpaf takes time-to-live (TTL) of client-owned services into account when computing the effective max idle time for a connection. Hence, it becomes important to configure an appropriate TTL. Low TTLs will cause a fair amount of keepalive signaling. The amount of network traffic is always lower in protocol v3 compared to protocol v2, but the cost of processing a single heartbeat is much higher in v3 than in v2.

Two new environment variables are added, PAF_IDLE_MIN and PAF_IDLE_MAX, which allow some user-level control over heartbeat behavior. See the API documentation for details.

The domain file format is extended with two new per-server configuration parameters, which allows control over which protocol versions are advertised as supported to the server. Using this mechanism, one may force libpaf to use a particular protocol version.

To allow for client protocol version observability and track latency monitoring, the "clients" Pathfinder protocol command is extended to provide more information on all connected clients in version 3.

libpaf behavior when a very large amount of services and/or subscriptions are issued from a single client is improved. The old design queued up a large amount of protocol-level request messages to the server. This approach may cause excessive transaction latencies (e.g., from a client-issued "request" to the client receiving an "accept" message from the server). In protocol v2, this is not a major issue, but with v3, very large transaction latencies (in the range of seconds) becomes an issue, since the heartbeat signaling is in-band (as opposed to the out-of-band TCP keepalive used previously). "Track" queries and replies must be processed in a timely manner, or the connection may be torn down by either side.

With this release, libpaf puts an upper bound to the number of concurrent, unacknowledged, protocol transaction. The limit is currently 32. This limit does not affect the maximum number of services and/or subscriptions, but rather only controls the details of the client<->server interaction. Another improvement is that libpaf puts an upper bound to the amount of messages are received and transmitted every paf_process() call, to avoid starving RX, TX or some non-libpaf task the thread should attend to.

lpafc is updated with support for the new "track" protocol-level command, as well as the extended version of the "stats" command. Just like libpaf, lpac supports both v2 and v3.

Some of the libpaf-internal processing related to TTL is likely to cause performance regressions in scenarios where a large number of services are published by the same client.

The library API (<paf.h>) contract is not affected by protocol version 3 support. However, for contexts linked over protocol v3 connections, an application failing to call paf_process() when the context's fd is active (in violation of the API) risks the connection being torn down, and any services orphaned.

The unchanged API/ABI is the reason this otherwise-substantial release is classified as a patch release.

Bugfixes in this release:

• Fixed bug where a server EOF could cause a libpaf server link to be stuck in operational state, when it should be restarted.
• Fixed bug where a PAF_RESCAN value of zero caused a library crash.

Documentation can be found at:
https://ericsson.github.io/libpaf/doc/v1.1.7/