When using background tasks with middleware, requests are not processed until the background task has finished.

1. Use the example below
2. Make several requests in a row - works as expected
3. Uncomment app.add_middleware(TransparentMiddleware) and re-run
4. Make several requests in a row - subsequent ones are not processed until the 10 second sleep has finished (the first request returns before then though).

The same behaviour occurs with asyncio.sleep (async) and time.sleep (sync, run in threadpool)

import asyncio
import uvicorn
from starlette.applications import Starlette
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.background import BackgroundTask
from starlette.responses import JSONResponse


class TransparentMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        # simple middleware that does absolutely nothing
        response = await call_next(request)
        return response


app = Starlette(debug=True)
# uncomment to break
# app.add_middleware(TransparentMiddleware)


@app.route("/")
async def test(_):
    task = BackgroundTask(asyncio.sleep, 10)
    return JSONResponse("hello", background=task)


if __name__ == '__main__':
    uvicorn.run(app)

Fixes: #811

This adds support for asyncio and trio by leveraging anyio and a little more structured concurrency in spots.

Things to do yet:

• [x] 100% tests passing (there's one failing test at the moment)
• [x] TestClient rewritten for anyio, probably with portals.
• [x] anyio 3.0 release

This adds a hard dependency for starlette, which didn't exist before, and was a selling point. In my opinion, the benefit is worth it. It would be great to use starlette with either uvicorn or hypercorn using Trio.

This also removes the need for aiofiles which is gained for free with anyio.

Some drawbacks are that the other integrations such as graphql are only currently compatible with asyncio. But, this does not make those integrations incompatible. It does give users the ability to use trio without them, and maybe they can be ported in the future as well.

I created a branch for framework benchmarks here: https://github.com/uSpike/FrameworkBenchmarks/tree/starlette-anyio

See results: https://www.techempower.com/benchmarks/#section=test&shareid=c92a1338-0058-486c-9e47-c92ec4710b6a&hw=ph&test=query&a=2

There is a performance penalty to using anyio. The weighted composite score is 173 vs 165, so a 4.5% drop in performance.

Helpers for sending SSE event streams over HTTP connections.

Related resources:

• https://github.com/encode/uvicorn/commit/07c6c18945ab4f4167118e717e197adce3aee3da#r29630623
• https://github.com/aio-libs/aiohttp-sse

This fixes #847 by using the Request scope to store consumed stream data so that new instances of Request can access the Request stream content. Previously await Request(...).json() followed by another await Request(...).json() would hang forever because the receive stream was exhausted and await receive() doesn't timeout after message {"more_body": False} is received. This PR is focused only on enabling Request.body(), Request.form() and Request.json() to return the cached data as originally intended and does not address the issue of await receive() hanging forever inside of Request.stream()

Hello! I think it would be interesting having a section in Starlette docs documenting how to use caching as this is something you end up doing typically for lots of services.

I'm the maintainer of aiocache which is a caching framework agnostic to any http framework. I could write docs about things like:

• how to use aiocache with starlette for caching endpoints
• how to write configuration for caching and load it when starting a Starlette app

Any other thing you could think of you usually do when setting caching for your app. Also happy to receive comments, issues and PRs if you think there is anything missing to integrate nicely with Starlette :).

Would you be interested on me providing a PR documenting that? A new section called "Caching" in https://www.starlette.io/ maybe?

This PR adds pluggable session backends and ships default InMemoryBackend, CookieBackend implementations.

solves: #284

The API of SessionMiddleware remains the same. It only receives new optional backend argument. The default value for this argument is CookieBackend so it has to be fully compatible with previous version.

Here I also add a new test dependency pytest-asyncio.

Usage example:

from starlette.applications import Starlette
from starlette.middleware.sessions import SessionMiddleware
from starlette.sessions import CookieBackend

backend = CookieBackend()

app = Starlette()
app.add_middleware(SessionMiddleware, backend=backend)

API

class MyCustomBackend(SessionBackend):
    async def read(self, session_id: str) -> Optional[str]: ...

    async def write(self, session_id: str, data: str) -> str: ...

    async def remove(self, session_id: str): ...

write returns session_id to make it possible to use cookie backends as they don't persist data anywhere and their data is an ID.

remove - currently unused but they may be used by logout handler.

Do I need to add session_backend to scope? We need some API to invalidate session on logout.

UPD: If you need this code please use this repository alex-oleshkevich/starsessions. There you will find a pip-installable package.

In case you reconsider https://github.com/encode/starlette/issues/685#issuecomment-550240999 @tomchristie

I think this would be a useful feature. I often see middleware parameters that are "a regex pattern to match routes" because the middleware has to determine what routes to interact with before routing is done. Here and here are two examples. This also closes https://github.com/tiangolo/fastapi/issues/1174

Aside from being a pain to build some complex regex, there are performance implications: imagine (in the absurd scenario) that you have 100 endpoints and 100 middleware, but each middleware applies only to 1 endpoint. Now you have 99 middleware executing and doing regex matching when they could have just been bypassed to begin with if they executed after routing.

That said, re-using the existing Middleware construct for this use has it's cons. For example, it is obvious that the middleware cannot modify the path. I can't think of any other major limitations, but I there may be others.

Hello, I'm developing an angular (7)+ starlette api backend and I would like to make starlette serve the angular app alongside with the api. I know that I could use ngnix to serve it but I would like to try to deploy just one server. Also I have found the https://github.com/tiangolo/uvicorn-gunicorn-starlette-docker and it would be amazing to be able to just use it with the whole app. As a normal angular app, it expects (by default) to be located to the "/" endpoint. As my angular prod files are in a folder ./angular relative to the starlette app.py file I have tried the following:

_CURDIR = dirname(abspath(__file__))
app = Starlette()
app.mount('/', StaticFiles(directory=join(_CURDIR, 'angular' )))

@app.exception_handler(404)
async def not_found(request, exc):
    return FileResponse('./angular/index.html')

if __name__ == '__main__':
    uvicorn.run(app, host='0.0.0.0', port=8090)

The index.html is the usual on the angular apps:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>ArcherytimerMatrix</title>
  <base href="/">

  <meta name="viewport" content="width=device-width, initial-scale=1">
  <link href="https://fonts.googleapis.com/css?family=Roboto:300,400,500" rel="stylesheet">
  <link href="https://fonts.googleapis.com/icon?family=Material+Icons" rel="stylesheet">
  <link rel="icon" type="image/x-icon" href="favicon.ico">
<link rel="stylesheet" href="styles.54bd9f72bfb2c07e2a6b.css"></head>
<body>
  <app-root></app-root>
<script type="text/javascript" src="runtime.253d2798c34ad4bc8428.js"></script><script type="text/javascript" src="es2015-polyfills.4a4cfea0ce682043f4e9.js" nomodule>
</script><script type="text/javascript" src="polyfills.407a467dedb63cfdd103.js"></script><script type="text/javascript" src="main.cfa2a2d950b21a173917.js"></script></body>
</html>

when I try to reach localhost:8090 the index.html is "shown" but it can't find the styles / runtime / polyfills and main

INFO: Uvicorn running on http://0.0.0.0:8090 (Press CTRL+C to quit)
INFO: ('127.0.0.1', 34138) - "GET / HTTP/1.1" 200
INFO: ('127.0.0.1', 34138) - "GET /styles.54bd9f72bfb2c07e2a6b.css HTTP/1.1" 200
INFO: ('127.0.0.1', 34140) - "GET /runtime.253d2798c34ad4bc8428.js HTTP/1.1" 200
INFO: ('127.0.0.1', 34138) - "GET /polyfills.407a467dedb63cfdd103.js HTTP/1.1" 200
INFO: ('127.0.0.1', 34140) - "GET /main.cfa2a2d950b21a173917.js HTTP/1.1" 200

(the status is 200 as I'm catching the exception and redirecting...) If I try to access the static file directy: localhost:8090/styles.54bd9f72bfb2c07e2a6b.css Is not found either

If I serve the statics files from an endpoint: app.mount('/angular', StaticFiles(directory=join(_CURDIR, 'angular' ))) and I try to access to the "angular" localhost:8090/angular/styles.54bd9f72bfb2c07e2a6b.css the file is served. So It seems that the "/" root can't be used for endopoint to static files (or there is a bug if this is not the intended behavior)

Maybe I'm doing it wrong, is there another way to achieve this?

Thank you in advance Regards

• Closes #1977

This solves the issue reported by @MrSalman333 on https://github.com/encode/starlette/pull/1609#issuecomment-1306742910.

Test 1 (https://github.com/encode/starlette/pull/1609#issuecomment-1306786049)

import logging

import anyio
from fastapi import Depends, FastAPI, Response
from starlette.middleware.base import BaseHTTPMiddleware
from starlette.middleware import Middleware


class CustomMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request, call_next):
        return await call_next(request)


app = FastAPI(middleware=[Middleware(CustomMiddleware)])


def dependency_a(response: Response):
    try:
        yield "A"
    finally:
        logging.warning("A")


def dependency_b(response: Response):
    try:
        yield "B"
    finally:
        logging.warning("B")


def dependency_c(response: Response):
    try:
        yield "C"
    finally:
        logging.warning("C")


@app.get(
    "/issue",
    dependencies=[
        Depends(dependency_a),
    ],
)
def show_dependencies_issue(
    b=Depends(dependency_b),
    c=Depends(dependency_c),
):
    print(b, c)
    return {"status": "ok"}

Test 2 (https://github.com/encode/starlette/pull/1579#issuecomment-1097119520)

from typing import Awaitable, Callable

from starlette.middleware.base import BaseHTTPMiddleware
from starlette.middleware.gzip import GZipMiddleware
from starlette.routing import Route
from starlette.middleware import Middleware
from starlette.applications import Starlette
from starlette.responses import Response
from starlette.requests import Request

class NoopMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next: Callable[[Request], Awaitable]):
        return await call_next(request)

def endpoint(request: Request):
    return Response(status_code=304)


app2 = Starlette(
    routes=[Route("/", endpoint=endpoint)],
    middleware=[Middleware(GZipMiddleware), Middleware(NoopMiddleware)]
)

Documentation still in progress.

This PR does not significantly remove any public API, but it does start to move us to a new prefered style of routing, moving away from the decorator style.

I think using plain route lists is more clearly decoupled, and gives a clearer indication of what's going on under the hood.

For example...

routes = [
    Route('/', homepage),
    Mount('/users', routes=[
        Route('/', users, methods=['GET', 'POST']),
        Route('/{username}', user),
    ])
]

app = Starlette(routes=routes)

Similarly, middleware now has a prefered configure-on-init style...

routes = ...

middleware = [
    Middleware(SentryAsgiMiddleware) if settings.SENTRY_DSN else None,
    Middleware(HTTPSRedirectMiddleware) if settings.HTTPS_ONLY else None,
    Middleware(SessionMiddleware, secret_key=settings.SECRET, https_only=settings.HTTPS_ONLY)
]

app = Starlette(routes=routes, middleware=middleware)

Still to do here...

• [ ] ~Review exception_handlers / server_error~. - We should defer this to a future release.
• [ ] Update starlette-example.
• [x] Update Routing docs.
• [x] Update Middleware docs.
• [x] Update routing examples in docs throughout.

We may also want to reivew our url_for and url_path_for documentation and API as part of this release version. I'm somewhat keen for us to switch things around there, so that path-only URLs are the default style, and there's less surface area for folks to need to care about configuring Uvicorn's --allow-forward-ips. For example if we were using this:

• app.url_for(), request.url_for(), url_for() in templates. Return a relative path-only URL.
• request.absolute_url_for(), absolute_url_for() in templates. Return a fully qualified URL.

I'm also pretty keen to switch things up here so that when debug=True we...

• Display helpful routing table info if no route matches during routing.
• Display helpful routing table info when url_for(...) fails.

Something else that I think is interesting here is that we're more clearly exposing that alternative subclasses of BaseRoute can also be added to the routing table. For example, it'd be interesting to consider if there's any worthwhile documentation work to do in the ecosystem around eg. noting how you can use FastAPI's APIRoute inside a regular Starlette application, to point at a handler which gets their dependency injection treatments, alongside other regular Route cases, which just get the standard request argument.

That line of thought is as much about demystifying how the different bits fit together, about making sure that we can display useful routing debug info for higher level frameworks as well as the plain starlette case, and also about enabling other framework authors to take the happy path when building on top of Starlette. (We kinda missed a trick with Responder here, which functions differently enough that it's working against the grain.)

I think this addresses https://github.com/tiangolo/fastapi/issues/953.

Thank you @smagafurov for the link in https://github.com/tiangolo/fastapi/issues/953#issuecomment-730302314

What does this do for users?

This fixes a confusing behavior where their endpoint works differently depending on if it is sync or async. And in FastAPI (which for better or worse re-uses run_in_threadpool), it impacts dependencies as well.

This is the current behavior:

from typing import List
from contextvars import ContextVar

from starlette.applications import Starlette
from starlette.routing import Route
from starlette.requests import Request
from starlette.responses import Response
from starlette.middleware import Middleware
from starlette.testclient import TestClient
from starlette.types import ASGIApp, Scope, Receive, Send, Message

user: ContextVar[str] = ContextVar("user")

log: List[str] = []


class LogUserMiddleware:
    def __init__(self, app: ASGIApp) -> None:
        self.app = app
    
    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
        async def send_wrapper(message: Message) -> None:
            if message["type"] == "http.response.start":
                log.append(user.get())
            await send(message)
        await self.app(scope, receive, send_wrapper)


def endpoint_sync(request: Request) -> Response:
    user.set(request.query_params["user"])
    return Response()


async def endpoint_async(request: Request) -> Response:
    return endpoint_sync(request)


app = Starlette(
    routes=[
        Route("/sync", endpoint_sync),
        Route("/async", endpoint_async),
    ],
    middleware=[Middleware(LogUserMiddleware)]
)


client = TestClient(app, raise_server_exceptions=False)


resp = client.get("/async", params={"user": "adrian"})
assert resp.status_code == 200, resp.content
assert log == ["adrian"]

resp = client.get("/sync", params={"user": "adrian"})
assert resp.status_code == 500, resp.content

I wouldn't expect a user to write this themselves, but some library they are using very well could use contextvars to set something that then gets picked up by a middleware (for example, some sort of tracing library). Since this is an implementation detail, and the failure mode is pretty tricky, it would be difficult for a user to figure out what happened.

• Closes #950.
• Relates to https://github.com/encode/starlette/pull/1013/.
• Inspired by https://github.com/abersheeran/baize/blob/23791841f30ca92775e50a544a8606d1d4deac93/baize/asgi/responses.py#L184

The implementation differs from baize's FileResponse, since that one takes in consideration the "range" request header. This is because the Response classes in Starlette are naive in regard to the request.

Alternative Solution

Don't be naive in regard to the request, and send a Content-Range in case the client sent Range.

I believe this alternative is cleaner than the implemented here.

References

• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Range
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/206
• https://developer.mozilla.org/en-US/docs/Web/HTTP/Range_requests

This PR adds Config.env_prefix argument.

import os
from starlette.config import Config

os.environ['APP_DEBUG'] = 'yes'
os.environ['ENVIRONMENT'] = 'dev'

config = Config(env_prefix='APP_')

DEBUG = config('DEBUG') # lookups APP_DEBUG, returns "yes"
ENVIRONMENT = config('ENVIRONMENT') # lookups APP_ENVIRONMENT, raises KeyError as variable is not defined

Checklist

• [ ] https://github.com/encode/starlette/pull/1908
• [ ] https://github.com/encode/starlette/pull/1701
• [ ] https://github.com/encode/starlette/pull/1965
• [ ] https://github.com/encode/starlette/pull/1922
• [ ] https://github.com/encode/starlette/pull/1413

The starting point for contributions should usually be a discussion

Simple documentation typos may be raised as stand-alone pull requests, but otherwise please ensure you've discussed your proposal prior to issuing a pull request.

This will help us direct work appropriately, and ensure that any suggested changes have been okayed by the maintainers.

• [ ] Initially raised as discussion #...