[Improve][Producer] normalize and export the errors

[gunli]

(If this PR fixes a github issue, please add Fixes #<xyz>.)

Fixes #

(or if this PR is one task of a github issue, please add Master Issue: #<xyz> to link to the master issue.)

Master Issue: #

Motivation

Currently, producing retrying is not implemented by the client, when I want to retry, it depends on the errors returned by the callback, some errors can retry, some should stop and fail fast(for example the queue is full), but the errors are not normalized and exported now, this PR normalize and export the errors of the producer.

Modifications

1. export the errors:

        ErrFailAddToBatch     = newError(AddToBatchFailed, "message add to batch failed")
	ErrSendTimeout        = newError(TimeoutError, "message send timeout")
	ErrSendQueueIsFull    = newError(ProducerQueueIsFull, "producer send queue is full")
	ErrContextExpired     = newError(TimeoutError, "message send context expired")
	ErrMessageTooLarge    = newError(MessageTooBig, "message size exceeds MaxMessageSize")
	ErrMetaTooLarge       = newError(InvalidMessage, "message metadata size exceeds MaxMessageSize")
	ErrProducerClosed     = newError(ProducerClosed, "producer already been closed")
	ErrMemoryBufferIsFull = newError(ClientMemoryBufferIsFull, "client memory buffer is full")
	ErrSchema                  = newError(SchemaFailure, "schema error")
	ErrTransaction        = newError(TransactionNoFoundError, "transaction error")
	ErrInvalidMessage     = newError(InvalidMessage, "invalid message")
	ErrTopicNotfound      = newError(TopicNotFound, "topic not found")
	ErrTopicTerminated    = newError(TopicTerminated, "topic terminated")
	ErrProducerBlocked    = newError(ProducerBlockedQuotaExceededException, "producer blocked")
	ErrProducerFenced     = newError(ProducerFenced, "producer fenced")

2. add a joinErrors(errs ...errors) to join errors:

// joinErrors can join multiple errors into one error, and the returned error can be tested by errors.Is()
// we use github.com/hashicorp/go-multierror instead of errors.Join() of Go 1.20 so that we can compile pulsar
// go client with go versions that newer than go 1.13
func joinErrors(errs ...error) error {
	return multierror.Append(nil, errs...)
}

3. In the application code, use errors.Is(err, pulsar.ErrChema) to determine if an error can retry or not;

Verifying this change

• Make sure that the change passes the CI checks.

(Please pick either of the following options)

This change is a trivial rework / code cleanup without any test coverage.

(or)

This change is already covered by existing tests, such as (please describe tests).

(or)

This change added tests and can be verified as follows:

(example:)

• Added integration tests for end-to-end deployment with large payloads (10MB)
• Extended integration test for recovery after broker failure

Does this pull request potentially affect one of the following parts:

If yes was chosen, please highlight the changes

• Dependencies (does it add or upgrade a dependency): (yes / no)
• The public API: (no)
• The schema: (yes / no / don't know)
• The default values of configurations: (yes / no)
• The wire protocol: (yes / no)

Documentation

• Does this pull request introduce a new feature? (yes / no)
• If yes, how is the feature documented? (not applicable / docs / GoDocs / not documented)
• If a feature is not applicable for documentation, explain why?
• If a feature is not documented yet in this PR, please create a followup issue for adding the documentation

[RobertIndie]

Overall looks good to me.

This is a major change. Could you upgrade the Go version in another PR?

[gunli]

@RobertIndie If I upgrade it in another PR, this PR will fail the CI, and the CI is failed now, may be I should update the go version in ci.yml either:

go-version: [1.16, 1.17, 1.18, 1.19]

[RobertIndie]

This will break the CI and will break the compatibility for the older go version. Could you implement it another way? Or do you think there is a strong motivation that we need to upgrade the go version?

[gunli]

I didn't mean to upgrade the go version, it just so happends that I use go 1.20 at the same time, I implement this is PR just in the purpose of retrying and when I test my retrying demo and found that I can not retry all the failed requests, some errors should fail fast instead of retrying(.e.g ErrSendQueueIsFull).

And I just found #1142 today, and found that this is a common requirement. I've checked the 3rd party packages, "https://github.com/cockroachdb/errors" require go 1.19, "https://github.com/hashicorp/go-multierror" has a different package name multierror, "https://github.com/uber-go/multierr" require go 1.20.

For the sake of compatibility, may be the simplest way is to implement errors.Join() in pulsar-client-go, what I mean is to copy the code in go SDK into our package, I will try that tomorrow.

[gunli]

@RobertIndie I have updated this PR and use "github.com/hashicorp/go-multierror" to join errors instead of errors.Join() of Go 1.20, would you PTAL at again?

Also cc @tisonkun @nodece @WoWsj! @Gleiphir2769

[nodece]

Reviewed.

[nodece]

fmt.Errorf("component error: %w", err) is also a good idea to wrap the error, and it works with errors.Is().

%w introduced by Go 1.30, see https://pkg.go.dev/[email protected] and https://stackoverflow.com/questions/61283248/format-errors-in-go-s-v-or-w

[nodece]

LGTM