Documentation needed (`PublishWithContext` does not use context)

[Av1shay]

Describe the bug

I'm not sure if I'm blind or something, but looking at the function PublishWithContext I can't see where it uses the context? it calls ch.PublishWithDeferredConfirmWithContext and inside it just check if ctx == nil, after that it does not use the ctx. What am I missing? (Version 1.8.1)

func (ch *Channel) PublishWithDeferredConfirmWithContext(ctx context.Context, exchange, key string, mandatory, immediate bool, msg Publishing) (*DeferredConfirmation, error) {
	if ctx == nil {
		return nil, errors.New("amqp091-go: nil Context")
	}

	if err := msg.Headers.Validate(); err != nil {
		return nil, err
	}

	ch.m.Lock()
	defer ch.m.Unlock()

	var dc *DeferredConfirmation
	if ch.confirming {
		dc = ch.confirms.publish()
	}

	if err := ch.send(&basicPublish{
		Exchange:   exchange,
		RoutingKey: key,
		Mandatory:  mandatory,
		Immediate:  immediate,
		Body:       msg.Body,
		Properties: properties{
			Headers:         msg.Headers,
			ContentType:     msg.ContentType,
			ContentEncoding: msg.ContentEncoding,
			DeliveryMode:    msg.DeliveryMode,
			Priority:        msg.Priority,
			CorrelationId:   msg.CorrelationId,
			ReplyTo:         msg.ReplyTo,
			Expiration:      msg.Expiration,
			MessageId:       msg.MessageId,
			Timestamp:       msg.Timestamp,
			Type:            msg.Type,
			UserId:          msg.UserId,
			AppId:           msg.AppId,
		},
	}); err != nil {
		if ch.confirming {
			ch.confirms.unpublish()
		}
		return nil, err
	}

	return dc, nil
}

Reproduction steps

none

Expected behavior

Honor context cancellation signals

Additional context

No response

[lukebakken]

Hello, thanks for using this library and RabbitMQ. You can see in #96 where the contexts were added, and #140 for where their use was removed. If you think that was the wrong decision, please start a discussion here.

In the future, use git blame or "blame" feature of the GitHub code navigator to figure out for yourself code changes.

[nemith]

In the future, use git blame or "blame" feature of the GitHub code navigator to figure out for yourself code changes.

This should be documented and not require people to code spelunking.

[lukebakken]

@nemith please take the time to add the relevant documentation via a PR. We would appreciate it.

[lukebakken]

Re-opening because the current API has confused users. We can only change it in 2.0, however, so documentation is necessary.

[laurentb-roy]

Regarding this issue, I think it is fixable without a 2.0, if we do the following

1. Remove the deprecation notice on the Publish() and PublishWithDeferredConfirm(). Their behavior right now are exactly the same as their WithContext variant.
2. Remove the null check on the context in the WithContext publish function so that we can send a unused nil value
3. Carefully document that the WithContext have the exact same behavior as the base function and that the context is not used (what is already planned for the 1.9.1)
4. Update the examples to remove the usage of WithContext function so that beginner are not confused.

Since the right function already exists, we may have "get out of jail free card" for this.

I may try for a PR if the idea seems good. Thoughts?

[Zerpet]

@laurentb-roy I like your proposal. We intended to add context to all channel function in #124, however, we encountered other challenges along the way, see #124 (comment) and #124 (comment)

Happy to review a contribution with the proposed actions.

[Zerpet]

I've opened a PR to address this issue, based on the feedback from @laurentb-roy. Anyone is welcome to provide any comments in the PR #259