feat: add Resource.replace() for PUT immutability verification (#138)

Extract public replace() method on Resource to verify that immutable
fields have not been modified, per RFC 7644 §3.5.1. Deprecate the
'original' parameter of model_validate().

Author: azmeuk

doc/changelog.rst

@@ -4,6 +4,14 @@ Changelog
 [0.6.8] - Unreleased
 --------------------
 
+Added
+^^^^^
+- :class:`~scim2_models.MutabilityException` handler in framework integration examples (FastAPI, Flask, Django).
+
+Deprecated
+^^^^^^^^^^
+- The ``original`` parameter of :meth:`~scim2_models.base.BaseModel.model_validate` is deprecated. Use :meth:`~scim2_models.Resource.replace` on the validated instance instead. Will be removed in 0.8.0.
+
 Fixed
 ^^^^^
 - PATCH operations on :attr:`~scim2_models.Mutability.immutable` fields are now validated at runtime per :rfc:`RFC 7644 §3.5.2 <7644#section-3.5.2>`: ``add`` is only allowed when the field has no previous value, ``replace`` is only allowed with the same value, and ``remove`` is only allowed on unset fields.

doc/guides/_examples/django_example.py

@@ -16,9 +16,9 @@
 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 SearchRequest
-from scim2_models import UniquenessException
 from scim2_models import User
 
 from .integrations import check_etag
@@ -81,12 +81,12 @@ def scim_validation_error(error):
 # -- validation-helper-end --
 
 
-# -- uniqueness-helper-start --
-def scim_uniqueness_error(error):
-    """Turn uniqueness errors into a SCIM 409 response."""
-    scim_error = UniquenessException(detail=str(error)).to_error()
-    return scim_response(scim_error.model_dump_json(), HTTPStatus.CONFLICT)
-# -- uniqueness-helper-end --
+# -- scim-exception-helper-start --
+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 --
@@ -152,17 +152,19 @@ def put(self, request, app_record):
             replacement = User.model_validate(
                 json.loads(request.body),
                 scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
-                original=existing_user,
             )
+            replacement.replace(existing_user)
         except ValidationError as error:
             return scim_validation_error(error)
+        except SCIMException as error:
+            return scim_exception_error(error)
 
         replacement.id = existing_user.id
         updated_record = from_scim_user(replacement)
         try:
             save_record(updated_record)
-        except ValueError as error:
-            return scim_uniqueness_error(error)
+        except SCIMException as error:
+            return scim_exception_error(error)
 
         response_user = to_scim_user(updated_record, resource_location(request, updated_record))
         resp = scim_response(
@@ -192,8 +194,8 @@ def patch(self, request, app_record):
         updated_record = from_scim_user(scim_user)
         try:
             save_record(updated_record)
-        except ValueError as error:
-            return scim_uniqueness_error(error)
+        except SCIMException as error:
+            return scim_exception_error(error)
 
         resp = scim_response(
             scim_user.model_dump_json(scim_ctx=Context.RESOURCE_PATCH_RESPONSE)
@@ -242,8 +244,8 @@ def post(self, request):
         app_record = from_scim_user(request_user)
         try:
             save_record(app_record)
-        except ValueError as error:
-            return scim_uniqueness_error(error)
+        except SCIMException as error:
+            return scim_exception_error(error)
 
         response_user = to_scim_user(app_record, resource_location(request, app_record))
         resp = scim_response(

doc/guides/_examples/fastapi_example.py

@@ -14,9 +14,9 @@
 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 SearchRequest
-from scim2_models import UniquenessException
 from scim2_models import User
 
 from .integrations import PreconditionFailed
@@ -79,11 +79,11 @@ async def handle_http_exception(request, error):
     return Response(scim_error.model_dump_json(), status_code=error.status_code)
 
 
-@app.exception_handler(ValueError)
-async def handle_value_error(request, error):
-    """Turn uniqueness errors into SCIM 409 responses."""
-    scim_error = UniquenessException(detail=str(error)).to_error()
-    return Response(scim_error.model_dump_json(), status_code=HTTPStatus.CONFLICT)
+@app.exception_handler(SCIMException)
+async def handle_scim_error(request, error):
+    """Turn SCIM exceptions into SCIM error responses."""
+    scim_error = error.to_error()
+    return Response(scim_error.model_dump_json(), status_code=scim_error.status)
 
 
 @app.exception_handler(PreconditionFailed)
@@ -151,8 +151,8 @@ async def replace_user(request: Request, app_record: dict = Depends(resolve_user
     replacement = User.model_validate(
         await request.json(),
         scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
-        original=existing_user,
     )
+    replacement.replace(existing_user)
 
     replacement.id = existing_user.id
     updated_record = from_scim_user(replacement)

doc/guides/_examples/flask_example.py

@@ -14,9 +14,9 @@
 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 SearchRequest
-from scim2_models import UniquenessException
 from scim2_models import User
 
 from .integrations import check_etag
@@ -87,11 +87,11 @@ def handle_not_found(error):
     return scim_error.model_dump_json(), HTTPStatus.NOT_FOUND
 
 
-@bp.errorhandler(ValueError)
-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(SCIMException)
+def handle_scim_error(error):
+    """Turn SCIM exceptions into SCIM error responses."""
+    scim_error = error.to_error()
+    return scim_error.model_dump_json(), scim_error.status
 
 
 @bp.errorhandler(PreconditionFailed)
@@ -156,8 +156,8 @@ def replace_user(app_record):
     replacement = User.model_validate(
         request.get_json(),
         scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
-        original=existing_user,
     )
+    replacement.replace(existing_user)
 
     replacement.id = existing_user.id
     updated_record = from_scim_user(replacement)

doc/guides/_examples/integrations.py

@@ -15,6 +15,7 @@
 from scim2_models import ResourceType
 from scim2_models import ServiceProviderConfig
 from scim2_models import Sort
+from scim2_models import UniquenessException
 from scim2_models import User
 
 # -- storage-start --
@@ -40,12 +41,14 @@ def list_records(start=None, stop=None):
 
 
 def save_record(record):
-    """Persist *record*, raising ValueError if its userName is already taken."""
+    """Persist *record*, raising UniquenessException 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")
+            raise UniquenessException(
+                detail=f"userName {record['user_name']!r} is already taken"
+            )
     now = datetime.now(timezone.utc)
     record.setdefault("created_at", now)
     record["updated_at"] = now

doc/guides/django.rst

@@ -67,16 +67,16 @@ If :meth:`~scim2_models.Resource.model_validate` or
 :class:`~pydantic.ValidationError` and return a SCIM :class:`~scim2_models.Error`
 response.
 
-Uniqueness error helper
-^^^^^^^^^^^^^^^^^^^^^^^
+SCIM exception helper
+^^^^^^^^^^^^^^^^^^^^^
 
-``scim_uniqueness_error`` catches the ``ValueError`` raised by ``save_record`` and returns a
-409 with ``scimType: uniqueness`` using :class:`~scim2_models.UniquenessException`.
+``scim_exception_error`` converts any :class:`~scim2_models.SCIMException`
+(uniqueness, mutability, …) into a SCIM error response.
 
 .. literalinclude:: _examples/django_example.py
    :language: python
-   :start-after: # -- uniqueness-helper-start --
-   :end-before: # -- uniqueness-helper-end --
+   :start-after: # -- scim-exception-helper-start --
+   :end-before: # -- scim-exception-helper-end --
 
 Precondition error helper
 ^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -121,8 +121,9 @@ For ``GET``, parse query parameters with :class:`~scim2_models.ResponseParameter
 SCIM resource, and serialize with :attr:`~scim2_models.Context.RESOURCE_QUERY_RESPONSE`.
 For ``DELETE``, remove the record and return an empty 204 response.
 For ``PUT``, validate the full replacement payload with
-:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST`, passing the ``original`` resource
-so that immutable attributes are checked for unintended modifications.
+:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST`, then call
+:meth:`~scim2_models.Resource.replace` to verify that immutable attributes
+have not been modified.
 Convert back to native and persist, then serialize with
 :attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_RESPONSE`.
 For ``PATCH``, validate the payload with :attr:`~scim2_models.Context.RESOURCE_PATCH_REQUEST`,

doc/guides/fastapi.rst

@@ -72,8 +72,8 @@ validation errors, HTTP exceptions, and application errors aligned with SCIM res
 response.
 ``handle_http_exception`` catches HTTP errors such as the 404 raised by the dependency and wraps
 them in a SCIM :class:`~scim2_models.Error`.
-``handle_value_error`` catches the ``ValueError`` raised by ``save_record`` and returns a 409
-with ``scimType: uniqueness`` using :class:`~scim2_models.UniquenessException`.
+``handle_scim_error`` catches any :class:`~scim2_models.SCIMException` (uniqueness, mutability, …)
+and returns the appropriate SCIM :class:`~scim2_models.Error` response.
 ``handle_precondition_failed`` catches
 :class:`~doc.guides._examples.integrations.PreconditionFailed` errors raised by the
 :ref:`ETag helpers <etag-helpers>` and returns a 412.
@@ -129,10 +129,9 @@ PUT /Users/<id>
 ^^^^^^^^^^^^^^^
 
 Validate the full replacement payload with
-:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST`, passing the ``original`` resource
-so that immutable attributes are checked for unintended modifications.
-Convert back to native and persist, then serialize the result with
-:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_RESPONSE`.
+:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST`, then call
+:meth:`~scim2_models.Resource.replace` to verify that immutable attributes
+have not been modified.
 
 .. literalinclude:: _examples/fastapi_example.py
    :language: python

doc/guides/flask.rst

@@ -66,8 +66,8 @@ responses.
 If :meth:`~scim2_models.Resource.model_validate`, Flask routes the
 :class:`~pydantic.ValidationError` to ``handle_validation_error`` and the client receives a
 SCIM :class:`~scim2_models.Error` response.
-``handle_value_error`` catches the ``ValueError`` raised by ``save_record`` and returns a 409
-with ``scimType: uniqueness`` using :class:`~scim2_models.UniquenessException`.
+``handle_scim_error`` catches any :class:`~scim2_models.SCIMException` (uniqueness, mutability, …)
+and returns the appropriate SCIM :class:`~scim2_models.Error` response.
 ``handle_precondition_failed`` catches
 :class:`~doc.guides._examples.integrations.PreconditionFailed` errors raised by the
 :ref:`ETag helpers <etag-helpers>` and returns a 412.
@@ -122,10 +122,9 @@ PUT /Users/<id>
 ^^^^^^^^^^^^^^^
 
 Validate the full replacement payload with
-:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST`, passing the ``original`` resource
-so that immutable attributes are checked for unintended modifications.
-Convert back to native and persist, then serialize the result with
-:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_RESPONSE`.
+:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST`, then call
+:meth:`~scim2_models.Resource.replace` to verify that immutable attributes
+have not been modified.
 
 .. literalinclude:: _examples/flask_example.py
    :language: python

doc/tutorial.rst

@@ -124,13 +124,6 @@ fields with unexpected values will raise :class:`~pydantic.ValidationError`:
     ... except pydantic.ValidationError:
     ...    obj = Error(...)
 
-.. note::
-
-   With the :attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST` context,
-   :meth:`~scim2_models.BaseModel.model_validate` takes an additional
-   :paramref:`~scim2_models.BaseModel.model_validate.original` argument that is used to compare
-   :attr:`~scim2_models.Mutability.immutable` attributes, and raise an exception when they have mutated.
-
 Attributes inclusions and exclusions
 ====================================
 
@@ -479,6 +472,29 @@ Client applications can use this to dynamically discover server resources by bro
           :language: json
           :caption: schema-group.json
 
+Replace operations
+==================
+
+When handling a ``PUT`` request, validate the incoming payload with the
+:attr:`~scim2_models.Context.RESOURCE_REPLACEMENT_REQUEST` context, then call
+:meth:`~scim2_models.Resource.replace` against the existing resource to
+verify that :attr:`~scim2_models.Mutability.immutable` attributes have not been
+modified.
+
+.. doctest::
+
+    >>> from scim2_models import User, Context
+    >>> from scim2_models.exceptions import MutabilityException
+    >>> existing = User(user_name="bjensen")
+    >>> replacement = User.model_validate(
+    ...     {"userName": "bjensen"},
+    ...     scim_ctx=Context.RESOURCE_REPLACEMENT_REQUEST,
+    ... )
+    >>> replacement.replace(existing)
+
+If an immutable attribute differs, a :class:`~scim2_models.MutabilityException`
+is raised.
+
 Patch operations
 ================