diff --git a/docs/microservices-framework/config-and-mappings/config.md b/docs/microservices-framework/config-and-mappings/config.md index cb85611..c39b06d 100644 --- a/docs/microservices-framework/config-and-mappings/config.md +++ b/docs/microservices-framework/config-and-mappings/config.md @@ -20,8 +20,6 @@ The configuration files under `config/` directory can have specific naming conve Environment variables in Godspeed are essential for securely managing configuration details like API keys, database URLs, and other sensitive information. Godspeed allows two primary ways to configure and access these variables. -> **Note**: For sensitive information such as secrets or passwords, it is recommended to use environment variables in this way to avoid hardcoding values directly in your configuration files. - ### Configuration Setup for Environment Variables Environment variables can be set up using: diff --git a/docs/microservices-framework/config-and-mappings/mappings.md b/docs/microservices-framework/config-and-mappings/mappings.md index 20e2da5..c8339f1 100644 --- a/docs/microservices-framework/config-and-mappings/mappings.md +++ b/docs/microservices-framework/config-and-mappings/mappings.md @@ -35,7 +35,44 @@ If the file name is index.yaml then its content is available directly at global However, for other file names you need to mention the file name while accessing the mappings object like `mappings.generate.genId` ::: -Sample workflow accessing mappings object: +### Sample Datasource Configuration using Mappings + ```yaml + # /src/datasources/aws.yaml + type: aws + default_client_config: + region: <% mappings.aws_region %> + services: + s3: + type: s3 + config: + bucket: <% mappings.aws_s3_bucket %> + dynamodb: + type: dynamodb + config: + tableName: <% mappings.aws_table_name %> + ``` + **Explanation**: + - `aws_region`, `aws_s3_bucket`, and `aws_table_name` are defined in `mappings`. + - This configuration dynamically injects these values into the datasource. + +--- + +### Sample Event Source Configuration using Mappings + ```yaml + # /src/eventsources/cron.yaml + type: cron + events: + cron.0 0 * * *.UTC: + description: Daily task at midnight UTC + fn: daily_update + args: + reportPath: <% mappings.report_path %> + ``` + **Explanation**: + - The `report_path` mapping is used to dynamically define the report path for the workflow triggered by the event. + +--- +### Sample Yaml Workflow accessing mappings ``` - id: httpbinCof_step1 description: Hit http bin with some dummy data. It will send back same as response @@ -47,8 +84,52 @@ Sample workflow accessing mappings object: gender: <% mappings.Gender[inputs.body.Gender] %> id: <% mappings.generate.genId %> ``` +### Sample typescript Workflow accessing mappings + +In this example, mappings is utilized to dynamically retrieve error messages based on an error code. + +``` +import { GSContext, GSStatus } from '@godspeedsystems/core'; + +export default async function(ctx: GSContext, args: any) { + const { mappings, childLogger, inputs } = ctx; + let error: any = {}; + error.code = args?.code; + error.message = args?.message; + + if (!error.code) { + error.code = "E001"; + } + if (!error.message) { + error.message = mappings.error_codes.codes[error.code]; + } + return new GSStatus(false, 400, undefined, error.message, undefined); + } + +``` +### Step-by-Step Explanation of above ts workflow + +- The mappings object is destructured from the ctx (Godspeed context). +- In this case, mappings.error_codes.codes contains a predefined set of error codes and their corresponding messages. +- The function checks if the args object contains an error code and a message, if the code is missing, it defaults to "E001". +- If the message is not provided in the args, the function retrieves it from `mappings.error_codes.codes` using the error code as the key. + +### Mappings file containing error codes +`src/mappings/error_codes.yaml` +```yaml + codes: + E001: Internal Server Error + E002: Missing mandatory field in the request body. + E003: Extra properties found in the request body. + E004: Wrong field type/format/pattern/length in the request body. + E005: Record already exists in the database. + E006: Record to update is not present in the database. + E007: Record to delete is not present in the database. +``` +This ensures that error messages are consistent and centralized. Instead of hardcoding messages in multiple places, they are stored in the mappings file. + -## Use mappings constants in other mapping files +## Using mapping constants in other mapping files You can use mapping constants in other mapping files using coffee/js scripting. For example, you have mapping files `index.yaml`, `relations.json` and `reference.yaml`. Use the mappings from first two files as reference in the third file as follows: diff --git a/docs/microservices-framework/datasources/datasource-plugins/Axios Datasource.md b/docs/microservices-framework/datasources/datasource-plugins/Axios Datasource.md index e85d1a0..3f6b8b7 100644 --- a/docs/microservices-framework/datasources/datasource-plugins/Axios Datasource.md +++ b/docs/microservices-framework/datasources/datasource-plugins/Axios Datasource.md @@ -35,10 +35,44 @@ import { DataSource } from '@godspeedsystems/plugins-axios-as-datasource'; export default DataSource; ``` +### Sample config file for Axios + +The sample config can be modified as per the usecase of your application. + ```yaml title=src/datasources/api.yaml -type: axios -base_url: http://localhost:4000 + type: axios + base_url: https://httpbin.org + + # print all api calls in curl format + curlifiedLogs: true + + # Authentication of API calls with token refresh logic + authn: + fn: my_bank.authn + refreshOn: + statusCode: [401] + + # Common headers to be set in all API calls + headers: + Content-Type: application/json + Cookie: <%mappings.my_bank.auth_workflow_cookie%> + + # Retry logic for failed API calls for ex on Internal server errors or request timeouts + retry: + when: #the condition + status: [500, 503] # an array or single value of codes (optional). Default 500 + message: my custom expected message for retry #And (optionally) when response has this message + max_attempts: 5 + type: constant # or random, exponential + interval: PT15s + # type: exponential + # min_interval: PT5s + # max_internal: PT15s + # type: random + # min_interval: PT5s + # max_internal: PT15s ``` +Retry interval values will be based on [ISO Temporal Duration standard](https://tc39.es/proposal-temporal/docs/duration.html) ### Sample axios datasource yaml workflow ```yaml title=src/functions/sample.yaml @@ -163,42 +197,7 @@ tasks: min_interval: PT5s max_internal: PT15s ``` -The sample config can be modified as per the usecase of your application. For example, -```yaml title=src/datasources/api.yaml -type: axios -base_url: https://httpbin.org - -# print all api calls in curl format -curlifiedLogs: true - -# Authentication of API calls with token refresh logic -authn: - fn: my_bank.authn - refreshOn: - statusCode: [401] - -# Common headers to be set in all API calls -headers: - Content-Type: application/json - Cookie: <%mappings.my_bank.auth_workflow_cookie%> - -# Retry logic for failed API calls for ex on Internal server errors or request timeouts -retry: - when: #the condition - status: [500, 503] # an array or single value of codes (optional). Default 500 - message: my custom expected message for retry #And (optionally) when response has this message - max_attempts: 5 - type: constant # or random, exponential - interval: PT15s - # type: exponential - # min_interval: PT5s - # max_internal: PT15s - # type: random - # min_interval: PT5s - # max_internal: PT15s -``` -Retry interval values will be based on [ISO Temporal Duration standard](https://tc39.es/proposal-temporal/docs/duration.html) ### 4. Authentication of API calls with token refresh logic HTTP requests sometimes need authentication, means they are validated against a token which is passed in the headers