doc: ETags in framework integrations

Author: azmeuk

doc/conf.py

@@ -44,6 +44,7 @@
     "python": ("https://docs.python.org/3", None),
     "pydantic": ("https://docs.pydantic.dev/latest/", None),
     "flask": ("https://flask.palletsprojects.com/en/stable/", None),
+    "sqlalchemy": ("https://docs.sqlalchemy.org/en/20/", None),
 }
 
 # -- Options for HTML output ----------------------------------------------

doc/guides/_examples/django_example.py

@@ -20,6 +20,7 @@
 from scim2_models import UniquenessException
 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
@@ -28,6 +29,8 @@
 from .integrations import get_schema
 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
@@ -78,6 +81,14 @@ def scim_uniqueness_error(error):
 # -- uniqueness-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 --
+
+
 # -- error-handler-start --
 def handler404(request, exception):
     """Turn Django 404 errors into SCIM error responses."""
@@ -99,20 +110,35 @@ def get(self, request, app_record):
         except ValidationError as error:
             return scim_validation_error(error)
 
+        etag = make_etag(app_record)
+        if_none_match = request.META.get("HTTP_IF_NONE_MATCH")
+        if if_none_match and etag in [t.strip() for t in if_none_match.split(",")]:
+            return HttpResponse(status=HTTPStatus.NOT_MODIFIED)
+
         scim_user = to_scim_user(app_record)
-        return scim_response(
+        resp = scim_response(
             scim_user.model_dump_json(
                 scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
                 attributes=req.attributes,
                 excluded_attributes=req.excluded_attributes,
             )
         )
+        resp["ETag"] = etag
+        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()
         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()
         existing_user = to_scim_user(app_record)
         try:
             replacement = User.model_validate(
@@ -131,13 +157,19 @@ def put(self, request, app_record):
             return scim_uniqueness_error(error)
 
         response_user = to_scim_user(updated_record)
-        return scim_response(
+        resp = scim_response(
             response_user.model_dump_json(
                 scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE
             )
         )
+        resp["ETag"] = make_etag(updated_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()
         try:
             patch = PatchOp[User].model_validate(
                 json.loads(request.body),
@@ -155,9 +187,11 @@ def patch(self, request, app_record):
         except ValueError as error:
             return scim_uniqueness_error(error)
 
-        return scim_response(
+        resp = scim_response(
             scim_user.model_dump_json(scim_ctx=Context.RESOURCE_PATCH_RESPONSE)
         )
+        resp["ETag"] = make_etag(updated_record)
+        return resp
 # -- single-resource-end --
 
 
@@ -204,10 +238,12 @@ def post(self, request):
             return scim_uniqueness_error(error)
 
         response_user = to_scim_user(app_record)
-        return scim_response(
+        resp = scim_response(
             response_user.model_dump_json(scim_ctx=Context.RESOURCE_CREATION_RESPONSE),
             HTTPStatus.CREATED,
         )
+        resp["ETag"] = make_etag(app_record)
+        return resp
 
 
 urlpatterns = [

doc/guides/_examples/flask_example.py

@@ -1,6 +1,7 @@
 from http import HTTPStatus
 
 from flask import Blueprint
+from flask import make_response
 from flask import request
 from pydantic import ValidationError
 from werkzeug.routing import BaseConverter
@@ -17,6 +18,7 @@
 from scim2_models import UniquenessException
 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
@@ -25,6 +27,8 @@
 from .integrations import get_schema
 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
@@ -82,6 +86,13 @@ def handle_value_error(error):
     """Turn uniqueness errors into SCIM 409 responses."""
     scim_error = UniquenessException(detail=str(error)).to_error()
     return scim_error.model_dump_json(), HTTPStatus.CONFLICT
+
+
+@bp.errorhandler(PreconditionFailed)
+def handle_precondition_failed(error):
+    """Turn ETag mismatches into SCIM 412 responses."""
+    scim_error = Error(status=412, detail="ETag mismatch")
+    return scim_error.model_dump_json(), HTTPStatus.PRECONDITION_FAILED
 # -- error-handlers-end --
 # -- refinements-end --
 
@@ -94,21 +105,24 @@ def get_user(app_record):
     """Return one SCIM user."""
     req = ResponseParameters.model_validate(request.args.to_dict())
     scim_user = to_scim_user(app_record)
-    return (
+    resp = make_response(
         scim_user.model_dump_json(
             scim_ctx=Context.RESOURCE_QUERY_RESPONSE,
             attributes=req.attributes,
             excluded_attributes=req.excluded_attributes,
-        ),
-        HTTPStatus.OK,
+        )
     )
+    resp.headers["ETag"] = make_etag(app_record)
+    resp.make_conditional(request)
+    return resp
 # -- get-user-end --
 
 
 # -- patch-user-start --
 @bp.patch("/Users/<user:app_record>")
 def patch_user(app_record):
     """Apply a SCIM PatchOp to an existing user."""
+    check_etag(app_record, request.headers.get("If-Match"))
     scim_user = to_scim_user(app_record)
     patch = PatchOp[User].model_validate(
         request.get_json(),
@@ -122,6 +136,7 @@ def patch_user(app_record):
     return (
         scim_user.model_dump_json(scim_ctx=Context.RESOURCE_PATCH_RESPONSE),
         HTTPStatus.OK,
+        {"ETag": make_etag(updated_record)},
     )
 # -- patch-user-end --
 
@@ -130,6 +145,7 @@ def patch_user(app_record):
 @bp.put("/Users/<user:app_record>")
 def replace_user(app_record):
     """Replace an existing user with a full SCIM resource."""
+    check_etag(app_record, request.headers.get("If-Match"))
     existing_user = to_scim_user(app_record)
     replacement = User.model_validate(
         request.get_json(),
@@ -147,6 +163,7 @@ def replace_user(app_record):
             scim_ctx=Context.RESOURCE_REPLACEMENT_RESPONSE
         ),
         HTTPStatus.OK,
+        {"ETag": make_etag(updated_record)},
     )
 # -- put-user-end --
 
@@ -155,6 +172,7 @@ def replace_user(app_record):
 @bp.delete("/Users/<user:app_record>")
 def delete_user(app_record):
     """Delete an existing user."""
+    check_etag(app_record, request.headers.get("If-Match"))
     delete_record(app_record["id"])
     return "", HTTPStatus.NO_CONTENT
 # -- delete-user-end --
@@ -201,6 +219,7 @@ def create_user():
     return (
         response_user.model_dump_json(scim_ctx=Context.RESOURCE_CREATION_RESPONSE),
         HTTPStatus.CREATED,
+        {"ETag": make_etag(app_record)},
     )
 # -- create-user-end --
 # -- collection-end --

doc/guides/_examples/integrations.py

@@ -1,5 +1,8 @@
 """Framework-agnostic storage and mapping layer shared by the integration examples."""
 
+import hashlib
+from datetime import datetime
+from datetime import timezone
 from uuid import uuid4
 
 from scim2_models import AuthenticationScheme
@@ -38,9 +41,14 @@ def list_records(start=None, stop=None):
 
 def save_record(record):
     """Persist *record*, raising ValueError if its userName is already taken."""
+    if not record.get("id"):
+        record["id"] = str(uuid4())
     for existing in records.values():
         if existing["id"] != record["id"] and existing["user_name"] == record["user_name"]:
             raise ValueError(f"userName {record['user_name']!r} is already taken")
+    now = datetime.now(timezone.utc)
+    record.setdefault("created_at", now)
+    record["updated_at"] = now
     records[record["id"]] = record
 
 
@@ -59,14 +67,19 @@ def to_scim_user(record):
         display_name=record.get("display_name"),
         active=record.get("active", True),
         emails=[User.Emails(value=record["email"])] if record.get("email") else None,
-        meta=Meta(resource_type="User"),
+        meta=Meta(
+            resource_type="User",
+            version=make_etag(record),
+            created=record["created_at"],
+            last_modified=record["updated_at"],
+        ),
     )
 
 
 def from_scim_user(scim_user):
     """Convert a validated SCIM payload into the application shape."""
     return {
-        "id": scim_user.id or str(uuid4()),
+        "id": scim_user.id,
         "user_name": scim_user.user_name,
         "display_name": scim_user.display_name,
         "active": True if scim_user.active is None else scim_user.active,
@@ -75,6 +88,35 @@ def from_scim_user(scim_user):
 # -- mapping-end --
 
 
+# -- etag-start --
+class PreconditionFailed(Exception):
+    """Raised when an ``If-Match`` ETag check fails."""
+
+
+def make_etag(record):
+    """Compute a weak ETag from a record's content."""
+    digest = hashlib.sha256(str(sorted(record.items())).encode()).hexdigest()[:16]
+    return f'W/"{digest}"'
+
+
+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 PreconditionFailed: 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 PreconditionFailed()
+# -- etag-end --
+
+
 # -- discovery-start --
 RESOURCE_MODELS = [User]
 
@@ -125,7 +167,7 @@ def get_resource_type(resource_type_id):
     filter=Filter(supported=False, max_results=0),
     change_password=ChangePassword(supported=False),
     sort=Sort(supported=False),
-    etag=ETag(supported=False),
+    etag=ETag(supported=True),
     authentication_schemes=[
         AuthenticationScheme(
             type=AuthenticationScheme.Type.httpbasic,

doc/guides/django.rst

@@ -78,6 +78,18 @@ Uniqueness error helper
    :start-after: # -- uniqueness-helper-start --
    :end-before: # -- uniqueness-helper-end --
 
+Precondition error helper
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+``scim_precondition_error`` catches the
+:class:`~doc.guides._examples.integrations.PreconditionFailed` errors raised by the
+:ref:`ETag helpers <etag-helpers>` and returns a 412.
+
+.. literalinclude:: _examples/django_example.py
+   :language: python
+   :start-after: # -- precondition-helper-start --
+   :end-before: # -- precondition-helper-end --
+
 Error handler
 ^^^^^^^^^^^^^
 
@@ -144,6 +156,41 @@ The ``urlpatterns`` list wires both views to their routes.
    :start-after: # -- collection-start --
    :end-before: # -- collection-end --
 
+Resource versioning (ETags)
+===========================
+
+SCIM supports resource versioning through HTTP ETags
+(:rfc:`RFC 7644 §3.14 <7644#section-3.14>`).
+The shared :ref:`ETag helpers <etag-helpers>` compute a weak ETag from each record and
+populate :attr:`~scim2_models.Meta.version`.
+
+On ``GET`` single-resource responses, the ``ETag`` header is set and the ``If-None-Match``
+request header is checked manually to return a ``304 Not Modified`` when the client already
+has the current version.
+
+On write operations (``PUT``, ``PATCH``, ``DELETE``), the ``If-Match`` header is checked
+before processing.
+If the client's ETag does not match, a ``412 Precondition Failed`` SCIM error is returned.
+``POST`` and ``PUT``/``PATCH`` responses include the ``ETag`` header for the newly created or
+updated resource.
+
+.. tip::
+
+   With Django ORM, a :class:`~uuid.UUIDField` regenerated on every
+   :meth:`~django.db.models.Model.save` provides a collision-free ETag value
+   without relying on clock precision::
+
+      import uuid
+
+      from django.db import models
+
+      class UserModel(models.Model):
+          version = models.UUIDField(default=uuid.uuid4)
+
+          def save(self, **kwargs):
+              self.version = uuid.uuid4()
+              super().save(**kwargs)
+
 Discovery endpoints
 ===================