Sibling crates russh_config and russh_keys

[andrewbaxter]

I only poked around a little, but I didn't see any reference to them in the readme or the docs.rs, but at least russh_keys has types that are used by various public interfaces. Those crates also don't have any documentation AFAICT.

Are those WIP or are they supposed to be internal or something? Or is there some documentation somewhere that I just missed?

I was looking for ways to emulate the openssh client (using system configs, agents, etc) and the config parser in russh_config and ssh agent stuff in russh_keys also look relevant, so I'd be grateful for any information on them.

[Eugeny]

They have their own documentation in https://docs.rs/russh-keys and https://docs.rs/russh-config (russh-config docstrings are lacking but it's an extremely simple crate)

[andrewbaxter]

Ah thanks! Yes, that helps.

I think there may be several things interacting here. Right now if you impl client::Handler with rust-analyzer you get an invalid signature because russh doesn't reexport russh_keys, and autocomplete also won't help you unless you cargo import russh_keys first. The readme doesn't mention adding this dependency. The examples piggyback off the main crate's dependencies so don't provide guidance in this regard. The russh package readme which happens to be the project overall's readme mentions supporting various key types, but that's actually the russh_keys package which adds more confusion - if I don't see a mention of multiple crates I assume the main crate has everything.

There are lots of rust libraries with child/sibling crates where you're not supposed to import those crates directly and doing so will make things more complicated.

To be clear, I'm not claiming anything's wrong here, but it's hard to get a big picture of all the pieces and how they combine together. Maybe the main readme could give an overview of all the crates, and which ones you're supposed to import to use which features?

I focused a lot on dependencies, but there's a lot that doesn't quite connect for me. Like russh_config::parse_home is able to figure out the paths to config files, but the russh_keys agent client can't figure out the path to the SSH agent on it's own? Or the expected way to keep a lookup of PublicKeys for host key verification. How to read a public key file into a PublicKey object? These are just a couple things I ran into doing an initial scan.

Maybe I'm looking in the wrong place again, or maybe they aren't implemented yet, or maybe they're not planned to be implemented, but regardless if the documentation stated this up front I think it would be a lot easier for prospective/new users.

I realize this is kind of specious but I guess to summarize where I'm hitting trouble:

• It seems like there are a lot of components here, but they're not thoroughly referenced from other parts of the documentation
• The documentation either doesn't describe how to idiomatically use the components or there's no examples for many use cases
• It's not clear when stuff is missing if 1. it's actually missing (need to search documentation harder), 2. not implemented yet (do minimal workaround and move on), or 3. won't be implemented (do long-term workaround or look for another solution). I default to 1 and spend a lot of time searching

[Eugeny]

Thank you for extensive feedback! A lot of this is carried over from the crate's thrussh origins. I'm of course open to improvements. I haven't considered the analyzer's "implement" function since usually the analyzer fails to find the correct signature when implementing singular methods anyway (due to async_trait).

Would a barrel re-export of russh_keys from russh solve the issue here? This seems to be the common pattern (and it's soon getting 1st class support in Cargo as public/private dependencies).

Or are there better ways here?

[andrewbaxter]

Oh, thanks for graciously considering my comments! :D

I'd be glad to try to contribute with some more documentation or other stuff too later, possibly if that helps. I just wanted to bring it up early to get a feel for the context surrounding it. There are some projects that I had trouble with the documentation with where the maintainers disagreed or weren't open to documentation changes etc, so just knowing you're open to changes is great.

And I kind of assumed some of it was inherited, so it's good to get confirmation. And yes, async_trait doesn't help things here too...

Yeah, TBH I'm not 100% sure either the best way to do this. I think a re-export would help... there are some conventions regarding packaging I'm still not super familiar with.

I was just looking at wry which uses tau for window setup (same org), and it looks like they do re-export stuff ex: here https://github.com/tauri-apps/wry/blob/dev/src/lib.rs

Hyper just adds the re-exports directly (no prelude thing): https://github.com/hyperium/hyper/blob/master/src/body/mod.rs

hickory_client does pub use at the root of hickory_proto which is the sibling crate with all the data types, but renames it to just proto. https://github.com/hickory-dns/hickory-dns/blob/main/crates/client/src/lib.rs

I'm not sure what all of that means.

[Eugeny]

For now I've reexported russh_keys as russh::keys which should cover most of the problems I hope

[Eugeny]

russh_keys will be merged into russh in the next release