Consumer Action API

[Jarema]

Overview

Since nats-server 2.10, Consumer Create API ($JS.API.CONSUMER.CREATE & $JS.API.CONSUMER.DURABLE.CREATE) support action` field.

This allows for clients to specify the intent when calling CREATE, which in turn allows for reduction of CONSUMER.INFO calls by the clients to figure out what to do and what is the state of the server/cluster.

type CreateConsumerRequest struct {
	Stream string         `json:"stream_name"`
	Config ConsumerConfig `json:"config"`
	// a new added field
	Action ConsumerAction `json:"action"`
}

There are three possible values for the action:

- "create"
- "update"
- ""

Empty value (default)

If field is not passed, or it's an empty string, it's the same behavior as before this change was intruduced.
It will create consumer if it was not there, and update it if its found.

Older clients will automatically default to this variant.

create

Consumer will be created only if consumer was not there.
If consumer is present, error 10148 will be returned.

Error will not be returned if the consumer is there, but with exactly the same config.
That allows clients to send a retry without a risk to get misleading errors (timeout after first call, already exist at second).

update

Consumer will be updated.
If consumer does not exist, error 10149 will be returned.

Server PR: https://github.com/nats-io/nats-server/pull/4217/files

Clients and Tools

• Schemas @ripienaar
• CLI @ripienaar
• Terraform @ripienaar
• Github Actions @ripienaar
• Go @piotrpio
• Java @scottf Add support for Consumer Create Action nats.java#1108
• JavaScript @aricart
• .Net @scottf https://github.com/nats-io/nats.net/pull/886
• C @levb
• Python @wallyqs
• Ruby @wallyqs
• Rust @Jarema
• .Net V2 @mtmk

Other Tasks

• docs.nats.io updated @bruth
• Update ADR to Implemented
• Update client features spreadsheet

Client authors please update with your progress. If you open issues in your own repositories as a result of this request, please link them to this one by pasting the issue URL in a comment or main issue description.

[Jarema]

javascript clients: nats-io/nats.deno#552

[Jarema]

go: nats-io/nats.go#1300