Add replay policy option for stream sub

[Zambito1]

Adds --replay=instant and --replay=original to nats sub --stream=...

[ripienaar]

Thanks for the contribution, I think though its a slippery slope - down this path lies adding every one of the "consumer add" options and its a lot and overly complicates the sub command.

I think its better to keep this one a bit minimal but - as it already supports - allow for binding to a pre-created consumer for cases that need special handling.

[Zambito1]

From a users perspective, it seems convenient to be able to subscribe to a stream without worrying about pre-creating a consumer and then binding to it. It would probably be better to create a single place where consumer arguments are handled and then use that from the consumer add as well as the sub subcommands, but I do think it makes sense to have in both places.

For what it's worth, the reason I implemented this was to be able to use the other options available for nats sub (specifically --translate) with the original replay policy, which there does not seem to be a way to do currently. I also tried nats c sub and nats c next, but both of them were terminating after getting one message at a time, and neither would let me --translate. I'm not sure if only getting one message at a time for c sub is a bug or if that is the expected behavior, but either way there did not seem to be a way to sub with an original replay policy, and it seems like there should be

[ripienaar]

We certainly do need to redesign some of this - especially c next and c sub needs to go - but I dont think adding all the settings here is a great idea. It's just too much and while I agree it's nice to be able to do it, we also have to think about just presenting massive walls of options to everyone in all places. Especially ones like this one that's quite infrequently used.

[Zambito1]

I was thinking about how to present the help output if all of the consumer options were also available for nats sub; I think it would make sense to break it out into multiple sections, like how the subcommand flags and the global flags are already broken out. Something like this (not verbatim, I used an llm to generate this to convey the idea):

Flags:
      --queue=QUEUE              Subscribe to a named queue group
  -r, --raw                      Show the raw data received
      --translate=TRANSLATE      Translate the message data by running it through the
                                 given command before output
      --[no-]ack                 Acknowledge JetStream message that have the correct
                                 metadata
      --match-replies            Match replies to requests
  -i, --inbox                    Subscribes to a generate inbox
      --count=COUNT              Quit after receiving this many messages
      --dump=DIRECTORY           Dump received messages to files, 1 file per message.
                                 Specify - for null terminated STDOUT for use with
                                 xargs -0
      --headers-only             Do not render any data, shows only headers
      --subjects-only            Prints only the messages' subjects
      --ignore-subject=SUBJECT ...   Subjects for which corresponding messages will be
                                 ignored and therefore not shown in the output
      --wait=WAIT                Unsubscribe after this amount of time without any
                                 traffic
      --report-subjects          Subscribes to subject patterns and builds a
                                 de-duplicated report of active subjects receiving
                                 data
      --report-subscriptions     Subscribes to subject patterns and builds a
                                 de-duplicated report of active subscriptions
                                 receiving data
      --report-top=10            Number of subjects to show when doing
                                 'report-subjects'. Default is 10.
  -t, --timestamp                Show timestamps in output
  -d, --delta-time               Show time since start in output
      --graph                    Graph the rate of messages received

JetStream Flags:
      --start-sequence=SEQUENCE  Starts at a specific Stream sequence (requires JetStream)
      --all                      Delivers all messages found in the Stream (requires JetStream)
      --new                      Delivers only future messages (requires JetStream)
      --last                     Delivers the most recent and all future messages
                                 (requires JetStream)
      --since=DURATION           Delivers messages received since a duration like 1d3h5m2s(requires JetStream)
      --last-per-subject         Deliver the most recent messages for each subject in
                                 the Stream (requires JetStream)
      --stream=STREAM            Subscribe to a specific stream (required JetStream)
      --durable-name=NAME        Name of the durable consumer (requires JetStream)
      --deliver-group=GROUP      Delivery group name for the consumer (requires JetStream)
      --ack-policy=AckPolicy     Acknowledgment policy for the consumer (requires JetStream)
      --replay-policy=ReplayPolicy Replay policy for the consumer (requires JetStream)
      --filter-subject=SUBJECT   Subject filter for the consumer (requires JetStream)
      --config-file=FILE         Configuration file for the consumer (requires JetStream)

Global Flags:
  -h, --help                    Show context-sensitive help
      --version                 Show application version.
  -s, --server=URL              NATS server urls ($NATS_URL)
      --user=USER               Username or Token ($NATS_USER)
      --password=PASSWORD       Password ($NATS_PASSWORD)
      --connection-name=NAME    Nickname to use for the underlying NATS Connection
      --timeout=DURATION        Time to wait on responses from NATS ($NATS_TIMEOUT)
      --socks-proxy=PROXY       SOCKS5 proxy for connecting to NATS server
                                ($NATS_SOCKS_PROXY)
      --js-api-prefix=PREFIX    Subject prefix for JetStream API interactions
      --context=NAME            Configuration context ($NATS_CONTEXT)
      --trace                   Trace API interactions
      --no-context              Disable the selected context

[ripienaar]

While yes that would be an improvement, the library we use for CLI handling doesn't support that kind of thing at present.

It would also be a huge amount of duplication.

Not against the idea per se, just with current code I am not ready to do that. We have a big release coming up soon and after I want to revisit a number of the sub command and modernise them, could keep it in mind for then. For now I'll rather park this one for later.