Skip to content

Home

Jump to bottom
Sandeep Kumar edited this page Apr 18, 2022 · 2 revisions

Index:

  1. Objective

  2. Technical Architecture 2.1. Technology stacks 2.1.1 Technology stack for Protocol Backend Architecture: 2.2. App configuration and installation requirements 2.3. Protocol Backend Architecture 2.3.1 Data Model 2.3.2 ORM 2.3.3 Database design 2.3.4 BAP Mode Trigger APIs 2.3.5 BAP Mode Response APIs 2.3.6 BPP Mode Trigger APIs 2.3.7 BAP Mode Response APIs 4.5.6. Network policy configuration

  3. Deployment Architecture 3.1 The general architecture of the app 3.2 Current Implementation

  4. Installation Guide on AWS 4.1 Primary Server Installation 4.1.1 Prerequisites 4.1.2 Launch EC2 Instance 4.1.3 Connect to the EC2 Instance 4.1.4 Assign an Elastic IP to Primary EC2 4.1.5 Configuration of Primary EC2 4.1.6 Configuration CertBot (This step is for staging) 4.2 Code Server Installation  

1. Objective:

2. Technical Architecture:

2.1. Technology Stack:

2.1.1. Technology stack for Protocol Backend Architecture:

● Typescript It is a strict syntactical superset of JavaScript and adds optional static typing to the language. TypeScript is designed for the development of large applications and trans compiles to JavaScript.

2.2. App configuration and installation requirements:

Below are the setups for the local environment for BIAB Protocol Server.

Protocol Server Installation Guide

Protocol Server requires the following services to be installed: ● NodeJs ● MongoDB ● NPM ● Typescript

Configuring Protocol Server

It uses the configuration file to configure the server. ● default.yaml needs to be present inside the config folder. In order to create the configuration file, you can refer to config-sample.yml.

Basic Configuration

Protocol Server requires port number and db url to be configured. port: 3000 db: url: mongodb://localhost:27017/protocol ● The port requires a valid integer number. The default port number is 3000. ● The db URL requires a valid MongoDB URL.

App Configuration

Protocol Server can be configured to run as a BAP(Beckn Application Platform) or as a BPP(Beckn Provider Platform). All app configurations are required to be inside the app object only.

BAP Configuration

In order to configure the protocol server as BAP, you need to provide the following configuration:

  1. Specify the app mode to be bap. app: mode: bap

  2. Specify the actions that this app will serve. actions: - search - init

  3. Provide the sign public key and private key privateKey: "your private key" publicKey: "your public key"

  4. Specify the subscriberId and subscriberUri as per the registry which is also known as bap_id and bap_uri. subscriberId: "dev.bap.protocol-server.com" subscriberUri: "https://dev.bap.protocol-server.com/"

  5. Specify the registry URL. registryUrl: “https://registry.becknprotocol.io/subscribers”

  6. Specify whether to authenticate the requests or not. This can be done by providing the auth property. auth: true

  7. The unique key id is also required in order to create authorization. uniqueKey: "dev.bap.protocol-server.key"

  8. Provide the Operation Region Information. city: "std:080" country: "IND"

  9. Provide the ttl for the requests and TTL for lookup cache. ttl: "P1M" lookupCacheTTL: "PT10S"

  10. Provide the HTTP Configuration. The httpTimeout specifies the timeout for the HTTP requests in milliseconds. The httpRetryCount will specify the number of retries for the HTTP requests. httpTimeout: 5000 httpRetryCount: 2

  11. Provide the client URL in order to communicate the responses to the client. clientUrl: "https://beckn.free.beeceptor.com/clientURL"

BPP Configuration

In order to configure the protocol server as BPP, you need to provide the following configuration:

  1. Specify the app mode to be bpp. app: mode: bap

  2. Specify the actions that this app will serve. actions: - search - init

  3. Provide the signing public key and private key. privateKey: "your private key" publicKey: "your public key"

  4. Specify the subscriberId and subscriberUri as per the registry which is also known as bpp_id and bpp_uri. subscriberId: "dev.bap.protocol-server.com" subscriberUri: "https://dev.bap.protocol-server.com/"

  5. Specify the registry URL. registryUrl: “https://registry.becknprotocol.io/subscribers‘

  6. Specify whether to authenticate the requests or not. This can be done by providing the auth property. auth: true

  7. The unique key id is also required in order to create authorization. uniqueKey: "dev.bap.protocol-server.key"

  8. Provide the Operation Region Information. city: "std:080" country: "IND”

  9. Provide the TTL for the requests and TTL for the lookup cache. ttl: "P1M" lookupCacheTTL: "PT10S"

  10. Provide the HTTP Configuration. The httpTimeout specify the timeout for the HTTP requests in milliseconds. The httpRetryCount will specify the number of retries for the HTTP requests. httpTimeout: 5000 httpRetryCount: 2

  11. Provide the client URL in order to communicate the responses to the client which is a provider application in the case of BPP. clientUrl: "https://beckn.free.beeceptor.com/clientURL"

Open API Schema Validation

In order to validate the API endpoint requests, responses, and headers against the same endpoint spec in beckn protocols' specifications, you need to provide the required open API schema file core.yaml. core.yaml should be consisting of specifications of each API as per the beckn protocol specifications. core.yaml should be located inside the schemas folder.

Installation

Once the whole protocol server is either configured to BAP or BPP, all npm packages needs to be installed. npm install

Running the server in Development Mode

Once all the packages are installed we can run the protocol server in development mode by using the following command. npm run dev

Building the Protocol Server

The whole server is built on typescript so, in order to run the server in production mode, we need to build the server in JS source code. npm run build

All the JS source code will be located in the dist folder.

Running the Protocol Server Once the server is built, we can run the server in production mode by using the following command. npm run start

2.3. Protocol Backend Architecture:

2.3.1 Data Model: Not available

2.3.2 ORM: Not available

2.3.3 Database design: Not available

2.3.4 BAP Mode Trigger APIs:

  1. POST “/search” - Triggering search from Client Layer
  2. POST “/select" - Triggering select from Client Layer
  3. POST "/init"- Triggering init from Client Layer
  4. POST “/confirm”- Triggering confirm from Client Layer
  5. POST "/status"- Triggering status from Client Layer
  6. POST "/update"- Triggering update from Client Layer
  7. POST "/track"- Triggering track from Client Layer
  8. POST "/rating"- Triggering rating from Client Layer
  9. POST "/support"- Triggering support from Client Layer
  10. POST "/cancel"-Triggering cancel from Client Layer

2.3.5 BAP Mode Response APIs:

  1. POST “/on_search” - Receiving search response from Beckn Network
  2. POST “/on_select" - Receiving select response from Beckn Network
  3. POST "/on_init"- Receiving init response from Beckn Network
  4. POST “/on_confirm”- Receiving confirm response from Beckn Network
  5. POST "/on_status"- Receiving status response from Beckn Network
  6. POST "/on_update"- Receiving update response from Beckn Network
  7. POST "/on_track"- Receiving track response from Beckn Network
  8. POST "/on_rating"- Receiving rating response from Beckn Network
  9. POST "/on_support"- Receiving support response from Beckn Network
  10. POST "/on_cancel"- Receiving cancel response from Beckn Network

2.3.6 BPP Mode Trigger APIs:

  1. POST “/search” - Receiving search request from Beckn Network
  2. POST “/select" - Receiving select request from Beckn Network
  3. POST "/init"- Receiving init request from Beckn Network
  4. POST “/confirm”- Receiving confirm request from Beckn Network
  5. POST "/status"- Receiving status request from Beckn Network
  6. POST "/update"- Receiving update request from Beckn Network
  7. POST "/track"- Receiving track request from Beckn Network
  8. POST "/rating"- Receiving rating request from Beckn Network
  9. POST "/support"- Receiving support request from Beckn Network
  10. POST "/cancel"- Receiving cancel request from Beckn Network 2.3.7 BAP Mode Response APIs:
  11. POST “/on_search” - Receiving search response from Provider Application Layer.
  12. POST “/on_select" - Receiving select response from Provider Application Layer.
  13. POST "/on_init"- Receiving init response from Provider Application Layer.
  14. POST “/on_confirm”- Receiving confirm response from Provider Application Layer.
  15. POST "/on_status"- Receiving status response from Provider Application Layer.
  16. POST "/on_update"- Receiving update response from Provider Application Layer.
  17. POST "/on_track"- Receiving track response from Provider Application Layer.
  18. POST "/on_rating"- Receiving rating response from Provider Application Layer.
  19. POST "/on_support"- Receiving support response from Provider Application Layer.
  20. POST "/on_cancel"- Receiving cancel response from Provider Application Layer.

3. Deployment Architecture:

3.1 The general architecture of the app is as below:

  1. The Protocol Servers are deployed on multiple instances and are responsible for handling different calls to and from the network.

  2. Depending upon the load that each call handles, the respective app that is configured to handle the call can be set for AutoScaling.

  3. The Load Balancer (i.e. Nginx or Apache) are responsible for routing the calls as per the URL to the respective app.

    3.2 Current Implementation :

  4. The Protocol server has an Elastic IP which Points to the Public Internet World.

  5. Used certbot to issue an SSL certificate for the main server.

  6. On Receiving a request the protocol server redirects the request to the main hosting the redirection is done through the NGINX proxy pass mechanism.

  7. The Main Server contains the code base for different endpoints

  8. Our main server runs on port 5000 which is configurable through the default.yaml file.

  9. In order to accomplish the request from port 80 to 5000, we use an NGINX proxy pass.

  10. Pm2 package is used to start the server.

  11. In case we need to host different endpoints in different serves then we need to spin different ec2 machines a. Pull the code using GIT. (As Docker image is not present) else we can use docker pull to get the latest image b. Install the node modules c. Change the default.yaml (which is basically a config file) d. Install the pm2 globally (Docker Image not configured. Else we could run using docker) e. We need to create private key & public key then use it in default.yaml f. We need to put the URI of the main server in subscriberUri g. Install Mongo DB in the code server. h. Create a username, password & database. Follow this link to do so. Mongo Link. i. Build the server code npm run build j. pm2 start dist/app.js to start the server.

  12. Installation Guide on AWS: 4.1 Primary Server Installation: 4.1.1 Prerequisites:

  13. Need to have full Permission on EC2 (Avoid being root user). a. Go to IAM b. Select User from the right pan c. Click on Add User d. Give User Name e. Select Access key - Programmatic access && Password - AWS Management Console access f. Click Next Permissions button g. Click on Add a Group h. Search on Group name ec2 and select AmazonEC2FullAccess i. Click on create group j. Add tags to determine the IAM user. k. Review the user & group creation l. Create the User. m. Logout from root user & login as the new created User

    4.1.2 Launch EC2 Instance:

  14. Go to EC2 Dashboard.

  15. Click on Instance.

  16. Click on Launch Instance.

  17. Give The Instance name

  18. Select your desired OS. (Here we will discuss about Ubuntu OS image)

  19. Select the instance type based on requirement

  20. Create or use an existing key pair (If you are creating a new key pair please download the key) a. Go to the downloaded folder where your key exists. b. Change the Permission of the downloaded key file to 400. c. You can run this command chmod 400 <key file name>

  21. In network setting select Allow SSH traffic from, Allow HTTP traffic from the internet a. In case you are setting up the Instance for code server you need to select Allow SSH traffic from, Allow HTTP traffic from the internet and give the IP of the Primary server. Ex : 52.123.2.2:32

  22. Leave storage Option

  23. Click on Launch Instance.

4.1.3 Connect to the EC2 Instance:

  1. Go to EC2 Dashboard.

  2. Click on Instance.

  3. Select the newly created instance or existing instance

  4. Click connect from the top menu.

  5. Go to SSH Client

  6. Copy the last command from the screen which looks like the below. a. ssh -i "" ubuntu@<aws endpoint/url>

    4.1.4 Assign an Elastic IP to  Primary EC2:

  7. Go to EC2 Dashboard.

  8. Click on Elastic IP under Network & Security

  9. Click Allocate Elastic IP Address

  10. Wait for a few sec and select the newly created Elastic IP.

  11. Click on the action and from the dropdown select Associate Elastic IP address

  12. By default, selection will be Instance.

  13. Go to the instance below & try to search your instance.

  14. Click Associate.

4.1.5 Configuration of Primary EC2:

  1. We need to install NGINX or APACHE

  2. In this, we will be discussing the NGINX server set up. a. sudo apt-get update b. sudo apt-get install nginx c. To verify If the Installation is done or not sudo nginx -v

  3. Go to cd /etc/nginx/sites-available

  4. Sudo nano default

  5. Go to location line and add the below code a. b. proxy_pass http://<2nD Server IP>; c. proxy_http_version 1.1; d. proxy_set_header Upgrade $http_upgrade; e. proxy_set_header Connection 'upgrade'; f. proxy_set_header Host $host; g. proxy_cache_bypass $http_upgrade h. i.

  6. Then save the default file by CTRL + X

  7. Then press Y

  8. Now we have to restart our NGINX server

  9. To restart run this command sudo systemctl restart nginx

  10. In case of Code Server we need to change the default file like ```

  11. proxy_pass http://localhost:;

  12. proxy_http_version 1.1;

  13. proxy_set_header Upgrade $http_upgrade;

  14. proxy_set_header Connection 'upgrade';

  15. proxy_set_header Host $host;

  16. proxy_cache_bypass $http_upgrade

  18.

4.1.6 Configuration CertBot (This step is for staging):

  1. Follow This link to activate the SSL for Certbot Ubuntu

4.2 Code Server Installation:

  1. Follow the steps from 6.1.2 to 6.1.3 & 6.1.5
  2. Pull the Codebase from git. a. To pull the code we need to set up the ssh key to the git.
  3. Pull the code using GIT. (As Docker image is not present) else we can use docker pull to get the latest image
  4. Install the node modules
  5. Change the default.yaml (which is basically a config file)
  6. Install the pm2 globally (Docker Image not configured. Else we could run using docker)
  7. We need to create a private key & public key and then use it in default.yaml
  8. We need to put the URI of the main server in subscriberUri
  9. Install Mongo DB in the code server. a. Follow the Mongo Installation
  10. Create a username, password & database. Follow this link to do so. Mongo Link.
  11. Build the server code npm run build
  12. Pm2 start dist/app.js to start the server.
  13. Then we need to set up the proxy server in Nginx a. To do that look at 6.1.5 point 10

  Client / Protocol Persistence Layer Initial State

  1. Client Layer will configure a webhook on the protocol layer config file
  2. client_protocol_session_table

message_id transaction_id request response

Transaction Flow

  1. Client will call protocol layer /write API

id message_id transaction_id server_error request response response_read 1 2cf8b342-cd99 null null { … } null false

If ( schema validation is successful)

  1. The protocol layer will generate message_id and (optional) transaction_id and return them in the same session (200 OK) of the /write API call

Else

  1. Protocol layer will return (400 Bad Request) as a response to the /write API call with error details

End if

  1. Protocol layer calls network (after signing)
  2. The network will respond with ACK / NACK

If ACK,

  1. Protocol Server receives callback after some time
  2. Protocol Server validates callback (signature and schema)

If validation is successful,

  1. Protocol Server passes response in the webhook of Client Layer

id message_id transaction_id request response response_read 1 2cf8b342-cd99 null { … } { … } false

keep-alive will be (statically / dynamically) configured at the UI layer as per business logic of the app.

UI / Client Interaction

Client will have a timeout configured that will automatically send a 408 timeout to UI if the session is open for a duration > timeout.

Once a response is received from the protocol server, the client layer will construct the standard response object as per the Client layer specification and push the response object back to the UI via push notifications, WebSockets, polling etc.

Clone this wiki locally