RFC: Blocking queries index param

nomad/api/acl.py

@@ -37,45 +37,54 @@ def generate_bootstrap(self):
         """
         return self.request("bootstrap", method="post").json()
 
-    def get_tokens(self):
+    def get_tokens(self, index=None):
         """ Get a list of tokens.
 
             https://www.nomadproject.io/api/acl-tokens.html
 
+            optional_arguments:
+              - index  :(dict) optional, provides a dictionary for keeping track of x-nomad-index
+
             returns: list
 
             raises:
               - nomad.api.exceptions.BaseNomadException
               - nomad.api.exceptions.URLNotFoundNomadException
         """
 
-        return self.request("tokens", method="get").json()
+        return self.request("tokens", method="get", index=index).json()
 
-    def get_token(self, id):
+    def get_token(self, id, index=None):
         """ Retrieve specific token.
 
             https://www.nomadproject.io/api/acl-tokens.html
 
+            optional_arguments:
+              - index  :(dict) optional, provides a dictionary for keeping track of x-nomad-index
+
             returns: dict
 
             raises:
               - nomad.api.exceptions.BaseNomadException
               - nomad.api.exceptions.URLNotFoundNomadException
         """
-        return self.request("token", id, method="get").json()
+        return self.request("token", id, method="get", index=index).json()
 
-    def get_self_token(self):
+    def get_self_token(self, index=None):
         """ Retrieve self token used for auth.
 
             https://www.nomadproject.io/api/acl-tokens.html
 
+            optional_arguments:
+              - index  :(dict) optional, provides a dictionary for keeping track of x-nomad-index
+
             returns: dict
 
             raises:
               - nomad.api.exceptions.BaseNomadException
               - nomad.api.exceptions.URLNotFoundNomadException
         """
-        return self.request("token", "self", method="get").json()
+        return self.request("token", "self", method="get", index=index).json()
 
     def create_token(self, token):
         """ Create token.

nomad/api/allocation.py

@@ -44,14 +44,17 @@ def __getitem__(self, item):
         except nomad.api.exceptions.URLNotFoundNomadException:
             raise KeyError
 
-    def get_allocation(self, id):
+    def get_allocation(self, id, index=None):
         """ Query a specific allocation.
 
            https://www.nomadproject.io/docs/http/alloc.html
 
+            arguments:
+              - id
+              - index  :(dict) optional, provides a dictionary for keeping track of x-nomad-index
             returns: dict
             raises:
               - nomad.api.exceptions.BaseNomadException
               - nomad.api.exceptions.URLNotFoundNomadException
         """
-        return self.request(id, method="get").json()
+        return self.request(id, method="get", index=index).json()

nomad/api/allocations.py

@@ -32,17 +32,18 @@ def __iter__(self):
         response = self.get_allocations()
         return iter(response)
 
-    def get_allocations(self, prefix=None):
+    def get_allocations(self, prefix=None, index=None):
         """ Lists all the allocations.
 
            https://www.nomadproject.io/docs/http/allocs.html
             arguments:
               - prefix :(str) optional, specifies a string to filter allocations on based on an prefix.
                         This is specified as a querystring parameter.
+              - index  :(dict) optional, provides a dictionary for keeping track of x-nomad-index
             returns: list
             raises:
               - nomad.api.exceptions.BaseNomadException
               - nomad.api.exceptions.URLNotFoundNomadException
         """
         params = {"prefix": prefix}
-        return self.request(method="get", params=params).json()
+        return self.request(method="get", params=params, index=index).json()

nomad/api/base.py

@@ -10,12 +10,13 @@ class Requester(object):
 
     ENDPOINT = ""
 
-    def __init__(self, address=None, uri='http://127.0.0.1', port=4646, namespace=None, token=None, timeout=5, version='v1', verify=False, cert=(), region=None, **kwargs):
+    def __init__(self, address=None, uri='http://127.0.0.1', port=4646, namespace=None, token=None, timeout=5, blocking_timeout=360, version='v1', verify=False, cert=(), region=None, **kwargs):
         self.uri = uri
         self.port = port
         self.namespace = namespace
         self.token = token
         self.timeout = timeout
+        self.blocking_timeout = blocking_timeout
         self.version = version
         self.verify = verify
         self.cert = cert
@@ -79,12 +80,13 @@ def request(self, *args, **kwargs):
             data=kwargs.get("data", None),
             json=kwargs.get("json", None),
             headers=kwargs.get("headers", None),
-            allow_redirects=kwargs.get("allow_redirects", False)
+            allow_redirects=kwargs.get("allow_redirects", False),
+            index=kwargs.get("index", None)
         )
 
         return response
 
-    def _request(self, method, endpoint, params=None, data=None, json=None, headers=None, allow_redirects=None):
+    def _request(self, method, endpoint, params=None, data=None, json=None, headers=None, allow_redirects=None, index=None):
         url = self._url_builder(endpoint)
         qs = self._query_string_builder(endpoint)
 
@@ -99,16 +101,20 @@ def _request(self, method, endpoint, params=None, data=None, json=None, headers=
             except TypeError:
                 headers = {"X-Nomad-Token": self.token}
 
+        if index and index.get("X-Nomad-Index"):
+            params["index"] = index["X-Nomad-Index"]
+
         response = None
 
         try:
             method = method.lower()
             if method == "get":
+                timeout = self.blocking_timeout if index else self.timeout
                 response = self.session.get(
                     url=url,
                     params=params,
                     headers=headers,
-                    timeout=self.timeout,
+                    timeout=timeout,
                     verify=self.verify,
                     cert=self.cert,
                     allow_redirects=allow_redirects
@@ -148,6 +154,8 @@ def _request(self, method, endpoint, params=None, data=None, json=None, headers=
                 )
 
             if response.ok:
+                if index is not None:
+                    index["X-Nomad-Index"] = response.headers["X-Nomad-Index"]
                 return response
             elif response.status_code == 400:
                 raise nomad.api.exceptions.BadRequestNomadException(response)

nomad/api/deployment.py

@@ -43,33 +43,35 @@ def __getitem__(self, item):
         except nomad.api.exceptions.URLNotFoundNomadException:
             raise KeyError
 
-    def get_deployment(self, id):
+    def get_deployment(self, id, index=None):
         """ This endpoint reads information about a specific deployment by ID.
 
            https://www.nomadproject.io/docs/http/deployments.html
 
             arguments:
               - id
+              - index  :(dict) optional, provides a dictionary for keeping track of x-nomad-index
             returns: dict
             raises:
               - nomad.api.exceptions.BaseNomadException
               - nomad.api.exceptions.URLNotFoundNomadException
         """
-        return self.request(id, method="get").json()
+        return self.request(id, method="get", index=index).json()
 
-    def get_deployment_allocations(self, id):
+    def get_deployment_allocations(self, id, index=None):
         """ This endpoint lists the allocations created or modified for the given deployment.
 
            https://www.nomadproject.io/docs/http/deployments.html
 
             arguments:
               - id
+              - index  :(dict) optional, provides a dictionary for keeping track of x-nomad-index
             returns: list of dicts
             raises:
               - nomad.api.exceptions.BaseNomadException
               - nomad.api.exceptions.URLNotFoundNomadException
         """
-        return self.request("allocations", id, method="get").json()
+        return self.request("allocations", id, method="get", index=index).json()
 
     def fail_deployment(self, id):
         """ This endpoint is used to mark a deployment as failed. This should be done to force the scheduler to stop

nomad/api/deployments.py

@@ -56,14 +56,16 @@ def __getitem__(self, item):
         except nomad.api.exceptions.URLNotFoundNomadException:
             raise KeyError
 
-    def get_deployments(self, prefix=""):
+    def get_deployments(self, prefix="", index=None):
         """ This endpoint lists all deployments.
 
            https://www.nomadproject.io/docs/http/deployments.html
 
             optional_arguments:
               - prefix, (default "") Specifies a string to filter deployments on based on an index prefix.
                         This is specified as a querystring parameter.
+              - index  :(dict) optional, provides a dictionary for keeping track of x-nomad-index
+
 
             returns: list of dicts
             raises:

nomad/api/evaluation.py

@@ -45,30 +45,32 @@ def __getitem__(self, item):
         except nomad.api.exceptions.URLNotFoundNomadException:
             raise KeyError
 
-    def get_evaluation(self, id):
+    def get_evaluation(self, id, index=None):
         """ Query a specific evaluation.
 
            https://www.nomadproject.io/docs/http/eval.html
 
             arguments:
               - id
+              - index  :(dict) optional, provides a dictionary for keeping track of x-nomad-index
             returns: dict
             raises:
               - nomad.api.exceptions.BaseNomadException
               - nomad.api.exceptions.URLNotFoundNomadException
         """
         return self.request(id, method="get").json()
 
-    def get_allocations(self, id):
+    def get_allocations(self, id, index=None):
         """ Query the allocations created or modified by an evaluation.
 
            https://www.nomadproject.io/docs/http/eval.html
 
             arguments:
               - id
+              - index  :(dict) optional, provides a dictionary for keeping track of x-nomad-index
             returns: list
             raises:
               - nomad.api.exceptions.BaseNomadException
               - nomad.api.exceptions.URLNotFoundNomadException
         """
-        return self.request(id, "allocations", method="get").json()
+        return self.request(id, "allocations", method="get", index=index).json()

nomad/api/evaluations.py

@@ -57,17 +57,18 @@ def __iter__(self):
         evaluations = self.get_evaluations()
         return iter(evaluations)
 
-    def get_evaluations(self, prefix=None):
+    def get_evaluations(self, prefix=None, index=None):
         """ Lists all the evaluations.
 
            https://www.nomadproject.io/docs/http/evals.html
             arguments:
               - prefix :(str) optional, specifies a string to filter evaluations on based on an prefix.
                         This is specified as a querystring parameter.
+              - index  :(dict) optional, provides a dictionary for keeping track of x-nomad-index
             returns: list
             raises:
               - nomad.api.exceptions.BaseNomadException
               - nomad.api.exceptions.URLNotFoundNomadException
         """
         params = {"prefix": prefix}
-        return self.request(method="get", params=params).json()
+        return self.request(method="get", params=params, index=index).json()