npm package: @opuscapita/web-init
Description: Basic web server setup for OpusCapita Business Network.
Latest version: 5.0.0

![](https://img.shields.io/bundlephobia/min/@opuscapita/web-init)
![](https://img.shields.io/node/v/@opuscapita/web-init)
![](https://img.shields.io/npm/types/@opuscapita/web-init)

# @opuscapita/web-init
![Build status](https://circleci.com/gh/OpusCapita/web-init.svg?style=shield&circle-token=2e3e2b7b174d781d2bf12a3fd2db7b1bb2385d03)

This module combines more general and common setup routines for creating a basic REST service environment.
Using it may help creating a more common and comparable structure over multiple services by following conventions
made by this service.

---

### Minimum setup

First got to your local code directory and run:
```
npm install @opuscapita/web-init
```
Now you would have to set up at least one basic route file that will automatically be included by the module
when initialized. The default path for routes is "./src/server/routes". This location can be changed by configuration
but may not be overwritten to stay with common service conventions.

A route module can be created using the following code:

```JS
// Optional health check callback to determine whenever the system is healthy/ready so it can e.g. be added/removed from an API gateway or load balancer automatically.
module.exports.onHealthCheck = async function()
{
    // Always return true or false but DO NOT run time consuming tasks inside this function as it has to retun in time.
    return true;
}

// Make sure this functions is async or returns a promise.
module.exports.init = async function(app, db, config)
{
    // app => express instance.
    // db => can be defined by configuration when running the .init() method.
    // config => everything from config.routes passed when running the .init() method.
    app.get('/', (req, res) => res.send('hello world'));
}
```

Go to your code file and put in the minimum setup code.
```JS
const server = require('@opuscapita/web-init');

// You might want to pass a configuration object to the init method. A list of parameters and their default values
// can be found at the .DefaultConfig module property.
(async () =>
{
    await server.init({
        server : {
            port : {{your-service-port}},
            events : {
                onStart : () => console.log('Server ready. Allons-y!')
            }
        }
    });
})();
```
This code applies a lot of conventions that of course can, but may not be overwritten by passing a configuration object
to the init() method.

---

### Request context (req.opuscapita)
@opuscapita/web-init adds a sub-context to every request coming in. The following properties will be available:

* [acceptLanguage](https://www.npmjs.com/package/accept-language-parser)
* [logger](https://github.com/OpusCapita/logger)
* [serviceClient](https://github.com/OpusCapita/service-client)
* [eventClient](https://github.com/OpusCapita/event-client)
* [timerStart](https://nodejs.org/api/process.html#process_process_hrtime_time)
* [userData](https://github.com/OpusCapita/useridentity-middleware)
* [i18n](#i18nproxy)

Additional context data might be injected by additional middleware. By default, web-init includes the [useridentity-middleware](https://github.com/OpusCapita/useridentity-middleware) which actually adds additional methods.

Example:

```JS
app.get('/hello', (req, res) =>
{
    req.opuscapita.logger.info('World');
    res.send('World');
});
```

---
### I18nProxy

The web-init library contains a special proxy class enveloping the [I18nManger](https://github.com/OpusCapita/i18n) to provide additional functionality. As the basic API is the exact same as the one found in I18nManager, the I18nProxy class extends these API by allowing all methods to be called as **xxxObject()** which then returns an object with all translated or formatted values for all languages available.

Example:

```JS
app.get('/hello', (req, res) =>
{
    const result = req.opuscapita.i18n.getMessageObject('world');
    res.send(result);

    /**
     * Sends:
     * { "en" : "World", "de" : "Welt" }
     */
 }
});
```
---

### Response context (res.opuscapita)
@opuscapita/web-init adds a sub-context to every response when a new request comes in. The following properties and methods will be available:

* setMaxAge(seconds) *// Maximum browser cache time.*
* setNoCache() *// Disable browser caching at all.*

Additional context data might be injected by additional middleware.

Example:

```JS
app.get('/hello', (req, res) =>
{
    res.opuscapita.setMaxAge(3600); // Sets browser caching to expire after one hour.
    res.send('World');
});
```

---

### Health checking
As another convention, this module provides a static REST endpoint for health checking. If the web server is up and running, GET calls to /api/health/check will return "200 OK" sending you the following object:

```JS
{"message":"Yes, I'm alive!"}
```

---

### Inter-Service-Communication
If desired, this module may provide a [ServiceClient](https://github.com/OpusCapita/service-client) instance initialized with and injected into any incoming HTTP request (req.opuscapita.serviceClient). This allows you to talk to other services while automatically keeping all headers and cookies sent with the original request. This will provide a full request context towards the target service. See the *serviceClient* key of the [DefaultConfig](#default-configuration) object.

---

### EventClient
The web-init module also provides a fully initialized instance of [EventClient](https://github.com/OpusCapita/event-client). To enable this, the configuration value *server.enableEventClient* has to be set to *true*. If this is enabled, every incoming request will contain an
event client instance (req.opuscapita.serviceClient) ready to use.

---

### Security

#### User identity
When enabled using the **enableIdentity** config switch, web-init automatically makes use of the [useridentity-middleware](https://github.com/OpusCapita/useridentity-middleware) which provides read-only user information from a JSON Web Token in order to identify the requesting user. Please refer to the documentation available through the middleware's repository.

#### Endpoint access
In addition to the built-in functionality of web-init, another module is available to ensure security on REST endpoints. When enabled using the **enableBouncer** config switch, defined endpoint protection is available. For further information on this, please have a look at the repository of [bouncer](https://github.com/OpusCapita/bouncer). The required **acl.json** file has to be located inside the *./src/server* directory.

---

### Internationalization / Translations

This library provides access to a fully initialized instance of OpusCapita [i18n](https://github.com/OpusCapita/i18n). It is available through the **req.opuscapita.i18n** object. The language is selected by choosing the following sources in order: *req.opuscapita.userData*, *req.opuscapita.acceptLanguage*. The default fallback language is english.

In order to **automatically load** translations, just **place an i18n folder** or i18n.js file inside the **src/server/routes** directory.

---

### Default configuration

The default configuration object provides hints about what the module's standard behavior is like. It is mostly recommended to leave most settings as they are and treat them more as general conventions to a common structure
in order to maintain a common setup across different services. The internal middleware adds an **opuscapita** sub-key to every request providing addition data and actions for every request.

```JS
{
    server : {
        mode : process.env.NODE_ENV === 'development' ? this.Server.Mode.Dev : this.Server.Mode.Productive,
        security : this.Server.Security.All,
        crossOrigins : [ '*' ],
        maxBodySize : 1048576, // 1 MiB
        staticFilePath : express.static(__dirname + '/static'),
        indexFilePath : null,
        indexFileRoutes : [ '/' ],
        hostname : process.env.HOST || '0.0.0.0',
        port : process.env.PORT || 3000,
        events : {
            onStart : function(server) { },
            onEnd : function(server) { },
            onRequest : function(req, res, next) { next(); },
            onError : function(err, server) { process.stderr.write(err); }
        },
        webpack : {
            useWebpack : false,
            useHotMiddleware: false,
            htmlWebpackPlugin : {
                enable : false,
                filename: 'index.html'
            },
            configFilePath : process.cwd() + '/webpack.conf.js'
        },
        middlewares : [ ],
        requestHeadersToResponse : [ 'Correlation-Id' ],
        appVariables : { },
        enableIdentity : true,
        enableBouncer : true,
        bouncer : {
            registerPermissions : {
                retryTimeout : 1000,
                retryCount : 30
            }
        },
        enableEventClient : true,
        cacheControl : {
            defaultAge : 3600,
            cachableEndpoints : [ '^/static/*', '^/public/static/*' ],
            nonCachableEndpoints : [ '^/api/*', '^/public/api/*' ]
        },
        publicApis : [ '*' ],
        noLogEndpoints : [ '^/api/list/apis$', '^/api/health/check$' ],
        maxMemory : process.env.MAX_MEMORY || -1
    },
    logger : new Logger(),
    serviceClient : {
        consul : {
            host : 'consul'
        },
        caching : {
            driver : 'dummy',
            defaultExpire : 600
        },
        headersToProxy : [ 'Cookie', 'Authorization', 'From', 'Correlation-Id' ]
    },
    routes : {
        addRoutes : true,
        modulePaths : [ process.cwd() + '/src/server/routes' ],
        dbInstance : null
    }
}
```


# Migration instruction

## Version 2.x to 3.x

Most important change is the use of `Op.eq`, `Op.neq`, `Op.gt`, etc. operators
instead of string literals like `$eq`, `$neq`, `$gt`.

## Version 3.x to 4.x

You should update your node version - web-init was tested with node 14.

The libraries are using local session storage which was introduced in node 10. It keeps the correlation ID (in the future it might keep more items).

Though not yet used in v4.0.3, it is planned to update other andariel libraries to improve traces. Those libraries could become also combined to avoid versioning issues. Keep track on the versions. We should follow the conventional npm versioning: patch versions for bugfixes or non-visible changes, minor for new features, major for breaking changes that require changes from your side (thus version 4.x should work on your code without any extra changes)