uSockets: Cross-Platform Non-Blocking TCP, TLS, and QUIC

uSockets as a non-blocking C networking layer

uSockets addresses the lower-level problem of moving network data through a non-blocking, thread-per-CPU foundation. The README describes it as the non-blocking, thread-per-CPU foundation used by µWebSockets. That makes it relevant to C applications that need event-driven sockets, TCP transport, TLS support, or a common programming interface across platforms and event-loop implementations. It is not positioned as an application server framework. Applications using it still need to define their own protocol handling, connection lifecycle, and higher-level behavior.

The library's central design choice is an opaque API. According to the README, the same programming interface is used across supported transports, event loops, and platforms. A caller can therefore keep application-level networking code consistent when moving between TCP and QUIC, provided that the selected transport and build configuration are available. The repository's examples include TCP, UDP, HTTP, HTTP/3, load testing, peer verification, and a Swift HTTP server example. Those files indicate several possible uses, but the README does not document a complete API reference for them.

How uSockets separates transport and event-loop choices

The build system makes the main architectural choice visible through compile-time options. The default minimal, TCP-only configuration is described as depending only on the operating system kernel. TLS and QUIC are optional. The Makefile also exposes event-loop and network-implementation choices through configuration variables including `WITH_IO_URING`, `WITH_LIBUV`, `WITH_ASIO`, and `WITH_GCD`. QUIC support is controlled by `WITH_QUIC`, while the README also lists `WITH_ASAN` among the possible configurations.

TLS has three documented branches. `WITH_BORINGSSL=1` links BoringSSL statically and adds the relevant include and library paths. `WITH_OPENSSL=1` enables OpenSSL 1.1 or later support. `WITH_WOLFSSL=1` enables WolfSSL 4.2.0 support and points the build at `/usr/local/include` and `/usr/local/lib`. Unless one of those branches is selected, the Makefile defines `LIBUS_NO_SSL`. This is a meaningful boundary: a TCP-only build and a TLS build do not have the same dependency surface.

The README calls QUIC and io_uring work in progress. That statement should be treated as a release-readiness constraint, not merely a missing feature in the repository description. An application can use the library for TCP without adopting either feature, but selecting those paths requires additional scrutiny.

Building the examples and choosing a first configuration

The documented starting point is the repository's examples target. The README gives this command:

make examples

This target is the documented way to get started and is appropriate for inspecting the repository's TCP, HTTP, and related examples. The repository contains `examples/tcp_server.c`, `examples/http_server.c`, `examples/http3_server.c`, and other C or Swift examples. The exact binaries produced by the target are not specified in the README, so the command should not be read as a promise that every experimental transport will build without the relevant dependencies.

For a TLS build using BoringSSL, the Makefile states that `make boringssl` must be called first. The documented TLS configuration is therefore:

make boringssl

The Makefile then uses `WITH_BORINGSSL=1` to add the BoringSSL headers and static libraries. The README does not give a complete command for building and running one particular example, nor does it document a runtime server address or port. That omission matters for a first use: the repository provides source examples, but the README does not provide enough verified instructions to state how a reader should connect to a specific example binary.

TCP, TLS, QUIC, and UDP example coverage

The examples directory gives a practical indication of the library's intended surface. `examples/tcp_server.c` and `examples/tcp_load_test.c` cover TCP-oriented server and load-test paths. `examples/http_server.c` shows HTTP-related use, while `examples/http3_client.c` and `examples/http3_server.c` correspond to the QUIC and HTTP/3 direction. `examples/udp_benchmark.c` addresses UDP benchmarking, and `examples/peer_verify_test.c` relates to peer verification.

This range does not mean uSockets itself implements every protocol represented by those examples. The repository description calls it a networking library with crypto support, while the names of the examples indicate higher-level programs built around that foundation. The README specifically names µWebSockets as a consumer, but it does not claim that every example is a supported public API tutorial.

For engineering evaluation, the example names are useful for scoping tests. A team interested in TCP can start with the TCP server and load test. A team evaluating TLS should inspect the peer verification example and confirm which SSL branch it expects. A team evaluating HTTP/3 or QUIC must account for the README's work-in-progress warning and the separate `lsquic` dependency mentioned in the lightweight-versus-featureful description.

Dependency trade-offs in uSockets configurations

The minimal configuration is attractive when dependency count matters. The README says that the minimal TCP-only configuration has no dependencies other than the operating system kernel and compiles to a tiny binary. The Makefile supports this path by defining `LIBUS_NO_SSL` when no SSL option is selected. This reduces the number of external components a deployment must acquire, but it also removes the TLS and crypto options available in the featureful configuration.

The full configuration depends on BoringSSL, lsquic, and potentially an event-loop library. BoringSSL is statically linked according to the Makefile, while OpenSSL and WolfSSL use their respective system or local library paths. These are not interchangeable deployment models. Static linking changes how the application is assembled and upgraded. Dynamic linking changes what must be installed alongside the application. The README does not discuss update procedures, ABI policy, or security support timelines for those dependencies.

The event-loop choices create another trade-off. `WITH_LIBUV=1` adds `-luv`, `WITH_ASIO=1` adds C++ and pthread linker flags, and `WITH_GCD=1` adds Apple's CoreFoundation framework. io_uring is described as a network implementation and event-loop option, but it is also marked as work in progress. A build choice should therefore be based on the target platform and the transport requirements, not only on the desire for a common API.

Operational limits and alternatives to uSockets

The clearest limitation is scope. uSockets is a C foundation library, not a documented high-level HTTP server, routing framework, or application deployment system. The README does not document rollback, connection migration behavior, observability interfaces, production configuration guidance, or a compatibility matrix beyond the broad statement that the same API is used across supported platforms and transports. Those omissions are important when evaluating operational adoption.

A real alternative is to use a platform-specific asynchronous networking stack directly. Such an approach can give an application direct control over its event loop and platform primitives without adding uSockets as a shared abstraction. The difference is portability: the alternative may require separate platform paths, while uSockets is designed to preserve one API across supported platforms, event loops, and transports. Another practical alternative is a higher-level framework built on conventional sockets, which can supply more application-level conventions but may not match uSockets' small C foundation and transport abstraction.

uSockets is therefore the wrong choice when the primary requirement is a documented, high-level server framework or when QUIC and io_uring must already be treated as complete production features. The README does not support that interpretation.

Maintenance signals and Apache-2.0 implications

The repository is not archived. Its last push was on 2026-10-08. The release list shows `v0.8.8` on 2024-02-07, preceded by `v0.8.7` on 2024-01-08 and `v0.8.6` on 2023-06-04. These facts show a recently pushed repository with a release history that includes multiple tagged versions, but the README does not document a release cadence or a detailed compatibility policy.

The project is licensed under Apache-2.0. The repository identifies the license but does not provide guidance about patent interpretation, notices, modifications, or distribution procedures. An engineer should read the repository `LICENSE` file before incorporating the library or its dependencies into a product.

Upgrade cost depends on configuration. A TCP-only application may have fewer dependency upgrades, while a BoringSSL, OpenSSL, WolfSSL, lsquic, or event-loop integration has additional components to track. The README does not document a supported upgrade path or compatibility matrix, so version selection should be checked against the example and source files used by the application.

Editorial conclusion

Adopt uSockets when an application in C needs a compact non-blocking networking layer with a consistent API across platforms and event-loop choices. Do not choose it as a high-level HTTP framework or assume that QUIC and io_uring are production-ready, because the README labels both as work in progress. Verify the required TLS or QUIC dependencies, the selected event-loop build, and the behavior of the relevant examples before integrating the library.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. uNetworking/uSockets on GitHub