feat(pubsub/v2): add subscriber shutdown options

[hongalex]

This introduces the ability to tell the client library how you want your messages to behave when shutdown is initiated. You can configure the behavior as ShutdownOptions.Behavior as ShutdownBehaviorWaitForProcessing or ShutdownBehaviorNackImmediately.

In addition, you can specify ShutdownOptions.Timeout to configure how long you want to wait for messages to be processed, or provide a timeout to the nack calls before returning.

[feywind]

I'm not a Go Pub/Sub expert, but this looks like it generally does what it's supposed to :)

[shollyman]

The use of new context.Background() in iterator looks a bit odd, but LGTM given our discussions.

[hongalex]

The use of new context.Background() in iterator looks a bit odd, but LGTM given our discussions.

To capture our offline discussions, a detached context.Background() always existed in the iterator (so in flight messages are not cancellable by the user by default). This matches the default behavior. I needed to introduce a context finally because nackInventory requires us to be able to cancel that request after ShutdownOptions.Timeout duration has passed.

[kurochan]

Hi @hongalex ,
In subscriber.go, I noticed that when Timeout > 0, the code always calls iter.nackInventory, regardless of the value of ShutdownOptions.Behavior.
This seems to mean that even if ShutdownBehaviorWaitForProcessing is set, messages will still be nacked immediately.
Was the intention that Behavior should only matter when Timeout is negative (infinite wait), or should the shutdown logic branch on Behavior as well? Could you clarify the intended interaction between Timeout and Behavior?

[hongalex]

Approved the above PR but responding here for completeness.

This was indeed a bug, the Behavior should have been checked here (thanks for the PR).

The interaction between Behavior/Timeout is this:

1. Timeout = 0 trumps everything. This tells the library to drop everything on the ground, and shutdown immediately. You don't need to specify a Behavior here.
2. Timeout <=0 means we disabled the timeout, and are waiting indefinitely for either Behavior to complete. In WaitForProcessing, wait for messages to be acked or nacked and the callback returns (current library behavior). In NackImmediately mode, we Nack all messages at shutdown.
3. Timeout >= 0 means we just follow the ShutdownBehavior (wait or nack) up to the specified timeout.

[kurochan]

@hongalex Thank you for your kind explanation. I understand.