Aura –

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Gateway API architecture and components

Development architecture and technical components of Aura Gateway API

Technical foundations

aura-gateway-api is mainly a web server built on Typescript 4.3 using nodejs as engine. It is api-first designed, using OpenAPI v3 to provide the API definition and openapi-backend to handle swagger specification.

aura-gateway-api server is composed by several plugins, which provide different functionalities to this component. From the different capabilities that aura-gateway-api can manage, certain plugins are used by all of them and others are specific of one capability.

A channel, service, or skill uses an application to connect with aura-gateway-api following this communication protocol.

Architecture overview

The following figure shows the main technical components of the aura-gateway-api.

ConfigurationManager

ConfigurationManager is a handler for configuration, obtained through a configuration file or environment variables.

RedisConnector

RedisConnector is a handler connection to redis.

Kpis-handler

KpisHandler is the module responsible for writing the KPIs entities.

HTTP server

Microservice is implemented as an HTTP server (AuraGatewayServer) that exposes an API to receive the request to be validated.

Middlewares

The route published in the API definition file is handled by a controller but, before a request lands on its controller, it goes through a series of middlewares that provides some common steps needed by all the controllers of the server such as: request validation, common parameters extraction, logging, metrics initialization, etc.

Plugins

Different plugins provide functionality to aura-gateway-api.

Check the available ones together with detailed information in: aura-gateway-api plugins.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Gateway API operational overview

Description of Aura Gateway API operation and communication protocol

Communication protocol

aura-gateway-api communication protocol is synchronous, depending on the endpoint.

A new component comes here into play: application, defined as an entity used by a channel, service or skill to connect with aura-gateway-api.

An application has a specific configuration and will be the entry point to the aura-gateway-api flow, previous pass through Kernel, meaning that the input parameters for aura-gateway-api come from the application, and no specific information regarding the channel, service or skill is required.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

Aura Gateway API environment variables

List of environment variables handled by Aura Gateway API

Properties marked in bold are mandatory.
Properties marked in italics are optional.

Introduction

aura-gateway-api environment variables can be common for all plugins or specific for each of them.

Common properties

Property	Type	Description	Modifiable by OB?
AURA_AUTHORIZATION_HEADER	string	APIKey to use with aura-services.	NO
AURA_CHANNELS_CONFIGURATION_API_ENDPOINT	string	Configuration API URL where the bot should get the configuration of all the channels available in the environment.	NO
AURA_ENCRYPTION_ALGORITHM	string	Encryption algorithm that will be used to validate the APIKey. By default: `aes-256-cbc`.	NO
AURA_ENCRYPTION_IV_LENGTH	number	Size for the initialization vector used by the encryption algorithm that validates the APIKey. By default: `16`.	NO
AURA_ENCRYPTION_IV_POSITION	number	Position where to insert the initialization vector in the final string with the encrypted payload. By default: `35`.	NO
AURA_ENCRYPTION_KEY	string	Encryption key or comma-separated list of encryption keys to be used in the environment. It is mainly used to decrypt the APIKeys.	NO. It would break database encrypted data and APIKey validation.
AURA_ENVIRONMENT_NAME	string	Name of the environment where the server is deployed. Used during server make-up to handle the indexes of the database properly.	NO
AURA_HTTP_KEEP_ALIVE	boolean	Use of keep-alive in HTTP connections. Used in monkey-patcher. By default: `true`.	NO
AURA_HTTP_KEEP_ALIVE_MSECS	number	Number of milliseconds to keep alive HTTP connections. Used in monkey-patcher. By default: `100000`.	NO
AURA_HTTP_KEEP_MAX_SOCKETS	number	Maximum number of sockets. Used in monkey-patcher. By default: `200`.	NO
AURA_HTTP_MAX_REQUEST_SIZE	string	Maximum size in bytes of body request. Allowed values must indicate the units: 10 mb, 200 kb, etc. By default, `20mb`.	NO
AURA_HTTP_PATHS_LOG_DISABLED	string	HTTP paths separated by commas whose request would not be logged. By default `aura-kpis,static-resources` Used in monkey-patcher.	NO
AURA_INTERNAL_RETRIES	number	Number of retries to be made by the server in case of error in an internal request. By default: `1`.	NO
AURA_KPI_ENABLED	Boolean	Boolean value, indicating whether aura-gateway-api writes entity files or not. By default: `true`	NO, excepting if requested by Product or Operations teams
AURA_KPI_FILE_PREFIX	string	String with the prefix used in the KPIs entities files of this service. By default, `gwapi/GWAPI`	NO
AURA_KPI_REMOVE_SPECIAL_CHARACTERS	string	Regular expression for removing special characters Default:`\n\r`	NO
AURA_KPI_STORE_MODE	string	It indicates which is the destination of the KPIs entities files. Default: `blob`. If `file`, they will be stored locally to the instance, in the folder shown in `KPI_TO_DSV_LOCAL_FILES_DIRECTORY`. For development purposes. If `blob`, they will be stored remotely in the Azure blob container shown in `KPIS_STORE_CONTAINER`. Mandatory in environments running on k8s.	NO, only configurable when running aura-gateway-api locally.
AURA_KPI_TO_DSV_CACHE_TTL	number	Number with the amount of milliseconds to cache existing requests to calculate their duration. Default: 1800.	NO
AURA_KPI_TO_DSV_DELIMITER	string	Field delimiter to be used in KPIs entities files. Default: \|	NO. It will break all the analysis and processes running on top of these files.
AURA_KPI_TO_DSV_EXTENSION	string	Extension to be used in KPIs entities files. Default: `txt`	NO. If changed without changing aura-kpis-uploader, the files will not be uploaded to Kernel.
AURA_KPIS_BLOB_STORE_INTERVAL	number	Time interval in milliseconds to upload asynchronously logs to the `KPIS_STORE_CONTAINER`. Default: `60000`. Only needed if `KPI_STORE_MODE==blob`.	NO. In pre/production, it must be `blob` so the files will be uploaded to Kernel instance afterwards. Setting file for development is recommended.
AURA_KPIS_LOG_API_REQUEST_BODY	boolean	Flag to log or not the request body of the API calls. Default: `true`	YES. Once disabled, to enable run performance tests to validate if it is possible to write them.
AURA_KPIS_LOG_API_RESPONSE_BODY	boolean	Flag to log or not the response body of the API calls. Default: `true`	YES. Once disabled, to enable run performance tests to validate if it is possible to write them.
AURA_KPIS_STORE_CONTAINER	string	The name of the Azure Blob container to store KPIs entities files. By default, `aura-kpis`. It MUST be the same than the one configured in `KPIS_UPLOADER` module. Only needed if `KPI_STORE_MODE==blob`.	NO. If changed without changing aura-kpis-uploader, the files will not be uploaded to Kernel.
AURA_LOGGING_FORMAT	string	Format to be used in monitoring logs: `json` or `dev`(more visual format). By default: `json`.	NO. Only for development, set it to `dev`.
AURA_LOGGING_LEVEL	string	Level to be used in logs, from more to less verbose: `'TRACE', 'DEBUG', 'INFO', 'WARN', 'ERROR', 'FATAL', 'OFF'`. By default: `INFO`.	NO
AURA_MAKEUP_MODE	string	It allows `dev` mode for the make-up process with the value `local`. By default: `full`.	NO
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCESS_KEY	string	Microsoft Storage password of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_COMMON_ACCOUNT	string	Microsoft Storage account of the common storage. Currently used for KPI storing.	NO. Only if Operations Team changes it.
AURA_MICROSOFT_AZURE_STORAGE_ACCESS_KEY	string	Microsoft Storage password of the deployment.	NO
AURA_MICROSOFT_AZURE_STORAGE_ACCOUNT	string	Microsoft Storage account of the environment.	NO
AURA_MICROSOFT_AZURE_STORAGE_CONFIGURATION_CONTAINER	string	Aura configuration container name. By default: `aura-configuration`.	NO
AURA_MICROSOFT_AZURE_STORAGE_STATIC_CONTAINER_NAME	string	Aura static container name.	NO
AURA_HTTP_MONKEY_PATCHER_ENABLED	boolean	Flag to indicate whether Monkey Patcher is used in service or not.	NO
AURA_REQUEST_TIMEOUT	number	Number of seconds to wait for a request. By default: `30 * 1000`.	NO
AURA_REQUEST_DEADLINE_TIMEOUT	number	Deadline timeout for the request.	NO
AURA_RETRIES_CODES	string[]	List of codes that will be used to retry the request. By default: `['ECONNRESET']`.	NO
AURA_SERVER_PORT	number	Port to where server is listening. By default: `8989`.	NO
AURA_SERVER_REMOTE_CONTAINER_PREFIX	number	Remote container prefix. By default: `aura-gateway-api`.	NO
AURA_SERVER_RETRIES	number	Number of retries made by aura-gateway-api in case of error in an HTTP request. By default: `3`.	NO, only if checked and validated with Aura Global Team.
AURA_SERVER_RETRY_DELAY	number	Delay between retries in case of error. By default: `100`.	NO, only if checked and validated with Aura Global Team.
AURA_SERVER_RETRY_FACTOR	number	Factor to multiply delay for every HTTP request retried. By default: `10`.	NO, only if checked and validated with Aura Global Team.
AURA_SERVICE_ENVIRONMENT	string	Type of environment: `'DEV', 'PRE', 'PRO'`. By default, `DEV`. It is used during locale translation, to get the correct text reference.	NO
AURA_SERVICES_PATH	string	Path where the services are located. By default: `/aura-services/`.	NO
AURA_SHUTDOWN_GRACEFUL_TTL	number	Time in milliseconds to complete the SHUTDOWN signal and process all the messages in queue before SIGTERM. By default: `25 1000`.	NO
AURA_SWAGGER_LOCAL_PATH	string	Location of the swagger file generated from all loaded plugins. By default: `swagger.yaml`. Used during makeup to upload the file to remote.	NO
AURA_SWAGGER_PLUGIN_PATH	string	Location of the swagger file of every plugin. Default: swagger.yaml.	NO
AURA_SWAGGER_LOCAL_CORE_PATH	string	Location of aura-generative-service swagger base file. By default: `swagger-core.yaml`.	NO
AURA_SWAGGER_REMOTE_CONTAINER_PREFIX	string	Remote container prefix to store the swagger information. By default: `swagger`	NO
AURA_SOURCE_PATH_AVRO_ADAPTERS	string	Relative path to file with the dimensions and entities to transform to Avro.	NO
AURA_TRUSTED_HOSTNAMES	string	Comma-separated list of the trusted domains URL of the current environment.	YES, all the trusted domains must be added.
AURA_VERSION	string	Mandatory, release of Aura.	NO

aura-development-api plugin

Property	Type	Description	Modifiable by OB?
AURA_REDIS_MODE	string	Mode of Redis distribution. Values: `CLUSTER`, `SENTINEL`, `SINGLE`. By default: `SENTINEL`.	NO
AURA_REDIS_PREFIX	string	Redis prefix.	NO
AURA_REDIS_SENTINEL_INSTANCE_NAME	string	Name of the Redis instance. Used in `SENTINEL` mode.	NO
AURA_REDIS_HOSTS	string	String with a list of nodes separated by ‘,’, including host and port separated by ‘:’. For example: “localhost:port,localhost2:port2”.	NO
AURA_REDIS_DATABASE	number	Database number for `SINGLE` or `SENTINEL` mode. By default: `0`.	YES
AURA_REDIS_PASSWORD	string	String with Redis password.	YES
AURA_REDIS_USE_CONNECTION_POOL	boolean	Use pool connections for Redis. By default: `true`.	YES
AURA_REDIS_CONNECTION_POOL_MIN	number	Minimum number of connections in the pool. By default: `2`.	YES
AURA_REDIS_CONNECTION_POOL_MAX	number	Maximum number of connections in the pool. By default: `100`.	YES
AURA_REDIS_MAX_RECONNECT_RETRIES	number	Number of retries to connect to Redis. By default: `25`	YES
AURA_REDIS_MAX_RECONNECT_INTERVAL	number	Time in milliseconds to wait before reconnecting to Redis. By default: `5000`.	YES
DEV_AURA_BEHAVIOR_CACHE_TTL	number	Maximum lifetime of behavior cache in seconds. After this time, the system will delete the message. By default: `60 * 60` (60 min).	NO in production environments. This feature could only be activated in development environments.
DEV_AURA_BEHAVIOR_COMMAND_PATTERN	string	Pattern to recognize a behavior command. By default: `gateway(:\| +)(get\|set\|unset)(:\| +)(\w+)(:\| +)?.+`	NO in production environments. This feature could only be activated in development environments.
DEV_AURA_BEHAVIOR_MANAGER_ACTIVE	boolean	Flag to indicate whether or not aura-behavior-manager module should be activated in the current deployment. It is only valid for development environments. By default: `false`	NO in production environments. This feature could only be activated in development environments.
DEV_AURA_BEHAVIOR_PREFIX	string	Used in cache key prefix and in command name. By default: `gateway`.	NO in production environments. This feature could only be activated in development environments.
DEV_AURA_BEHAVIOR_SETTINGS_FILE_CRON_PATTERN	string	CRON expression associated with the reload time of the configuration file. Configuration file is defined in: `DEV_AURA_BEHAVIOR_SETTINGS_FILE_MICROSOFT_AZURE_STORAGE`. By default: `\/5 * * *`.	NO in production environments. This feature could only be activated in development environments.
DEV_AURA_BEHAVIOR_SETTINGS_FILE_MICROSOFT_AZURE_STORAGE	string	Profile configuration file location for the aura-behavior-manager. By default: `aura-gateway/aura-gateway-behavior-manager.json`	NO in production environments. This feature could only be activated in development environments.

aura-generative-api plugin

Property	Type	Description	Modifiable by OB?
AURA_MODEL_GW_ENDPOINT	string	URL of Atria Model GW API.	NO. In any case, it must be the internal k8s URL pointing to the `atria-model-gateway`.

aura-update-me-api plugin

Property	Type	Description	Modifiable by OB?
AURA_CONFIGURATION_RETRIES	number	Number of retries to get the configuration. By default: `3`.	NO, only if checked and validated with Aura Global Team.
AURA_CONFIGURATION_RETRY_DELAY	number	Delay between retries in case of error. By default: `100`.	NO, only if checked and validated with Aura Global Team.
AURA_CONFIGURATION_RETRY_FACTOR	number	Factor to multiply delay for every HTTP request retried. By default: `10`.	NO, only if checked and validated with Aura Global Team.

aura-nlp-resolution-process-services plugin

aura-feedback-api plugin

Property	Type	Description	Modifiable by OB?
AURA_MODEL_GW_ENDPOINT	string	URL of Atria Model GW API.	NO. In any case, it must be the internal k8s URL pointing to the `atria-model-gateway`.

aura-agents-api plugin

Property	Type	Description	Modifiable by OB?
AURA_AGENTS_MANAGER_ENDPOINT	string	URL of agents-manager API.	NO. In any case, it must be the internal k8s URL pointing to the `agents-manager`.
AURA_AUTHORIZATION_HEADER	string	APIKey to use with aura-services.	NO

aura-operations-api plugin

Property	Type	Description	Modifiable by OB?
AURA_CONFIG_WATCHER_ENDPOINT	string	URL of config-watcher API.	NO. In any case, it must be the internal k8s URL pointing to the `config-watcher`.

Docs:

Mon, 01 Jan 0001 00:00:00 +0000

API definition for Aura Gateway API

Description of API swaggers for aura-gateway-api component

APIs index

Aura Gateway API
Definition of the complete API in aura-gateway-api
Aura Gateway Core API
Definition of the core API in aura-gateway-api that handle its operations
Aura Gateway Agents API
This API is exposed in Kernel to handle agents services: https://developers.baikalplatform.com/apis/aura-aiservices/
Aura Generative API
This API is exposed in Kernel to handle Generative and RAG services: https://developers.baikalplatform.com/apis/aura-aiservices/
Aura NLP Resolution API
This API is exposed in Kernel to handle NLP as a Service: https://developers.baikalplatform.com/apis/aura-aiservices/
Aura Feedback API
This API is exposed in Kernel to provide feedback about the behavior of Generative and RAG services: https://developers.baikalplatform.com/apis/aura-aiservices/
Aura Gateway Update-Me API
Aura Gateway Development API
Only available in development environments.
Dapr PubSub API
Aura Operations API
API that include a set of endpoints related to operations over Aura.