|
55 | 55 | <li class="toctree-l1"><a class="reference internal" href="../examples">Usage Examples</a> |
56 | 56 | </li> |
57 | 57 | </ul> |
| 58 | + <ul> |
| 59 | + <li class="toctree-l1"><a class="reference internal" href="../api">API Reference</a> |
| 60 | + </li> |
| 61 | + </ul> |
58 | 62 | <ul> |
59 | 63 | <li class="toctree-l1"><a class="reference internal" href="../concurrent_queries">Concurrent SQL Queries</a> |
60 | 64 | </li> |
|
70 | 74 | <ul class="current"> |
71 | 75 | <li class="toctree-l1 current"><a class="reference internal current" href="#">How middleware works</a> |
72 | 76 | <ul class="current"> |
| 77 | + <li class="toctree-l2"><a class="reference internal" href="#code-example">Code example</a> |
| 78 | + </li> |
73 | 79 | </ul> |
74 | 80 | </li> |
75 | 81 | </ul> |
|
95 | 101 | <div class="section" itemprop="articleBody"> |
96 | 102 |
|
97 | 103 | <h1 id="how-middleware-works">How middleware works</h1> |
98 | | -<p>Most of the work - and the “magic” - happens inside the middleware. |
99 | | -The library aims to provide ready-made solutions so that you don’t have to |
| 104 | +<p>Most of the work - and the “magic” - happens inside the middleware.</p> |
| 105 | +<p>Here is a diagram describing how it works.</p> |
| 106 | +<p><img alt="middleware_schema.png" src="../img/middleware_schema.png" /></p> |
| 107 | +<p>At the beginning of a request, the middleware initializes a new |
| 108 | +asynchronous context. |
| 109 | +This asynchronous context is implemented using a contextvar. |
| 110 | +It holds a mutable container that stores sessions.</p> |
| 111 | +<p>A mutable container is used so that any coroutine, at any level, can |
| 112 | +create, modify, or close sessions, and those changes will |
| 113 | +affect the execution of the entire request.</p> |
| 114 | +<p>Whenever your code accesses the library’s functionality, it interacts with |
| 115 | +this container.</p> |
| 116 | +<p>Finally, the middleware checks the container for any active sessions and |
| 117 | +open transactions. |
| 118 | +If transactions are open, they are either committed when the query |
| 119 | +execution is successful or rolled back if it fails. |
| 120 | +After that, all sessions are closed.</p> |
| 121 | +<p>That’s precisely why you can safely close transactions and sessions early. |
| 122 | +The middleware simply works with whatever is in the container: |
| 123 | +if there’s anything left, it will close it properly; if you’ve |
| 124 | +already handled it yourself, the middleware only needs to reset the context.</p> |
| 125 | +<h2 id="code-example">Code example</h2> |
| 126 | +<p>The library aims to provide ready-made solutions so that you don’t have to |
100 | 127 | worry about these details - but they’re not always available.</p> |
101 | 128 | <p>So, let’s take a look at how Starlette middleware works. |
102 | 129 | You can use this example as a reference to implement your own.</p> |
| 130 | +<p><a href="https://github.com/krylosov-aa/context-async-sqlalchemy/blob/main/context_async_sqlalchemy/starlette_utils/http_middleware.py#L34">CODE</a></p> |
103 | 131 | <pre><code class="language-python">from starlette.middleware.base import ( # type: ignore[attr-defined] |
104 | 132 | Request, |
105 | 133 | Response, |
|
0 commit comments