339 lines
14 KiB
HTML
339 lines
14 KiB
HTML
|
<!doctype html>
|
||
|
|
<html>
|
||
|
|
<head>
|
||
|
|
<meta charset="utf-8">
|
||
|
|
<meta http-equiv="X-UA-Compatible" content="chrome=1">
|
||
|
|
<title>Cosmopolite Reference</title>
|
||
|
|
|
||
|
|
<link rel="stylesheet" href="stylesheets/styles.css">
|
||
|
|
<link rel="stylesheet" href="stylesheets/pygment_trac.css">
|
||
|
|
</head>
|
||
|
|
<body>
|
||
|
|
<div class="wrapper">
|
||
|
|
<header>
|
||
|
|
<h1 class="header"><a href="/">Cosmopolite</a></h1>
|
||
|
|
<p class="header">Client/server publish/subscribe, presence and key/value storage for AppEngine</p>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li class="download"><a class="buttons" href="https://github.com/flamingcowtv/cosmopolite/zipball/master">Download ZIP</a></li>
|
||
|
|
<li class="download"><a class="buttons" href="https://github.com/flamingcowtv/cosmopolite/tarball/master">Download TAR</a></li>
|
||
|
|
<li><a class="buttons github" href="https://github.com/flamingcowtv/cosmopolite">View On GitHub</a></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
</header>
|
||
|
|
<section>
|
||
|
|
<h1>
|
||
|
|
<a name="cosmopolite" class="anchor" href="#cosmopolite"><span class="octicon octicon-link"></span></a>Cosmopolite Reference</h1>
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="#terms">Terms</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href="#profile">Profile</a></li>
|
||
|
|
<li><a href="#client">Client</a></li>
|
||
|
|
<li><a href="#instance">Instance</a></li>
|
||
|
|
<li><a href="#channel">Channel</a></li>
|
||
|
|
<li><a href="#subject">Subject</a></li>
|
||
|
|
<li><a href="#subscription">Subscription</a></li>
|
||
|
|
<li><a href="#message">Message</a></li>
|
||
|
|
<li><a href="#pin">Pin</a></li>
|
||
|
|
</ul>
|
||
|
|
</li>
|
||
|
|
|
||
|
|
<li><a href="#callbacks">Callbacks</a>
|
||
|
|
<ul>
|
||
|
|
<li><a href="#onConnect">onConnect</a></li>
|
||
|
|
<li><a href="#onDisconnect">onDisconnect</a></li>
|
||
|
|
<li><a href="#onLogin">onLogin</a></li>
|
||
|
|
<li><a href="#onLogout">onLogout</a></li>
|
||
|
|
<li><a href="#onMessage">onMessage</a></li>
|
||
|
|
<li><a href="#onPin">onPin</a></li>
|
||
|
|
<li><a href="#onUnpin">onUnpin</a></li>
|
||
|
|
</ul>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3><a name="terms">Terms</a></h3>
|
||
|
|
|
||
|
|
<h4><a name="profile">Profile</a></h4>
|
||
|
|
|
||
|
|
<p>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 <a href="#getProfile">getProfile()</a> or
|
||
|
|
<a href="#currentProfile">currentProfile()</a>. Profile information for other users is provided
|
||
|
|
in the <i>sender</i> field of a <a href="#message">Message</a>.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>Logging out changes profiles.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="client">Client</a></h4>
|
||
|
|
|
||
|
|
<p>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 <a href="#profile">profile</a>
|
||
|
|
at any time, but may change associated profiles on log in.</p>
|
||
|
|
|
||
|
|
<p>Logging out generates and stores a new client key.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="instance">Instance</a></h4>
|
||
|
|
|
||
|
|
<p>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
|
||
|
|
<a href="#channel">channel</a> connection is interrupted.</p>
|
||
|
|
|
||
|
|
<p>Instances are used to track <a href="#subscription">Subscriptions</a> and <a href="#pin">Pins</a>
|
||
|
|
which cease to exist (from the server perspective) when a client disconnects.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="channel">Channel</a></h4>
|
||
|
|
|
||
|
|
<p>A channel is the message push connection from the server to the client used to send updates. It
|
||
|
|
uses Google AppEngine's
|
||
|
|
<a href="https://developers.google.com/appengine/docs/python/channel/">Channel service</a>.</p>
|
||
|
|
|
||
|
|
<p>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
|
||
|
|
<a href="#onConnect">onConnect</a> and <a href="#onDisconnect">onDisconnect</a> callbacks.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="subject">Subject</a></h4>
|
||
|
|
|
||
|
|
<p>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 <b>and different</b>
|
||
|
|
subjects:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><code>"foo"</code></li>
|
||
|
|
<li><code>5</code></li>
|
||
|
|
<li><code>{ name: "foo", readable_only_by: "XXXprofileXXX" }</code></li>
|
||
|
|
<li><code>{ name: "foo", writable_only_by: "YYYprofileYYY" }</code></li>
|
||
|
|
<li><code>{ name: "foo", readable_only_by: "XXXprofileXXX", writable_only_by: "YYYprofileYYY" }</code></li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
(where XXXprofileXXX and YYYprofileYYY are profile keys)</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="subscription">Subscription</a></h4>
|
||
|
|
|
||
|
|
<p>A subscription ties an <a href="#instance">instance</a> to a <a href="#subject">subject</a> and
|
||
|
|
requests that the client be kept informed of changes to that subject. Changes that cause
|
||
|
|
notification are:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li>A client sends a <a href="#message">message</a> to the subject.</li>
|
||
|
|
<li>A client adds a <a href="#pin">pin</a> to the subject.</li>
|
||
|
|
<li>A client removes a <a href="#pin">pin</a> from the subject.</li>
|
||
|
|
<li>A client which had previously added a <a href="#pin">pin</a> disconnects. This appears to an
|
||
|
|
observer as if the client had removed the pin.</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
When a new subscription is established, the server sends all active pins and a client-specified
|
||
|
|
subset of historical messages to the client.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>Subscriptions are created by the application using the <a href="#subscribe">subscribe()</a>
|
||
|
|
method.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="message">Message</a></h4>
|
||
|
|
|
||
|
|
<p>A message is a piece of information sent by a <a href="#client">client</a> to a
|
||
|
|
<a href="#subject">subject</a>. It is stored by the server and transmitted to any clients currently
|
||
|
|
<a href="#subscription">subscribing</a> to that subject.</p>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>When a message is received (via the <a href="#onMessage">onMessage callback</a> or the return
|
||
|
|
result from <a href="#getMessages">getMessages()</a> or
|
||
|
|
<a href="#getLastMessage">getLastMessage()</a>), metadata is attached, packaged into an object with
|
||
|
|
the message data itself:
|
||
|
|
|
||
|
|
<pre>{
|
||
|
|
<comment>// Server-assigned sequence number</comment>
|
||
|
|
"id": 1,
|
||
|
|
|
||
|
|
<comment>// Type may also be <a href="#pin">"pin"</a></comment>
|
||
|
|
"event_type": "message",
|
||
|
|
|
||
|
|
<comment>// Sender-assigned UUID</comment>
|
||
|
|
"sender_message_id": "cbdae48d-7a02-4850-208c-986b18121b9c",
|
||
|
|
|
||
|
|
<comment>// Canonical subject that message was sent to</comment>
|
||
|
|
"subject": {
|
||
|
|
"name": "foobar"
|
||
|
|
},
|
||
|
|
|
||
|
|
<comment>// Server-recorded UNIX timestamp that the server received the message</comment>
|
||
|
|
"created": 1402212355.0,
|
||
|
|
|
||
|
|
<comment>// Deserialized message data</comment>
|
||
|
|
"message": "test",
|
||
|
|
|
||
|
|
<comment>// <a href="#profile">Profile</a> key of sender</comment>
|
||
|
|
"sender": "XXXprofileXXX"
|
||
|
|
}</pre></p>
|
||
|
|
|
||
|
|
<p>Messages are sent by the application using the <a href="#sendMessage">sendMessage()</a>
|
||
|
|
method.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="pin">Pin</a></h4>
|
||
|
|
|
||
|
|
<p>A pin is a <a href="#message">message</a> that is deleted when the
|
||
|
|
<a href="#instance">instance</a> that sent it disconnects. Subscribers to the pin's
|
||
|
|
<a href="#subject">subject</a> are notified (via the <a href="#onPin">onPin</a> and
|
||
|
|
<a href="#onUnpin">onUnpin</a> callbacks) when it is added and deleted. This allows pins to be
|
||
|
|
used for presence detection.</p>
|
||
|
|
|
||
|
|
<p>Pins are added and deleted by the application using the <a href="#pin_method">pin()</a>
|
||
|
|
and <a href="#unpin">unpin()</a> methods.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h3><a name="callbacks">Callbacks</a></h3>
|
||
|
|
|
||
|
|
Callbacks are used by the Cosmopolite client library to notify the application of events. Callbacks
|
||
|
|
are passed to the Cosmopolite constructor in an object. The object itself and all callbacks are
|
||
|
|
optional.
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="onConnect">onConnect</a></h4>
|
||
|
|
|
||
|
|
<p>Arguments: <i>none</i></p>
|
||
|
|
|
||
|
|
<p>The onConnect callback is called when the <a href="#channel">channel</a> is established to the
|
||
|
|
server. It is paired with the <a href="#onDisconnect">onDisconnect</a> callback except when
|
||
|
|
<a href="#shutdown">shutdown()</a> is called.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="onDisconnect">onDisconnect</a></h4>
|
||
|
|
|
||
|
|
<p>Arguments: <i>none</i></p>
|
||
|
|
|
||
|
|
<p>The onDisconnect callback is called when the <a href="#channel">channel</a> is disconnected.
|
||
|
|
This can happen due to connectivity problems, server outages or periodically when the channel
|
||
|
|
expires.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="onLogin">onLogin</a></h4>
|
||
|
|
|
||
|
|
<p>Arguments:
|
||
|
|
<ol>
|
||
|
|
<li><code>username</code>: The user's Google username string.</li>
|
||
|
|
<li><code>logout_url</code>: A URL that the user can load to terminate their session. This should
|
||
|
|
be opened in a new window (using <code>target="_blank"</code>).</li>
|
||
|
|
</ol></p>
|
||
|
|
|
||
|
|
<p>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 <a href="#onLogout">onLogout</a> is called after the first RPC succeeds.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="onLogout">onLogout</a></h4>
|
||
|
|
|
||
|
|
<p>Arguments:
|
||
|
|
<ol>
|
||
|
|
<li><code>login_url</code>: A URL that the user cna load to log in to their Google account. This
|
||
|
|
should be opened in a new window (using <code>target="_blank"</code>).</li>
|
||
|
|
</ol></p>
|
||
|
|
|
||
|
|
<p>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 <a href="#onLogin">onLogin</a> or onLogout is called after the first RPC
|
||
|
|
succeeds.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="onMessage">onMessage</a></h4>
|
||
|
|
|
||
|
|
<p>Arguments:
|
||
|
|
<ol>
|
||
|
|
<li><code>message</code>: A <a href="#message">message</a> object including metadata and message
|
||
|
|
content.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p>The onMessage callback is called when a historical or new message is received from the server.
|
||
|
|
It is only called for <a href="#subject">subjects</a> that the client is currently subscribed to.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>After a call to <a href="#subscribe">subscribe()</a>, 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.</p>
|
||
|
|
|
||
|
|
<p>Calling <a href="#subscribe">subscribe()</a> more than once may lead to additional historical
|
||
|
|
messages being retreived. onMessage will not fire twice for the same message unless
|
||
|
|
<a href="#unsubscribe">unsubscribe()</a> is called in the interim.</p>
|
||
|
|
|
||
|
|
<p>onMessage fires for messages sent by our own <a href="#profile">profile</a> and
|
||
|
|
<a href="#client">client</a>. You can filter messages by comparing their sender field to the return
|
||
|
|
value of <a href="#currentProfile">currentProfile()</a> to avoid processing your own messages.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="onPin">onPin</a></h4>
|
||
|
|
|
||
|
|
<p>Arguments:
|
||
|
|
<ol>
|
||
|
|
<li><code>message</code>: A <a href="#message">message</a> object including metadata and message
|
||
|
|
content.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p>The onPin callback is called when a new pin is received from the server. It is only called for
|
||
|
|
<a href="#subject">subjects</a> that the client is currently subscribed to.</p>
|
||
|
|
|
||
|
|
<p>After a call to <a href="#subscribe">subscribe()</a>, 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.</p>
|
||
|
|
|
||
|
|
<p>onPin callbacks are paired with <a href="#onUnpin">onUnpin</a> callbacks except when
|
||
|
|
<a href="#shutdown">shutdown()</a> is called.</p>
|
||
|
|
|
||
|
|
<p>onPin fires for pins from own <a href="#profile">profile</a> and <a href="#client">client</a>.
|
||
|
|
You can filter pins by comparing their sender field to the return value of
|
||
|
|
<a href="#currentProfile">currentProfile()</a> to avoid processing your own pins.</p>
|
||
|
|
|
||
|
|
|
||
|
|
<h4><a name="onUnpin">onUnpin</a></h4>
|
||
|
|
|
||
|
|
<p>Arguments:
|
||
|
|
<ol>
|
||
|
|
<li><code>message</code>: A <a href="#message">message</a> object including metadata and message
|
||
|
|
content.</li>
|
||
|
|
</ol>
|
||
|
|
|
||
|
|
<p>The onUnpin callback is called when a pin is deleted on from the server. It is also called when
|
||
|
|
the <a href="#channel">channel</a> disconnects from the server, hence the server state of pins is
|
||
|
|
unknown.</p>
|
||
|
|
|
||
|
|
<p>onUnpin callbacks are paired with <a href="#onPin">onPin</a> callbacks except when
|
||
|
|
<a href="#shutdown">shutdown()</a> is called.</p>
|
||
|
|
|
||
|
|
<p>onUnpin fires for pins from own <a href="#profile">profile</a> and <a href="#client">client</a>.
|
||
|
|
You can filter pins by comparing their sender field to the return value of
|
||
|
|
<a href="#currentProfile">currentProfile()</a> to avoid processing your own pins.</p>
|
||
|
|
|
||
|
|
</section>
|
||
|
|
</div>
|
||
|
|
<script>
|
||
|
|
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
|
||
|
|
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
|
||
|
|
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
|
||
|
|
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
|
||
|
|
|
||
|
|
ga('create', 'UA-37845853-2', 'auto');
|
||
|
|
ga('send', 'pageview');
|
||
|
|
|
||
|
|
</script>
|
||
|
|
</body>
|
||
|
|
</html>
|