Flesh out implementation of user to user messages

[jordoh]

These commits flesh out the implementation of the private messaging functionality, which can help simplify implementations of one-to-one publishing. The main changes are:

• The "message" web hook is now passed the sender's cookies, and both the sender and recipient user names. This allows the web hook to perform validation on the sending user based on the cookie data.
• The message frame is delivered to the recipient, then to the sender as well. This addresses one of the difficulties in implementing private messaging using a single dedicated channel per user, where there is not a particularly good way to echo the message back to the sender.
• User#send_message now calls the web hook for all requests.

The second and third changes listed above could benefit from some additional configuration options at the user level (i.e.: returned along with the "name" option from the connect web hook). However, they are not included in these changes as they would require some larger additions to User. They are:

• "reflective" - whether messages sent by this user should be sent back to the user.
• "moderated_message" whether the web hook should be called when this user tries to send a message.

[mcarter]

I pulled in the these changes, thanks!

I wonder, could we just put the "reflective" option on the response of the message webhook -- maybe just call it "reflect" ? This gives us reflection on a per-message basis, but it doesn't give us a way to turn reflective on for the whole user, which would be most useful if we turned off moderated_message... thoughts?

[jordoh]

Okay - I took a stab at adding options to the User. I'm not sure I like it, as it duplicates a lot of code from Channel#update_options, but it does add the two options so at least it is configurable.

I wasn't sure about the web hook returning "reflect", since as you mention, it wouldn't be very useful with moderation turned off (and I wasn't sure if there were similar precedents in other web hooks).

[mcarter]

Yeah, the option handling duplication is a bit annoying. I can't help but feel like that whole awful mess of TODOs could be rewritten in like 2 lines. I mean, I bet python has some kind of "deepcopy" somewhere that could make that much more straightforward.

Despite that, this seems like a good change. I would further recommend that you 1) add a way to do update these user options via the api (by modifying api/internal.py and api/web.py .) 2) Modify the docs for webhooks and web api to include these changes.

It seems like you know your way around the code pretty well; nice work, and Thanks!

p.s. Consider joining the google group as well.

[jordoh]

Updated with both your suggestions, though I was unable to build the sphinx documentation correctly (before my changes) - they contain an Mako runtime error stating "TypeError: 'Undefined' object is not callable" (Mako-0.3.5-py2.6 on OS X).

[jordoh]

Re-opened to add an additional commit:

The webhook for message is now called even if the receiving user name is not a valid user name. The form posted to the webhook includes a "recipient_exists" field, which indicates whether the recipient is a connected user. The existing behavior when the webhook is used can be achieved by returning { "error": "Invalid user name" } from the webhook if the "recipient_exists" field is false. If there is no webhook used for the message callback, sending a message to a non-existent user will result in an "Invalid user name" error, as before. This is particularly useful in the use case of a chat client with private messaging where the message webhook saves the message to a database, even if the receiver is not currently online.

Additionally, the message webhook can return an "override_recipient_name" to specify a different user name to deliver the message to. This is useful when the JavaScript client does not know the exact user name of the receiving user, in which case the application called by the webhook can determine the receiving user name based on some other criteria.

[mcarter]

Looks good; I pulled the change in.

[jordoh]

Re-opened to add one more commit.