msg transport - by reference issue

Review the “receiving messages” section of the creating-nodes/node-js documentation and the “Writing a function” subsection of writing-functions. Check the issue’s claims about message references, RED.util.cloneMessage(msg), and property preservation before deciding what guidance is accurate. Done means both sections clearly explain the behavior and its consequences without contradicting each other.

Following discussions elsewhere I made a node called "node-red-contrib-diode" after discovering something I should have known already - that messages are passed by referrence, not by value. This can cause issues as someone may use a message twice in a function - sending it out with node-send and then re-using it. Should the receiving function or node alter the message in any way, because it was sent by reference - this can actually damage the original message. "diode" stops this - but I think this should be clearly pointed out in the documentation.

I found this...

ttp://nodered.org/docs/creating-nodes/node-js
Section "receiving messages"

Suggest you add: "Please note that a reference to the original message is passed here. Altering that message could, in edge cases, affect the calling function."

http://nodered.org/docs/writing-functions
Section "Writing functions"
Subsection "Writing a function"...

You say:

"The returned message object does not need to be same object as was passed in; the function can construct a completely new object before returning it. For example:
var newMsg = { payload: msg.payload.length };
return newMsg;
Note: constructing a new message object will lose any message properties of the received message. This will break some flows, for example the HTTP In/Response flow requires the msg.req and msg.res properties to be preserved end-to-end. In general, function nodes should return the message object they were passed having made any changes to its properties."

So firstly - why would construction a new message lose properties of the old. Using the code DaveCJ provided:

var newMsg = RED.util.cloneMessage(msg);

does not lose any of the original message - I tested it... so you seem to be saying NOT to make a new object - but you don't warn of the consequences. Why not change that example to use the code above which will ensure everything is copied across - scrap the warning that data could be lost and instead tell readers that this might slightly increase overhead - but will eliminate any chance of interaction with the original message.

In my diode node - here you see the unprocessed output - and the output through the node - they are identical down to the msgID - except for the payload which I deliberately altered to show the feedback effect.

msg : Object
{ _msgid: "e5a704f0.1a58f8", topic: "", payload: "goodbye", blah: "fred" }
6/26/2017, 2:31:23 PMnode: d9f3747f.7ef978
msg : Object
{ _msgid: "e5a704f0.1a58f8", topic: "", payload: "hello", blah: "fred" }

Hope this is helpful.