Naming changes for consistency and ability to publish a NATS::Message

[samueleaton]

There were interchangeable uses of "message", "body", and "data" referring
to the message payload data. This change conforms to the NATS protocol
which uses "message" as the encompassing message (headers + payload), and
"payload" as the primary data.

Also adds another publish method that takes a NATS::Message struct and
pipes it to the existing publish method

[samueleaton]

I'm making NATS a more central part of a service I'm working on and its nice to pass around NATS::Message or return new ones from functions so that other functions can then send in a reply or publish. Some encapsulation.

[jgaskins]

Yeah, I don't mind this change. It seems all the first-party clients have this form of this method. The Go client seems to only have this form, even.

[jgaskins]

Making the naming (especially for this very specific thing) more consistent is something I've been meaning to do, tbh. I don't even remember where I got body from because I don't think they use it at all in the first-party clients. They seem to use data as the name for the payload, though:

• Go
• Ruby
• Rust

Aligning more with what the first-party clients are doing (specifically the Go client) is what the Synadia folks are recommending these days now that they've all gotten more standardized. Could you swap the name over to data to match those clients?

[samueleaton]

yeah good call, found it here as Data. will change.

[samueleaton]

its common for methods in crystal to use raw for the, eh-hem, more raw representation. how about #raw_data is the bytes, and #data does a lazy stringify.

[samueleaton]

I kept the internal alias name as Payload because data : Data in the function signature seems a little ambiguous. The Go client uses "payload" several times when needed for clarity.

[samueleaton]

still have to fix some specs

[samueleaton]

all specs pass

[jgaskins]

its common for methods in crystal to use raw for the, eh-hem, more raw representation. how about #raw_data is the bytes, and #data does a lazy stringify.

I really like the lazy stringification to reduce heap allocations when bytes are acceptable. I'm not sure if data/raw_data is the right naming to use, though. Your example doesn't show any raw_* methods that deal with Bytes and Crystal does have conventions where the undecorated name deals with Bytes and the string version is suffixed with _string. For example, in Base64:

Also, IO#read populates Bytes and read_string returns a String.

I'm also trying to consider it from the perspective of what serialization formats most people would use in case it makes sense for the most common format to use the name that's easier to type. I'm not sure, though. NATS JetStream uses JSON internally, where String would be a good default, but also I could imagine a lot of folks are using binary serialization formats to save on bytes over the wire (especially since message size in NATS has a hard limit), CPU time consumed, and memory.

[samueleaton]

right, whichever naming you prefer is fine. I'm having to write a lot of String.new msg.body all over the place so a condensed, lazily parsed shorthand would be improved UX.

Although since its lazily parsed and then cached, I would expect as a user for read_string to be re-parsing it even though its not.

IMO users don't need to know about the internal implementation that we're converting a Bytes to a String. The encoding is an implementation detail. Imagine having to call .read_gzip_to_string on an http client instead of it assuming it will take care of that for me. haha 😆

[jgaskins]

@samueleaton If you want to change these up to be data : Bytes and data_string : String, I'll go ahead and merge.