AwesomeServer > HTTPS Setup and Configuration
This document details how to work with HTTPS Servers in relation to AwesomeServer including configuration, request, and responses.
The HTTPSServer detailed below extends the HTTPServer described already in our documentation. Everything that is true for HTTPServer is true for HTTPSServer, and thus can be used in HTTPSServer. (The inverse is not true, so things specific to HTTPSServer are may not be available for HTTPServer.)
To create an HTTPS Server for usage with AwesomeServer you use the server.addHTTPSServer(config) method and then start() AwesomeServer. It takes a configuration option, as described below.
When a new request is received on the HTTPS Server, it takes the incoming request/response objects and wraps them in custom request/response objects. The details of these wrapped request/response objects is below.
Note that it is entirely possible to have multiple calls to server.addHTTPSServer(config) which are listening on different ports with different configurations, but using the same underlying AwesomeServer for handling.
When calling server.addHTTPSServer(config) you may pass an optional configuration object. This object has the shape described below, but is also fully compatable with the configuration object passed to nodejs' http.createServer() function, nodejs' server.listen(options) function, nodejs' https.createServer() function, **nodejs tls.createServer()function**, and **nodejs'tls.createSecureContext()` function.
The example below shows the default configuration object you would get if you did not pass anything to server.addHTTPSServer().
let config = {
hostname: "localhost",
port: 7080,
cert: null,
key: null
};
host: [string] specifies the host interface to bind to. AwesomeServer sets this to "localhost" by default. To bind to all interfaces change this to "0.0.0.0".
port: [number] the interface port to bind to. For a random port, set to 0.
cert: [string|buffer] The cert option is required for an https server to be instantiated. You may pass in a string or buffer that contains a PEM encoded certificate. Optionally, you may pass in a valid existing filename that contains a PEM encoded certificate and AwesomeServer will load its contents for you.
key: [string|buffer] The key option is required for an https server to be instantiated. You may pass in a string or buffer that contains a PEM encoded private key. Optionally, you may pass in a valid existing filename that contains a PEM encoded private key and AwesomeServer will load its contents for you.
If you need greater fidelity of configuration, please see the following for more information on options:
- nodejs http.createServer() options
- nodejs net.server.listen() options
- nodejs https.createServer() options
- nodejs tls.createServer()
- nodejs tls.createSecureContext()
Each incoming request that is received by AwesomeServer has both a request and a response object. When the incoming request is received by the HTTPS server, its request object is wrapped in a custom AwesomeServer HTTPS Request object. Likewise, its response object is wrapped in a custom AwesomeServer HTTPS Response object. We do this to provide a more consistent, simplified request structure.
An AwesomeServer HTTPS Request object is an instance of AwesomeServer.https.HTTPRequest which is itself an instance of AwesomeServer.http.HTTPRequest which in turn is an instance of AwesomeServer.AbstractRequest. if you need access to the original nodejs IncomingMessage object, you can simply use the request.original getter to obtain it.
Because the AwesomeServer HTTPSRequest extends AwesomeServer HTTPRequest, it has all the same members and methods. Please refer to the HTTPServer Guide Request Section for more information.
Each request that is received by AwesomeServer has both a request and a response object. When the request is received by the HTTPS server, the original response is wrapped in a custom AwesomeServer Response object. We do this to provide a more consistent, simplified response structure.
An AwesomeServer Response object is an instance of AwesomeServer.https.HTTPSResponse which is itself an instance of AwesomeServer.http.HTTPResponse which is finally an instance of AwesomeServer.AbstractResponse.
Because the AwesomeServer HTTPSRequest extends AwesomeServer HTTPResponse, it has all the same members and methods. Please refer to the HTTPServer Guide Response Section for more information.