declare stream expiration setting ignored

[paulbalomiri]

Describe the bug

Thank you for this admin client, it is very useful for our dev!

The problem i am facing is how to set the data retention period for streams at creation time, and also verify that it's set.

I'll separately also do this by policy as a workaround and sound practice, but this is specific to how the --expiration flag (mandatory) is used. the table below is the markdown output of the stream details.

It does not show anything related to the 12M --expiration set. Omitting the --arguments '{"max-age":"12M"}' does omit themax-age in the output below, but i'm wondering if this setting

• has any effect at all
• if yes how could it be verified that it's set.

name	vhost	queue_type	durable	auto_delete	exclusive	arguments	node	state	leader	members	online	memory	consumer_count	consumer_utilisation	policy	message_bytes	message_count	unacknowledged_message_count
test_stream	test	stream	true	false	false	max-age: "12M"	rabbit@35e9877f3b57	running	rabbit@35e9877f3b57	rabbit@35e9877f3b57	rabbit@35e9877f3b57	0	0	0		0	0	0
						max_length_bytes: 37000
						x-queue-type: "stream"

I could not associate this commit 94ee677 (here is the diff) with any issue.

• the max-age argument does get stored and appears in the listing, but it can have any value. The serrver side logs do not tell anything about this either:

2026-05-01 12:05:24.838339+00:00 rabbit_stream_coordinator: running mnesia update for test_test_stream_1777637124831501688: 
#{
  name => [116,101,115,116,95,116,101,115|...],
  nodes => [rabbit@35e9877f3b57],
  reference => {resource,<<116,101,115,116>>,queue,<<116,101,115,116,...>>},
  leader_pid => <0.5710460.0>,
  leader_node => rabbit@35e9877f3b57,
  replica_nodes => [],
  epoch => 1,
  retention => [],
  event_formatter => {rabbit_stream_queue,format_osiris_event,[{resource,<<116,101,...>>,queue,<<...>>}]},...}","pid":"<0.5717336.0>","domain":"rabbitmq"}

Reproduction steps

First i'm deleting the pre-existing stream

> rabbitmqadmin streams delete --name test_stream --vhost test

then create it:

> rabbitmqadmin streams declare --name test_stream --expiration 12M --max-length-bytes 37000 --arguments '{"max-age":"12M"}'  --vhost test

without the --expiration 12M it errors out

❯ rabbitmqadmin streams declare --name test_stream --max-length-bytes 37000 --arguments '{"max-age":"12M"}'  --vhost test
error: the following required arguments were not provided:
  --expiration <expiration>

Usage: rabbitmqadmin-2.29.0-x86_64-unknown-linux-gnu streams declare --name <name> --expiration <expiration> --max-length-bytes <max_length_bytes> --arguments <arguments> --vhost <vhost>

For more information, try '--help'.

with the --expiration 12M it works, but the output of the show command does not show any such setting

> rabbitmqadmin streams show --vhost test --name test_stream

Expected behavior

the streams show output should:

• confirm the --expiration duration setting
• if it's not effective/in use it should be removed as a CLI arg
• if it's intended to set the max-age argument, it should do that.

i also think that the expiration setting is optional according to the docs, where it's mentioned that Streams grow indefinitely, and only then goes on to tell how this can be prevented by the max size and TTL settings.

Additional context

The Admin api documentation is also rather sparse. I'm assuming that streams are handled together with queues at GET /api/queues ?

[lukebakken]

Thanks for the comprehensive report. I'll take a look.

[paulbalomiri]

It does not show anything related to the 12M --expiration set. Omitting the --arguments '{"max-age":"12M"}' does omit themax-age in the output below, but i'm wondering if this setting

I now realize that the correct argument is --arguments '{"x-max-age":"12M"}' with rabbitmqadmin streams declare, as opposed to setting the max-age policy setting.

Still, the issue with --expiration is distinct

[lukebakken]

The root cause is in the rabbitmq_http_client Rust crate, which rabbitmqadmin v2 depends on. The declare_stream function had three bugs:

1. StreamParams::expiration was never mapped to the x-max-age queue argument - it was silently dropped
2. max_length_bytes was inserted with the wrong key name (max_length_bytes instead of x-max-length-bytes)
3. max_segment_length_bytes was inserted with the wrong key name (max_segment_length_bytes instead of x-stream-max-segment-size-bytes)

The broker silently accepts unknown argument keys, so the API call succeeds but the settings have no effect on stream behavior. This is why the server-side log shows retention => [].

Also worth noting: the workaround --arguments '{"max-age":"12M"}' does not work either, because the broker expects x-max-age (with the x- prefix) as a queue argument. As @paulbalomiri noted in their follow-up comment, --arguments '{"x-max-age":"12M"}' is the correct workaround until this fix is released.

Fix PR: michaelklishin/rabbitmq-http-api-rs#120
Upstream issue: michaelklishin/rabbitmq-http-api-rs#118

Once the fix is released in a new version of rabbitmq_http_client, rabbitmqadmin will need to bump its dependency to pick it up.

[paulbalomiri]

• StreamParams::expiration was never mapped to the x-max-age queue argument - it was silently dropped

Are you open to then also rename the arg from --expiration to --max-age or --max_age ( i think all args are with dash), to match the policy setting and x-max-age given that the x- prefix is a standardish mapping?

Also, if i'm not misreading the api, the x-max-age argument is optional. Perhaps it's an opportunity to make the option non-mandatory, especially given that --expiration has had no effect yet.

[lukebakken]

@paulbalomiri would you mind starting a discussion in this repo with regard to your suggestions? They seem valid to me.

[paulbalomiri]

yes, sure. I've marked it the previous comment as Off-topic, because i reposted that comment in michaelklishin/rabbitmq-http-api-rs#118 (comment).

I'll start a discussion. Would it be ok to make it about formalizing some kind of openapi/swagger definition, for this and the admin api combined, or is that too broad a scope?

[lukebakken]

Would it be ok to make it about formalizing some kind of openapi/swagger definition, for this and the admin api combined, or is that too broad a scope?

That sounds like it's a RabbitMQ thing, yes? If so, start a discussion here: https://github.com/rabbitmq/rabbitmq-server/discussions

I'd suggest searching to see if the "swagger" topic has been brought up already.