From World of VOC - Wiki

Jump to: navigation, search

Contents

A Prototype for Accessing SessionVOC from Browser-Side JavaScript

The triAGENS SessionVOC server is normally used in a multi-tier-architecture with three or more tiers to share session-related data between several middle-ware servers and to persist the data in a database.

In the following text we show

  • how to install and setup a SessionVOC-server on Debian 6.0 (Squeeze)
  • how to access (some of) its functions via a minimalistic Browser-side JavaScript

thus ending up in a two-tier-application.

While this certainly is not the way to implement sophisticated applications, it helps to show the functionality of SessionVOC and it might even be a way to implement very simple applications without the need for a middle-ware.

Install and Setup a SessionVOC-server on Debian 6.0 (Squeeze)

It is possible to build the components of the SessionVOC from the sources (detailed instructions) - for simplicity we here use the repository provided by triAGENS to install SessionVOC via aptitude&friends.

First we get the PGP key of the triAGENS repository

 wget http://www.worldofvoc.com/repositories/RPM-GPG-KEY-www.worldofvoc.com

and import it into the APT key management by

 apt-key add RPM-GPG-KEY-www.worldofvoc.com

In /etc/apt/sources.list add the line

 deb http://www.worldofvoc.com/repositories debian_60 main

You can now simply install the SessionVOC-server by

 aptitude install sessionvoc-server

After this default installation the SessionVOC-Server listens on the local IPv4 address (127.0.0.1) on port 8208 (session service) and 8209 (administrative port). The details are configured in /etc/sessionvoc.conf as session-port and admin-port.

By changing session-port to an external address you can make the session-service available to remote machines, since the SessionVOC has a built-in SSL engine you can directly talk HTTPS. The problem here is that for binding to the standard https-port (443) as for all ports < 1024 on UNIX the SessionVOC would need to be started by root. To avoid possible security implication we in this example use stunnel to bind to the external address and forward all request to the default port, in short install stunnel

 aptitude install stunnel

generate a self-signed certificate

 cd /etc/stunnel
 openssl req -new -x509 -days 1095 -nodes -out stunnel.pem -keyout stunnel.pem
 chmod 600 /etc/stunnel/stunnel.pem

and configure sessionvoc in /etc/stunnel/stunnel.conf by adding

 [sessionvoc]
 accept = <insert your external ip address here>:443
 connect = 127.0.0.1:8208

and commenting out all other services.

Configure SessionVOC to act also as a simple HTTP server

Since browser-side JavaScript code can only access the same address/port from which the browser downloaded the HTML/JavaScript page, we must configure the SessionVOC server to serve these pages.

Luckily, the SessionVOC server can easily be configured to deliver static content as well:

Add the line

 document-root = /usr/share/sessionvoc/document-root

to /etc/sessionvoc.conf, create the directory by

 mkdir /usr/share/sessionvoc/document-root
 chown sessionvoc:sessionvoc /usr/share/sessionvoc/document-root/

and restart SessionVOC server with

 /etc/init.d/sessionvoc restart

Note: There's a single redirect from / to /html/index.html compiled into the SessionVOC server, so in our setup access to https://<your-address> will be directed to https://<your-address>/html/index.html which is loaded from the file /usr/share/sessionvoc/document-root/index.html - simple, but sufficient for most applications.

Test your setup

The easiest test is to see if you SessionVOC server is correctly connected to the local adddress, on the machine where the SesionVOC server is installed run:

 telnet 127.0.0.1 8208

and enter

 GET /version
 

(there's a newline after GET /version that terminates the HTTP request!), and you should get something like

 HTTP/1.1 200 OK
 content-type: application/json; charset=utf-8
 connection: Keep-Alive
 server: triagens GmbH High-Performance HTTP Server
 content-length: 60
 
 {"server":"","version":"1.7.11 (9382)","edition":"standard"}

as answer. (You can terminate this test request by hitting enter twice.)

Let's repeat this step from an external machine, since we now connect via https instead of http we have to use openssl as a client:

 openssl s_client -crlf -connect <your-ip-address>:443

You will get a lot of output regarding the SSL connection setup, then you can proceed with your GET /version as above.

Note 1: Since SessionVOC - in compliance with the HTTP standard - only accepts the sequence carriage return-line feed as a end of line this will not run without the -crlf option.

Note 2: If you get the message

 CONNECTED(00000003)
 write:errno=104

instead of a connection your openssl client tries to connect with an older protocol version than stunnel allow, to fix this you can change sslVersion = SSLv4 to sslVersion = all in /etc/stunnel/stunnel.conf.

To see if the redirection mentioned above works we issue a GET / request instead of the GET /version, this should be answered with

 HTTP/1.1 301 Moved
 content-type: text/html
 connection: Keep-Alive
 server: triagens GmbH High-Performance HTTP Server
 location: /html/index.html
 content-length: 150
 
 <html><head><title>Moved</title></head><body><h1>Moved</h1><p>This page has moved to <a href="/html/index.html>/html/index.html</a>.</p></body></html>

Finally we test the delivery of static content, after creating one with

 echo TEST > /usr/share/sessionvoc/document-root/index.html

a GET /html/index.html request issued via openssl should return

 HTTP/1.1 200 OK
 content-type: text/html
 connection: Keep-Alive
 server: triagens GmbH High-Performance HTTP Server
 content-length: 5
 
 TEST

Once this works, a request https://<your-address/ issued from your browser should display a page with simply TEST in it (probably after a warning that you are connecting to an untrusted website).

Directly access a SessionVOC server from Browser-Side JavaScript

Compared to this really uncomplicated installation procedure writing (simple) code to access the SessionVOC server from browser-side JavaScript is even easier...

Partly, this is because we can make the following simplification: While a middle-ware will first ask a directory server (see [[]] for details) to get information to which session server it should connect to we here assume - as already mentioned above - that the right session server is running on the port we loaded the page from since we cannot access any other HTTP server from browser-side JavaScript.

In our simple example that you can download from directly into your SessionVoc's document-root by

 cd /usr/share/sessionvoc/document-root/
 wget https://github.com/triAGENS/SessionVoc-Browser/blob/master/index.html

we use four of the functions provided by the SessionVOC server:

  • get a session
  • login to a session
  • save a session
  • logout from a session

They are coded in JavaScript functions called sessionvoc_getsession, _login, _save and _logout.

They all are built more or less in the following way:

  • Create a XMLHttpRequest object with the appropriate HTTP request, optionally add the JSONfied content of the global variable data or the JSONfied user information to it and then send it out synchronously.
  • Depending on the return code write the information returned from server back into data by evaluating the JSON string or

return some error code to the calling function.

The application codes reads and modifies the data object by simply accessing the data variable, it will be stored on the server by calling sessionvoc_save as explained above.

When inspecting the data object you will see that is is composed out of three sections

  • General session information (session and user id being the most important)
  • the userData subobject - the information therein will be stored to a persistent memory
  • the transData subobject - the information therein will only be stored in memory

Perspective

As said in the introduction, this example is primarily intended for demonstrating the basic functionality of SessionVOC. Nevertheless the idea behind might be helpful to implement very simple applications (where one user has access to one set of data only).

If this restriction fits your requirements you will - besides making the JavaScript more robust e.g. by handling the HTTP status codes returned by SessionVOC - adapt the data-model to your needs and maybe consider storing the data in a relational database (at the time of writing this, MySQL is the only candidate). Detailed instructions are available in [[]].