@velocejs/server

The package is built on top of uWebSocket.js.

Installation

``sh
$ npm i @velocejs/server
`

How to

All the examples using Typscript. We will start from the
lower level code.

$3

`ts
import { createApp, shutdownServer } from '@velocejs/server'
const port = 9001
let connectedSocket

createApp()
.get('/*', (res: HttpResponse) => {
res.end('Hello')
})
.listen(port, token => {
if (token) {
connectedSocket
console.log(Server is running ${port})
}
})
// now some time later if you need to gracefully shutdown your server
shutdownServer(connectedSocket)
`
If you pass the following configuration object, then it will create a SSLApp

`js
{
key_file_name: 'path/to/key.pem',
cert_file_name: 'path/to/cert.pem',
passphrase: 'your_pass_phrase'
}
`

You can also specify a host when you call the listen method

`ts
createApp()
// ... add route handlers
.listen('0.0.0.0', 3456, token => {
// the rest of your code
})
`

#### Automatically determine port number

You can let the server to decided which port number to use (very handy when you need to run multiple instance per CPU).
All you have to do is to set the startup port to 0.

`ts
import { createApp, getPort } from '@velocejs/server'
const port = 0 // <-- here

createApp()
.any('/*', (res: HttpResponse) => {
res.end('Hello')
})
.listen(port, token => {
const thisPortNumber = getPort(token)
// it will return the actual port number this server is running on
})
`

$3

Extract the JSON from the request using readJsonAsync and serve up your JSON using writeJsonAsync (It creates all the appropriate headers for you)

`ts
// store the token for use later
let listenSocket: us_listen_socket = null
// create app
createApp()
.post('/*', async (res: HttpResponse) => {
const json: object = await readJsonAsync(res)
// do your thing with your json
writeJson(res, {OK: true})
})
.listen(port, token => {
listenSocket = token
if (!token) {
console.log(Start up server failed on, port)
}
})
`

$3

Serve up your static assets or your actual rendered HTML page etc.

`ts
const app = createApp()
.get('/assets/*', serveStatic('/path/to/assets')) // can be an array of multiple folders
.listen(port, token => {
console.log("running")
})
`

All you have to do is the provide the url, and where your files are (you can pass array of directories),
and serveStatic takes care of the rest.

$3

bodyParser is now a standalone project @velocejs/bodyparser

This will help you to parse the request input, and put into easier to use format.

`ts
import bodyParser from '@velocejs/bodyparser'

const app = createApp()
.get('/*', async (res: HttpResponse, req: HttpRequest) => {
const result: UwsRespondBody = await bodyParser(
res,
req,
/ optional onAbortedHandler / () => console.log(something wrong)
)
// do your thing with the result
})
.listen(port, token => {
console.log("running")
})
`

The result is a UwsRespondBody type object with this signature:

`ts
type UwsRespondBody = {
url: string
method: string
query: string,
headers: UwsStringPairObj
params: any
payload?: Buffer
}
`
Please visit @velocejs/bodyparser for more info.

$3

This is an all-in-one solution to create the (UWS) server

`ts
import { UwsServer } from '@velocejs/server'

const app: UwsServer = new UwsServer()
// by default we randomly assign a port, see below for more info
app.run([
{
type: 'any',
path: '/*',
handler: (res: HttpResponse) => {
res.onAborted(() => {
console.log(server aborted)
})
res.end(Hello)
}
},
{ // we also support WebSocket
type: 'ws',
path: '/socket/*',
handler: {
open: function(ws: WebSocket) {
ws.send('Hello World')
},
message: function(ws: WebSocket, message: ArrayBuffer) {
ws.send('Got your message')
}
}
}
])
`

Please note the res.onAborted if you don't provide one, and when something wrong happen with the server, the server will simply crash. If you provide one, then even the handler throw error, the server will keep on running.

---

Next will be all available public methods

#### UwsServer.onStart(): void

By default there is no output, if you pass DEBUG=velocejs:server:uws-server-class in your startup script
then you will able to see a start-up message.

Or you can overwrite it by using onStart setter:

`ts
app.onStart = () => console.info(My own message)
`

Please note, you have to overload this before you call app.run

#### UwsServer.run(handlers: UwsRouteSetup[]): void

This is the main method to create the server, apply end points (routes) and bind the server to port.

The UwsRouteSetup interface has this signature:

`ts
interface UwsRouteSetup {
type: string
path: string
handler: any
}
`

available type options are any, get, post, put, options ,del, patch, head, connect, trace.

#### UwsServer.shutdown(): void

To gracefully shutdown the server

`ts
app.shutdown()
`

#### getPortNum(): number AND set portNum(port: number)

By default the server will randomly assign an unused port, you could
overwrite it by:

1. portNum setter
2. using the node environment variable PORT (this will have higher priority)

Assume that you have put everything in a file call server.js

`sh
$ PORT=3456 node ./server.js
`

Or if you just stick with the randomly port, you can use this method to retrieve the port number.

`ts
const port = app.getPortNum()
`

#### hostName setter and getter

You can also specify a host name, default is localhost.
There are two ways to overwrite this:

1. hostName setter
2. using the node environment variable HOST (this will have higher priority)

Assume that you have put everything in a file call server-with-hostname.js

`sh
$ HOST=0.0.0.0 node ./server-with-hostname.js
``

This is handy to write start-up script for your DevOps.

---

(Class) FastApi

This project is now standalone module on @velocejs/fastapi

---

Joel Chu (c) 2022