@gasket/plugin-https
v7.0.6
Published
Create http/s servers with graceful termination
Downloads
1,090
Readme
@gasket/plugin-https
A plugin that creates http
, https
and/or http2
servers based on the given
gasket
configuration.
Installation
npm i @gasket/plugin-https
Update your gasket
file plugin configuration:
// gasket.js
+ import pluginHttps from '@gasket/plugin-https';
export default makeGasket({
plugins: [
+ pluginHttps
]
});
Configuration
You can specify what port to open up on, or what certificates to use via
gasket.js
.
// gasket.js
export default makeGasket({
hostname: 'example.com',
http: 80,
https: {
port: 443,
root: '/path/to/ssl/files',
key: 'your-key.pem',
cert: 'your-cert.pem',
ca: 'your-ca.pem' // Can be an Array of CAs
},
terminus: {
healthcheck: ['/healthcheck', '/healthcheck.html']
}
});
Terminus is configured with the following defaults:
healthcheck
:['/healthcheck', '/healthcheck.html']
signals
:['SIGTERM']
Any of the options that are specified on the Terminus project page are accepted
in the terminus
object. Just note that the functions are already assigned by
default to trigger the appropriate lifecycle events.
HTTP/2
You can configure both HTTPS and HTTP/2 on the same socket with ALPN negotiation.
// gasket.js
export default makeGasket({
http: 80,
- https: {
+ http2: {
port: 443,
root: '/path/to/ssl/files',
key: 'your-key.pem',
cert: 'your-cert.pem',
ca: 'your-ca.pem' // Can be an Array of CAs,
+ allowHTTP1: true
}
});
Local Proxy Server
Create a proxy server for local development. See full http-proxy
options here.
// gasket.js
export default makeGasket({
http: 80,
+ devProxy: {
+ hostname: 'my-host.com',
+ port: 443,
+ protocol: 'https',
+ xfwd: true,
+ ws: true,
+ target: {
+ host: 'localhost',
+ port: 80
+ }
+ }
});
Actions
startServer
This action kicks off the machinery to get your Gasket app running.
Typically placed in a server.js
file, it can be executed with node
or your preferred runner.
import gasket from './gasket.js';
gasket.actions.startServer();
This action will execute several of the lifecycles mentioned next, allowing apps and plugins to further set the server up.
Lifecycles
devProxy
Adjust and configure devProxy
options for a proxy server during local development.
This is useful if https
is needed in local development.
The options for http-proxy
can be found here.
The devProxy
configuration must be defined in some capacity on the gasket config for this lifecycle to execute.
/**
* Adding options to `devProxy` that are not defined in the gasket config
*
* @param {Gasket} gasket Gasket API.
* @param {Object} devProxyConfig The original config if defined in the gasket config
* @return {Object} devProxy config
*/
devProxy: async function devProxy(gasket, devProxyConfig) {
return {
...devProxyConfig,
hostname: 'local.example.com',
port: 8443
}
}
serverConfig
Allows for server options to be added before createServers
is called.
Example use-case would be adding sni
configurations when using https
for local development.
/**
* Adding sni certs to https
*
* @param {Gasket} gasket Gasket API.
* @param {Object} rawConfig raw server config
* @returns {Object} rawConfig
*/
serverConfig: async function serverConfig(gasket, rawConfig) {
rawConfig.https.sni = {
'*.my-domain.com': '/path/to/cert',
'*.my-other-domain.com': '/path/to/cert'
};
return rawConfig;
}
createServers
Executed in order to retrieve the server options and the handler. Prefer to configure HTTP and port information in the gasket.js
or
configure
lifecycle.
/**
* In this example returns the express app
*
* @param {Gasket} gasket Gasket API.
* @param {Object} serverOpts Server options.
* @returns {Express} The web server.
* @public
*/
createServers: async function createServers(gasket, serverOpts) {
const newServerOpts;
return { ...serverOpts, ...newServerOpts, handler: express() };
}
servers
Your application can use this plugin to hook the servers
hook. These servers
are provided directly from the create-servers callback.
/**
* Called when all servers are created.
*
* @param {Gasket} gasket The Gasket API
* @param {object} servers - http and/or https servers
* @return {Promise<object>} updated manifest
*/
export default async function serversHook(gasket, servers) {
const cert = servers.https.cert;
console.log('Started https server with cert:');
console.log(cert);
}
In a typical use case, the servers
object will contain server instances for
http
and https
keys. In some cases if there are multiple configs and servers
created, this will be an array of servers. See create-servers docs for more
details.
terminus
Allows you to dynamically configure terminus and override any of the handlers
that we assign by default. Our default handlers onSendFailureDuringShutdown
,
beforeShutdown
, onSignal
, and onShutdown
all take care of triggering the
appropriate lifecycle events, so if you override those, you will no longer
receive those events.
/**
* Allows for dynamic configuration
*
* @param {Gasket} gasket Gasket API.
* @param {Object} terminus Terminus options.
* @returns {Object} The configuration.
* @public
*/
export default {
name: 'sample-plugin',
hooks: {
terminus: async function (gasket, terminus) {
console.log(terminus); // { ... terminus options ... }
return terminus
}
}
}
healthcheck
Triggered when the specified healthcheck
route is requested on the server.
This lifecycle allows you to assert if everything in your server is still
working as intended. A thrown error is considered a failed checked.
export default {
name: 'sample-plugin',
hooks: {
healthcheck: async function healthcheck(gasket, HealthCheckError) {
await checkDatabaseConnection();
await doAnotherSanityCheck();
}
}
}
The lifecycle receives the custom HealthCheckError
class from terminus if you
want to throw custom errors.
onSendFailureDuringShutdown
Triggered when terminus about to send a 503 Error to the healthcheck route but server is currently shutting down.
export default {
name: 'sample-plugin',
hooks: {
onSendFailureDuringShutdown: async function onSendFailureDuringShutdown(gasket) {
gasket.logger.info('healthcheck failed but we are already shutting down');
}
}
}
beforeShutdown
Triggered when we've received a signal that triggered the shutdown process of the server. This is the first function that is called and allows you to clean up your server before it's stopped.
export default {
name: 'sample-plugin',
hooks: {
beforeShutdown: async function beforeShutdown(gasket) {
gasket.logger.info('the server is about to shut down');
}
}
}
onSignal
Triggered when the server is stopped. Allowing you to clean up everything you
need before your node
process is shutting down.
export default {
name: 'sample-plugin',
hooks: {
onSignal: async function onSignal(gasket) {
await stopDatabaseConnect();
await cleanupTmpFiles();
}
}
}
onShutdown
Triggered when the onSignal
lifecycle has completed, right before the node
process is killed.
export default {
name: 'sample-plugin',
hooks: {
onShutdown: async function onShutdown(gasket) {
gasket.logger.info('Closing server');
}
}
}