mariaws
v0.1.2
Published
A simple Web Socket server for communicating with a MariaDB server.
Downloads
14
Readme
MariaWS
MariaWS is a simple WebSocket server for communicating to a MariaDB server (should also work with MySQL).
Browser <---WebSocket---> MariaWS <---TCP---> MariaDB/MySQL
With MariaWS you can use your browser to directly talk to a remote database.
Once you have globally installed MariaWS (npm install mariaws -g
) you can start the server with the command:
mariaws log=LOG ws-port=WSPORT heartrate=HEARTRATE sql-host=SQLHOST sql-port=SQLPORT
Where:
LOG
is the granularity of the loggin information. The possible values areinfo
,warning
,error
and the default value iserror
.- The
info
level logs pretty much everything into the standard output stream (e.g. incomming messages, responses and pings). - The
warning
level logs into the standard output streams events that deviate the ideal behavior (e.g. ping timeouts and WebSocket errors). - The
error
level only logs programmatic and critical errors into the standard error stream.
- The
WSPORT
is the port the node WebSocket server should listen to, the default value is8000
.HEARTRATE
is the number of seconds between successive pings, the default value is30000
.SQLHOST
is the host address of the MariaDB server, the default value islocalhost
.SQLPORT
is the port that MariaDB server is listening to, the default value is3306
.
To gracefully stop MariaWS, simply send the SIGINT
or SIGTERM
signal to the node process.
Note that if you are using Unix/OSX you can use the nohup
command to cheaply daemonize MariaWS. For instance: nohup mariaws 1>mariaws.log 2>mariaws.err &
.
Protocol
MariaWS is a pull based server, that is it only respond to client's request and never send message on its own initiative. The JSON format is used to encode data through the WebSocket channel. Two JSON templates are recognized by MariaWS:
{echo:anything, user:string, password:string}
: Attempting to connect to the mariadb server.{echo:anything, key:string, sql:string}
: Performing an sql query using a key obtained with a previous successfull connection.
Below is example of successful communication:
>> {"echo":1, "user":"smith", "password":"secret"}
<< {"echo":1, "error":null, "data":"as2dK...w4="}
>> {"echo":2, "key":"as2dK...w4=", "sql":"SELECT * FROM car;"}
<< {"echo":2, "error":null, "data":[[["mercedes", "65000€"], ["volkswaegen", "25000€"]]]}
Beside mysql error code, the error field can contain one of the below values:
"json-parse-error"
: the incoming message was not a valid JSON string."not-an-object"
: the incoming JSON value was not a javascript object."no-echo-field"
: the incoming JSON value did not contain theecho
field."invalid-fields"
: the incoming JSON value was not a valid template."db-connection-close"
: the connection to the database crashed, the connection request need to be send again.
Note that there is no correspondance between WebSocket connection and MariaDB connections. More specifically a browser can have access to multiple MariaDB connection and a MariaDB connection can serve mutiple browsers. MariaDB connections are established when an unknown login is used and are cannot be closed.
Demonstration
To demonstrate the usage of MariaWS, lets setup a SQL console within your browser. To do so, you should:
Have a MariaDB server running locally and listening to port 3306.
Have a local HTTP server able to serve the
index.html
file from this repository and that forward Web Socket connections tohttp://localhost:8000
. If you do not know how to do this you can: 1. Get nginx. 2. Create anywhere a file named nginx.conf with the below content:events { } http { server { listen 80; root PATH-TO-MARIAWS; location = /ws { proxy_pass http://localhost:8000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } } }
3. Replace `PATH-TO-MARIAWS` with the absolute path to the installation directory of MariaWS.
4. Make sure everyone is able to read `index.html` ; if your system is Unix/OSX you can run `chmod a+r demo.html`.
5. Run `nginx -c PATH-TO-NGINX`, where `PATH-TO-NGINX` is the absolute path to the `nginx.conf` file.
- Start MariaWS with the command
mariaws
. - Open your preferred browser (should support WebSockets) and navigate to
http://localhost/index.html
.
API
MariaWS can also be installed locally and be used within other node modules. MariaWS only exposes two functions:
log
: changes the logging level (initially set toerror
).start
: starts a new WebSocket server and returns a function that when invoked shut it down gracefully ;start
takes an object as parameter that can contain the following fields:ws_port
: the WebSocket port.sql_port
: the MariaDB port.sql_host
: the MariaDB host.heartrate
: the number of second between two successive pings.
For instance:
var Mariaws = require("mariaws")
Mariaws.log("info")
var stop = Mariaws.start({
ws_port: 8000,
sql_port: 3306,
sql_host: "localhost",
heartrate: 30
})
process.on("SIGINT", stop)