doc: improve etags documentation

Author: azmeuk

doc/guides/_examples/django_example.py

@@ -16,12 +16,11 @@
 from scim2_models import PatchOp
 from scim2_models import ResourceType
 from scim2_models import ResponseParameters
-from scim2_models import SCIMException
 from scim2_models import Schema
+from scim2_models import SCIMException
 from scim2_models import SearchRequest
 from scim2_models import User
 
-from .integrations import check_etag
 from .integrations import delete_record
 from .integrations import from_scim_user
 from .integrations import get_record
@@ -31,11 +30,11 @@
 from .integrations import get_schemas
 from .integrations import list_records
 from .integrations import make_etag
-from .integrations import PreconditionFailed
 from .integrations import save_record
 from .integrations import service_provider_config
 from .integrations import to_scim_user
 
+
 # -- setup-start --
 def scim_response(payload, status=HTTPStatus.OK):
     """Build a Django response with the SCIM media type."""
@@ -54,6 +53,30 @@ def resource_location(request, app_record):
 # -- setup-end --
 
 
+# -- etag-start --
+def check_etag(record, request):
+    """Compare the record's ETag against the ``If-Match`` request header.
+
+    :param record: The application record.
+    :param request: The Django request.
+    :return: A 412 SCIM error response if the ETag does not match, or :data:`None`.
+    """
+    if_match = request.META.get("HTTP_IF_MATCH")
+    if not if_match:
+        return None
+    if if_match.strip() == "*":
+        return None
+    etag = make_etag(record)
+    tags = [t.strip() for t in if_match.split(",")]
+    if etag not in tags:
+        scim_error = Error(status=412, detail="ETag mismatch")
+        return scim_response(
+            scim_error.model_dump_json(), HTTPStatus.PRECONDITION_FAILED
+        )
+    return None
+# -- etag-end --
+
+
 # -- refinements-start --
 # -- converters-start --
 class UserConverter:
@@ -86,22 +109,18 @@ def scim_exception_error(error):
     """Turn SCIM exceptions into a SCIM error response."""
     scim_error = error.to_error()
     return scim_response(scim_error.model_dump_json(), scim_error.status)
-# -- scim-exception-helper-end --
 
 
-# -- precondition-helper-start --
-def scim_precondition_error():
-    """Turn ETag mismatches into a SCIM 412 response."""
-    scim_error = Error(status=412, detail="ETag mismatch")
-    return scim_response(scim_error.model_dump_json(), HTTPStatus.PRECONDITION_FAILED)
-# -- precondition-helper-end --
+# -- scim-exception-helper-end --
 
 
 # -- error-handler-start --
 def handler404(request, exception):
     """Turn Django 404 errors into SCIM error responses."""
     scim_error = Error(status=404, detail=str(exception))
     return scim_response(scim_error.model_dump_json(), HTTPStatus.NOT_FOUND)
+
+
 # -- error-handler-end --
 # -- refinements-end --
 
@@ -135,18 +154,14 @@ def get(self, request, app_record):
         return resp
 
     def delete(self, request, app_record):
-        try:
-            check_etag(app_record, request.META.get("HTTP_IF_MATCH"))
-        except PreconditionFailed:
-            return scim_precondition_error()
+        if resp := check_etag(app_record, request):
+            return resp
         delete_record(app_record["id"])
         return scim_response("", HTTPStatus.NO_CONTENT)
 
     def put(self, request, app_record):
-        try:
-            check_etag(app_record, request.META.get("HTTP_IF_MATCH"))
-        except PreconditionFailed:
-            return scim_precondition_error()
+        if resp := check_etag(app_record, request):
+            return resp
         existing_user = to_scim_user(app_record, resource_location(request, app_record))
         try:
             replacement = User.model_validate(
@@ -166,7 +181,9 @@ def put(self, request, app_record):
         except SCIMException as error:
             return scim_exception_error(error)
 
-        response_user = to_scim_user(updated_record, resource_location(request, updated_record))
+        response_user = to_scim_user(
+            updated_record, resource_location(request, updated_record)
+        )
         resp = scim_response(
             response_user.model_dump_json(
                 scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE
@@ -176,10 +193,8 @@ def put(self, request, app_record):
         return resp
 
     def patch(self, request, app_record):
-        try:
-            check_etag(app_record, request.META.get("HTTP_IF_MATCH"))
-        except PreconditionFailed:
-            return scim_precondition_error()
+        if resp := check_etag(app_record, request):
+            return resp
         try:
             patch = PatchOp[User].model_validate(
                 json.loads(request.body),
@@ -202,6 +217,8 @@ def patch(self, request, app_record):
         )
         resp["ETag"] = make_etag(updated_record)
         return resp
+
+
 # -- single-resource-end --
 
 
@@ -217,7 +234,9 @@ def get(self, request):
             return scim_validation_error(error)
 
         total, page = list_records(req.start_index_0, req.stop_index_0)
-        resources = [to_scim_user(record, resource_location(request, record)) for record in page]
+        resources = [
+            to_scim_user(record, resource_location(request, record)) for record in page
+        ]
         response = ListResponse[User](
             total_results=total,
             start_index=req.start_index or 1,
@@ -298,6 +317,8 @@ def get(self, request, schema_id):
         return scim_response(
             schema.model_dump_json(scim_ctx=Context.RESOURCE_QUERY_RESPONSE)
         )
+
+
 # -- schemas-end --
 
 
@@ -337,6 +358,8 @@ def get(self, request, resource_type_id):
         return scim_response(
             rt.model_dump_json(scim_ctx=Context.RESOURCE_QUERY_RESPONSE)
         )
+
+
 # -- resource-types-end --
 
 
@@ -350,6 +373,8 @@ def get(self, request):
                 scim_ctx=Context.RESOURCE_QUERY_RESPONSE
             )
         )
+
+
 # -- service-provider-config-end --
 
 

doc/guides/_examples/fastapi_example.py

@@ -14,13 +14,11 @@
 from scim2_models import PatchOp
 from scim2_models import ResourceType
 from scim2_models import ResponseParameters
-from scim2_models import SCIMException
 from scim2_models import Schema
+from scim2_models import SCIMException
 from scim2_models import SearchRequest
 from scim2_models import User
 
-from .integrations import PreconditionFailed
-from .integrations import check_etag
 from .integrations import delete_record
 from .integrations import from_scim_user
 from .integrations import get_record
@@ -53,6 +51,25 @@ def resource_location(request, app_record):
 # -- setup-end --
 
 
+# -- etag-start --
+def check_etag(record, if_match):
+    """Compare the record's ETag against an ``If-Match`` header value.
+
+    :param record: The application record.
+    :param if_match: Raw ``If-Match`` header value, or :data:`None`.
+    :raises ~fastapi.HTTPException: If the header is present and does not match.
+    """
+    if not if_match:
+        return
+    if if_match.strip() == "*":
+        return
+    etag = make_etag(record)
+    tags = [t.strip() for t in if_match.split(",")]
+    if etag not in tags:
+        raise HTTPException(status_code=412, detail="ETag mismatch")
+# -- etag-end --
+
+
 # -- refinements-start --
 # -- dependency-start --
 def resolve_user(user_id: str):
@@ -61,6 +78,8 @@ def resolve_user(user_id: str):
         return get_record(user_id)
     except KeyError:
         raise HTTPException(status_code=HTTPStatus.NOT_FOUND)
+
+
 # -- dependency-end --
 
 
@@ -86,13 +105,6 @@ async def handle_scim_error(request, error):
     return Response(scim_error.model_dump_json(), status_code=scim_error.status)
 
 
-@app.exception_handler(PreconditionFailed)
-async def handle_precondition_failed(request, error):
-    """Turn ETag mismatches into SCIM 412 responses."""
-    scim_error = Error(status=412, detail="ETag mismatch")
-    return Response(
-        scim_error.model_dump_json(), status_code=HTTPStatus.PRECONDITION_FAILED
-    )
 # -- error-handlers-end --
 # -- refinements-end --
 
@@ -117,6 +129,8 @@ async def get_user(request: Request, app_record: dict = Depends(resolve_user)):
         ),
         headers={"ETag": etag},
     )
+
+
 # -- get-user-end --
 
 
@@ -139,6 +153,8 @@ async def patch_user(request: Request, app_record: dict = Depends(resolve_user))
         scim_user.model_dump_json(scim_ctx=Context.RESOURCE_PATCH_RESPONSE),
         headers={"ETag": make_etag(updated_record)},
     )
+
+
 # -- patch-user-end --
 
 
@@ -162,11 +178,11 @@ async def replace_user(request: Request, app_record: dict = Depends(resolve_user
         updated_record, resource_location(request, updated_record)
     )
     return Response(
-        response_user.model_dump_json(
-            scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE
-        ),
+        response_user.model_dump_json(scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE),
         headers={"ETag": make_etag(updated_record)},
     )
+
+
 # -- put-user-end --
 
 
@@ -177,6 +193,8 @@ async def delete_user(request: Request, app_record: dict = Depends(resolve_user)
     check_etag(app_record, request.headers.get("If-Match"))
     delete_record(app_record["id"])
     return Response(status_code=HTTPStatus.NO_CONTENT)
+
+
 # -- delete-user-end --
 # -- single-resource-end --
 
@@ -204,6 +222,8 @@ async def list_users(request: Request):
             excluded_attributes=req.excluded_attributes,
         ),
     )
+
+
 # -- list-users-end --
 
 
@@ -224,6 +244,8 @@ async def create_user(request: Request):
         status_code=HTTPStatus.CREATED,
         headers={"ETag": make_etag(app_record)},
     )
+
+
 # -- create-user-end --
 # -- collection-end --
 
@@ -257,6 +279,8 @@ async def get_schema_by_id(schema_id: str):
     return Response(
         schema.model_dump_json(scim_ctx=Context.RESOURCE_QUERY_RESPONSE),
     )
+
+
 # -- schemas-end --
 
 
@@ -290,6 +314,8 @@ async def get_resource_type_by_id(resource_type_id: str):
     return Response(
         rt.model_dump_json(scim_ctx=Context.RESOURCE_QUERY_RESPONSE),
     )
+
+
 # -- resource-types-end --
 
 
@@ -302,6 +328,8 @@ async def get_service_provider_config():
             scim_ctx=Context.RESOURCE_QUERY_RESPONSE
         ),
     )
+
+
 # -- service-provider-config-end --
 # -- discovery-end --