Builders for async_nats

[Jarema]

Overview

As we're getting close to 1.0.0, we want to finalise API and breaking changes.
One set will be about concrete errors, and another - consistent and nice builders.

This Discussion is about the builders.

Possibilites

With the recent introduction of IntoFuture trait,
we got a new way of adding seamless builders.

Though after spending some time with them, I'm worried that despite being sleek API-wise, abusing that trait for builders might resemble abusing Deref for newtypes.

Propositions

We would attach builders to a given context, to make calling those easy:

non-hot-path / nouns

jetstream.build_stream()
  .subjects(vec!["data", "events"])
  .max_age(Duration::from_secs(60))
  .create().await?;

That means that:

1. we use build_noun -> options -> verb as in non-builder method.
2. We do not leverage into_future

hotpaths / verbs

1. IntoFuture

jetstream.publish().header("Some-Key", "value").await?;

With into_future, the await acts as a finalizer (send) of the builder.
That makes working with verbs/hotpaths seamless - no need to create a builder,
no need to call finalizer.

2. Standard

jetstream.publish_with_options().header("Some-Key", "value").send().await?;

This is a less magical, approach.
It does seem verbose, though.

*.with_options was used, as it fit better with verb-related builders and hotpaths.

Open questions

We lean towards not leveraging IntoFuture for noun/not hotpaths, and using it for hotpaths, but we would love to hear your feedback. We want to make this change only once, and provide as nice as possible API for you all.

What do you think about the above?
Do you think that even for hotpaths, leveraging IntoFuture is abusing the trait?
Or the other way around - you think we should use it everywhere?

Tagging a few users/contributors for visibility, but everybody's opinion is valuable here!
@segfaultdoc @autodidaddict @thomastaylor312 @stevelr @paulgb @caspervonb

[thomastaylor312]

I really like the IntoFuture behavior suggestion. As for builders in general (particularly the non-hotpath ones), I personally have mixed feelings about them (they're an overly verbose replacement for just filling out data members of a struct and finishing with ..Default::default()). They are common in the rust environment though, so I think using them is probably a good idea

[segfaultdoc]

+1 from me!

[sloveridge]

I like the non-hot-path / nouns builder approach. I find it clear and readable.

For verbs I think into_future is fine. It is still clear and less verbose.

So +1 to proposal.