Lack of separation of Core NATS/JetStream API is confusing

[cedws]

I'm a bit confused about the API and could use some clarification.

There's the jetstream package which is for consuming/publishing messages on JetStream. But as far as I can tell, the main nats.go package can also be used to publish on JetStream. I guess this kind of makes sense in a way because JetStream is simply a server side configuration on top of Core NATS.

I'm also confused that the Core NATS package has methods like Nak() and Term() for the nats.Msg type. Obviously, Core NATS has no redelivery, so I'm not sure why these methods are implemented for the Core NATS message type.

I tested what happens if you Nak() a Core NATS request and IIRC it just returned a string that looked like +NAK to the requester. There were no headers to indicate this was a special 'sentinel' value. It seems like a massive footgun if the requester expects the payload to be JSON or something - how are you supposed to handle this sentinel value?

The Go docs for the Core NATS package doesn't mention anything or warn about the above - that Nak() and Term() makes no sense for Core NATS messages and could break things by unexpectedly sending a payload.

The original problem I was trying to solve was indicating an error handling a request (received via request-reply). As far as I can tell the library cannot help with this - it must be implemented in application using a Status header or something. This isn't necessarily a problem but in our case it necessitates building our own wrapper library.

In my opinion the nats.go package mixes Core NATS and JetStream APIs together in a confusing and fragile way. Is there something I can use that separates them more distinctly?

Thanks in advance.

[Jarema]

The jetstream package was added when we iterated over the jetstream API and decided that not only it needs improvements, but it should also be separated.

You pointed out quite few of the reasons we had in our minds too - like Nak on Core NATS message.

However, we cannot just remove the old code, as the userbase of the old implementation is huge and that would be a major breaking change, so instead we added deprecation notices whenever it made sense around the old API. Maybe we should add a bit more.

Hope that this clears out why the Core NATS has JS api in it.

[cedws]

Thank you for the fast response.

Are there any plans on the horizon to deprecate these methods in the Core NATS lib?

[Jarema]

We are very careful about breaking any users/customers, so we might be adding more deprecation notices, but we won't remove them until next major client release (which is currently not on any roadmap).