WebSocket support

[usq]

Have you ever thought about adding WebSocket support?

I am looking for a way to push XML messages to clients to enable multi-client xml-applications and WebSockets would be an ideal fit.
I added a %rest:WEBSOCKET annotation to test the concept and got it to work, so I was wondering if something like this was ever on the roadmap for BaseX/RESTXQ?

Thanks!
Mike

[ChristianGruen]

Dear Mike, I remember there has been some discussion on web sockets on our mailing list (see e.g. https://www.mail-archive.com/basex-talk@mailman.uni-konstanz.de/msg08836.html). Glad to hear it’s working for you. Fel free to share your experiences or your code with us.

[dirkk]

+1000 for WebSocket support and sharing your code. A simple %rest:WEBSOCKET annotation sounds perfect to me.

[ChristianGruen]

@usq: Did you get the WebSocket extension working? If yes, is you solution similar to the one from Marco (see my link to our mailing list)?

[usq]

Hi,
sorry for the late reply, I was swamped with work the last days.

Thanks for the mailing list link!

I just added https://github.com/TooTallNate/Java-WebSocket, added the %rest:WEBSOCKET annotation and send the serialized XML via the WebSocket to all connected clients when creating the RestXqResponse. But this was just for a prototype and is far from production code!

The websocket support is actually part of my master thesis on multi-client XML applications. I need to notify a group of connected clients about changes to the database (e.g. for an XML chat application, or multi-client word processing like Google Docs)

At the moment, I'm trying to figure out an API/annotation-parameter to specify that WebSocket messages should only be sent to either all clients, a subgroup or just one.
An example would be a chat server, which allows users to join specific chat rooms. As soon as a message is posted and stored in the database, only the clients inside the room should receive a WebSocket message containing the new database state.

As soon as I got that, I'll post a clean/non-hacky pull request (adding the WebSocket like mentioned on the mailing list).

[ChristianGruen]

Mike, thanks for your efforts. Looking forward to your pull request.

[ChristianGruen]

Hi @usq. I am curious. Any news so far?

[usq]

Hi,

I got everything I needed to work and pushed my code to
https://github.com/usq/basex/tree/Feature/WebSocketSupport

I got the Jetty 8 WebSocket module working, but I'm not really a Java developer and did not manage to get the WebSocket to listen to it's own port without rewriting half the Jetty setup method, so the WebSocket is listening on the same port as Jetty but on the staticoption WEBSOCKET path which defaults to "/ws".

When the rest:WEBSOCKET annotation is set, the result is sent via WebSocket as well as HTTP response.
However, my changes to the serialize method in RestXqResponse were not one of my proudest moments, this definitely needs work!

The WebSocket will send all responses wrapped in a JSON object of form

{
    "type":"xmlresponse", 
    "xml": "<XML here>"
}

as most WS clients should be using JavaScript and most WS clients require a JSON message container.

WebSocket subscriptions

When a clients sends the message

{
    "type":"subscribe", 
    "data": [<subscriptionkey>*]
}

via the WebSocket, the client will receive messages sent with one of the specified subscription keys (see major hack 1.).
The message

{
    "type":"unsubscribe", 
    "data": [<subscriptionkey>*]
}

unsubscribes the client.

There are two major hacks:

1. The XQuery method can choose to send the result only to certain subscribed WebSockets.
   This is done by specifying the attribute websocketchannel="<subscriptionkey>" on the root element of the XML response. This is a horrible hack, but I didn't find any other "non-invasive" and user-friendly way to pass information from the XQuery function to the WebSocketFactory :(
   If the attribute is not present, the message is sent to all connected WebSockets.

2. The WebSocket connections are created by the WebSocketFactory servlet, which is a Singleton.
   I have to register the servlet at the WebAppContext, which means Jetty will instantiate the Servlet when needed.
   When serialising the XML response, I needed a way to pass the response to the WebSocketFactory, so I got weak and created a Singleton.

I implemented everything with as few changes as possible, but due to the hacks I'm no longer sure if this was a good idea ;)

I can create a pull request if you are interested but didn't want to surprise you without giving fair warning :)

Regards,
Mike

[ChristianGruen]

Great feedback, Mike! I’ll check out your branch pretty soon.

[ChristianGruen]

I had a first (and superficial) look at your code enhancements, and I think it is definitely a great start to gather experiences with RESTXQ and WebSockets. I was positively surprised to see that (eventually, I guess, now that’s it’s working) your solution is so slick.

A general thought (which I guess goes beyond the scope of your master thesis): Maybe we would even have more freedom if we do not strictly bind server replies to client requests. Instead, we could introduce an additional XQuery module for sending WebSocket messages. This could also be a solution for the first hack you described (the function for sending messages could have a channel argument). Some background:

We also stumbled across use cases in the past in which WebSocket support would have been helpful. One common use case is that client requests are too time consuming in order to be evaluated just-in-time. In this case, we would possibly like to notify the client later, i. e., as soon as the result is available. This could be realized by the relatively new Jobs Module, which will ensure that the client receives a request before the actual work is done, and the yet-to-be-realized WebSocket Module. A virtual example:

module namespace code = 'code';

import module namespace websocket = "http://basex.org/modules/websocket";

declare %rest:path('expensive') function code:prepare() {
  jobs:eval("import module namespace code='code'; code:run()"),
  'your result will be generated; you’ll be notified.'
};

declare function code:run() {
  (: do the thing, return the result :)
  websocket:send(<expensive-result/>)
};

The example has been simplified a lot. For example, we would need to clarify if the result is really to be sent to all clients, or just the one that asked for it.

The WebSocket could have the following functions (and more):

(: Send result to all channels :)
websocket:send($result as item()*) as empty-sequence()

(: Send result to specified channels :)
websocket:send($result as item()*, $channels as xs:string()*) as empty-sequence()

(: Subscribe to a channel; requires an additional RESTXQ entry point that calls this function :)
websocket:subscribe($channel as xs:string()) as empty-sequence()

(: Unsubscribe :)
websocket:unsubscribe($channel as xs:string()) as empty-sequence()

Obviously, this approach opens up new questions. One question I immediately get in mind is: how can output options and response headers be specified? Maybe an additional argument could be passed on the websocket:send function:

websocket:send('the result', web:response-header(), 'channel-x')

Another question is: (When) does it make sense to repeatedly subscribe and unsubscribe channels?

And the next question: Is the module approach reasonable at all? ;) As we already have the Jetty 8 WebSocketServlet class, for example, it may not necessarily be the best idea to assign (un)registering of clients to the client.

Any feedback is welcome!

[usq]

I totally agree that WebSocket messages should not be tied to client requests!

An XQuery module for sending WebSocket messages would be a great idea and solve the first hack.

If I got you right, the WebSocket module would use Java bindings to call the WebSocket Servlet?

The interface

(: Send result to all channels :)
websocket:send($result as item()*) as empty-sequence()

(: Send result to specified channels :)
websocket:send($result as item()*, $channels as xs:string()*) as empty-sequence()

should cover most use cases in my opinion.

I did not really get the methods:

(: Subscribe to a channel; requires an additional RESTXQ entry point that calls this function :)
websocket:subscribe($channel as xs:string()) as empty-sequence()

(: Unsubscribe :)
websocket:unsubscribe($channel as xs:string()) as empty-sequence()

Clients could use RESTXQ methods to subscribe to channels/topics (similar to the MQTT protocol), but the WebSocket Servlet (which holds open WebSocket connections) does not know which WebSocket connection maps to which client.
I sent the subscription message via the established WebSocket connection so that the server knows which connection belongs to which client (or which connection is interested in which 'channel')

Another possibility would be for the client to send an identifier via the WebSocket and then send a HTTP request to a RESTXQ method to subscribe to this channel.
Something like this:

declare 
%POST 
%rest:path("subscribe/{$websocketId}")
%rest:form-param("channel","{$channel}", "")
function code:subscribe(
$websocketId as xs:string, 
$channel as xs:string
) {
    websocket:subscribe($websocketId, $channel)
};

After this call, the WebSocket Servlet knows that all messages to $channel should be sent via the connection which sent the $websocketId. Still not perfect though...

This approach would pass subscription-control back to the server, which can decide if a client is allowed to subscribe to a channel. I think allowing the client to subscribe to any channel without server supervision is a security risk, as a client could subscribe to everything and receive all messages.

But maybe I misunderstood the intention of your websocket:subscribe method?

Subscribe/Unsubscribe is a valid use case in my opinion.
A (probably a bit fabricated) warehouse example:
A client wants to receive all new open orders, so the client subscribes to the channel newOrders. After that, the clients switches to the 'processed orders' view, which should unsubscribe him from newOrders and subscribe him to processedOrders.

Passing output options to the websocket:send method is a great idea!
What exactly did you mean by "response header" though? As far as I know WebSocket messages do not contain a header (apart from the WebSocket message protocol header, which just contains a few bytes), but maybe I missed something?

[ChristianGruen]

Thanks for your feedback. I am glad to see that we seem to agree upon many aspects.

If I got you right, the WebSocket module would use Java bindings to call the WebSocket Servlet?

Some more background:

In BaseX, we have two types of built-in modules: Most of the modules can be used without explicitly importing the URL in the query prolog. There is a second group, listed at the end of the Module_Library documentation, which needs to be imported, because the implementations are contained in the optional basex-api sub project of BaseX (https://github.com/BaseXdb/basex/tree/master/basex-api/src/main/java/org).

If we move the Java implementation of the WebSocket Module to this project (java.org.basex.modules.Websocket.class ), we’ll be able to import it and address the Java functions via import module namespace websocket = "http://basex.org/modules/websocket";. So, as you say, we use Java bindings, but they pretty much look like XQuery function calls (and after we have realized #1413, they may even be XQuery function calls, who call the Java code in a second step). Within the module, we can access the HTTP context of the current servlet instance via queryContext.http (see Session.java#L114 as an example).

Regarding my idea with the (un)subscribe functions: If we implement websocket:subscribe as described above, we have access to the current HTTP context; for example, ((HTTPConnection) queryContext.http).req gives us access to the current javax.servlet.http.HttpServletRequest instance. Maybe we can utilize the available information to to the same what the WebSocketServlet class does.

But it could very well be that we either have too little information in our hands to do this by our own, or that we would need to reimplement things that are currently working out-of-the-box, so I’m not sure if this is the best way to proceed. As you say, one clear advantage would be that we could decide within RESTXQ and XQuery if we want to allow a client to subscribe to a channel or not. Maybe we could find out if the Jetty WebSocket solution provides other ways to subscribe clients (apart from using the WebSocketServlet), and which client information is required to make it work?

Passing output options to the websocket:send method is a great idea!
What exactly did you mean by "response header" though? As far as I know WebSocket messages do not contain a header

Good to know, thanks! So the output will always be sent as UTF8 string, I guess? So we could…

1. simplify the argument to map with output options (identical to what is used by e.g. fn:serialize or file:write),
2. only allow a string as argument (because fn:serialize can be called in advance), or
3. define a fixed output format (based on your JSON example), if we know that the available WS clients will be able to handle it,

[ChristianGruen]

One month has passed… And I didn’t have time to pursure this further. Maybe I’ll get it done for BaseX 8.6.6.