24.3 Websocket named-pipe ¶

Artanis provides the named-pipe based on Websocket, which is very useful to interact between the client and server. NOTE: The Websocket named-pipe is very useful to implement server-push messaging.

Here is the critical API:

(named-pipe-subscribe <route-context>)

Let’s try a simple example:

(get "/robot" #:websocket '(proto echo) named-pipe-subscribe)

Here we register a WebAPI named "/robot", and configure it a Websocket API by #:websocket '(proto echo). As you may see, we specify its protocol to a simple echo protocal, it is to say, it will redirect what it receives. Each time it receives a message, it will redirect the message to the specified named-pipe, and the subscriber of that named-pipe will get the message instantly. The name of the pipe is specified by the client like this:

var ws = new WebSocket("ws://localhost:3000/robot?artanis_named_pipe=robot-1");

The query-string "artanis_named_pipe" is a special key in Artanis, you MUST use this key to specify the pipe name. Here we specify the pipe name as "robot-1".

Now we setup the named-pipe, however, we still need to setup another WebAPI to let the client send message:

(get "/welcome/:whom/:what" #:websocket 'send-only
     (lambda (rc)
       (:websocket rc 'send (params rc "whom") (params rc "what"))
       "ok"))

The configure "#:websocket 'send-only" means this API is only for sending, so that it’s half-duplex. And another critical Websocket API here:

(:websocket <route-context> 'send <pipe-name> <data>)

Each time you send data from the WebAPI, for example:

curl localhost:3000/welcome/robot-1/nala

In our simple example of Websocket named-pipe test, you should run The named-pipe will receive the message "nala", and the page on the browser will print "hello welcome...nala" instantly.