Client Library
Here is an example client that subscribes to receive events on a topic.
https://github.com/ohyo-io/wampire/blob/master/examples/simple/sub/subscriber.go
Let's walk through the code inside func main() { ... }
The client configuration in this example is very simple. It only specifies the realm that the client is to join when connected to the router and provides a logger for the client to use. The logger is any logger instance that implements the StdLog interface. If not provided, the client logs to os.Stderr.
The cfg.Serialization field specifies the serialization, client.JSON or client.MSGPACK, for the client to use.
The default is client.JSON which is what will be used here.
The ClientConfig allows configuration of other
transport and client options.
It is not necessary to define the client roles and features. Role and feature announcement is already taken
care of by the wampire client when it joins the realm. It announces all the roles and features it supports.
However, if you want your client to announce a subset of the roles and features, you can provide your
own dictionary of roles and features in the HelloDetails section
of the ClientConfig.
The next section of code calls ConnectNet to
create the websocket client instance, connect it to the server/router, and join the realm specified in the ClientConfig.
A websocket server endpoint is identified by a URL of the form "scheme://address", given as the
first argument to ConnectNet. Possible schemes and their meaning are as follows:
-
ws: Websocket -
wss: Websocket with TLS -
tcp: TCP socket -
tcps: TCP socket with TLS -
unix: Unix socket
For details on URL format, see ConnectNet API reference.
Also note that a ConnectLocal API is available
for clients that are embedded in the same application as the router.
After checking for errors, the defer subscriber.Close() sets the client to be closed at function exit.
When a client subscribes to a topic, it is registering its interest in having the router send it any events that are
published by other clients for that topic.
Subscribing to a topic, using the wampire client, configures the client to automatically call an event handler
call-back function whenever the client receives an event from the router.
The next section of code defines an event handler call-back function and specifies that function when subscribing to a topic.
The event handler receives the message portion of an Event message.
The sample here only prints that the event was received and the first item in the args list if any.
Event handlers are called serially so that they execute in the same order as the event messages are received in.
This could not be guaranteed if executing concurrently. However, if order is not important in your implementation,
you can process events concurrently by starting a goroutine in your handler implementation to do the processing work.
The call to Subscribe subscribes the client
to the specified topic or topic pattern. The first argument to Subscribe specifies an exact event URI to match
or it can specify a URI pattern to match multiple events for the same handler. The second argument specifies
the event handler function that is registered to be called every time an event is received for the topic.
The last argument is and optional dictionary that specifies
options for the subscribe message.
To subscribe to topics matching a URI wildcard pattern, specify wamp.Dict{wamp.OptMatch: wamp.MatchWildcard} as
the value of the last argument. The option value wamp.MatchPrefix is also available.
The default behavior is to match exactly.
The last section of code waits to receive a shutdown signal, CTRL-c in this example, or for the router connection to close, and then gracefully exits. While waiting, the event handler is called each time the client receives an event on the topic it subscribed to.
Since the client is exiting, calling Unsubscribe it not necessary since the router will remove all the
client's subscriptions as soon as the client goes away. The Unsubscribe is included here as an example
of how to unsubscribe from a topic. The graceful exit is accomplished by
calling Close() on the client, which
was done using `` in the first part of the example.