Optimize backend selection API

[Aalivexy]

Currently backend selection is done using a separate presets crate, which doesn't work out of the box (currently returns an error if not registered).

Perhaps we could provide a sensible default and control the backend via a feature, like rustls does for example?

[bdbai]

Thank you for the thoughtful suggestion! This design choice was carefully considered during the project's architecture phase. Let me explain the rationale behind the current approach:

Why Separate Crates?

We opted for decoupled backend implementations because:

• Dependency Control: Prevents dependency bloat for downstream libraries. Default features in transitive dependencies can unintentionally pull in unwanted backends for end users (a common pain point in Rust ecosystems).

• Explicit Selection: Encourages conscious backend choice rather than implicit feature-based auto-selection. This avoids surprises in cross-platform scenarios.

Current Trade-offs

• The extra step of backend registration (via nyquest-preset) isn't ideal for quickstart scenarios
• NoBackend errors create friction for new users

Potential Improvements

• Re-export nyquest through nyquest-preset
• Enhance documentation with clear platform-specific guidance
• Explore automatic backend registration if feasible

This architecture remains flexible as we approach a stable release. Your feedback is invaluable - if more users express similar preferences, we'll prioritize re-evaluating the feature-based approach.

Disclaimer: the content has been enhanced by AI

[Aalivexy]

What do you think about the generic, trait-based way of specifying the backend and injecting dependencies? I think it is clear enough and can also separate dependencies. It seems that the advantages of separating crates can also be achieved through this method?

[bdbai]

generic, trait-based way of specifying the backend and injecting dependencies

Do you mean this? https://github.com/bdbai/nyquest/blob/b2acba59c9a95e7454c04bd8889b5adeb8c610cd/nyquest-interface/src/register.rs

[Aalivexy]

Yes, I want it to be exposed to the user, I can choose the backend by specifying a generic parameter to the function (or choose to read the global value and let the end user choose the backend)

[bdbai]

@Aalivexy actually it is already doable in a few ways:

1. By convention, a backend exposes a register function at crate level, such as this, so that you have the freedom to call it instead of going through nyquest_preset::register(). It also serves as the customization point to support some kind of global set up of the backend. For example, calling curl::init().
2. Again by convention, a backend exposes its backend implementation type, such as this. With this you can manually plug it into nyquest_interface::register_backend. It is subject to the backend implementation to allow users to instantiate a backend instance.

[Aalivexy]

The API I expect may be similar to this, where the automatic backend can use the default value when the user does not specify it, or it can be specified by the end user.

pub mod nyq {
    use std::sync::OnceLock;

    pub trait Backend {
        fn new() -> Self;
        fn get(&self, key: &str) -> Option<String>;
    }

    pub static BACKEND: OnceLock<Box<dyn std::fmt::Display + Send + Sync>> = OnceLock::new();

    // AutoBackend may differ based on the platform
    pub struct AutoBackend;

    impl AutoBackend {
        pub fn init_with_backend(backend: Box<dyn std::fmt::Display + Send + Sync>) -> Result<(), Box<(dyn std::fmt::Display + Send + Sync + 'static)>>  {
            BACKEND.set(backend)
        }
    }

    impl Backend for AutoBackend {
        fn new() -> Self {
            BACKEND.get_or_init(|| {
                // initialize the backend here if needed
                Box::new("Backend initialized")
            });
            AutoBackend
        }

        fn get(&self, url: &str) -> Option<String> {
            Some(format!("Value for {}", url))
        }
    }

    pub struct Client<B: Backend = AutoBackend> {
        backend: B,
    }

    impl<B: Backend> Client<B> {
        pub fn new() -> Self {
            Client { backend: B::new() }
        }

        pub fn get(&self, url: &str) -> Option<String> {
            self.backend.get(url)
        }
    }

    pub mod winrt {
        use super::Backend as BackendTrait;

        pub struct Backend;

        impl BackendTrait for Backend {
            fn new() -> Self {
                Backend
            }

            fn get(&self, url: &str) -> Option<String> {
                Some(format!("WinRT value for {}", url))
            }
        }
    }
}

fn main() {
    // select specific backend (optional)
    let _ = nyq::AutoBackend::init_with_backend(Box::new("unique backend"));

    // use the Client with the default autoselect backend
    <nyq::Client>::new().get("https://example.com");

    // select the backend explicitly
    nyq::Client::<nyq::winrt::Backend>::new().get("https://example.com");
}

This allows us to use two or more backends at the same time (although this is probably rarely necessary).

[bdbai]

@Aalivexy Now I get your point. Currently most of the types in our facade crate is simply a wrapper over the corresponding types in nyquest-interface, or a type-erased (boxed) component of the backend. Based on this, a simpler way is to add an option to the ClientBuilder for a custom backend. Carrying a generic parameter around can be a burden of library authors. wdyt? In the worst case, the naked backend can be used directly with nyquest-interface but hopefully this will never happen.

Regarding the public AutoBackend being exposed, I really think it is user's responsibility to maintain it, who is also the one deciding which backend to register to global. nyquest-presets should expose that as well (which I am planning to add).

[Aalivexy]

Using generics may indeed be a burden on library authors, but this is inevitable for a complete, zero-cost abstraction, which is what Rust is pursuing. If you only add a ClientBuilder with generic parameters, it may cause some strange behaviors, because it should theoretically coexist with Clients constructed in other ways. This all-generic backend approach has already been used in production and seems to work well (see burn).

The reason I want to provide an AutoBackend is that I want to provide a reasonable default value to library authors so that they can provide an out-of-the-box API when users don't care about the backend (or think the default is reasonable). I think this is reasonable for users who care about or don't care about the backend implementation.

[bdbai]

@Aalivexy

a complete, zero-cost abstraction

Please note that achieving high performance is a non-goal in nyquest. This is explicitly stated In README: you might not need Nyquest if you ... want to minimize the overhead introduced by abstraction or interop with external libraries. Actually if you take a look at the backend implementations, you will realize that overhead is everywhere: external COM/objc objects that are "boxed", ref-counted and dynamically invoked, Strings being converted to and from CStrings or wide strings etc. etc. that users have to bear in exchange for a native experience. In light of this, I won't be bothered to make the interface more complicated, but only to get a marginal performance gain in return.

A notable difference of this project and reqwest is that nyquest focuses more on casual usages. A valid use case would be, for example, a GUI application with Check for updates feature while it does not serve network functionalities as its main purpose. On the other hand, let's say you are building a really sophisticated HTTP API library like Cloudflare API SDK, reqwest would be a better choice for full low-level control and less overhead.

coexist with Clients constructed in other ways

Currently nyquest Clients cannot interact with each other by any means. We will explore viable options when needed in the future.

reasonable default value to library authors so that they can provide an out-of-the-box API when users don't care about the backend

We can consider exposing nyquest_interface::register::BACKEND as public so that lib authors can decide whether to register via nyquest-presets, or we provide try_register_backend to let libs call during initialization. But I still feel like it is redundant work for lib authors to think about backends. Simply accepting a ClientBuilder should just work.

Another concern for libs to ship backends is, we might end up having duplicate backend dependencies of different versions in an application, when the end user or another lib also coincidently does this. Ideally, the interface crate remains stable as much as possible, while the backend implementations and the preset crate can upgrade more frequently. If the lib makes the defaults opt-in, for end users it's just a matter of adding a feature or another dependency. I'd rather choose the latter for the explicit is better than implicit philosophy. If it's an opt-out thing, apparently it will possibly be another "didn't read the doc" tax for end users to pay.

[Aalivexy]

There may be some problems with my expression. What I really want to express is that I want to select the backend for each Client at compile time through generics, because I want to avoid using the global, runtime registered nyquest_interface::register::BACKEND.

I think the choice of backend should be determined at compile time, not at runtime. Moreover, the current implementation only allows one backend to exist. What's the reason to use dynamic dispatch?

[bdbai]

avoid using the global, runtime registered nyquest_interface::register::BACKEND

As I have mentioned earlier, we can consider custom backend per client exposed as a client builder option.

the choice of backend should be determined at compile time, not at runtime

I don't see any concrete benefit of doing this. Maybe elaborate more?

What's the reason to use dynamic dispatch?

This is to allow the default backend to exist at global level.

[Aalivexy]

It is indeed a hassle to configure the options of dependent libraries in Rust, and maybe you are right.

Maybe it is more in line with the Rust philosophy to determine some things at compile time? After all, most Rust libraries will not have an internal global value at runtime, which will make it look more like a library that exposes a C interface.

I have no more questions. If you are satisfied with your current design and plan, I think it is okay and you can close the issue. If you have any questions or suggestions about my ideas, please feel free to raise them.

[bdbai]

@Aalivexy I understand that most Rust users may incline towards using generics, and normally would not consider global variables in the first place. Think about it this way - nyquest aims to exploit platform-native functionalities as much as possible, which includes proxy, cache, TLS and a bunch of other stuff that share the same set of system settings, whose behavior would be controlled in a far wider scope (user- or system-level singleton) than our individual executables. The so-called custom backend will not be considered as a norm, hence it shouldn't be encouraged.

In general, I am open to different voices. Given nyquest is still in early stage and yet not being used by community users in large, it is a bit hard for me to visualize whether the current design plays well in various scenarios. Let's see how far we can go from here. By the time we collect enough feedbacks backed by real-world use cases, we can adjust accordingly.

Regarding this issue, I would keep it open as there are still things to do for improvement:

• Quick Start and documentation for backends and nyquest-preset
• Custom backend per client
• Auto backend registration