Merge pull request #14 from CMSgov/jfuqian/BB2-1386-Python-SDK-Configurable-Retry-Params

[BB2-1386] Python SDK expose retry parameters as configurable

Author: James Fuqian

README.md

@@ -36,6 +36,7 @@ The configuration parameters are:
 - The app's callback url
 - The version number of the API
 - The app's environment (the BB2.0 web location where the app is registered)
+- The FHIR call retry settings
 
 | Parameter    | Value                   | Comments                        |
 | ------------ | ----------------------- | ------------------------------- |
@@ -48,6 +49,23 @@ The configuration parameters are:
 For application registration and client id and client secret, please refer to:
 [Blue Button 2.0 API Docs - Try the API](https://bluebutton.cms.gov/developers/#try-the-api)
 
+FHIR requests retry:
+
+Retry is enabled by default for FHIR requests, retry_settings: parameters for exponential back off retry algorithm
+
+| retry parameter   | value (default)      | Comments                         |
+| ----------------- | -------------------- | -------------------------------- |
+| backoff_factor    | 5                    | back off factor in seconds       |
+| total             | 3                    | max retries                      |
+| status_forcelist  | [500, 502, 503, 504] | error response codes to retry on |
+
+the exponential back off factor (in seconds) is used to calculate interval between retries by below formular, where i starts from 0:
+
+backoff factor * (2 ** (i - 1))
+
+e.g. for backoff_factor is 5 seconds, it will generate wait intervals: 2.5, 5, 10, ...
+
+to disable the retry: set total = 0
 
 There are three ways to configure the SDK when instantiating a `BlueButton` class instance:
 
@@ -62,6 +80,11 @@ There are three ways to configure the SDK when instantiating a `BlueButton` clas
                "client_secret": "bar",
                "callback_url": "https://www.fake.com/callback",
                "version": 2,
+               "retry_settings": {
+                   "total": 3,
+                   "backoff_factor": 5,
+                   "status_forcelist": [500, 502, 503, 504]
+               }
             }
       ```
   * JSON config file:
@@ -79,7 +102,12 @@ There are three ways to configure the SDK when instantiating a `BlueButton` clas
           "client_id": "foo",
           "client_secret": "bar",
           "callback_url": "https://www.fake.com/callback",
-          "version": 2
+          "version": 2,
+          "retry_settings": {
+              "total": 3,
+              "backoff_factor": 5,
+              "status_forcelist": [500, 502, 503, 504]
+          }
       }
       ```
 

cms_bluebutton/auth.py

@@ -42,8 +42,7 @@ def set_dict(self, auth_token_dict):
                     auth_token_dict.get("expires_at")
                 ).astimezone(datetime.timezone.utc)
         else:
-            self.expires_at = datetime.datetime.now(datetime.timezone.utc)
-            +datetime.timedelta(seconds=self.expires_in)
+            self.expires_at = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(seconds=self.expires_in)
 
         self.patient = auth_token_dict.get("patient")
         self.refresh_token = auth_token_dict.get("refresh_token")

cms_bluebutton/cms_bluebutton.py

@@ -28,6 +28,10 @@ def __init__(self, config=DEFAULT_CONFIG_FILE_LOCATION):
         self.client_secret = None
         self.callback_url = None
         self.version = 2  # Default to BB2 version 2
+        # initilized with default
+        self.retry_config = {"total": 3,
+                             "backoff_factor": 5,
+                             "status_forcelist": [500, 502, 503, 504]}
 
         self.base_url = None
 
@@ -88,6 +92,12 @@ def set_configuration(self, config):
         self.version = config_dict.get("version", 2)
         self.auth_base_url = "{}/v{}/o/authorize".format(self.base_url, self.version)
         self.auth_token_url = "{}/v{}/o/token/".format(self.base_url, self.version)
+        retrycfg = config_dict.get("retry_settings")
+        if retrycfg:
+            # override default with normalization
+            self.retry_config["total"] = retrycfg.get("total", 3)
+            self.retry_config["backoff_factor"] = retrycfg.get("backoff_factor", 5)
+            self.retry_config["status_forcelist"] = retrycfg.get("status_forcelist", [500, 502, 503, 504])
 
     def get_patient_data(self, config):
         config["url"] = FHIR_RESOURCE_TYPE["Patient"]

cms_bluebutton/fhir_request.py

@@ -1,6 +1,6 @@
 import requests
 from requests.adapters import HTTPAdapter, Retry
-
+from .auth import refresh_auth_token
 from .constants import SDK_HEADERS
 
 
@@ -12,7 +12,9 @@ def fhir_request(bb, config):
         auth_token = new_auth_token
 
     retry_config = Retry(
-        total=3, backoff_factor=5, status_forcelist=[500, 502, 503, 504]
+        total=bb.retry_config.get("total"),
+        backoff_factor=bb.retry_config.get("backoff_factor"),
+        status_forcelist=bb.retry_config.get("status_forcelist")
     )
     full_url = "{}/v{}/{}".format(bb.base_url, bb.version, config["url"])
     headers = SDK_HEADERS
@@ -28,6 +30,6 @@ def fhir_request(bb, config):
 
 def handle_expired(bb, auth_token):
     if auth_token.access_token_expired():
-        return bb.refresh_auth_token(auth_token)
+        return refresh_auth_token(bb, auth_token)
     else:
         return None

cms_bluebutton/tests/test_configs.py

@@ -59,6 +59,17 @@ def test_valid_config():
     assert bb.client_secret == "<your BB2 client_secret here>"
     assert bb.callback_url == "https://www.fake-prod.com/your/callback/here"
     assert bb.version == 1
+    assert bb.retry_config.get("total") == 3
+    assert bb.retry_config.get("backoff_factor") == 5
+    assert bb.retry_config.get("status_forcelist") == [500, 502, 503, 504]
+
+
+def test_valid_config_w_retry():
+    # valid config sbx
+    bb = BlueButton(config=CONFIGS_DIR + "json/bluebutton-sample-config-valid-w-retry.json")
+    assert bb.retry_config.get("total") == 7
+    assert bb.retry_config.get("backoff_factor") == 10
+    assert bb.retry_config.get("status_forcelist") == [500, 502]
 
 
 def test_config_setting_environment():

cms_bluebutton/tests/test_configs/json/bluebutton-sample-config-valid-w-retry.json

@@ -0,0 +1,12 @@
+{
+    "environment": "PRODUCTION",
+    "client_id": "<your BB2 client_id here>",
+    "client_secret": "<your BB2 client_secret here>",
+    "callback_url": "https://www.fake-prod.com/your/callback/here",
+    "version": 1,
+    "retry_settings": {
+        "total": 7,
+        "backoff_factor": 10,
+        "status_forcelist": [500, 502]
+    }
+}