Core tramvai
module, responsible for processing the users requests.
You need to install @tramvai/module-server
npm i --save @tramvai/module-server
And connect to the project
import { createApp } from '@tramvai/core';
import { ServerModule } from '@tramvai/module-server';
createApp({
name: 'tincoin',
modules: [ServerModule],
});
ServerModule
creates express.js application, handles user requests, runs commandLineRunner, and sends responses to users with data, headers and status from RESPONSE_MANAGER_TOKEN
token.
ServerModule
allows you to configure the proxying of urls to the application using the library http-proxy-middleware
To enable proxying, create a file proxy.conf.js
or proxy.conf.json
in the root of the project to export the request mapping object, or you can use the PROXY_CONFIG_TOKEN
token.
const testStand = 'https://example.org';
module.exports = {
// The key is the path pattern for the `express` to be passed to `app.use`
// value can be a string, in order to proxy all urls starting with `/login/`
'/login/': testStand,
// or can be a config object for [http-proxy](https://github.com/chimurai/http-proxy-middleware#http-proxy-options)
'/test/': {
target: testStand,
auth: true,
xfwd: true,
...
}
};
module.exports = {
// context - is similar to the option for [http-proxy-middleware](https://github.com/chimurai/http-proxy-middleware#context-matching)
context: ['/login/', '/registration/', '/auth/papi/'],
target: 'https://example.org',
// other `http-proxy-middleware` options
changeOrigin: true,
};
[
{
"context": ["/a/", "/b/*/c/"],
"target": "https://example.org"
}
]
import { Scope, provide } from '@tramvai/core';
import { PROXY_CONFIG_TOKEN } from '@tramvai/tokens-server';
[
provide({
provide: PROXY_CONFIG_TOKEN,
scope: Scope.SINGLETON,
useValue: {
context: ['/a/', '/b/*/c/'],
target: 'https://example.org',
},
multi: true,
}),
];
The ServerModule
has a built-in static server that allows you to distribute static files to users.
To serve files, you need to create a directory public
in the root of the project in which to place the necessary files. After that, all files will be available for request by browsers.
For example, we want to distribute sw.js file from the project's root: for this we create a folder public
in which we put the file sw.js
. Now on the client side, we will be able to request data from the url http://localhost:3000/sw.js. Also, we will most likely need some modifications on the CI/CD side to copy the public folder to the stands.
This function is also available in production. For this purpose, copy the folder public
into the docker container
:::caution
Module will not serve the newly added file on the filesystem, works only for all defined files in the served folder at the time of the server startup.
:::
Papi - API routes for the tramvai
application. More information is available in Papi
(functionality is only available in dev mode)
The server has the ability to increase the response time of all requests.
To do this you must:
- start the application
- send a POST request to
/private/papi/debug-http-request
with a delay for the request:
curl --location --request POST 'http://localhost:3000/tincoin/private/papi/debug-http-request' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'delay=2000'
- check if the application works. Note: after each restart of the server the settings are reset, so after each rebuild it is necessary to access papi again.
- you can disable the timeout by accessing the same papi using the DELETE method
curl --location --request DELETE 'http://localhost:3000/tincoin/private/papi/debug-http-request'
In dev mode, all requests sent through the standard http
and https
libraries for nodejs are logged under a special server:node-debug:request
key. This allows you to see all requests that have been sent to the server, even if no logging has been defined for the requests explicitly.
To enable such logging, simply add the server:node-debug:request
key to the LOG_ENABLE
environment variable
-
/healthz
- always repliesOK
after starting the application -
/readyz
- always repliesOK
after starting the application
Metrics
The metrics module is automatically connected into the server module. For more information on metrics, you can read in the metrics documentation
The cache-warmup module is automatically plugged into the server module. Detailed information on cache warmup can be found in cache-warmup documentation
There are special headers in the module, which help to determine the exact information about the version of the built application, commit, branch, etc:
-
x-app-id - The name of the application specified in
createApp
. Specified in the application code. - x-host - Hostname of the server where the current application is running. Computed in runtime.
-
x-app-version - version of the running application. Transmitted through the environment variable
APP_VERSION
. -
x-deploy-branch - branch from which the current application image was built. Passed through environment variable
DEPLOY_BRANCH
. -
x-deploy-commit - sha commit from which current application image was built. Passed through environment variable
DEPLOY_COMMIT
. -
x-deploy-version - deploy revision number in k8s. Passed through environment variable
DEPLOY_VERSION
. -
x-deploy-repository - application repository link. Passed through environment variable
DEPLOY_REPOSITORY
.
For all of the headers above which are passed via environment variables to be available, you need the external infrastructure to pass them when building and deprovisioning the application image (inside tinkoff this is done automatically).
Header Server-Timing provides additional information about different timings that were spent on server to handle current request. Currently, it shows timings for CommandLineRunner's lines execution.
To see values that related to request look for the header Server-Timing
or check the Timing
tab in browser DevTools for the page's main html.
Module uses loggers with identifiers: server
, server:static
, server:webapp
, server:node-debug:request
Module can send the 103 Early Hints response to provide better performance, though there are several limitations (look here and here).
If you want to enable Early Hints, provide EARLY_HINTS_ENABLED
env variable:
EARLY_HINTS_ENABLED: 'true'
Or provide custom EARLY_HINTS_ENABLED_TOKEN
token (EARLY_HINTS_ENABLED
will be ignored):
import { EARLY_HINTS_ENABLED_TOKEN } from '@tramvai/tokens-server';
const provider = {
provide: EARLY_HINTS_ENABLED_TOKEN,
useValue: () => true,
};
:::info
You must check that the balancers and proxies in front of your application support Early Hints
:::
Currently, module provides hints for next resources:
- Resources with
preconnectLink
type; - General resources, which have the
preloadLink
type; - Page resources, that exist in the
ResourcesRegistry
with'data-critical': "true"
attribute; - Preconnects for CDN urls, that are computed from
preloadLink
ordata-critical
resources, described above;
Server will try to response with 103 as soon as possible and there can be more than one such responses.
curl -I -X HEAD http://localhost:3000
HTTP/1.1 103 Early Hints
Link: <https://www.cdn-tinkoff.ru>; rel=preconnect
Link: <https://www.cdn-tinkoff.ru/frontend-libraries/npm/react-kit-font/1.0.0/TinkoffSans.woff2>; rel=preload; as=font
Link: <https://www-stage.cdn-tinkoff.ru/frontend-libraries/feedback/1.14.0/feedback.css>; rel=preload; as=style
Link: <https://www-stage.cdn-tinkoff.ru>; rel=preconnect
HTTP/1.1 200 OK
...
The default value for server's keepAliveTimeout
is 5000. However, in case you want to set it manually just pass the environment variable NODE_KEEPALIVE_TIMEOUT=[your_value]
. For further reading go to NodeJs server.keepAliveTimeout page.
By default server starts at 3000
port. You have next options to override this value depending on your environment:
-
in dev environment port in fully controlled by
@tramvai/cli
and should be specified by-p
option -
in prod environment it can be specified explicitly as an environment variable
PORT
e.g.PORT=8080
It includes: health checks, liveness checks, metrics.
By default port for utility paths equals base server port and they will use the same http server.
If you want to change this and run utility routes on different server with different port, use token UTILITY_SERVER_PORT_TOKEN
:
import { UTILITY_SERVER_PORT_TOKEN } from '@tramvai/tokens-server';
const providers = [
{
provide: UTILITY_SERVER_PORT_TOKEN,
useValue: 6532,
},
];
Or use env variable UTILITY_SERVER_PORT
with defined value.
env UTILITY_SERVER_PORT=6532 tramvai start app
By default, liveness and readiness probes are available by healtz
and readyz
paths.
If you want to change this paths, use LIVENESS_PATH_TOKEN
and READINESS_PATH_TOKEN
tokens.
import { LIVENESS_PATH_TOKEN, READINESS_PATH_TOKEN } from '@tramvai/tokens-server';
const providers = [
{
provide: LIVENESS_PATH_TOKEN,
useValue: '/custom-liveness',
},
{
provide: READINESS_PATH_TOKEN,
useValue: '/custom-readiness',
},
];