Feat/add rpc header arg

[elizabethengelman]

What

Adds a --rpc-headers argument to allow users to pass in an auth header, so that RPC providers that require API keys can be used with the CLI.

Companion rpc-client PR: stellar/rs-stellar-rpc-client#13

Here are some screenshots showing that this change works for multiple headers, with both adding a new network, and using a configured rpc provider:

using multiple —rpc-headers args for adding a network

using env vars for multiple headers for adding a network

using multiple —rpc-headers args for using the rpc provider

using the env var for multiple headers for using the rpc provider

Why

This allows users to use one of the rpc providers that require an API passed in via a header.

Closes #1583

Known limitations

This change requires this change from the rpc-client: stellar/rs-stellar-rpc-client#13

[leighmcculloch]

Couple thoughts. I realise this PR is incomplete and doesn't yet use the header. 😅

[leighmcculloch]

I think this should probably be a multi-value key, therefore be a Vec<String>, but as far as I know the clap-rs env feature doesn't work well with it. We'd have to try it out.

Given all use cases we have only need a single header at this time, then as it is looks good, but if you wanted to do a mini timeboxed exploration on whether Vec<String> is supported with env in some way, and it turned out it worked, then I'd change it to:

Suggested change

	/// Optional RPC provider api key headers
	#[arg(
	long = "rpc-header",
	requires = "rpc_url",
	env = "STELLAR_RPC_HEADER",
	help_heading = HEADING_RPC,
	)]
	pub rpc_header: Option<String>,
	/// Optional RPC provider api key headers
	#[arg(
	long = "rpc-header",
	num_args(0..),
	requires = "rpc_url",
	env = "STELLAR_RPC_HEADERS",
	help_heading = HEADING_RPC,
	)]
	pub rpc_header: Vec<String>,

[elizabethengelman]

I like the idea of making this a vec of strings - it seems like there's a possibility that users may want to pass multiple headers to their rpc requests.

I think that we are doing something similar to this with the --with-example flag in stellar contract init, that allows for passing multiple values like this: stellar contract init --with-example alloc --with-example auth

[elizabethengelman]

Just re-reading your comment, and I missed the env part the first time. I'll timebox looking into this today 👌

[overcat]

It might be better to define it as Vec<(String, String)>. This would help allow users to more clearly pass in multiple headers, and it would also be simpler when handling STELLAR_RPC_HEADER env.

The code may be helpful: https://github.com/lightsail-network/stellar-cli/blob/5d93640d2d2f629c91cabd0340ec7f59bac6ebd9/cmd/soroban-cli/src/config/network.rs#L122-L152

(This is the code I wrote a few days ago, and at that time I didn't realize there was already an existing PR here.)

[elizabethengelman]

Thanks @overcat! I agree that rpc_header should be a vec, and I like that you made it a vec of tuples instead! 👌 That definitely makes it easier to handle STELLAR_RPC_HEADER. 🎉

[leighmcculloch]

Does that work with env vars though? I don't think the clap env feature knows what to do with multiple values inside the env. Or can you share an example of what hte cli and env UX becomes with this?

[overcat]

Hi @leighmcculloch, I think it is supported, please check the screenshot.

Because we used value_delimiter = '\n', it will need to be line-separated, but you can use a different delimiter based on your needs.

[elizabethengelman]

Adding to this, I've put screenshots in the pr description showing that multiple headers work for adding a network and using the configured rpc provider.

[overcat]

For more general purposes, we may need to consider whether we should use , as a separator, because , is likely to appear in the value. For example, my User-Agent contains it: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/129.0.0.0 Safari/537.36

[leighmcculloch]

I like the idea of using new line as you did in the other example, given that new lines are the natural delimiter of headers. New lines may create issues in some environments for env vars, but also, we expect only a single header to be used so I'm not sure it's worth dwelling on that.

[elizabethengelman]

Good call, I can push up a fix for that today.