Add support for request_delay in client and server (#2237)

Author: ml-evs

openapi/index_openapi.json

@@ -2004,6 +2004,19 @@
             "title": "Response Message",
             "description": "response string from the server"
           },
+          "request_delay": {
+            "anyOf": [
+              {
+                "type": "number",
+                "minimum": 0.0
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Request Delay",
+            "description": "A non-negative float giving time in seconds that the client is suggested to wait before issuing a subsequent request.\nImplementation note: the functionality of this field overlaps to some degree with features provided by the HTTP error `429 Too Many Requests` and the `Retry-After` HTTP header.\nImplementations are suggested to provide consistent handling of request overload through both mechanisms."
+          },
           "implementation": {
             "anyOf": [
               {

openapi/openapi.json

@@ -3852,6 +3852,19 @@
             "title": "Response Message",
             "description": "response string from the server"
           },
+          "request_delay": {
+            "anyOf": [
+              {
+                "type": "number",
+                "minimum": 0.0
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "title": "Request Delay",
+            "description": "A non-negative float giving time in seconds that the client is suggested to wait before issuing a subsequent request.\nImplementation note: the functionality of this field overlaps to some degree with features provided by the HTTP error `429 Too Many Requests` and the `Retry-After` HTTP header.\nImplementations are suggested to provide consistent handling of request overload through both mechanisms."
+          },
           "implementation": {
             "anyOf": [
               {

optimade/client/client.py

@@ -954,6 +954,8 @@ async def _get_one_async(
         if override_url:
             next_url = override_url
 
+        request_delay: float | None = None
+
         results = QueryResults()
         try:
             async with self._http_client(headers=self.headers) as client:  # type: ignore[union-attr,call-arg,misc]
@@ -968,13 +970,18 @@ async def _get_one_async(
                             next_url, follow_redirects=True, timeout=self.http_timeout
                         )
                         page_results, next_url = self._handle_response(r, _task)
+                        request_delay = page_results["meta"].get("request_delay", None)
+                        # Don't wait any longer than 5 seconds
+                        if request_delay:
+                            request_delay = min(request_delay, 5)
+
                     except RecoverableHTTPError:
                         attempts += 1
                         if attempts > self.max_attempts:
                             raise RuntimeError(
                                 f"Exceeded maximum number of retries for {next_url}"
                             )
-                        await asyncio.sleep(1)
+                        await asyncio.sleep(request_delay or 1)
                         continue
 
                     results.update(page_results)
@@ -1023,6 +1030,8 @@ def _get_one(
         if override_url:
             next_url = override_url
 
+        request_delay: float | None = None
+
         results = QueryResults()
         try:
             with self._http_client() as client:  # type: ignore[misc]
@@ -1041,13 +1050,19 @@ def _get_one(
                             )
                         r = client.get(next_url, timeout=timeout)
                         page_results, next_url = self._handle_response(r, _task)
+
+                        request_delay = page_results["meta"].get("request_delay", None)
+                        # Don't wait any longer than 5 seconds
+                        if request_delay:
+                            request_delay = min(request_delay, 5)
+
                     except RecoverableHTTPError:
                         attempts += 1
                         if attempts > self.max_attempts:
                             raise RuntimeError(
                                 f"Exceeded maximum number of retries for {next_url}"
                             )
-                        time.sleep(1)
+                        time.sleep(request_delay or 1)
                         continue
 
                     results.update(page_results)

optimade/models/optimade_json.py

@@ -4,7 +4,14 @@
 from enum import Enum
 from typing import Annotated, Any, Literal, Optional
 
-from pydantic import BaseModel, ConfigDict, EmailStr, Field, model_validator
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    EmailStr,
+    Field,
+    NonNegativeFloat,
+    model_validator,
+)
 
 from optimade.models import jsonapi
 from optimade.models.types import SemanticVersion
@@ -360,6 +367,15 @@ class ResponseMeta(jsonapi.Meta):
         str | None, StrictField(description="response string from the server")
     ] = None
 
+    request_delay: Annotated[
+        NonNegativeFloat | None,
+        StrictField(
+            description="""A non-negative float giving time in seconds that the client is suggested to wait before issuing a subsequent request.
+Implementation note: the functionality of this field overlaps to some degree with features provided by the HTTP error `429 Too Many Requests` and the `Retry-After` HTTP header.
+Implementations are suggested to provide consistent handling of request overload through both mechanisms."""
+        ),
+    ] = None
+
     implementation: Annotated[
         Implementation | None,
         StrictField(description="a dictionary describing the server implementation"),

optimade/server/config.py

@@ -6,7 +6,13 @@
 from typing import Annotated, Any, Literal
 
 import yaml
-from pydantic import AnyHttpUrl, Field, field_validator, model_validator
+from pydantic import (
+    AnyHttpUrl,
+    Field,
+    NonNegativeFloat,
+    field_validator,
+    model_validator,
+)
 from pydantic.fields import FieldInfo
 from pydantic_settings import (
     BaseSettings,
@@ -435,6 +441,12 @@ class ServerConfig(BaseSettings):
             ),
         ),
     ] = True
+    request_delay: Annotated[
+        NonNegativeFloat | None,
+        Field(
+            description="The value to use for the `meta->request_delay` field, which indicates to clients how long they should leave between success queries."
+        ),
+    ] = None
 
     validate_api_response: Annotated[
         bool | None,
@@ -455,6 +467,15 @@ def check_jsonl_path(cls, value: Any) -> Path | None:
 
         return value
 
+    @field_validator("request_delay", mode="before")
+    @classmethod
+    def check_request_delay(cls, value: Any) -> Path | None:
+        """Make sure the request delay is not adversarially large."""
+        if value and value > 5:
+            raise ValueError("Request delay must be less than 5 seconds.")
+
+        return value
+
     @field_validator("implementation", mode="before")
     @classmethod
     def set_implementation_version(cls, value: Any) -> dict[str, Any]:

optimade/server/routers/utils.py

@@ -69,6 +69,10 @@ def meta_values(
     if schema is None:
         schema = CONFIG.schema_url if not CONFIG.is_index else CONFIG.index_schema_url
 
+    if CONFIG.request_delay:
+        # Double-guard against the server setting an adversarially large request delay
+        kwargs["request_delay"] = min(CONFIG.request_delay, 10.0)
+
     return ResponseMeta(
         query=ResponseMetaQuery(representation=f"{url_path}?{url.query}"),
         api_version=__api_version__,

tests/test_config.json

@@ -38,5 +38,6 @@
             "chemsys": "nelements"
         }
     },
-    "license": "CC-BY-4.0"
+    "license": "CC-BY-4.0",
+    "request_delay": 0.1
 }