Near-api-rs: Feature Flags To Reduce Dependencies?

Hey everyone, I've been diving into the world of near-api-rs lately, and seriously, great job to all the contributors! I've been using it for a project, and it's been pretty smooth sailing. However, I ran into a small hiccup that I wanted to chat about, and hopefully, we can find a good solution to this.

The Dependency Dilemma: hidapi and libudev

So, here's the deal, guys. I bumped into an issue where one of the underlying dependencies, specifically the hidapi crate, requires me to install an extra library on my system: libudev. Now, this wasn't immediately obvious from the documentation or the README, which is totally understandable – documentation can always be a work in progress. But, when I was setting up my project, I got this rather unfriendly error message:

--- stderr

  thread 'main' panicked at /home/runner/.cargo/registry/src/index.crates.io-1949cf8c6b5b557f/hidapi-2.6.3/build.rs:61:54:
  Unable to find libudev: 
  pkg-config exited with status code 1
  > PKG_CONFIG_ALLOW_SYSTEM_LIBS=1 PKG_CONFIG_ALLOW_SYSTEM_CFLAGS=1 pkg-config --libs --cflags libudev

  The system library `libudev` required by crate `hidapi` was not found.
  The file `libudev.pc` needs to be installed and the PKG_CONFIG_PATH environment variable must contain its parent directory.
  The PKG_CONFIG_PATH environment variable is not set.

  HINT: if you have installed the library, try setting PKG_CONFIG_PATH to the directory containing `libudev.pc`.

  note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
warning: build failed, waiting for other jobs to finish...

This basically means my build failed because it couldn't find libudev, which hidapi needs to do its thing. After a bit of digging, I figured out that this dependency is related to the ledger-transport-hid crate, which is used for interacting with Ledger hardware wallets. The connection becomes clear when you look at the dependency tree:

$ cargo tree -i hidapi
hidapi v2.6.3
└── ledger-transport-hid v0.11.0
    └── near-ledger v0.9.1
        └── near-api v0.7.3
            └── ...

So, hidapi is pulled in through ledger-transport-hid, which is used by near-ledger, which is then used by near-api.

The Core of the Request: Feature Flags

The reason I'm bringing this up is that, in my particular project, I'm not using the Ledger functionality at all. I don't need to interact with a hardware wallet. So, I'm essentially being forced to install libudev and deal with this dependency even though it's not relevant to my project's core functionality. This brings us to the core of my suggestion: introducing feature flags in near-api-rs.

Feature flags are a great way to control which parts of a library or crate get compiled and included in your project. They allow you to opt-in to specific functionalities while keeping the rest of the code (and its dependencies) out of your build. In this case, I propose adding a feature flag, something like ledger-support or hardware-wallet, that would enable the near-ledger and ledger-transport-hid dependencies, and therefore, the hidapi dependency. If this feature flag isn't enabled, those dependencies would not be included, and the build would not require libudev.

This approach offers several benefits. First, it reduces dependencies for projects that don't need Ledger support. This leads to faster build times, smaller binary sizes, and fewer potential conflicts with other libraries. Second, it improves the developer experience. Users who don't need Ledger integration won't have to worry about installing libudev or troubleshooting related issues. Finally, it keeps the code clean and focused. It separates the Ledger-specific code from the core functionality of near-api-rs, making the codebase easier to maintain and understand. By implementing feature flags, you allow developers to tailor the library to their specific needs. This means a more streamlined development process and a smaller final application size if you don't require the Ledger functionality. It is a fantastic practice that allows the developers to only include the required dependencies.

The Benefits in Detail

Let's break down the advantages of implementing feature flags a bit more. First and foremost, it streamlines the development process. Think about the number of times you've started a new project, only to be bogged down by dependency errors. With feature flags, you can say goodbye to those headaches. You simply declare the features you need, and the build process takes care of the rest. Another key benefit is the reduction in build times. Every dependency adds to the time it takes to compile your project. By excluding unnecessary dependencies, you can significantly speed up the build process, especially for larger projects. This is a game-changer when you're iterating on your code or working on a tight deadline. And, let's not forget the reduced binary size. Smaller binaries are generally easier to deploy and faster to load. This can be particularly important for applications that need to be lightweight or run on resource-constrained devices. Feature flags allow you to trim the fat and ensure that only the necessary code is included in your final product. This also minimizes the risk of dependency conflicts. When your project has fewer dependencies, there are fewer opportunities for conflicts to arise. This leads to a more stable and reliable development environment, saving you time and frustration down the road.

Implementation Considerations

Now, let's talk about how this might be implemented. The process itself is pretty straightforward. Inside the Cargo.toml file of near-api-rs, you'd define a feature flag, such as ledger-support. Then, you would use this flag to conditionally include the near-ledger and ledger-transport-hid dependencies. For example:

[features]
ledger-support = [
    "near-ledger",
    "ledger-transport-hid",
]

[dependencies]
near-ledger = { version = "...", optional = true, enabled = false }
ledger-transport-hid = { version = "...", optional = true, enabled = false }

Inside the code, you would use the cfg attribute to conditionally compile code based on the feature flag. For example:

#[cfg(feature = "ledger-support")]
mod ledger_integration {
    // Code that uses near-ledger and ledger-transport-hid
}

This would ensure that the Ledger-related code is only compiled when the ledger-support feature is enabled. This is a pretty common pattern in Rust, and it's well-supported by the Cargo build system.

Potential Challenges and Mitigation

Of course, there might be some challenges. For instance, you would need to ensure that the public API remains consistent, regardless of whether the ledger-support feature is enabled. This might require some careful design choices to ensure that functions and types related to Ledger are only exposed when the feature is enabled. Another consideration is documentation. You would need to clearly document the feature flag and its implications. Users need to understand which features are available, how to enable them, and what dependencies they require. Clear and concise documentation is crucial for making the feature flags easy to use and understand. There is also the potential for increased complexity. Adding feature flags can make the codebase slightly more complex. However, the benefits – reduced dependencies, faster build times, and a cleaner codebase – usually outweigh this added complexity. Careful planning and a well-structured implementation can minimize the impact on the overall complexity of the project.

Conclusion: A Win-Win for Everyone

In conclusion, adding feature flags to near-api-rs to control the Ledger support would be a fantastic improvement, and it's a win-win for everyone. It simplifies the setup for users who don't need Ledger integration, reduces dependencies, and keeps the codebase clean. This helps maintainers and makes near-api-rs more adaptable and user-friendly. Thanks for considering my suggestion! I'm really enjoying working with the library, and I'm excited to see where it goes from here!

I think feature flags are a fantastic practice that allows the developers to tailor the library to their specific needs. This means a more streamlined development process and a smaller final application size if you don't require the Ledger functionality. By implementing feature flags, the library can cater to the specific needs of developers, resulting in a more streamlined development process and a smaller final application size when Ledger functionality is not required. By reducing the number of dependencies required to use the library, the project will be more accessible to a wider audience, and reduce build times and potential conflicts, resulting in more stable and efficient development.