Proposal to update channel subscriptions behavior and/or documentation around Pending and Draining

[anthonyjacques20]

What motivated this proposal?

We are using ChanQueueSubscribe (but applies to any channel subscription), we noticed that calling the Pending method doesn't do exactly what we expect.

The Pending method on a channel subscription returns an error. Line in code here - https://github.com/nats-io/nats.go/blob/main/nats.go#L4706

And also the Drain method looks like it only applies to callbacks.

What is the proposed change?

The proposed change is that the Pending method returns the pending messages for channel subscriptions. The nats cli shows pending messages for channel subscriptions so not sure why it's different here?

For the Drain method description, I know the description says:

Drain will remove interest but continue callbacks until all messages have been processed.
But I feel like it could be made a bit more explicit that this only applies to callbacks and doesn't do anything for non-callback subscriptions. (And feel free to ignore this Drain method suggestion, it's probably more of an issue with my initial understanding, but I thought I'd bring it up in case others had initially been confused by it as well)

Who benefits from this change?

People using channel subscriptions will benefit from the change. Needing to differentiate between a channel subscription and a non-channel subscription to get the number of pending messages seems to add unneeded complexity on the application side.

As far as the Drain method, making the documentation more clear would save time for people to understand how it is supposed to work for non-callback subscriptions.

What alternatives have you evaluated?

We can get the number of pending messages for a channel subscription with len(chan) but needing to differentiate seems unnecessary.