Server core using uWebsocket.js with additional helpers
The package is built on top of uWebSocket.js.
``sh`
$ npm i @velocejs/server
All the examples using Typscript. We will start from the
lower level code.
`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)SSLApp
If you pass the following configuration object, then it will create a
`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
})
`
Extract the JSON from the request using readJsonAsync and serve up your JSON using writeJsonAsync (It creates all the appropriate headers for you)
`tsStart up server failed on
// 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(, port)`
}
})
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),serveStatic
and takes care of the rest.
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.
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)Hello
})
res.end()`
}
},
{ // 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:
`tsMy own message
app.onStart = () => console.info()`
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 setterPORT
2. using the node environment variable (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 setterHOST
2. using the node environment variable (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.
---
This project is now standalone module on @velocejs/fastapi
---
Joel Chu (c) 2022