Add warning about known problems when configuring use_frozen_dicts (#19711)

Known problems: #18117

As a follow-up, we should consider removing this config option
altogether. It's "expensive" and claims to "prevent bugs" but actually
introduces a whole new class of bugs. It could be re-introduced with a
more holistic solution to the typing. Or a completely new approach (safe
mode that blows up when someone mutates the event content, always make
deep clones when handing out references, etc)

The `use_frozen_dict` config option was there [since
inception](a7b65bd)
but was only recently
[documented](#18122) for
completeness sake.

Author: MadLittleMods

changelog.d/19711.doc

@@ -0,0 +1 @@
+Add warning about known problems when configuring `use_frozen_dicts`.

docs/usage/configuration/config_documentation.md

@@ -194,7 +194,11 @@ user_agent_suffix: ' (I''m a teapot; Linux x86_64)'
 ---
 ### `use_frozen_dicts`
 
-*(boolean)* Determines whether we should freeze the internal dict object in `FrozenEvent`. Freezing prevents bugs where we accidentally share e.g. signature dicts. However, freezing a dict is expensive. Defaults to `false`.
+*(boolean)* Determines whether we should freeze the internal dict object in `FrozenEvent`. Freezing prevents bugs where we accidentally share e.g. signature dicts. However, freezing a dict is expensive.
+
+> ⚠️ **Warning** – This option is known to introduce a new class of [comparison bugs](https://github.com/element-hq/synapse/issues/18117) in Synapse.
+
+Defaults to `false`.
 
 Example configuration:
 ```yaml

schema/synapse-config.schema.yaml

@@ -94,6 +94,10 @@ properties:
       Determines whether we should freeze the internal dict object in
       `FrozenEvent`. Freezing prevents bugs where we accidentally share e.g.
       signature dicts. However, freezing a dict is expensive.
+
+
+      > ⚠️ **Warning** – This option is known to introduce a new class of [comparison
+      bugs](https://github.com/element-hq/synapse/issues/18117) in Synapse.
     default: false
     examples:
       - true

synapse/events/__init__.py

@@ -63,6 +63,10 @@
 NOTE: This is overridden by the configuration by the Synapse worker apps, but
 for the sake of tests, it is set here because it cannot be configured on the
 homeserver object itself.
+
+FIXME: Because of how this option works (changing the underlying types), it causes
+subtle downstream bugs that makes type comparisons brittle, tracked by
+https://github.com/element-hq/synapse/issues/18117
 """
 
 T = TypeVar("T")