wemake-services/django-modern-rest 0.15.0

Version 0.15.0

on GitHub

You are migrating a Python project from `django-modern-rest` 0.14.0 to 0.15.0.
Load the latest documentation from https://django-modern-rest.readthedocs.io/llms-full.txt
before making any changes.

Apply **all** of the following breaking changes to the codebase.
For each change, search the entire project (including tests, fixtures, and
any helper modules) before editing.

---

### `check_auth` of the JWT refresh and verify controllers takes the `token`

`RefreshTokenSyncController`, `RefreshTokenAsyncController`,
`VerifyTokenSyncController`, and `VerifyTokenAsyncController`
now call `check_auth(user, token)`. The `user` argument is typed
as `AbstractBaseUser` instead of `Any`, the new `token` argument
is the decoded `JWToken`. This is the same signature
that `check_auth` of the JWT auth classes already had.

Find every subclass of these controllers that overrides `check_auth`
and add the `token` parameter (keep it even if it is unused),
including `super().check_auth(...)` calls and direct calls in tests.

Before:
    from typing import Any

    class MyRefresh(RefreshTokenSyncController[...]):
        def check_auth(self, user: Any) -> None:
            super().check_auth(user)
            ...

After:
    from django.contrib.auth.base_user import AbstractBaseUser
    from dmr.security.jwt import JWToken

    class MyRefresh(RefreshTokenSyncController[...]):
        def check_auth(self, user: AbstractBaseUser, token: JWToken) -> None:
            super().check_auth(user, token)
            ...

Do the same for the async variants (`async def check_auth`).

Now that the signatures match, `JWTokenBlocklistSyncMixin`
and `JWTokenBlocklistAsyncMixin` can be mixed into these controllers.
If the project reimplemented blocklist checks inside a refresh controller
by hand, consider replacing that code with the mixin.

---

### `JWToken.encode` raises `JWTokenError` instead of `InternalServerError`

`JWToken.encode` now raises `dmr.security.jwt.token.JWTokenError`
(a plain `Exception` subclass about the token itself)
when encoding fails or when the token cannot be issued right now.
The original `pyjwt` exception is preserved as `__cause__`.

Inside request handling nothing changes: `BaseTokenController.create_jwt_token`
converts `JWTokenError` back into `InternalServerError`, so the `500` contract
of the shipped views is kept.

Find every place that calls `JWToken(...).encode(...)` directly
(management commands, Celery tasks, test factories, custom views that bypass
`create_jwt_token`) and update the exception handling:

Before:
    from dmr.exceptions import InternalServerError

    try:
        token = JWToken(...).encode(secret, algorithm)
    except InternalServerError:
        ...

After:
    from dmr.security.jwt.token import JWTokenError

    try:
        token = JWToken(...).encode(secret, algorithm)
    except JWTokenError:
        ...

Tests that assert `pytest.raises(InternalServerError)` around `encode`
must now assert `JWTokenError`. Tests that expected `pyjwt` errors
to be swallowed (`from None`) can now inspect `exc.__cause__`.

---

### `json_dump` → `json_dumps`

The function was renamed in both `dmr.openapi.dump` and `dmr.internal.json`.

Before:
    from dmr.openapi.dump import json_dump
    json_dump(schema)

After:
    from dmr.openapi.dump import json_dumps
    json_dumps(schema)

Do the same for `dmr.internal.json.json_dump`, if it was used
(it is an internal module and should not be imported by user code,
prefer `dmr.openapi.dump.json_dumps`).

---

### Removed `QueryTokenSyncAuth` and `QueryTokenAsyncAuth`

Both classes were removed from `dmr.security.token`, because passing
auth tokens in the query string is insecure (tokens leak into logs,
browser history, and `Referer` headers).

Find every import and usage of `QueryTokenSyncAuth` and `QueryTokenAsyncAuth`
(auth lists in `@modify`/`@validate`, controller `auth = [...]` attributes,
`DMR_SETTINGS['auth']` defaults, subclasses, tests) and replace them
with the header-based classes, keeping the same constructor arguments
where they still apply:

Before:
    from dmr.security.token import QueryTokenSyncAuth
    auth = [QueryTokenSyncAuth()]

After:
    from dmr.security.token import HeaderTokenSyncAuth
    auth = [HeaderTokenSyncAuth()]

Do the same for `QueryTokenAsyncAuth` → `HeaderTokenAsyncAuth`.
Update clients and tests to send the token in the header
(`Authorization: Bearer <token>` by default) instead of `?token=...`.

If the project truly cannot move tokens out of the query string,
copy the last shipped implementation into the project as a custom auth
(and add the `www_authenticate_challenge` property from change 11):
https://github.com/wemake-services/django-modern-rest/blob/14884b432ee075ec3d78ff388944ebc5f0b5d432/dmr/security/token/auth/query.py

---

### `FileResponseSpec.file_body` → `FileResponseSpec.return_type`

Find every `FileResponseSpec(...)` construction, attribute access,
and subclass that uses `file_body` and rename it to `return_type`.
The value is the same kind of object: a `FileBody` (now `FileBodyLike`) subclass.

Before:
    FileResponseSpec(file_body=MyFileBody, status_code=HTTPStatus.OK)
    spec.file_body

After:
    FileResponseSpec(return_type=MyFileBody, status_code=HTTPStatus.OK)
    spec.return_type

---

### Removed `FileMetadataComponent.schema_metadata`, use `SupportsFileParsing.schema_metadata`

`FileMetadataComponent` no longer takes or stores a `schema_metadata` model.
The file schema is now provided by the parser: `SupportsFileParsing.schema_metadata`
is an abstract method that every file-capable parser must implement.

Find every `FileMetadataComponent(schema_metadata=...)` call
or `component.schema_metadata` access and remove it.
Move the customization to the parser class that handles file uploads
(a subclass of a parser that inherits from `SupportsFileParsing`):

Before:
    FileMetadataComponent(schema_metadata=MyFileBody)

After:
    class MyMultiPartParser(MultiPartParser):
        def schema_metadata(
            self,
            model: Any,
            model_meta: tuple[Any, ...],
            metadata: EndpointMetadata,
            serializer: type[BaseSerializer],
            context: OpenAPIContext,
        ) -> type[FileBodyLike]:
            return MyFileBody

    # and register `MyMultiPartParser` in `parsers` of the controller
    # or in `DMR_SETTINGS`.

If the project defines its own parser that inherits from `SupportsFileParsing`,
it must now implement `schema_metadata`, otherwise it cannot be instantiated.
Return `FileBody` (from `dmr.files`) to keep the default schema.

---

### `SSEvent` no longer validates `id` and `event` on creation

`SSEvent(...)` does not check the `id` and `event` fields for null bytes
and line breaks in `__init__` anymore. The check moved into
the `SSEStreamingValidator` pipeline as `validate_event_fields`,
so it now respects the `validate_events` setting and runs for custom
event types too.

Consequences to handle:

- Constructing an invalid `SSEvent` no longer raises. Tests that assert
  `pytest.raises(ValueError)` on `SSEvent(id='a\n')` must be rewritten
  to stream the event through an endpoint and assert
  the resulting `error` event instead.
- With `validate_events=False` these fields are not checked at all anymore.
  Enable `validate_events` where the stream may carry untrusted `id`/`event`.
- If the project has a custom `SSEStreamingValidator.validation_pipeline`
  override, add `validate_event_fields` to it (after `validate_event_type`).

---

### `check_event_field` raises `ValidationError` instead of `ValueError`

`dmr.streaming.sse.validation.check_event_field` now raises
`dmr.exceptions.ValidationError` (with `ErrorType.streaming`),
so a wrong field is streamed as an `error` event instead of breaking
the whole stream.

Find every direct call of `check_event_field` and every
`except ValueError` / `pytest.raises(ValueError)` around it:

Before:
    try:
        check_event_field(event.id, field_name='id')
    except ValueError:
        ...

After:
    from dmr.exceptions import ValidationError

    try:
        check_event_field(event.id, field_name='id')
    except ValidationError:
        ...

---

### `401` responses now carry a `WWW-Authenticate` header

When the endpoint's auth chain can express a challenge
(`HttpBasicSyncAuth`, `HttpBasicAsyncAuth`, `HeaderJWTSyncAuth`,
`HeaderJWTAsyncAuth`, `HeaderTokenSyncAuth`, `HeaderTokenAsyncAuth`,
and any custom auth returning a challenge), every `401` response now
includes `WWW-Authenticate`, for example `Bearer` or
`Basic realm="api", charset="UTF-8"`. The header is also documented
in the OpenAPI schema of the `401` response.

- Update tests that assert the exact set of response headers
  or compare a generated OpenAPI schema snapshot: regenerate the snapshot.
- Browsers show their native login prompt on a `Basic` challenge.
  For browser-facing APIs using HTTP Basic auth pass `www_authenticate=False`
  to the auth instance to opt out, or set a custom `realm=`:

      HttpBasicSyncAuth(www_authenticate=False)
      HttpBasicSyncAuth(realm='admin')

- The header is added by `global_error_handler` via
  `dmr.security.add_www_authenticate`. If the project replaces
  `global_error_handler`, decide whether to call `add_www_authenticate(exc, auth)`
  in the replacement; without it, `401` responses will have no challenge.

---

### Custom auth classes must implement `www_authenticate_challenge`

`SyncAuth` and `AsyncAuth` gained an abstract property
`www_authenticate_challenge -> str | None`. Every custom auth class
in the project must define it, or it cannot be instantiated.

- Return the HTTP auth scheme challenge when credentials are read
  from the `Authorization` header (`'Bearer'`, `'Basic realm="api"'`, ...).
- Return `None` when the auth reads a cookie, a custom header,
  or anything that cannot be expressed as a challenge.

Before:
    class ProxyHeaderSyncAuth(SyncAuth):
        def __call__(self, endpoint, controller): ...

After:
    class ProxyHeaderSyncAuth(SyncAuth):
        @property
        def www_authenticate_challenge(self) -> str | None:
            return None  # reads `X-Proxy-User`, nothing to advertise

        def __call__(self, endpoint, controller): ...

Do this for every subclass of `SyncAuth`, `AsyncAuth`, and for custom
subclasses of the token/JWT base auth classes that do not inherit
the property from a shipped concrete class.

---

### Removed init-only `leeway` argument of `JWToken`

`JWToken(..., leeway=N)` is gone. `leeway` is only accepted
by `JWToken.decode(...)` now.

Before:
    JWToken(sub='1', exp=exp, leeway=30)

After:
    JWToken(sub='1', exp=exp)
    # and, where the token is decoded:
    JWToken.decode(raw, secret, algorithms, leeway=30)

Search for `leeway=` in every `JWToken(` constructor call, dataclass
`replace(...)` call, and subclass `__post_init__` override, and remove it.

---

### `JWToken` validates `exp` and `iat` in `encode`, not on creation

`JWToken.__post_init__` no longer raises for an expired `exp`
or a future `iat`. The checks moved to `JWToken.validate_issued_claims`,
which `JWToken.encode` calls before signing, raising `JWTokenError`.

- Creating a `JWToken` with a past `exp` is now allowed (it is how decoded
  or fixture tokens are represented). Tests that expected `ValueError`
  from the constructor must call `.encode(...)` and expect `JWTokenError`.
- Code that relied on the constructor to reject bad claims before
  storing them somewhere must call `token.validate_issued_claims()`
  explicitly.
- Subclasses that overrode `__post_init__` to add issue-time checks
  should override `validate_issued_claims` instead (call `super()` first).

Before:
    with pytest.raises(ValueError):
        JWToken(sub='1', exp=past)

After:
    from dmr.security.jwt.token import JWTokenError

    with pytest.raises(JWTokenError):
        JWToken(sub='1', exp=past).encode(secret, algorithm)

---

### `JWToken.extras` no longer accepts dataclass instances

Values in `extras` must be json-native (or handled by the serializer),
dataclass instances are not converted with `dataclasses.asdict` anymore.

Find every `JWToken(..., extras={...})` where a value is a dataclass
instance and convert it before passing:

Before:
    JWToken(sub='1', exp=exp, extras={'profile': Profile(...)})

After:
    import dataclasses
    JWToken(sub='1', exp=exp, extras={'profile': dataclasses.asdict(Profile(...))})

Note that with `msgspec` installed tokens are now encoded with `msgspec`,
only json-native values in `extras` are guaranteed to encode identically
with and without it.

---

### Throttling cache keys are now hashed

The cache key used by throttles changed from a long `::`-joined string
to `f'{cache_key.name}::{sha256(...).hexdigest()}'`.

- Any code that builds, inspects, deletes, or asserts on raw throttle
  cache keys (custom backends, admin tooling, tests reading the cache
  directly) must be updated to the new format, or better, to go through
  the throttle's own key method instead of reproducing the format.
- Existing counters stored under the old keys are orphaned after deploy:
  clients get a fresh throttling window once. Flush the throttling cache
  on deploy if that matters.
- Custom `BaseThrottleCacheKey` subclasses must define a `name` attribute,
  it is the human-readable prefix of the hashed key.

---

### HTTP Basic Auth credentials are no longer URL-decoded

`HttpBasicSyncAuth` and `HttpBasicAsyncAuth` used to `unquote` the decoded
`username:password` pair, so `user%40example.com` became `user@example.com`.
Percent-encoded characters are now preserved as-is.

- Update clients and test fixtures that percent-encoded credentials
  to send the raw characters instead.
- If the project subclassed the basic auth and applied `unquote` itself,
  drop that, otherwise credentials containing a literal `%` break.

---

### `HttpBasicSyncAuth` and `HttpBasicAsyncAuth` require the `auth_scheme` prefix

The header value must now start with the `auth_scheme` prefix
(`Basic` by default), matched exactly and case-sensitively:
`Authorization: Basic <base64>`. A header without the prefix is treated
as belonging to another auth in the chain and is ignored.

Find every test fixture, client, or docs example that sent the bare base64
value and add the prefix:

Before:
    client.get(url, headers={'Authorization': base64_credentials})

After:
    client.get(url, headers={'Authorization': f'Basic {base64_credentials}'})

If the API must keep accepting prefixless credentials, pass
`auth_scheme=''` to the auth instance:

    HttpBasicSyncAuth(auth_scheme='')

A custom prefix is also possible: `HttpBasicSyncAuth(auth_scheme='Token')`.

---

### Undecodable HTTP Basic credentials now raise `NotAuthenticatedError`

When the header has the right `auth_scheme` prefix but the credentials
cannot be base64-decoded or split into `username:password`,
the request now fails with `401` immediately. Previously the next auth
in the chain was tried.

Review endpoints with several auth instances where basic auth
is not the last one: a malformed `Basic ...` header no longer falls
through to the next auth. Update tests that relied on that fallback.

---

### `ToJsonKwargs` and `ToModelKwargs` are now `closed=True` typed dicts

The `to_json_kwargs` and `to_model_kwargs` class attributes
of `PydanticSerializer` and `MsgspecSerializer` (and subclasses)
only accept the declared keys now, extra keys are a type error.

Find every serializer subclass that sets these dicts with keys that
are not declared in `dmr.plugins.pydantic.serializer.ToJsonKwargs`,
`dmr.plugins.pydantic.serializer.ToModelKwargs`,
`dmr.plugins.msgspec.serializer.ToJsonKwargs`,
or `dmr.plugins.msgspec.serializer.ToModelKwargs`, and remove the extra keys.
If a non-declared kwarg is truly needed, override `serialize` / `deserialize`
(or `from_python` / `to_python`) on the serializer subclass
and pass it there explicitly.
Run the type checker afterwards, it reports the offending keys.