Use context for Publish methods

[sapk]

Implement #92

This currently require context to be always cancelled (like net/http query) to not have stuck goroutine.

I am considering switching from waitgroup to the context of query for the sync pattern of DeferredConfirmation. This could lead to no leaking goroutine.

The latest implementation replace waitgroup of deferred with context so that we don't need goroutine to monitor context.

[michaelklishin]

Thank you, this is a non-trivial contribution!

[sapk]

It introduce some breaking change on methods arguments by adding context and enforce an non-nil context on Publish methods.

I enforce it because someone should never use a nil context and I feel it should failed early on that.
From context documentation:

Do not pass a nil Context, even if a function permits it. Pass context.TODO if you are unsure about which Context to use.

Even so, I understand that it could be better to support it if you feel it is needed. We could change it to support nil context by creating a background context in DeferredConfirmation in case of nil or an other solution is only require it when needed in case of ch.confirming == true.

[michaelklishin]

We can bump minor or even major version to accommodate this change if it is accepted.

[guidog]

Changing the API out of the blue is not nice.

I suggest to rename the context based Publish and leave the old one in place.

Not every one wants to change their application (time, money, you name it).
Given how it looks like I'm quite confident that there won't be "backports" to older versions.

A little sense of stability would be nice.

[Zerpet]

Changing the API out of the blue is not nice.

I agree that those changes are not nice. However, a major version, according to semver, reflect a breaking change in the API. I am in favour of introducing this change in a major.

A little sense of stability would be nice.

The API has been stable almost since its inception in streadway/amqp. We have to find a balance between having stability and evolving the API. The addition of context.Context is a necessary step to unlock the potential of Open Telemetry and context propagation.

[sapk]

I could do a Publish and PublishWithContext and manage nil context case to be mergeable in this current major version if it is easier.
I could also indicate that publish methods without context will be deprecated to help prepare migration with later version.

[lukebakken]

@sapk thank you for your work on this. A suggestion for you, @Gsantomaggio, @Zerpet and others (cc @fho) to consider, that may direct users of this library to use it correctly:

• Do not change the API for Publish. If the user calls Publish with confirmations enabled on a channel, an error will be returned to indicate that PublishWithDeferredConfirm must be used.
• If the user calls PublishWithDeferredConfirm when confirmations are not enabled, an error would be returned stating that confirmations must be enabled on the channel.

Or, add a new API keeping the existing one to preserve backwards-compatibility 🤷‍♂️

Thoughts?

[sapk]

I updated the PR to be backward compatible and rollback client test changes to validate working with previous Publish methods without context.
But kept using with context, in examples tests.

With Deprecated: comment, the methods without context should trigger linters if used to ease migration.

Deprecated: notice in documentation:

[fho]

I would prefer to change the API instead of introducing WithContext methods + deprecating the old ones.
It's a minor change and not much effort to adapt code when upgrading to new major amqp091-go release

[lukebakken]

@fho we will do that for version 2.0