Client/server publish/subscribe, presence and key/value storage for AppEngine
Client/server publish/subscribe, presence and key/value storage for AppEngine
+ +A profile is a collection of clients that all speak as the same user, and so should appear as the +same to subscribers. Profiles are identified by a string key assigned by the server. Clients can +fetch their own profile by calling getProfile() or +currentProfile(). Profile information for other users is provided +in the sender field of a Message.
+ +A client keeps its profile when it logs in to a Google account, accept if that account is +already associated with a different profile. In that case, messages that were sent using the old +profile are re-assigned to the profile associated with the logged in user.
+ +Logging out changes profiles.
+ +The profile key is passed to Google Analytics (if enabled) as the userId, so sessions from +different clients across different browsers are associated with the same user for analytics +purposes.
+ + +A client is a persistent identifier for a given browser. It is identified by a string key +generated by the client and stored in localStorage, so it is persistent across restarts (except in +incognito mode or the like). A client is associated with exactly one profile +at any time, but may change associated profiles on log in.
+ +Logging out generates and stores a new client key.
+ + +An instance is a persistent identifier for a single connection to the server. It is generated +when a new Cosmopolite instance is constructed or whenever the server -> client +channel connection is interrupted.
+ +Instances are used to track Subscriptions and Pins +which cease to exist (from the server perspective) when a client disconnects.
+ + +A channel is the message push connection from the server to the client used to send updates. It +uses Google AppEngine's +Channel service.
+ +In addition to message passing, the channel library also provides notification of connection +state to the server. This is passed to the application code using the +onConnect and onDisconnect callbacks.
+ + +A subject is a topic that clients publish and subscribe to. Subjects may be strings, numbers +or objects with access control information embedded. The follow are all valid and different +subjects: + +
"foo"5{ name: "foo", readable_only_by: "XXXprofileXXX" }{ name: "foo", writable_only_by: "YYYprofileYYY" }{ name: "foo", readable_only_by: "XXXprofileXXX", writable_only_by: "YYYprofileYYY" }A subscription ties an instance to a subject and +requests that the client be kept informed of changes to that subject. Changes that cause +notification are: + +
Subscriptions are automatically destroyed on the server side when an instance disconnects. The +client library keeps lists of subjects and the last messages seen from them and automatically +re-subscribes after reconnection. This process is transparent to application code.
+ +Subscriptions are created by the application using the subscribe() +method.
+ + +A message is a piece of information sent by a client to a +subject. It is stored by the server and transmitted to any clients currently +subscribing to that subject.
+ +A message can consist of any type that is serializable in JSON: numbers, booleans, strings, +null, arrays and objects composed of these values (or of other arrays and objects). Serialization +and deserialization is handled by Cosmopolite.
+ +When a message is received (via the onMessage callback or the return +result from getMessages() or +getLastMessage()), metadata is attached, packaged into an object with +the message data itself: + +
{
+ // Server-assigned sequence number
+ "id": 1,
+
+ // Type may also be "pin"
+ "event_type": "message",
+
+ // Sender-assigned UUID
+ "sender_message_id": "cbdae48d-7a02-4850-208c-986b18121b9c",
+
+ // Canonical subject that message was sent to
+ "subject": {
+ "name": "foobar"
+ },
+
+ // Server-recorded UNIX timestamp that the server received the message
+ "created": 1402212355.0,
+
+ // Deserialized message data
+ "message": "test",
+
+ // Profile key of sender
+ "sender": "XXXprofileXXX"
+}
+
+Messages are sent by the application using the sendMessage() +method.
+ + +A pin is a message that is deleted when the +instance that sent it disconnects. Subscribers to the pin's +subject are notified (via the onPin and +onUnpin callbacks) when it is added and deleted. This allows pins to be +used for presence detection.
+ +Pins are added and deleted by the application using the pin() +and unpin() methods.
+ + +Arguments: none
+ +The onConnect callback is called when the channel is established to the +server. It is paired with the onDisconnect callback except when +shutdown() is called.
+ + +Arguments: none
+ +The onDisconnect callback is called when the channel is disconnected. +This can happen due to connectivity problems, server outages or periodically when the channel +expires.
+ + +Arguments: +
username: The user's Google username string.logout_url: A URL that the user can load to terminate their session. This should
+ be opened in a new window (using target="_blank").The onLogin callback is called when the user logs in. It is also called after the first RPC +to the server succeeds if the user was already logged in. It is guaranteed that either onLogin +or onLogout is called after the first RPC succeeds.
+ + +Arguments: +
login_url: A URL that the user cna load to log in to their Google account. This
+ should be opened in a new window (using target="_blank").The onLogin callback is called when the user logs out or is logged out by Google. It is also +called after the first RPC to the server succeeds if the user was not already logged in. It is +guaranteed that either onLogin or onLogout is called after the first RPC +succeeds.
+ + +Arguments: +
message: A message object including metadata and message
+ content.The onMessage callback is called when a historical or new message is received from the server. +It is only called for subjects that the client is currently subscribed to. +
+ +After a call to subscribe(), onMessage fires once for each historical +message received from the server. After all historical messages have been processed, the resolve +callback for the Promise returned by subscribe() is called. Any onMessage events after that point +are for new messages.
+ +Calling subscribe() more than once may lead to additional historical +messages being retreived. onMessage will not fire twice for the same message unless +unsubscribe() is called in the interim.
+ +onMessage fires for messages sent by our own profile and +client. You can filter messages by comparing their sender field to the return +value of currentProfile() to avoid processing your own messages.
+ + +Arguments: +
message: A message object including metadata and message
+ content.The onPin callback is called when a new pin is received from the server. It is only called for +subjects that the client is currently subscribed to.
+ +After a call to subscribe(), onPin fires once for each pin already +present in the subject. After all standing pins have been processed, the resolve callback for the +Promise returned by subscribe() is called. Any onPin events after that point are for new pins.
+ +onPin callbacks are paired with onUnpin callbacks except when +shutdown() is called.
+ +onPin fires for pins from own profile and client. +You can filter pins by comparing their sender field to the return value of +currentProfile() to avoid processing your own pins.
+ + +Arguments: +
message: A message object including metadata and message
+ content.The onUnpin callback is called when a pin is deleted on from the server. It is also called when +the channel disconnects from the server, hence the server state of pins is +unknown.
+ +onUnpin callbacks are paired with onPin callbacks except when +shutdown() is called.
+ +onUnpin fires for pins from own profile and client. +You can filter pins by comparing their sender field to the return value of +currentProfile() to avoid processing your own pins.
+ +Client/server publish/subscribe, presence and key/value storage for AppEngine