@usvc/server
Scope
- x Basic HTTP security
- x Support for reading cookies
- x Support for issuing cookies
- x Parses POST data with
Content-Type: application/json
correctly - x Parses POST data with
Content-Type: application/x-www-form-urlencoded
correctly - x Support for Cross-Origin-Resource-Sharing (CORS)
- x Support for Content-Security-Policy (CSP) management
- Bundled distributed tracing with Zipkin
- Bundled metrics supporting Prometheus
- Readiness check configuration
- Liveness check configuration
Installation
npm i @usvc/server;
# OR
yarn add @usvc/server;
Usage
const {createServer} = require('@usvc/server');
// OR
import {createServer} from '@usvc/server';
Basic
// require as ^
const server = createServer();
const instance = server.listen(() => {
const {port} = instance.address;
console.info(`Listening on http://localhost:${port}`)
});
Full Configuration
// require as ^
const server = createServer({
enableCookies: true,
enableCors: true,
enableJsonBody: true,
enableUrlEncodedBody: true,
cookies: {
keys: [],
name: 'session',
secret: undefined,
domain: 'localhost',
httpOnly: true,
maxAge: 60e3 * 60,
path: '/',
},
cors: {
allowedHeaders: undefined,
credentials: true,
exposedHeaders: undefined,
maxAge: ONE_DAY,
methods: ALL_HTTP_METHODS,
optionsSuccessStatus: 204,
preflightContinue: true,
urls: [],
},
csp: {
childSrc: ['"self"'],
connectSrc: ['"self"'],
defaultSrc: ['"self"'],
disableAndroid: false,
fontSrc: ['"self"'],
imgSrc: ['"self"'],
logger: console,
logLevel: 'warn',
objectSrc: ['"none"'],
reportUri: '/csp-report',
sandbox: ['allow-forms', 'allow-scripts'],
scriptSrc: ['"self"'],
styleSrc: ['"self"'],
},
jsonBody: {
limit: '100kb',
type: '*/json',
},
logger: console,
middlewares: {},
urlEncodedBody: {
limit: '100kb',
type: '*/x-www-form-urlencoded',
},
});
const instance = server.listen(() => {
const {port} = instance.address;
console.info(`Listening on http://localhost:${port}`)
});
API Documentaiton
.createServer(:options)
Returns a bootstrapped Express server. The :options
parameter has the following schema:| Key | Type | Defaults To | Description | | --- | --- | --- | --- | |
enableCookies
| Boolean | true
| Enables use of .cookies
and .session
in the request object in Express handlers |
| enableJsonBody
| Boolean | true
| Enables use of .body
in the request object if the Content-Type
matches the :jsonBodyType
parameter |
| enableUrlEncodedBody
| Boolean | true
| Enables use of .body
in the request object if the Content-Type
matches the :urlEncodedType
parameter |
| cookies
| DataCookieOptions | Options for configuring cookies management |
| cors
| SecurityCorsOptions | Options for configuring CORS |
| jsonBody
| DataJsonOptions | - | Options for configuring parsing of JSON body data |
| logger
| Object | console
| The logger to use for this server instance |
| middlewares
| CreateServerHooks | {}
| Any pre/post middleware injections you may need |
| urlEncodedBody
| DataUrlEncodedOptions | Options for configuring parsing of URL encoded body data |Options Documentation
Options for cookies
(DataCookiesOptions
)
| Key | Type | Defaults To | Description |
| --- | --- | --- | --- |
| keys
| String | []
| Keys used to sign (index zero) and verify cookies (other index numbers) |
| name
| String | "session"
| Name of the cookie |
| secret
| String | - | Secret used to compute the hash |
| domain
| String | "localhost"
| Domain which the cookie is registered on |
| httpOnly
| Boolean | true
| Set the HTTP-Only flag or not |
| maxAge
| Number | 60e3 * 60
| Maximum time the cookie is cacheable |
| path
| String | "/"
| Path of the cookie |Options for cors
(SecurityCorsOptions
)
| Key | Type | Defaults To | Description |
| --- | --- | --- | --- |
| allowedHeaders
| String | undefined
| Sets the Access-Control-Allow-Headers
HTTP response header |
| credentials
| Boolean | true
| Specifies if credentials are allowed |
| exposedHeaders
| String | undefined
| Sets the allowed headers to be exposed |
| maxAge
| Number | One day | The maximum age of caching in milliseconds |
| methods
| String | All HTTP methods | The allowed HTTP methods |
| optionsSuccessStatus
| Number | 204
| Specifies the HTTP status code to send on OPTIONS
success |
| preflightContinue
| Boolean | true
| Specifies if the preflight response should be sent immediately (false
) or not (true
) |
| urls
| String | []
| An array of allowed URLs for which the Origin
request header can be |Options for csp
(SecurityCspOptions
)
| Key | Type | Defaults To | Description |
| --- | --- | --- | --- |
| childSrc
| String | ['"self"']
| Sets the child-src
in the CSP |
| connectSrc
| String | ['"self"']
| Sets the connect-src
in the CSP |
| defaultSrc
| String | ['"self"']
| Sets the default-src
in the CSP |
| disableAndroid
| Boolean | false
| |
| fontSrc
| String | ['"self"']
| Sets the font-src
in the CSP |
| imgSrc
| String | ['"self"']
| Sets the img-src
in the CSP |
| logger
| Object | console
| The logger object to use for logging |
| logLevel
| String | "warn"
| The log level to use with the logger object. If this level is not found as a property of the logger object, an error will be thrown at runtime |
| objectSrc
| String | ['"none"']
| Sets the object-src
in the CSP |
| reportUri
| URI | "/csp-report"
| Sets the report-uri
in the CSP where browsers will post to if a CSP violation is found. |
| sandbox
| String | ['allow-forms', 'allow-scripts]
| Sets the sandbox
in the CSP |
| scriptSrc
| String | ['"self"']
| Sets the script-src
in the CSP |
| styleSrc
| String | ['"self"']
| Sets the style-src
in the CSP |Options for jsonBody
(DataJsonOptions
)
| Key | Type | Defaults To | Description |
| --- | --- | --- | --- |
| limit
| String | "100kb"
| Maximum size of the JSON body |
| type
| String | "*/json"
| Pattern of the Content-Type
HTTP header value to invoke JSON body parsing |Options for middlewares
(CreateServerHooks
)
| Key | type | Defaults To | Description |
| --- | --- | --- | --- |
| after
| RequestHandler | []
| Any post-initialisation middlewares |
| before
| RequestHandler | []
| Any pre-initialisation middlewares |Options for urlEncodedBody
(DataUrlEncodedOptions
)
| Key | Type | Defaults To | Description |
| --- | --- | --- | --- |
| limit
| String | "100kb"
| Maximum size of the JSON body |
| type
| String | "*/x-www-form-urlencoded"
| Pattern of the Content-Type
HTTP header value to invoke JSON body parsing |Examples
WIP
Development
WIP
License
This package is licensed under the MIT license.View the license at LICENSE.
Changelog
0.1.x
0.1.0
- Added cookie sessions
- Added CSP support
- Added server middleware hooks
0.x
0.0.2
- Cross Origin Resource Sharing (CORS) support
0.0.1
- Cookie parsing
- Basic HTTP header security
- Parsing of JSON encoded boday data
- Parsing of URL encoded body data
Contributors
| Name | Email | Website | About Me | | --- | --- | --- | --- | | Joseph | - | https://github.com/zephinzer | - |Cheers