more breaking changes to cloud.google.com/go/pubsub

[Jonathan Amsterdam]

The second set of breaking Pub/Sub changes has landed, as I mentioned it would in last week's announcement. To avoid being affected, vendor to hash 2e6a95edb1071d750f6d7db777bf66cd2997af6c or tag v0.7.0.

There are two changes this week. The first is simple: Message.Done has been replaced by two functions, Message.Ack and Message.Nack.

Instead of writing

   msg.Done(true)

write

    msg.Ack()

Similarly, replace msg.Done(false) with msg.Nack().

We made this change because there may be other ways in the future for subscribers to communicate message status to the Pub/Sub service, and now we can support them without a breaking change by adding more methods to Message.

The second change is bigger. Instead of calling Subscription.Pull and getting an iterator, you call Subscription.Receive with a callback. So where you now have

   it, err := sub.Pull(ctx)

   if err != nil {...}

   for {

        m, err := it.Next()

        if err {...}

        process(m)

        m.Done(true)

    }

you'll instead write

    err := sub.Receive(ctx, func(ctx context.Context, m *Message) {

        process(m)

        m.Ack()

    })

Receive blocks indefinitely, so cancel its context if you want to end it early.

Instead of configuring a call to Pull with PullOptions, you set fields in Subscription.ReceiveSettings. MaxExtension hasn't changed, but the job of MaxPrefetch is now taken over by MaxOutstandingMessages.

Why the change from an iterator to a callback? To provide good performance out of the box. Subscription.Receive invokes the callback in a new goroutine for each message, so even if the callback takes a while, throughput should be high. So don't feel that your callbacks have to complete quickly and pass the heavy lifting off to another goroutine—they can take their time. (Use the MaxOutstandingMessages and MaxOutstandingBytes settings to avoid spawning too many goroutines.) Your callbacks do have to be careful about accessing shared memory, since they will run concurrently.