Stateful API¶
Unlike in low-level API stateful API has the following goals:
- Seamlessly reconnect websocket (except “reconnecting…” label)
- Keep data updated on reconnect:
- Current values might be updated on server, receive them
- Things subscribed on client should be subscribed again
- Unsubscribe at any time
Look-a-like¶
Here is the example request to subscribe for simple pub-sub channel:
componentDidMount() {
this.guard = swindon.guard()
.init('notifications.subscribe', [mytopic])
.listen('notifications.'+mytopic, message => {
this.setState(message.n_notifications)
})
.deinit('notifications.unsubscribe', [mytopic])
this.guard.on_init(response => {
this.setState({'nmessages': response.n_notifications}))
})
}
componentWillUnmount() {
this.guard.close()
}
The notifications.subscribe
will be called again on every reconnect, and
notifications.xxx
subscription is local, and will be put before the request
is sent (this leaves no opportunity to miss messages).
API Description¶
-
class
_Guard
¶ A class returned by
swindon.guard()
. It follows “fluent” pattern on every method (exceptclose()
), which means every method returnsthis
, and method calls are chainable.-
init
(method_name, args=[], kwargs={}, callback=null)¶ Call the server method
method_name
as part of guard initialization. Basically this means call the method wheninit()
called and every time connection is establishes, until guard is closed.Except being called on each reconnect and that it returns guard, it resembles semantics of
Swindon.call()
.callback
is a function called with result of method call. It may be called multiple times.
-
deinit
(method_name, args=[], kwargs={}, callback=null)¶ Call the server method
method_name
onguard.close()
. This should be used to unsubscribe to all resources that were subscribed ininit
.While technically you can call
swindon.call()
at the same time asguard.close()
, thedeinit
method is a convenience helper to keepinit
anddeinit
in the same place.callback
is a function called with result of method call.
-
listen
(topic, callback)¶ A (client-side) subscription to the topic.
callback(data, metadata)
is a function called when data arrives for specified topic. Data is completely opaque from swindon and is what swindon receives. The only guaranteed field inmetadata
istopic
which represents topic this callback subscribed to. Refer to swindon docs for more info onmetadata
.Note
Library doesn’t ensure that this connection is subscribed to the specified topic in swindon itself. It’s your responsibility to make sure that backend call executed in
init
subscribes current connection to specifiedtopic
using the API, and that it unsubscribes indeinit
. Guard frees resources occupied by client-side subscription inclose
.
-
lattice
(namespace, prefix, lattice_object)¶ Registers lattice object within this guard. All callback and state management is implemented in
Lattice
itself.The respective class lattice tracks all the keys prefixed by
prefix
with the prefix itself removed. This allows easy composition of lattices from different applications without applications themselves managing the prefix.Note
Library doesn’t ensure that this connection is subscribed to the specified topic in swindon itself. It’s your responsibility to make sure that backend call executed in
init
subscribes current connection to specifiedlattice
with neede keys using the API, and that it unsubscribes indeinit
. Guard frees resources occupied by client-side subscription inclose
.
-