First crates: Rustify and Vaultrs

rustify
vaultrs

I've been learning Rust over the past month and have put together two crates that are mostly interwoven. The first is rustify which is a crate for wrapping HTTP API endpoints to enable easily querying them and deserializing responses. It contains a macro that allows easily scaffolding common REST-style endpoints. It's primarily targeting async but also offers blocking versions of its clients.

The second is vaultrs which leans heavily on rustify to create a client library for Hashicorp Vault. It currently supports the PKI and secrets backend as well as wrapping responses.

I'd love feedback on the code and overall design of the crates. I spent a lot of time trying to structure them to be consistent and easily extendable. Things should be well documented as well.

Thanks!

Hi Joshua,

cool projects :slight_smile: A couple of things I notice:

Ad READMEs:

  • The installation instructions in your README use cargo add. That command requires cargo-edit to be installed, not everybody has that, in which case you'll get a no such subcommand error message which might confuse users.

  • The code block in the Advanced Usage section in rustify's README is quite long, with the explanation below it. I guess I'd find it easier to follow if code and text were more interwoven.

Ad Rustify API design:

  • if a trait is essential to your crate I'd personally put it in the root namespace instead of a submodule that only contains that trait, so e.g. rustify::Endpoint instead of rustify::endpoint::Endpoint.

  • the name of the result parameter in the endpoint macro might be a bit confusing, since it makes you think of std::result::Result

Ad documentation:

  • You might want to make the examples in your crate documentation tested, so you can't accidentally break them in future updates.

  • You don't need to prefix your description in Cargo.toml with A Rust crate which ... that's implied. e.g. A library which might be more descriptive (since there are also non-library crates).

  • I like to add at least one-line descriptions to the modules using module-level documentation, so that you can easily get an overview of what the modules are about.

  • I think for Rustify a Cargo example would be neat (e.g. examples/foo.rs can be run with cargo run --example=foo).

  • You got some broken links in your documentation.

1 Like

Thanks for the great feedback! I've went ahead and implemented most of your recommendations and it looks a lot better :slight_smile:

1 Like

This topic was automatically closed 90 days after the last reply. We invite you to open a new topic if you have further questions or comments.