search

krakenjs / post-robot

Cross domain post-messaging on the client side using a simple listener/client pattern.
Apache License 2.0
746 stars 91 forks source link

documentation #60

Closed brucou closed 5 years ago

brucou commented 6 years ago

Hi,

I could not find API documentation for post-robot. Is there any official source serving as reference? It is great to have the examples, but it would be good to have a proper reference documentation (including types).

For instance, in the demo postRobot.bridge.openBridge is used but I could not find what that refers to in the README.md.

Also for instance, there is an init channel mentioned in the README which can listened on. I could not figure out whether that init event was an event automatically sent when the iframe has loaded.

Then, if one sends a message to a window, and that window for some reason is not ready, or if one sends message to the window faster than it can process, is there a buffer or alternative back-pressure mechanism set up with post-robot? Or is it expected that messages are sent one by one, after receiving some ACK from the receiver?

If one receives a message, and returns a value, is there also an ACK mechanism to signal that the receiver indeed received the returned value?

Is the secure message channel only created when both domain and window are filled in? cf. https://github.com/krakenjs/post-robot#secure-message-channel

Thanks for the good work, this is a great library

bluepnume commented 5 years ago

For instance, in the demo postRobot.bridge.openBridge is used but I could not find what that refers to in the README.md.

openBridge is documented here: https://github.com/krakenjs/post-robot#parent-to-popup-messaging

Also for instance, there is an init channel mentioned in the README which can listened on. I could not figure out whether that init event was an event automatically sent when the iframe has loaded.

No, init is not a special event. You would need to manually send that message from another window with init as the event name. I've updated the readme to make that clearer.

Then, if one sends a message to a window, and that window for some reason is not ready, or if one sends message to the window faster than it can process, is there a buffer or alternative back-pressure mechanism set up with post-robot?

If the window is the child window of the current window, post-robot will wait for that window to be ready to receive messages before the message is passed over.

Otherwise, if the message fails to send, the promise will be rejected and you can .catch() and handle the error.

If one receives a message, and returns a value, is there also an ACK mechanism to signal that the receiver indeed received the returned value?

No. This is essentially the two generals problem :) https://en.wikipedia.org/wiki/Two_Generals%27_Problem -- if we receive a message from a window, we assume that window is set up to receive a response. That pattern has worked pretty well so far.

Is the secure message channel only created when both domain and window are filled in? cf. https://github.com/krakenjs/post-robot#secure-message-channel

You can check both window and domain, or just one, or neither. Totally up to you.