local

Utilities for local deployment.

The following files are expected to exist:

In the directory above the server’s root directory: mSTConfig.json, mIDConfig.json, mITConfig.json, sumoLog.json, kinesisLog.json, s3Log.json, customerConfig.json, key.json, and locationConfig.json. If they don’t exist when the script launches, defaults will be set up.

• For mSTConfig.json:

 {
   "basePath": "Base path of the mST server, e.g., `/mST/v1`",
   "protocol": "Protocol for the mST server, e.g., `http:` (default: `http:`)",
   "domainName": "Domain name of the mST server",
   "port": "Port for the mST server, e.g., `8025`",
   "passphrase": "Passphrase used to generate the public/private key pair; if not present, mST will use a regular key",
   "update": "Whether mST should be updated (default: `false`). If the address is localhost, mST will be updated.",
   "admin": {
     "clientId": "Client ID used to obtain an mST admin token, e.g., `12345`",
     "clientSecret": "Client secret used to obtain an mST admin token, e.g., `timeForSecret`"
   }
 }

domainName must exist. When domainName is localhost, port must also exist. When domainName is localhost, the local IP will replace localhost. When domainName is different from localhost, port is ignored.

• For mIDConfig.json:

 {
   "basePath": "Base path of the mID server, e.g., `/mID/v1`",
   "protocol": "Protocol for the mID server, e.g., `http:` (default: `http:`)",
   "domainName": "Domain name of the mID server",
   "port": "Port for the mID server, e.g., `8015`",
   "implicit": {
     "key": "Key to sign and verify the signature of a user token, e.g., `timeForSecret`",
     "audience": "URL defining the audience used in the user token, e.g., `https://mimik`"
   }
 }

The same domainName/port rules as in mSTConfig.json apply.

• For mITConfig.json:

 {
   "basePath": "Base path of the mIT server, e.g., `/mIT/v1`",
   "protocol": "Protocol for the mIT server, e.g., `http:` (default: `http:`)",
   "domainName": "Domain name of the mIT server",
   "port": "Port for the mIT server, e.g., `8050`"
 }

The same domainName/port rules as in mSTConfig.json apply.

• For sumoLog.json:

 {
   "<serverType>": {
     "url": "Base URL for Sumo Logic, e.g., `https://endpoint2.collection.us2.sumologic.com/receiver/v1/http/`",
     "code": "The code for Sumo Logic (the part after the last `/` in the URL)"
   },
   "default": {
     "url": "Base URL for Sumo Logic, e.g., `https://endpoint2.collection.us2.sumologic.com/receiver/v1/http/`",
     "code": "The code for Sumo Logic (the part after the last `/` in the URL)"
   }
 }

• For kinesisLog.json:

 {
   "region": "Region of the Kinesis implementation",
   "accessKeyId": "Access key ID for Kinesis",
   "secretAccessKey": "Secret access key for Kinesis",
   "streamNameInfo": "Name of the Kinesis stream for info",
   "streamNameError": "Name of the Kinesis stream for errors",
   "streamNameOther": "Name of the Kinesis stream for all other levels"
   "maxEvents": "Number of events buffered before sending to Kinesis",
   "timeout": "Number of minutes before a timeout triggers sending to Kinesis",
   "maxSize": "Maximum size in bytes before sending to Kinesis",
   "maxRetries": "Maximum retries to connect to Kinesis",
   "httpOptions": {
      "socketTimeout": "Socket timeout for the HTTP handler (in millisecond)",
      "connectionTimeout": "Connection timeout for the HTTP handler (in millisecond)",
   }
 }

• For s3Log.json:

 {
   "region": "Region of the S3 implementation",
   "accessKeyId": "Access key ID for S3",
   "secretAccessKey": "Secret access key for S3",
   "bucketname": "Name of the S3 bucket used to store information",
   "maxEvents": "Number of events buffered before sending to S3",
   "timeout": "Number of minutes before a timeout triggers sending to S3",
   "maxSize": "Maximum size in bytes before sending to S3"
 }

• for key.json:

 {
   "bitbucket": {
     "username": "Username to access the Bitbucket account",
     "password": "Password to access the Bitbucket account"
   },
   "swaggerhub": "Key to access private APIs on SwaggerHub"
 }

• For locationConfig.json:

 {
   "url": "URL of the location provider",
   "key": "API key used to make requests to the location provider"
 }

A property may be defined for each serverType involved. If the serverType does not exist, the default entry is used.

• for customerConfig.json: see mST README.md file for an example of a customer configuration. This may have to be updated to reflect the new server.
• In the local directory under the server's root directory: two files, start.json and testStart.json, may exist. start.json is used when npm start is executed; testStart.json is used when npm test is executed. If these files don't exist, example-start.json is used to create start.json and testStart.json. Additionally, example-testStart.json is used to create testStart.json; values in example-testStart.json take precedence over values in example-start.json. The configuration of these files depends on the server's configuration parameters.

Example start.json for mIT:

 {
   "NODE_ENV": "local",
   "LOG_LEVEL": "debug",
   "CONSOLE_LEVEL": "silly",
   "DATABASE_NAME": "itResources",
   "SERVER_PORT": 8050,
   "IP_LOCATION_PROVIDER": "http://localhost:9000/json",
   // "LOCATION_PROVIDER": "http://ip-api.com/json",
   // "DEBUG": "swagger-tools:middleware.*",
   "SERVER_SECURITY_SET": "off"
 }

Although all files use the .json extension, you may still add // comments to make them more explicit or to remove parameters.

Reserved environment variables used by the library for configuration:

• oauthImplicitNeeded: if the service handles user tokens, the implicit configuration is required
• mIDNeeded: if the service targets mID
• locationNeeded: if location translation is needed
• standAlone: if the service must operate without other services (if the service has targets, 500 errors are likely)

If SERVER_ID is not set in start.json or testStart.json, it will be assigned using uuidv4.

For tests, a JSON file (server-test.json) is created in the project root (.). This file contains information needed to start the tests:

 {
   "start": "Information needed to set environment variables for the test",
   "CUSTOMER_NAME": "Customer name used to set up customer config",
   "CUSTOMER_CODE": "Customer code used to set up customer config (`not available for mST`)",
   "BASE_PATH": "Base path of the API",
   "MST_TOKEN": "mST admin token for creating clients (`not available in standAlone`)",
   "ADMIN_TOKEN": "Admin token of the service (`not available in standAlone`)",
   "MID_TOKEN": "mID admin token for creating users when `authImplicitNeeded` is set (`not available in standAlone`)"
 }

In standAlone mode, the test can obtain tokens using oauth-helper-temp.

Example

import local from '@mimik/local';
or
import { mSTTestSetup, mSTSetup, mITTestSetup, mITSetup, testSetup, setup, dotFiles, scripts, unScripts, commitCheckMsg, start2process, testJsonFile} from '@mimik/local';

• local
  • static
    • .testJsonFile : string
  • inner
    • async
      • ~commitCheckMsg() ⇒ Promise
    • sync
      • ~mSTTestSetup() ⇒
      • ~mSTSetup() ⇒
      • ~mITTestSetup() ⇒
      • ~mITSetup() ⇒
      • ~testSetup() ⇒
      • ~setup() ⇒
      • ~dotFiles() ⇒
      • ~scripts() ⇒
      • ~unscripts() ⇒
      • ~start2process(start) ⇒

local.testJsonFile : string

Path to the JSON test file.

Kind: static constant of local

local~commitCheckMsg() ⇒ Promise

Check the validity of the commit message.

Kind: inner method of local
Returns: Promise - .
Category: async
Fulfil: null.

Exits with code 1 if the commit message is not correct or if the branch is not a Jira generated branch.

local~mSTTestSetup() ⇒

Set up mST for tests.

Kind: inner method of local
Returns: null.

Exits with code 1 on error.

Actions performed:

1. Retrieve the API definition from SwaggerHub.
2. Generate a JSON object and store it in a file in the project root (.) to enable tests.

Files required:

| Filename | Description | | -------- | ----------- | | ../sumoLog.json | Sumologic endpoints and code | ../kinesisLog.json | AWS Kinesis configuration | ../s3Log.json | AWS S3 configuration | ../mSTConfig.json | mST configuration | ../mITConfig.json | mIT configuration | ../locationConfig.json | Location provider URL and key (when needed) | ../key.json | Github username and password or Swaggerhub key | ./local/testStart.json | Local configuration (if it does not exist, example-start.json will be used to create testStart.json)
Category: sync

local~mSTSetup() ⇒

Set up mST.

Kind: inner method of local
Returns: null.

Exits with code 1 on error.

Actions performed:

1. Retrieve the API definition from SwaggerHub.
2. Generate a shell script in the project root (.) to start the server.

Files required:

| Filename | Description | | -------- | ----------- | | ../sumoLog.json | Sumologic endpoints and code | ../kinesisLog.json | AWS Kinesis configuration | ../s3Log.json | AWS S3 configuration | ../mSTConfig.json | mST configuration | ../mITConfig.json | mIT configuration | ../locationConfig.json | Location provider URL and key (when needed) | ../key.json | Github username and password or Swaggerhub key | ./local/start.json | Local configuration (if it does not exist, example-start.json will be used to create start.json)
Category: sync

local~mITTestSetup() ⇒

Set up mIT for tests.

Kind: inner method of local
Returns: null.

Exits with code 1 on error.

Two modes are available:

1. Standalone
2. With mST

The environment variable STAND_ALONE selects the mode.

When standalone, the following actions are performed:

1. Retrieve the API definition from SwaggerHub.
2. Obtain an admin token for the service.
3. Generate a JSON object and store it in a file under the project root (.).

In standAlone mode, dependencies are not reachable and operations that contact dependencies will most likely return a 500 error.

When mST and other servers are present, the following actions are performed:

1. Retrieve the API definition from SwaggerHub.
2. Obtain an admin token for mST.
3. Register the service in mST.
4. Register an admin client for the service in mST.
5. Obtain an admin token for the service.
6. Obtain an admin token for mID if needed.
7. Generate a JSON object and store it in a file under the project root (.).

Files required:

| Filename | Description | | -------- | ----------- | | ../sumoLog.json | Sumologic endpoints and code | ../kinesisLog.json | AWS Kinesis configuration | ../s3Log.json | AWS S3 configuration | ../mSTConfig.json | mST configuration | ../mITConfig.json | mIT configuration | ../locationConfig.json | Location provider URL and key (when needed) | ../key.json | Github username and password or Swaggerhub key | ./local/testStart.json | Local configuration (if it does not exist, example-start.json will be used to create testStart.json)
Category: sync

local~mITSetup() ⇒

Set up mIT.

Kind: inner method of local
Returns: null.

Exits with code 1 on error.

Two modes are available:

1. Standalone
2. With mST

The environment variable STAND_ALONE selects the mode.

When standalone, the following actions are performed:

1. Retrieve the API definition from SwaggerHub.
2. Obtain an admin token for the service.
3. Generate a shell script in the project root (.) to start the server.

In standAlone mode, dependencies are not reachable and operations that contact dependencies will most likely return a 500 error.

When mST is present, the following actions are performed:

1. Retrieve the API definition from SwaggerHub.
2. Obtain an admin token for mST.
3. Register the service in mST.
4. Generate a shell script in the project root (.) to start the server.

Files required:

| Filename | Description | | -------- | ----------- | | ../sumoLog.json | Sumologic endpoints and code | ../kinesisLog.json | AWS Kinesis configuration | ../s3Log.json | AWS S3 configuration | ../mSTConfig.json | mST configuration | ../mITConfig.json | mIT configuration | ../locationConfig.json | Location provider URL and key (when needed) | ../key.json | Github username and password or Swaggerhub key | ./local/start.json | Local configuration (if it does not exist, example-start.json will be used to create start.json)
Category: sync

local~testSetup() ⇒

Set up a service (not mST or mIT) for tests.

Kind: inner method of local
Returns: null.

Exits with code 1 on error.

Two modes are available:

1. Standalone
2. With mST/mID and other dependent servers

The environment variable STAND_ALONE selects the mode.

When standalone, the following actions are performed:

1. Retrieve the API definition from SwaggerHub.
2. Obtain an admin token for the service.
3. Generate a JSON object and store it in a file under the project root (.).

In standAlone mode, dependencies are not reachable and operations that contact dependencies will most likely return a 500 error.

When mST and other servers are present, the following actions are performed:

1. Retrieve the API definition from SwaggerHub.
2. Obtain an admin token for mST.
3. Set up the customer in mST.
4. Register the service in mST.
5. Register an admin client for the service in mST.
6. Obtain an admin token for the service.
7. Obtain an admin token for mID if needed.
8. Generate a JSON object and store it in a file under the project root (.).

Files required:

| Filename | Description | | -------- | ----------- | | ../sumoLog.json | Sumologic endpoints and code | ../kinesisLog.json | AWS Kinesis configuration | ../s3Log.json | AWS S3 configuration | ../mSTConfig.json | mST configuration | ../mITConfig.json | mIT configuration | ../mIDConfig.json | mID configuration (when needed) | ../customerConfig.json | mST customer configuration | ../locationConfig.json | Location provider URL and key (when needed) | ../key.json | Github username and password or Swaggerhub key | ./local/testStart.json | Local configuration (if it does not exist, example-start.json will be used to create testStart.json)
Category: sync

local~setup() ⇒

Set up a service (not mST or mIT).

Kind: inner method of local
Returns: null.

Exits with code 1 on error.

Two modes are available:

1. Standalone
2. With mST/mID and other dependent servers

The environment variable STAND_ALONE selects the mode.

When standalone, the following actions are performed:

1. Retrieve the API definition from SwaggerHub.
2. Obtain an admin token for the service.
3. Generate a shell script to start the server.

In standAlone mode, dependencies are not reachable and operations that contact dependencies will most likely return a 500 error.

When mST and other servers are present, the following actions are performed:

1. Retrieve the API definition from SwaggerHub.
2. Obtain an admin token for mST.
3. Set up the customer in mST.
4. Register the service in mST.
5. Generate a shell script in the project root (.) to start the server.

The following files are needed to perform these actions:

| Filename | Description | | -------- | ----------- | | ../sumo.json | Sumo Logic endpoints and code | ../kinesisLog.json | Kinesis configuration | ../s3Log.json | S3 configuration | ../mSTConfig.json | mST configuration | ../mITConfig.json | mIT configuration | ../mIDConfig.json | mID configuration (when needed) | ../customerConfig.json | mST customer configuration | ../locationConfig.json | Location provider URL and key (when needed) | ../key.json | Github username and password or Swaggerhub key | ./local/start.json | Local configuration (if it does not exist, example-start.json will be used to create start.json)
Category: sync

local~dotFiles() ⇒

Utility to create rule files.

Kind: inner method of local
Returns: null.

Creates the rule files for:

• eslint -> eslint.config.js.
• c8 -> .nycrc
• github -> .gitignore

If a file already exists, it will be overwritten.
Category: sync

local~scripts() ⇒

Utility to add scripts and husky.

Kind: inner method of local
Returns: null.

Adds scripts and husky to package.json. If a script already exists, it will be overwritten.
Category: sync

local~unscripts() ⇒

Utility to remove scripts and husky.

Kind: inner method of local
Returns: null.

Removes scripts and husky from package.json. Only removes the scripts that are in the script file.
Category: sync

local~start2process(start) ⇒

Set up the environment variables based on given JSON object.

Kind: inner method of local
Returns: null.
Category: sync

| Param | Type | Description | | --- | --- | --- | | start | object | JSON object that is used to configure the environment variables. The comments (starting by //) are ignored. |