DOCSEARCHbyAlgolia
Submit Docs

Nyquest HTTP Client

repository·main·Indexed 42 days ago

https://github.com/bdbai/nyquest

A platform-native HTTP client library for Rust (v0.4.0) that abstracts over system-provided HTTP stacks such as WinHTTP, NSURLSession, and libcurl. It reduces binary size and honors system-level settings like proxies and security updates. Nyquest provides a runtime-agnostic async API and supports multiple backends including nyquest-backend-curl, nyquest-backend-nsurlsession, nyquest-backend-winhttp, nyquest-backend-winrt, and nyquest-backend-reqwest.

Tokens
28.4K
Snippets
95
Records
138
Agent score
53%

What's inside Nyquest

  1. What is Nyquest?

    main

    Nyquest is a platform-native HTTP client library for Rust. Instead of shipping a full HTTP stack (like hyper or reqwest) with your application, Nyquest provides an abstraction layer (nyquest-interface) that allows you to use the HTTP client libraries already present on the user's operating system (e.g., WinHTTP, NSURLSession, or libcurl).

    Key Benefits

    • System Integration: Automatically honors system-managed security updates, proxy settings, cache management, and global configurations.
    • Reduced Binary Size: Avoids pulling in heavy dependencies like the full hyper stack.
    • Runtime Agnostic: The async API is not tied to a specific async runtime; backends utilize the system's event loop or manage their own.
    • Flexibility: Library authors can provide a flexible interface, allowing end-users to choose their preferred backend implementation.

  2. Use the NSURLSession backend for Nyquest

    main

    The nyquest-backend-nsurlsession crate provides an implementation of the NSURLSession backend for the nyquest library. This backend is specifically designed for Apple platforms, leveraging the native NSURLSession Foundation framework for network requests.

    It supports several execution modes and data handling patterns:

    • Blocking: Synchronous request execution.
    • Blocking Stream: Synchronous streaming of data.
    • Async: Asynchronous request execution using Swift/Rust async patterns.
    • Async Stream: Asynchronous streaming of data.
    • Multipart: Support for multipart/form-data requests.

  3. Use the WinRT backend for Nyquest

    main

    The nyquest-backend-winrt crate provides a UWP/WinRT implementation of the HttpClient for use with the nyquest framework. It allows nyquest to perform HTTP operations using the Windows Runtime HttpClient API.

    Supported features include:

    • blocking: Synchronous HTTP requests.
    • blocking-stream: Synchronous streaming.
    • async: Asynchronous HTTP requests.
    • async-stream: Asynchronous streaming.
    • multipart: Support for multipart/form-data requests.

  4. Use the WinHTTP backend for nyquest

    main

    The nyquest-backend-winhttp crate provides a WinHTTP implementation for the nyquest framework. It utilizes the Windows HTTP Services (WinHTTP) API, which is the recommended approach for performing HTTP requests within Windows services.

    Note: This backend is only compatible with Windows platforms.

  5. Platform support in nyquest-preset

    main

    The nyquest-preset crate automatically selects a backend based on your target platform using cfg gates:

    • Windows: Uses nyquest-backend-winrt.
    • Apple (macOS/iOS): Uses nyquest-backend-nsurlsession.
    • Other platforms: Uses nyquest-backend-curl.

  6. Understand the Nyquest package structure

    main

    Nyquest is organized into several crates to separate the interface, the user-facing API, and specific backend implementations:

    • nyquest: The primary crate providing a convenient, user-friendly HTTP client API for most users.
    • nyquest-interface: The core abstraction crate that defines the API for backends and manages the global default backend.
    • nyquest-preset: An umbrella crate containing recommended backends for various platforms.
    • nyquest-backend-<name>: Specific implementations for different HTTP clients:
      • nyquest-backend-libcurl: Uses libcurl.
      • nyquest-backend-winrt: Uses UWP/WinRT HttpClient.
      • nyquest-backend-nsurlsession: Uses NSURLSession (macOS/iOS).
      • nyquest-backend-reqwest: Uses reqwest (includes WASM support).
    • nyquest-backend-tests: The testing framework used for validating backends.

  7. Use nyquest-backend-reqwest as a backend

    main

    The nyquest-backend-reqwest crate provides a reqwest-based implementation of the nyquest HTTP client interface. It supports both async and blocking operations, and is compatible with WebAssembly (WASM) targets.

    When to use this backend

    • Dependency Alignment: When your application already includes reqwest in its dependency tree, using this backend avoids duplication.
    • Runtime Isolation: It helps manage reqwest's runtime constraints. Specifically, it can isolate the reqwest client from your application's async runtime (e.g., preventing panics when using reqwest's blocking variant inside a tokio runtime) and supports non-tokio async runtimes like async-std.

    Registration

    To use this backend, you must register it as the default backend for nyquest.

    // Register the reqwest backend as the default
nyquest_backend_reqwest::register();

// Now you can use nyquest with the reqwest backend
// (This example requires the nyquest crate to be in scope)
// let response = nyquest::r#async::get("https://httpbin.org/get").await?;

  8. Install and use the nyquest-backend-curl backend

    main

    The nyquest-backend-curl crate provides a libcurl implementation for the nyquest framework.

    Prerequisites

    • You must have libcurl 7.68.0 or later installed on your system.

    Features

    You can enable the following features via Cargo to customize the backend behavior:

    FeatureDescription
    sslEnable SSL support (enabled by default).
    blockingEnable blocking request mode.
    blocking-streamEnable blocking streaming mode.
    asyncEnable asynchronous request mode.
    async-streamEnable asynchronous streaming mode.
    multipartEnable multipart/form-data support.
    charset-defaultsEnable encoding conversion via iconv-native with its default features enabled.
    charsetEnable encoding conversion via iconv-native without activating any of its default features. (See iconv-native documentation for details).

  9. Quick Start with nyquest-preset

    main

    To use the default backend configuration in your application, add nyquest_preset to your dependencies and call nyquest_preset::register() at the very beginning of your program startup. This registers a platform-appropriate backend as the global default for the nyquest library.

    Note for Library Authors: Do not include nyquest-preset as a dependency in a library. Libraries should depend on nyquest directly. nyquest-preset is intended for end-user applications to set the global backend state.

    nyquest_preset::register();

  10. Streaming requests in WinHttpBlockingClient

    main

    If the blocking-stream feature is enabled, WinHttpBlockingClient supports streaming request bodies. This is handled internally by send_streaming_request when the request body is a PreparedBody::Stream.

    It uses a StreamWriter to poll data from BoxedStream parts and write them to the WinHTTP request handle. If the stream has a known size, it uses send_with_total_length; otherwise, it uses chunked encoding via send_chunked.

  11. Handle Request Bodies in NSUrlSessionClient

    main

    The NSUrlSessionClient supports several body types via the Body enum:

    • Body::Bytes: Sends raw bytes with a specified content_type.
    • Body::Form: Sends URL-encoded form data (application/x-www-form-urlencoded).
    • Body::Multipart: Sends multipart/form-data (requires the multipart feature).
    • Body::Stream: Streams data to the request (requires async-stream or blocking-stream features).

  12. Configure nyquest-backend-winhttp features

    main

    The WinHTTP backend supports several optional features that can be enabled via Cargo features to customize its capabilities:

    • blocking: Enables blocking HTTP client support.
    • blocking-stream: Enables blocking streaming for uploads and downloads.
    • async: Enables asynchronous HTTP client support.
    • async-stream: Enables asynchronous streaming for uploads and downloads.
    • multipart: Enables support for multipart form data.
    • charset-defaults: Enables encoding conversion using iconv-native with its default features enabled.
    • charset: Enables encoding conversion using iconv-native without activating any of its default features (refer to iconv-native documentation for specific feature details).