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, 20, ...
+
+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")
@@ -57,16 +56,7 @@ def refresh_auth_token(bb, auth_token):
         "grant_type": "refresh_token",
         "refresh_token": auth_token.refresh_token,
     }
-
-    headers = SDK_HEADERS
-
-    token_response = requests.post(
-        url=bb.auth_token_url,
-        data=data,
-        headers=headers,
-        auth=(bb.client_id, bb.client_secret),
-    )
-
+    token_response = _do_post(data, bb, (bb.client_id, bb.client_secret))
     token_response.raise_for_status()
     return AuthorizationToken(token_response.json())
 
@@ -129,14 +119,7 @@ def get_access_token_from_code(bb, auth_data, callback_code):
         "code_challenge": auth_data["code_challenge"],
     }
 
-    mp_encoder = MultipartEncoder(data)
-    headers = SDK_HEADERS
-    headers["content-type"] = mp_encoder.content_type
-    token_response = requests.post(
-        url=bb.auth_token_url,
-        data=mp_encoder,
-        headers=headers
-    )
+    token_response = _do_post(data, bb, None)
     token_response.raise_for_status()
     token_dict = token_response.json()
     token_dict["expires_at"] = datetime.datetime.now(
@@ -157,3 +140,19 @@ def get_authorization_token(bb, auth_data, callback_code, callback_state):
         raise ValueError("Provided callback state does not match.")
 
     return AuthorizationToken(get_access_token_from_code(bb, auth_data, callback_code))
+
+
+def _do_post(data, bb, auth):
+    mp_encoder = MultipartEncoder(data)
+    headers = SDK_HEADERS
+    headers["content-type"] = mp_encoder.content_type
+    return requests.post(
+        url=bb.auth_token_url,
+        data=mp_encoder,
+        headers=headers
+    ) if not auth else requests.post(
+        url=bb.auth_token_url,
+        data=mp_encoder,
+        headers=headers,
+        auth=auth
+    )

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]
+    }
+}

requirements/req.dev.in

@@ -1,3 +1,4 @@
+pyyaml==5.4.1
 requests==2.27.1
 requests-mock==1.9.3
 requests-toolbelt==0.9.1

requirements/req.dev.txt

@@ -103,6 +103,37 @@ pytest==7.0.1 \
     --hash=sha256:9ce3ff477af913ecf6321fe337b93a2c0dcf2a0a1439c43f5452112c1e4280db \
     --hash=sha256:e30905a0c131d3d94b89624a1cc5afec3e0ba2fbdb151867d8e0ebd49850f171
     # via -r requirements/req.dev.in
+pyyaml==5.4.1 \
+    --hash=sha256:08682f6b72c722394747bddaf0aa62277e02557c0fd1c42cb853016a38f8dedf \
+    --hash=sha256:0f5f5786c0e09baddcd8b4b45f20a7b5d61a7e7e99846e3c799b05c7c53fa696 \
+    --hash=sha256:129def1b7c1bf22faffd67b8f3724645203b79d8f4cc81f674654d9902cb4393 \
+    --hash=sha256:294db365efa064d00b8d1ef65d8ea2c3426ac366c0c4368d930bf1c5fb497f77 \
+    --hash=sha256:3b2b1824fe7112845700f815ff6a489360226a5609b96ec2190a45e62a9fc922 \
+    --hash=sha256:3bd0e463264cf257d1ffd2e40223b197271046d09dadf73a0fe82b9c1fc385a5 \
+    --hash=sha256:4465124ef1b18d9ace298060f4eccc64b0850899ac4ac53294547536533800c8 \
+    --hash=sha256:49d4cdd9065b9b6e206d0595fee27a96b5dd22618e7520c33204a4a3239d5b10 \
+    --hash=sha256:4e0583d24c881e14342eaf4ec5fbc97f934b999a6828693a99157fde912540cc \
+    --hash=sha256:5accb17103e43963b80e6f837831f38d314a0495500067cb25afab2e8d7a4018 \
+    --hash=sha256:607774cbba28732bfa802b54baa7484215f530991055bb562efbed5b2f20a45e \
+    --hash=sha256:6c78645d400265a062508ae399b60b8c167bf003db364ecb26dcab2bda048253 \
+    --hash=sha256:72a01f726a9c7851ca9bfad6fd09ca4e090a023c00945ea05ba1638c09dc3347 \
+    --hash=sha256:74c1485f7707cf707a7aef42ef6322b8f97921bd89be2ab6317fd782c2d53183 \
+    --hash=sha256:895f61ef02e8fed38159bb70f7e100e00f471eae2bc838cd0f4ebb21e28f8541 \
+    --hash=sha256:8c1be557ee92a20f184922c7b6424e8ab6691788e6d86137c5d93c1a6ec1b8fb \
+    --hash=sha256:bb4191dfc9306777bc594117aee052446b3fa88737cd13b7188d0e7aa8162185 \
+    --hash=sha256:bfb51918d4ff3d77c1c856a9699f8492c612cde32fd3bcd344af9be34999bfdc \
+    --hash=sha256:c20cfa2d49991c8b4147af39859b167664f2ad4561704ee74c1de03318e898db \
+    --hash=sha256:cb333c16912324fd5f769fff6bc5de372e9e7a202247b48870bc251ed40239aa \
+    --hash=sha256:d2d9808ea7b4af864f35ea216be506ecec180628aced0704e34aca0b040ffe46 \
+    --hash=sha256:d483ad4e639292c90170eb6f7783ad19490e7a8defb3e46f97dfe4bacae89122 \
+    --hash=sha256:dd5de0646207f053eb0d6c74ae45ba98c3395a571a2891858e87df7c9b9bd51b \
+    --hash=sha256:e1d4970ea66be07ae37a3c2e48b5ec63f7ba6804bdddfdbd3cfd954d25a82e63 \
+    --hash=sha256:e4fac90784481d221a8e4b1162afa7c47ed953be40d31ab4629ae917510051df \
+    --hash=sha256:fa5ae20527d8e831e8230cbffd9f8fe952815b2b7dae6ffec25318803a7528fc \
+    --hash=sha256:fd7f6999a8070df521b6384004ef42833b9bd62cfee11a09bda1079b4b704247 \
+    --hash=sha256:fdc842473cd33f45ff6bce46aea678a54e3d21f1b61a7750ce3c498eedfe25d6 \
+    --hash=sha256:fe69978f3f768926cfa37b867e3843918e012cf83f680806599ddce33c2c68b0
+    # via -r requirements/req.dev.in
 requests==2.27.1 \
     --hash=sha256:68d7c56fd5a8999887728ef304a6d12edc7be74f1cfa47714fc8b414525c9a61 \
     --hash=sha256:f22fa1e554c9ddfd16e6e41ac79759e17be9e492b3587efa038054674760e72d