[pull] master from aio-libs:master

CHANGES/12549.doc.rst

@@ -0,0 +1 @@
+Added the :doc:`threat_model` to the Sphinx documentation -- by :user:`omkar-334`.

CONTRIBUTORS.txt

@@ -292,6 +292,7 @@ Nándor Mátravölgyi
 Oisin Aylward
 Olaf Conradi
 Oleg Höfling
+Omkar Kabde
 Pahaz Blinov
 Panagiotis Kolokotronis
 Pankaj Pandey

THREAT_MODEL.md

@@ -1,4 +1,4 @@
-# aiohttp Threat Model
+# Threat Model
 
 This document is a STRIDE-based threat model for the
 [aiohttp](https://github.com/aio-libs/aiohttp) library. It is a living document
@@ -310,5 +310,3 @@ into `StreamReader`) is then handed to `web_protocol.RequestHandler` and
   request parser (strict).
 
 These are all currently in place; this section assumes no regression.
-
----

docs/conf.py

@@ -59,6 +59,8 @@
     "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
     # Third-party extensions:
+    "myst_parser",  # renders Markdown sources (e.g. ``THREAT_MODEL.md``)
+    "sphinxcontrib.mermaid",  # renders the Mermaid flowcharts in ``THREAT_MODEL.md``
     "sphinxcontrib.towncrier.ext",  # provides `towncrier-draft-entries` directive
 ]
 
@@ -70,6 +72,23 @@
 except ImportError:
     pass
 
+spelling_exclude_patterns = [
+    # THREAT_MODEL.md is already spell-checked by the codespell pre-commit hook.
+    # The spelling builder additionally mis-tokenises its ``**S**poofing`` STRIDE
+    # list into non-words, so skip the threat model here to avoid double coverage.
+    "threat_model.md",
+]
+
+
+# -- MyST (Markdown) configuration ----------------------------------------
+
+# ``THREAT_MODEL.md`` lives at the repo root and is surfaced through
+# ``docs/threat_model.md``.
+myst_heading_anchors = 3  # anchors for h1-h3 so the in-page section links work
+myst_fence_as_directive = ["mermaid"]  # render ```mermaid fences as diagrams
+
+# TODO: Remove this option once THREAT_MODEL.md is complete.
+suppress_warnings = ["myst.xref_missing"]
 
 intersphinx_mapping = {
     "pytest": ("http://docs.pytest.org/en/latest/", None),

docs/index.rst

@@ -231,3 +231,4 @@ Table Of Contents
    misc
    external
    contributing
+   threat_model

docs/threat_model.md

@@ -0,0 +1,2 @@
+```{include} ../THREAT_MODEL.md
+```

requirements/constraints.txt

@@ -32,7 +32,9 @@ async-timeout==5.0.1 ; python_version < "3.11"
     #   aiohttp
     #   valkey
 attrs==26.1.0
-    # via aiohttp
+    # via
+    #   aiohttp
+    #   myst-parser
 babel==2.18.0
     # via sphinx
 backports-asyncio-runner==1.2.0
@@ -76,7 +78,9 @@ cython==3.2.4
 distlib==0.4.0
     # via virtualenv
 docutils==0.21.2
-    # via sphinx
+    # via
+    #   myst-parser
+    #   sphinx
 exceptiongroup==1.3.1
     # via pytest
 execnet==2.1.2
@@ -115,14 +119,21 @@ isal==1.7.2 ; python_version < "3.14" and implementation_name == "cpython"
     #   -r requirements/test-common.in
 jinja2==3.1.6
     # via
+    #   myst-parser
     #   sphinx
+    #   sphinxcontrib-mermaid
     #   towncrier
 librt==0.11.0
     # via mypy
-markdown-it-py==4.2.0
-    # via rich
+markdown-it-py==3.0.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+    #   rich
 markupsafe==3.0.3
     # via jinja2
+mdit-py-plugins==0.6.1
+    # via myst-parser
 mdurl==0.1.2
     # via markdown-it-py
 multidict==6.7.1
@@ -137,6 +148,8 @@ mypy==2.1.0 ; implementation_name == "cpython"
     #   -r requirements/test-common.in
 mypy-extensions==1.1.0
     # via mypy
+myst-parser==4.0.1
+    # via -r requirements/doc.in
 nodeenv==1.10.0
     # via pre-commit
 packaging==26.2
@@ -230,7 +243,10 @@ python-on-whales==0.81.0
     #   -r requirements/lint.in
     #   -r requirements/test-common.in
 pyyaml==6.0.3
-    # via pre-commit
+    # via
+    #   myst-parser
+    #   pre-commit
+    #   sphinxcontrib-mermaid
 requests==2.34.2
     # via
     #   sphinx
@@ -248,6 +264,8 @@ snowballstemmer==3.0.1
 sphinx==8.1.3
     # via
     #   -r requirements/doc.in
+    #   myst-parser
+    #   sphinxcontrib-mermaid
     #   sphinxcontrib-spelling
     #   sphinxcontrib-towncrier
 sphinxcontrib-applehelp==2.0.0
@@ -258,6 +276,8 @@ sphinxcontrib-htmlhelp==2.1.0
     # via sphinx
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
+sphinxcontrib-mermaid==2.0.2
+    # via -r requirements/doc.in
 sphinxcontrib-qthelp==2.0.0
     # via sphinx
 sphinxcontrib-serializinghtml==2.0.0

requirements/dev.txt

@@ -32,7 +32,9 @@ async-timeout==5.0.1 ; python_version < "3.11"
     #   aiohttp
     #   valkey
 attrs==26.1.0
-    # via aiohttp
+    # via
+    #   aiohttp
+    #   myst-parser
 babel==2.18.0
     # via sphinx
 backports-asyncio-runner==1.2.0
@@ -74,7 +76,9 @@ cryptography==48.0.0
 distlib==0.4.0
     # via virtualenv
 docutils==0.21.2
-    # via sphinx
+    # via
+    #   myst-parser
+    #   sphinx
 exceptiongroup==1.3.1
     # via pytest
 execnet==2.1.2
@@ -113,14 +117,21 @@ isal==1.7.2 ; python_version < "3.14" and implementation_name == "cpython"
     #   -r requirements/test-common.in
 jinja2==3.1.6
     # via
+    #   myst-parser
     #   sphinx
+    #   sphinxcontrib-mermaid
     #   towncrier
 librt==0.11.0
     # via mypy
-markdown-it-py==4.2.0
-    # via rich
+markdown-it-py==3.0.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
+    #   rich
 markupsafe==3.0.3
     # via jinja2
+mdit-py-plugins==0.6.1
+    # via myst-parser
 mdurl==0.1.2
     # via markdown-it-py
 multidict==6.7.1
@@ -134,6 +145,8 @@ mypy==2.1.0 ; implementation_name == "cpython"
     #   -r requirements/test-common.in
 mypy-extensions==1.1.0
     # via mypy
+myst-parser==4.0.1
+    # via -r requirements/doc.in
 nodeenv==1.10.0
     # via pre-commit
 packaging==26.2
@@ -225,7 +238,10 @@ python-on-whales==0.81.0
     #   -r requirements/lint.in
     #   -r requirements/test-common.in
 pyyaml==6.0.3
-    # via pre-commit
+    # via
+    #   myst-parser
+    #   pre-commit
+    #   sphinxcontrib-mermaid
 requests==2.34.2
     # via sphinx
 rich==15.0.0
@@ -241,6 +257,8 @@ snowballstemmer==3.0.1
 sphinx==8.1.3
     # via
     #   -r requirements/doc.in
+    #   myst-parser
+    #   sphinxcontrib-mermaid
     #   sphinxcontrib-towncrier
 sphinxcontrib-applehelp==2.0.0
     # via sphinx
@@ -250,6 +268,8 @@ sphinxcontrib-htmlhelp==2.1.0
     # via sphinx
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
+sphinxcontrib-mermaid==2.0.2
+    # via -r requirements/doc.in
 sphinxcontrib-qthelp==2.0.0
     # via sphinx
 sphinxcontrib-serializinghtml==2.0.0

requirements/doc-spelling.txt

@@ -17,23 +17,41 @@ charset-normalizer==3.4.7
 click==8.4.0
     # via towncrier
 docutils==0.21.2
-    # via sphinx
+    # via
+    #   myst-parser
+    #   sphinx
 idna==3.15
     # via requests
 imagesize==2.0.0
     # via sphinx
 jinja2==3.1.6
     # via
+    #   myst-parser
     #   sphinx
+    #   sphinxcontrib-mermaid
     #   towncrier
+markdown-it-py==3.0.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
 markupsafe==3.0.3
     # via jinja2
+mdit-py-plugins==0.6.1
+    # via myst-parser
+mdurl==0.1.2
+    # via markdown-it-py
+myst-parser==4.0.1
+    # via -r requirements/doc.in
 packaging==26.2
     # via sphinx
 pyenchant==3.3.0
     # via sphinxcontrib-spelling
 pygments==2.20.0
     # via sphinx
+pyyaml==6.0.3
+    # via
+    #   myst-parser
+    #   sphinxcontrib-mermaid
 requests==2.34.2
     # via
     #   sphinx
@@ -43,6 +61,8 @@ snowballstemmer==3.0.1
 sphinx==8.1.3
     # via
     #   -r requirements/doc.in
+    #   myst-parser
+    #   sphinxcontrib-mermaid
     #   sphinxcontrib-spelling
     #   sphinxcontrib-towncrier
 sphinxcontrib-applehelp==2.0.0
@@ -53,6 +73,8 @@ sphinxcontrib-htmlhelp==2.1.0
     # via sphinx
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
+sphinxcontrib-mermaid==2.0.2
+    # via -r requirements/doc.in
 sphinxcontrib-qthelp==2.0.0
     # via sphinx
 sphinxcontrib-serializinghtml==2.0.0

requirements/doc.in

@@ -1,4 +1,6 @@
 aiohttp-theme
+myst-parser
 sphinx
+sphinxcontrib-mermaid
 sphinxcontrib-towncrier
 towncrier

requirements/doc.txt

@@ -17,28 +17,48 @@ charset-normalizer==3.4.7
 click==8.4.0
     # via towncrier
 docutils==0.21.2
-    # via sphinx
+    # via
+    #   myst-parser
+    #   sphinx
 idna==3.15
     # via requests
 imagesize==2.0.0
     # via sphinx
 jinja2==3.1.6
     # via
+    #   myst-parser
     #   sphinx
+    #   sphinxcontrib-mermaid
     #   towncrier
+markdown-it-py==3.0.0
+    # via
+    #   mdit-py-plugins
+    #   myst-parser
 markupsafe==3.0.3
     # via jinja2
+mdit-py-plugins==0.6.1
+    # via myst-parser
+mdurl==0.1.2
+    # via markdown-it-py
+myst-parser==4.0.1
+    # via -r requirements/doc.in
 packaging==26.2
     # via sphinx
 pygments==2.20.0
     # via sphinx
+pyyaml==6.0.3
+    # via
+    #   myst-parser
+    #   sphinxcontrib-mermaid
 requests==2.34.2
     # via sphinx
 snowballstemmer==3.0.1
     # via sphinx
 sphinx==8.1.3
     # via
     #   -r requirements/doc.in
+    #   myst-parser
+    #   sphinxcontrib-mermaid
     #   sphinxcontrib-towncrier
 sphinxcontrib-applehelp==2.0.0
     # via sphinx
@@ -48,6 +68,8 @@ sphinxcontrib-htmlhelp==2.1.0
     # via sphinx
 sphinxcontrib-jsmath==1.0.1
     # via sphinx
+sphinxcontrib-mermaid==2.0.2
+    # via -r requirements/doc.in
 sphinxcontrib-qthelp==2.0.0
     # via sphinx
 sphinxcontrib-serializinghtml==2.0.0