BE-679 Create online documentation phase -2

BE-674 Connection to DB lost, reverting Signed-off-by: nfrunza <nfrunza@gmail.com> Change-Id: Ia3d2603c99d1a395aaf2809cea8b52fbf012a062
hyperledger-labs · Nov 4, 2019 · 834f233 · 834f233
1 parent 76a1611
commit 834f233
Show file tree

Hide file tree

Showing 41 changed files with 324 additions and 68 deletions.
diff --git a/app/persistence/PersistenceFactory.js b/app/persistence/PersistenceFactory.js
@@ -25,6 +25,7 @@ class PersistenceFactory {
 			// Avoid to load all db Persist module
 			const PostgreSQL = require('./postgreSQL/Persist');
 			const persistence = new PostgreSQL(dbconfig);
+			await persistence.getPGService().handleDisconnect();
 			return persistence;
 		}
 		throw new ExplorerError(explorer_error.ERROR_1003, db);

diff --git a/app/persistence/postgreSQL/PgService.js b/app/persistence/postgreSQL/PgService.js
@@ -18,10 +18,9 @@
  * limitations under the License.
  */
 
-// const { Client } = require('pg');
+const { Client } = require('pg');
 
 const fs = require('fs');
-const Pool = require('pg-pool');
 
 const helper = require('../../common/helper');
 
@@ -66,10 +65,7 @@ class PgService {
 			 * Value this.pgconfig.ssl.key is private key
 			 */
 			const { rejectUnauthorized, requestCert } = this.pgconfig.ssl;
-			const printConfig = {
-				rejectUnauthorized,
-				requestCert
-			};
+			const printConfig = { rejectUnauthorized, requestCert };
 			logger.info('SSL to Postgresql enabled with settings: ', printConfig);
 		} else {
 			logger.info('SSL to Postgresql disabled');
@@ -82,21 +78,42 @@ class PgService {
 
 		logger.info(`connecting to Postgresql ${connectionString}`);
 
-		this.client = new Pool(this.pgconfig);
-
-		console.log('DB Pool created: ');
-		logger.info('DB Pool created: ');
-
-		this.client.on('error', err => {
-			console.log('db error:', err);
-			logger.error('db error:', err);
-		});
+		this.client = new Client(this.pgconfig);
 
 		logger.info(
 			'Please set logger.setLevel to DEBUG in ./app/helper.js to log the debugging.'
 		);
 	}
 
+	/**
+	 *
+	 *
+	 * @memberof PgService
+	 */
+	async handleDisconnect() {
+		try {
+			this.client.on('error', err => {
+				console.log('db error', err);
+				if (err.code === 'PROTOCOL_CONNECTION_LOST') {
+					this.handleDisconnect();
+				} else {
+					throw err;
+				}
+			});
+			await this.client.connect();
+		} catch (err) {
+			if (err) {
+				/*
+				 * We introduce a delay before attempting to reconnect,
+				 * To avoid a hot loop, and to allow our node script to
+				 * Process asynchronous requests in the meantime.
+				 */
+				console.log('error when connecting to db:', err);
+				setTimeout(this.handleDisconnect, 2000);
+			}
+		}
+	}
+
 	/**
 	 *
 	 *

diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
@@ -13,7 +13,7 @@ Architecture Reference
 .. toctree::
    :maxdepth: 1
 
-
+   architecture/index
    architecture/ui_presentation
    architecture/backend
    architecture/databaselayer

diff --git a/docs/source/architecture/backend.rst b/docs/source/architecture/backend.rst
@@ -21,19 +21,19 @@ Back End Layer
 Main components of the HLExplorer back end can be listed as:
 
   .. .. image:: ../images/backend.png
-  .. :width: 850px
+     .. :width: 850px
 
 .. toctree::
    :maxdepth: 1
 
-
    restapi
    gateway
    dbservices
    metrics
    synchronizer
    websockets
    configuration
+   logs
 
 
 

diff --git a/docs/source/architecture/configuration.rst b/docs/source/architecture/configuration.rst
@@ -5,9 +5,6 @@
 Configuration
 ===========================================
 
-.. TODO
-
-
 One of the requirements to receive blocks, transactions, and config properties from Hyperledger Fabric blockchain is to configure Hyperledger Explorer
 to be able to connect to the default fabric network. For this we tried to have a minimal as possible configuration by taking advantage of the latest
 Hyperledger Fabric `Service Discovery <https://hyperledger-fabric.readthedocs.io/en/release-1.4/discovery-overview.html>`__,
@@ -45,16 +42,23 @@ Modify config.json to point to your first-network network `connection-profile <h
 ::
 
 	"first-network" is the name of your connection profile, and can be changed to any name.
+
 	"name" is a name you want to give to your fabric network, you can change only value of the key "name".
+
 	"profile" is the location of your connection profile, you can change only value of the key "profile"
+
 	Modify connection profile in the JSON file first-network.json:
 	Change "fabric-path" to your fabric network disk path in the first-network.json file:
 	/blockchain-explorer/app/platform/fabric/connection-profile/first-network.json
 	Provide the full disk path to the adminPrivateKey config option, it usually ends with "_sk", for example:
-	"/fabric-path/fabric-samples/first-network/crypto-config/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/aaacd899a6362a5c8cc1e6f86d13bfccc777375365bbda9c710bb7119993d71c_sk"
-	"adminUser" is the the admin user of the network, in this case it's fabric CA or an identity user.
-	"adminPassword" is the password for the admin user.
-	"enableAuthentication" is a flag to enable authentication using a login page, setting to false
+
+	* "/fabric-path/fabric-samples/first-network/crypto-config/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/aaacd899a6362a5c8cc1e6f86d13bfccc777375365bbda9c710bb7119993d71c_sk"
+
+	* "adminUser" is the the admin user of the network, in this case it's fabric CA or an identity user.
+
+	* "adminPassword" is the password for the admin user.
+
+	* "enableAuthentication" is a flag to enable authentication using a login page, setting to false
 	will skip authentication.
 
 

diff --git a/docs/source/architecture/databaselayer.rst b/docs/source/architecture/databaselayer.rst
@@ -5,6 +5,8 @@
 Database Layer
 ===========================================
 
+
+
 .. TODO
 
 

diff --git a/docs/source/architecture/gateway.rst b/docs/source/architecture/gateway.rst
@@ -5,4 +5,11 @@
 Gateway to Hyperledger Fabric
 ===========================================
 
+Due to the fact that Hyperledger Fabric network channel can constantly change, the peer, orderer and CA components, contributed by the
+different organizations in the network, will come and go, the need of reconfiguration for the Hyperledger Explorer becomes very difficult to maintain
+and get real time updates of the fabric network.
+
+Hypeledger Explorer took another approach to connect to Hyperledger Fabric after the introduction of the "fabric-network" module by the
+`Hyperledger Fabric SDK for NodeJS <https://fabric-sdk-node.github.io/release-1.4/module-fabric-network.html>`__.
+
 .. TODO
diff --git a/docs/source/architecture/index.rst b/docs/source/architecture/index.rst
@@ -0,0 +1,12 @@
+
+.. SPDX-License-Identifier: Apache-2.0
+
+
+Hyperledger Explorer Architecture
+----------------------------------
+
+The high-level architecture of Hyperledger Explorer
+
+
+.. image:: ../images/hl_explorer_architecture.png
+   :width: 850px
diff --git a/docs/source/architecture/logs.rst b/docs/source/architecture/logs.rst
@@ -0,0 +1,47 @@
+
+
+.. SPDX-License-Identifier: Apache-2.0
+
+
+Logs
+===========================================
+
+Logging is an important part of supporting Hyperledger Explorer in the complete application life cycle. Logs are created to debug,
+and provide information while troubleshooting, and detect problems, and any failure of the application.
+
+Why do we log?
+
+* Performance, we care about performance, and to measure it we count on logging.
+* Debugging, we need a mechanism to see when, and where the error occurred, and under what conditions.
+* Error tracking, when errors do occur, we need to know when they started, and how often they occurred.
+* Analyzing, logs are valuable sources of information. We can analyze logs to discover usage patterns and make decisions.
+
+
+We have divided logs by the following categories:
+
+* Application logs
+
+  * We record, information, debug, error and other types of events, these logs are located in ``$blockchain-explorer/logs/app`` directory.
+
+* Database logs
+
+  * Useful information, debug, and errors are recorded during the CRUD operations, logs are located in ``$blockchain-explorer/logs/db`` directory.
+
+* Console logs
+
+  * We print different levels of messages to stdout and stderr, all the console logs are also redirected to a console.log files for the auditing purposes, location the the logs are in ``$blockchain-explorer/logs/console`` directory.
+
+
+.. note::
+
+   Logs are rotated every 7 days.
+
+
+
+
+
+
+
+
+
+
diff --git a/docs/source/architecture/restapi.rst b/docs/source/architecture/restapi.rst
@@ -5,6 +5,62 @@
 REST API
 ===========================================
 
+The Hyperledger Explorer REST API provides endpoints to retrieve information, and metrics about the Hyperledger Fabric blockchain,
+such as blocks, transactions, nodes, chaincodes, channels, peers, and other information.
+
+The REST API is designed to be used in the Node.js JavaScript runtime, and uses built-in middleware function in Express to parse incoming
+requests with JSON payloads and is based on body-parser.
+
+Security on the Hyperledger Explorer REST API is enforced with a token. All requests made to the REST API must have a token that is generated by the API.
+
+Overview
+~~~~~~~~~
+The REST API list of features include:
+ * Authorization routes
+    * Login
+    * Network list
+ * Platform routes
+    * Transactions by organization(s)
+    * Channel info
+    * Channel list
+    * Current channel
+    * Change channel
+    * Block by number
+    * Peer status
+ * Database routes
+    * Blocks counts
+    * Block list
+    * Transactions counts
+    * Transaction list
+    * Transaction information
+    * Block and transaction list
+    * Chaincode list
+    * Peer list
+    * Transactions per minute
+    * Transactions per hour(s)
+    * Blocks per minute
+    * Blocks per hour(s)
+
+
+
+Swagger
+~~~~~~~~
+To learn more about REST API, and use an interactive API console to submit requests you can take advantage of the `SWAGGER <https://github.com/hyperledger/blockchain-explorer/tree/master#Hyperledger-Explorer-Swagger>`__
+provided by the Hyperledger Explorer.
+
+Some screenshots of the SWAGGER in local environment.
+
+
+Hyperledger Explorer SWAGGER home page.
+
+.. image:: ../images/swagger.png
+   :width: 850px
+
+
+.. image:: ../images/swagger-blocks.png
+   :width: 850px
+
+
+
+
 
-Rest Api is
-.. TODO
diff --git a/docs/source/architecture/ui_presentation.rst b/docs/source/architecture/ui_presentation.rst
@@ -3,15 +3,14 @@
 
 
 
-User Interface Presentation
-===========================================
+Front End
+========================================
 
 When choosing a framework, or a library in most of the cases we look at the performance, maturity, and support this is where ReactJs was a benefit
 to us and used in our HLExplorer front end.
 
-
-.. add an overview
-
+The high-level architecture of presentation layer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .. image:: ../images/ui_presentation.png
    :width: 850px
 

diff --git a/docs/source/architecture/websockets.rst b/docs/source/architecture/websockets.rst
@@ -5,4 +5,16 @@
 WebSockets
 ===========================================
 
+
+Websocket API is used to push information from the server to the clients. Information about new blocks, stats.
+are pushed via Websocket API. This is a convenient API that reduces load on clients and server.
+
+The image below illustrates how the notification is displayed when new blocks are received from the blockchain network, and a link to the
+new block details is provided in the notification panel.
+
+
+.. image:: ../_static/images/hl_new_block_notification_panel.png
+   :width: 850px
+
+
 .. TODO
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -109,8 +109,16 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-# html_theme = 'alabaster'
+#html_theme = 'alabaster'
 html_theme = 'sphinx_rtd_theme'
+# html_theme = 'sphinxdoc'
+# html_theme = 'traditional'
+# html_theme = 'bizstyle'
+# html_theme = 'haiku'
+# html_theme = 'nature'
+# html_theme = 'pyramid'
+# html_theme = 'pyramid'
+
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the

diff --git a/docs/source/images/block_details.png b/docs/source/images/block_details.png
diff --git a/docs/source/images/block_hour.png b/docs/source/images/block_hour.png
diff --git a/docs/source/images/block_minute.png b/docs/source/images/block_minute.png
diff --git a/docs/source/images/blocks.png b/docs/source/images/blocks.png
diff --git a/docs/source/images/blocks_hour.png b/docs/source/images/blocks_hour.png
diff --git a/docs/source/images/chaincodes.png b/docs/source/images/chaincodes.png
diff --git a/docs/source/images/channels.png b/docs/source/images/channels.png
diff --git a/docs/source/images/dashboard.png b/docs/source/images/dashboard.png
diff --git a/docs/source/images/dashboard_dark_theme.png b/docs/source/images/dashboard_dark_theme.png
diff --git a/docs/source/images/filter_transactions.png b/docs/source/images/filter_transactions.png
diff --git a/docs/source/images/hl_explorer_architecture.png b/docs/source/images/hl_explorer_architecture.png
diff --git a/docs/source/images/login.png b/docs/source/images/login.png
diff --git a/docs/source/images/logs_dir.png b/docs/source/images/logs_dir.png
diff --git a/docs/source/images/network.png b/docs/source/images/network.png
diff --git a/docs/source/images/notification.png b/docs/source/images/notification.png
diff --git a/docs/source/images/notification_panel.png b/docs/source/images/notification_panel.png
diff --git a/docs/source/images/register_user.png b/docs/source/images/register_user.png
diff --git a/docs/source/images/swagger-blocks.png b/docs/source/images/swagger-blocks.png
diff --git a/docs/source/images/swagger.png b/docs/source/images/swagger.png
diff --git a/docs/source/images/transactions.png b/docs/source/images/transactions.png
diff --git a/docs/source/images/tx_details.png b/docs/source/images/tx_details.png
diff --git a/docs/source/images/tx_hour.png b/docs/source/images/tx_hour.png
diff --git a/docs/source/images/tx_min.png b/docs/source/images/tx_min.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -29,7 +29,6 @@ Table of contents
 
    introduction
    architecture
-   ui_screens/ui_screens
    getting_started
    tutorials
    CONTRIBUTING