Interface definitions for nyquest HTTP client backends.

This crate provides the interface that backends must implement to be compatible with the nyquest HTTP client facade. It defines the core types and traits that are used across all nyquest implementations.

Backend Registration

Backend implementations must register themselves using the register_backend function before they can be used by nyquest.

Features

• async: Enable async interface support
• blocking: Enable blocking interface support
• multipart: Enable multipart form support

Nyquest

A truly native HTTP client library for Rust.

Why Nyquest?

You should ask the other way around: why shipping an entire HTTP stack with your application when you know your users already have WinHTTP/NSURLSession/libcurl/whatever HTTP client library available on their system?

The nyquest-interface crate provides only an abstraction over the HTTP client operations. The actual functionality is implemented by Nyquest backends that talk to either platform APIs or third-party libraries. Even though Nyquest API interface has an async variant, it is not tied to any specific async runtime. Instead, the backends will as much as possible utilize the async mechanism or event loop provided by the system, or manage an event loop for the application. This way, end application developers can easily choose and switch among HTTP client implementations without thinking too much about the details. Library authors can also consume HTTP endpoints without worrying about which async runtime the end application uses.

By using platform native APIs, users will automatically benefit from system-managed security updates, functionality improvements, cache management, global proxy settings etc. that are tightly integrated with the operating system. [^1]

As an end application developer, consider Nyquest if you:

• want to behave like a good citizen on the user's system,
• want to honor the user's system settings for HTTP client, such as proxy,
• do not use an async runtime at all, or
• do not want to pull in the whole hyper or reqwest stack hence to reduce the binary size.

As a library author, consider Nyquest if you:

• want to provide a flexible way for users to choose their HTTP client implementation,
• do not want to assume the async runtime of the end application, or
• do not want to bring maintenance burden of depending on the whole hyper or reqwest stack to your users.

Meanwhile, you might not need Nyquest if you:

• want to minimize the overhead introduced by abstraction or interop with external libraries,
• want to keep every single byte of HTTP requests sent over the wire under your control,
• already have reqwest in your dependency tree, or
• are already maintaining bindings to various HTTP client libraries.

[^1]: Subject to the backend's capability.

On top of the nyquest-interface crate and backend crates, the nyquest crate provides a convenient, user-friendly API for Nyquest users, including library authors and end application developers.

Package Structure

• nyquest: The main crate that provides a user-friendly HTTP client API.
• nyquest-interface: The interface crate that defines the API for Nyquest backends and hosts the global default Nyquest backend.
• nyquest-preset: The umbralla crate of recommended Nyquest backends on various platforms.
• nyquest-backend-<backend>: The backend crate that implements the Nyquest interface for a specific HTTP client library or platform API. Currently, we have:
  • nyquest-backend-libcurl: libcurl
  • nyquest-backend-winrt: UWP/WinRT HttpClient
  • nyquest-backend-nsurlsession: NSURLSession
• nyquest-backend-tests: The test framework for Nyquest backends going through nyquest.

Roadmap

Nyquest is still at POC stage. We want to keep Nyquest itself as a greatest common divisor for all backends, therefore the API surface is subject to change along with the development of backends.

The following items are planned in MVP:

• Nyquest blocking API
• Nyquest async API
• Backend: WinRT HttpClient
  • Blocking
  • Async
• Backend: libcurl
  • Blocking
  • Async
• Backend: NSURLSession
• Client Options
• Streaming download
• Test framework for backends
• Presets
• Documentation

Future work may include:

• Backend: reqwest
• Cookie management
• Progress tracking
• Streaming upload
• Direct file upload/download support
• URL manipulation utilities
• Middleware infrastructure
• Telemetry
• Backend: Plugin FFI via libloading
• Backend: Mock
• Backend: WASM fetch
• Backend: WinHTTP
• Backend: libsoup3
• Backend: QNetworkAccessManager
• Explore alternative options on Android other than libcurl

License

Licensed under Apache License, Version 2.0 or MIT license, at your option.

Backend implementations and their adapter crates may have different licenses. Please refer to their respective READMEs for details.