Merge b8ba81b698 into 76b324d95b

docs/en/docs/tutorial/middleware.md

@@ -2,7 +2,13 @@
 
 You can add middleware to **FastAPI** applications.
 
-A "middleware" is a function that works with every **request** before it is processed by any specific *path operation*. And also with every **response** before returning it.
+In this tutorial we will discuss how to add a custom `http` middleware to your FastAPI applications.
+
+The `http` middleware is designed to work with HTTP protocol, and it is responsible for handling of HTTP requests and responses.
+
+## How `http` middleware works?
+
+The `http` middleware works with every **request** before it is processed by any specific *path operation*. And also with every **response** before returning it.
 
 * It takes each **request** that comes to your application.
 * It can then do something to that **request** or run any needed code.
@@ -65,6 +71,36 @@ Here we use <a href="https://docs.python.org/3/library/time.html#time.perf_count
 
 ///
 
+/// note | Technical Details
+
+As you noticed the decorator `@app.middleware('http')` contains a parameter called `http`. This parameter defines the type of server events to be handled by the middleware, and hence the name `http` middleware.
+
+ASGI server supports the following scope types (or event types): `lifespan`, `http`, and `websocket`.
+
+///
+
+## Class-Based Middleware
+
+It is possible to define a custom `http` middleware using classes.
+
+We will implement a class-based middleware with exactly the same functionality as in the example with the `@app.middleware('http')` decorator.
+
+We will use an abstract `BaseHTTPMiddleware` class from Starlette that allows to write custom `http` middlewares.
+
+{* ../../docs_src/middleware/tutorial002.py hl[7:13,17] *}
+
+To create the middleware we need to override the `async dispatch` method of the `BaseHTTPMiddleware` class.
+
+The functionality of the method is very similar to the decorated middleware function from the previous example.
+
+The middleware is connected to the FastAPI application using `app.add_middleware` method.
+
+/// note
+
+You can read more about Starlette middleware in [Starlette documentation](https://www.starlette.io/middleware).
+
+///
+
 ## Other middlewares
 
 You can later read more about other middlewares in the [Advanced User Guide: Advanced Middleware](../advanced/middleware.md){.internal-link target=_blank}.

docs_src/middleware/tutorial001.py

@@ -12,3 +12,8 @@ async def add_process_time_header(request: Request, call_next):
     process_time = time.perf_counter() - start_time
     response.headers["X-Process-Time"] = str(process_time)
     return response
+
+
+@app.get("/")
+def hello():
+    return {"hello": "world"}

docs_src/middleware/tutorial002.py

@@ -0,0 +1,22 @@
+import time
+
+from fastapi import FastAPI, Request, Response
+from starlette.middleware.base import BaseHTTPMiddleware
+
+
+class ProcessTimeHeaderMiddleware(BaseHTTPMiddleware):
+    async def dispatch(self, request: Request, call_next):
+        start_time = time.perf_counter()
+        response: Response = await call_next(request)
+        process_time = time.perf_counter() - start_time
+        response.headers["X-Process-Time"] = str(process_time)
+        return response
+
+
+app = FastAPI()
+app.add_middleware(ProcessTimeHeaderMiddleware)
+
+
+@app.get("/")
+def hello():
+    return {"hello": "world"}

tests/test_tutorial/test_middleware/test_tutorial001.py

@@ -0,0 +1,15 @@
+from fastapi.testclient import TestClient
+
+from docs_src.middleware.tutorial001 import app
+
+
+def test_add_process_time_header_middleware():
+    client = TestClient(app)
+    response = client.get("/")
+    assert response.status_code == 200
+    assert response.json() == {"hello": "world"}
+    assert "X-Process-Time" in response.headers
+    assert len(response.headers["X-Process-Time"]) > 0
+    # request/response process time
+    process_time = response.headers["X-Process-Time"]
+    assert float(process_time) > 0

tests/test_tutorial/test_middleware/test_tutorial002.py

@@ -0,0 +1,15 @@
+from fastapi.testclient import TestClient
+
+from docs_src.middleware.tutorial002 import app
+
+
+def test_add_process_time_header_middleware():
+    client = TestClient(app)
+    response = client.get("/")
+    assert response.status_code == 200
+    assert response.json() == {"hello": "world"}
+    assert "X-Process-Time" in response.headers
+    assert len(response.headers["X-Process-Time"]) > 0
+    # request/response process time
+    process_time = response.headers["X-Process-Time"]
+    assert float(process_time) > 0