AsgiWhiteNoise and async WhiteNoiseMiddleware

README.rst

@@ -31,7 +31,7 @@ useful on Heroku, OpenShift and other PaaS providers.)
 It's designed to work nicely with a CDN for high-traffic sites so you don't have to
 sacrifice performance to benefit from simplicity.
 
-WhiteNoise works with any WSGI-compatible app but has some special auto-configuration
+WhiteNoise works with any ASGI or WSGI compatible app but has some special auto-configuration
 features for Django.
 
 WhiteNoise takes care of best-practices for you, for instance:

docs/asgi.rst

@@ -0,0 +1,76 @@
+Using WhiteNoise with any ASGI application
+==========================================
+
+.. note:: These instructions apply to any ASGI application. However, for Django
+    applications you would be better off using the :doc:`WhiteNoiseMiddleware
+    <django>` class which makes integration easier.
+
+To enable WhiteNoise you need to wrap your existing ASGI application in a
+WhiteNoise instance and tell it where to find your static files. For example:
+
+.. code-block:: python
+
+   from whitenoise import AsgiWhiteNoise
+
+   from my_project import MyASGIApp
+
+   application = MyWAGIApp()
+   application = AsgiWhiteNoise(application, root="/path/to/static/files")
+   application.add_files("/path/to/more/static/files", prefix="more-files/")
+
+On initialization, WhiteNoise walks over all the files in the directories that have
+been added (descending into sub-directories) and builds a list of available static files.
+Any requests which match a static file get served by WhiteNoise, all others are passed
+through to the original WSGI application.
+
+
+.. tip:: ``AsgiWhiteNoise`` inherits all interfaces from WSGI ``WhiteNoise`` but adds
+    support for ASGI applications. See the :doc:`WSGI WhiteNoise documentation <wsgi>` for
+    more details.
+
+
+AsgiWhiteNoise API
+------------------
+
+``AsgiWhiteNoise`` inherits its interface from WSGI ``WhiteNoise``, however, ``application``
+must be an ASGI application.
+
+See the section on WSGI ``WhiteNoise`` :ref:`interface <interface>` for details.
+
+
+Compression Support
+--------------------
+
+See the section on WSGI ``WhiteNoise`` :ref:`compression support <compression>` for details.
+
+
+Caching Headers
+---------------
+
+See the section on WSGI ``WhiteNoise`` :ref:`caching headers <caching>` for details.
+
+
+Index Files
+-----------
+
+See the section on WSGI ``WhiteNoise`` :ref:`index files <index_files>` for details.
+
+
+Using a Content Distribution Network
+------------------------------------
+
+See the instructions for :ref:`using a CDN with Django <cdn>` . The same principles
+apply here although obviously the exact method for generating the URLs for your static
+files will depend on the libraries you're using.
+
+
+Redirecting to HTTPS
+--------------------
+
+See the section on WSGI ``WhiteNoise`` :ref:`redirecting to HTTPS <https>` for details.
+
+
+Configuration attributes
+------------------------
+
+See the section on WSGI ``WhiteNoise`` :ref:`configuration attributes <configuration>` for details.

docs/changelog.rst

@@ -180,7 +180,7 @@ Other changes include:
   ``wsgi.py``.
   See the :ref:`documentation <django-middleware>` for more details.
 
-  (The :doc:`pure WSGI <base>` integration is still available for non-Django apps.)
+  (The :doc:`pure WSGI <wsgi>` integration is still available for non-Django apps.)
 
 * The ``whitenoise.django.GzipManifestStaticFilesStorage`` alias has now
   been removed. Instead you should use the correct import path:

docs/django.rst

@@ -2,7 +2,7 @@ Using WhiteNoise with Django
 ============================
 
 .. note:: To use WhiteNoise with a non-Django application see the
-   :doc:`generic WSGI documentation <base>`.
+   :doc:`generic WSGI documentation <wsgi>` or the :doc:`generic ASGI documentation <asgi>`.
 
 This guide walks you through setting up a Django project with WhiteNoise.
 In most cases it shouldn't take more than a couple of lines of configuration.

docs/index.rst

@@ -79,8 +79,28 @@ WhiteNoise instance and tell it where to find your static files. For example:
    application = WhiteNoise(application, root="/path/to/static/files")
    application.add_files("/path/to/more/static/files", prefix="more-files/")
 
-And that's it, you're ready to go. For more details see the :doc:`full
-documentation <base>`.
+And that's it, you're ready to go. For more details see the :doc:`full WSGI
+documentation <wsgi>`.
+
+
+QuickStart for other ASGI apps
+------------------------------
+
+To enable WhiteNoise you need to wrap your existing ASGI application in a
+WhiteNoise instance and tell it where to find your static files. For example:
+
+.. code-block:: python
+
+   from whitenoise import AsgiWhiteNoise
+
+   from my_project import MyASGIApp
+
+   application = MyASGIApp()
+   application = AsgiWhiteNoise(application, root="/path/to/static/files")
+   application.add_files("/path/to/more/static/files", prefix="more-files/")
+
+And that's it, you're ready to go. For more details see the :doc:`full ASGI
+documentation <asgi>`.
 
 
 Using WhiteNoise with Flask
@@ -94,7 +114,7 @@ the standard WSGI protocol it is easy to integrate with WhiteNoise (see the
 Compatibility
 -------------
 
-WhiteNoise works with any WSGI-compatible application and is tested on Python
+WhiteNoise works with any ASGI or WSGI compatible application and is tested on Python
 **3.8** – **3.12**, on both Linux and Windows.
 
 Django WhiteNoiseMiddleware is tested with Django versions **3.2** --- **4.2**
@@ -202,6 +222,7 @@ MIT Licensed
 
    self
    django
-   base
+   wsgi
+   asgi
    flask
    changelog

docs/base.rst → docs/wsgi.rst

@@ -27,12 +27,14 @@ See the sections on :ref:`compression <compression>` and :ref:`caching <caching>
 for further details.
 
 
+.. _interface:
+
 WhiteNoise API
 --------------
 
 .. class:: WhiteNoise(application, root=None, prefix=None, \**kwargs)
 
-   :param callable application: Original WSGI application
+   :param Callable application: Original WSGI application
    :param str root: If set, passed to ``add_files`` method
    :param str prefix: If set, passed to ``add_files`` method
    :param  \**kwargs: Sets :ref:`configuration attributes <configuration>` for this instance
@@ -146,6 +148,8 @@ apply here although obviously the exact method for generating the URLs for your
 files will depend on the libraries you're using.
 
 
+.. _https:
+
 Redirecting to HTTPS
 --------------------
 

setup.cfg

@@ -1,7 +1,7 @@
 [metadata]
 name = whitenoise
 version = 6.5.0
-description = Radically simplified static file serving for WSGI applications
+description = Radically simplified static file serving for ASGI or WSGI applications
 long_description = file: README.rst
 long_description_content_type = text/x-rst
 url = https://github.com/evansd/whitenoise
@@ -26,6 +26,7 @@ classifiers =
     Programming Language :: Python :: 3.11
     Programming Language :: Python :: 3.12
     Programming Language :: Python :: Implementation :: CPython
+    Topic :: Internet :: WWW/HTTP :: ASGI :: Middleware
     Topic :: Internet :: WWW/HTTP :: WSGI :: Middleware
     Typing :: Typed
 keywords = Django
@@ -35,6 +36,8 @@ project_urls =
 
 [options]
 packages = find:
+install_requires =
+    aiofiles>=22.1.0
 python_requires = >=3.8
 include_package_data = True
 package_dir =

src/whitenoise/__init__.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
-from .base import WhiteNoise
+from .asgi import AsgiWhiteNoise
+from .wsgi import WhiteNoise
 
-__all__ = ["WhiteNoise"]
+__all__ = ["AsgiWhiteNoise", "WhiteNoise"]

src/whitenoise/asgi.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import asyncio
+
+from asgiref.compatibility import guarantee_single_callable
+
+from .string_utils import decode_path_info
+from whitenoise.base import BaseWhiteNoise
+
+# This is the same size as wsgiref.FileWrapper
+BLOCK_SIZE = 8192
+
+
+class AsgiWhiteNoise(BaseWhiteNoise):
+    user_app = None
+
+    async def __call__(self, scope, receive, send):
+        # Ensure ASGI v2 is converted to ASGI v3
+        if not self.user_app:
+            self.user_app = guarantee_single_callable(self.application)
+
+        # Determine if the request is for a static file
+        path = decode_path_info(scope["path"])
+        static_file = None
+        if scope["type"] == "http":
+            if self.autorefresh and hasattr(asyncio, "to_thread"):
+                # Use a thread while searching disk for files on Python 3.9+
+                static_file = await asyncio.to_thread(self.find_file, path)
+            elif self.autorefresh:
+                static_file = self.find_file(path)
+            else:
+                static_file = self.files.get(path)
+
+        # Serve static file if it exists
+        if static_file:
+            await AsgiFileServer(static_file)(scope, receive, send)
+            return
+
+        # Serve the user's ASGI application
+        await self.user_app(scope, receive, send)
+
+
+class AsgiFileServer:
+    """Simple ASGI application that streams a StaticFile over HTTP in chunks."""
+
+    def __init__(self, static_file):
+        self.static_file = static_file
+
+    async def __call__(self, scope, receive, send):
+        # Convert ASGI headers into WSGI headers. Allows us to reuse all of our WSGI
+        # header logic inside of aget_response().
+        wsgi_headers = {
+            "HTTP_" + key.decode().upper().replace("-", "_"): value.decode()
+            for key, value in scope["headers"]
+        }
+
+        # Get the WhiteNoise file response
+        response = await self.static_file.aget_response(scope["method"], wsgi_headers)
+
+        # Start a new HTTP response for the file
+        await send(
+            {
+                "type": "http.response.start",
+                "status": response.status,
+                "headers": [
+                    # Convert headers back to ASGI spec
+                    (key.lower().encode(), value.encode())
+                    for key, value in response.headers
+                ],
+            }
+        )
+
+        # Head responses have no body, so we terminate early
+        if response.file is None:
+            await send({"type": "http.response.body", "body": b""})
+            return
+
+        # Stream the file response body
+        async with response.file as async_file:
+            while True:
+                chunk = await async_file.read(BLOCK_SIZE)
+                more_body = bool(chunk)
+                await send(
+                    {
+                        "type": "http.response.body",
+                        "body": chunk,
+                        "more_body": more_body,
+                    }
+                )
+                if not more_body:
+                    break

src/whitenoise/base.py

@@ -6,18 +6,16 @@
 from posixpath import normpath
 from typing import Callable
 from wsgiref.headers import Headers
-from wsgiref.util import FileWrapper
 
 from .media_types import MediaTypes
 from .responders import IsDirectoryError
 from .responders import MissingFileError
 from .responders import Redirect
 from .responders import StaticFile
-from .string_utils import decode_path_info
 from .string_utils import ensure_leading_trailing_slash
 
 
-class WhiteNoise:
+class BaseWhiteNoise:
     # Ten years is what nginx sets a max age if you use 'expires max;'
     # so we'll follow its lead
     FOREVER = 10 * 365 * 24 * 60 * 60
@@ -71,27 +69,8 @@ def __init__(
         if root is not None:
             self.add_files(root, prefix)
 
-    def __call__(self, environ, start_response):
-        path = decode_path_info(environ.get("PATH_INFO", ""))
-        if self.autorefresh:
-            static_file = self.find_file(path)
-        else:
-            static_file = self.files.get(path)
-        if static_file is None:
-            return self.application(environ, start_response)
-        else:
-            return self.serve(static_file, environ, start_response)
-
-    @staticmethod
-    def serve(static_file, environ, start_response):
-        response = static_file.get_response(environ["REQUEST_METHOD"], environ)
-        status_line = f"{response.status} {response.status.phrase}"
-        start_response(status_line, list(response.headers))
-        if response.file is not None:
-            file_wrapper = environ.get("wsgi.file_wrapper", FileWrapper)
-            return file_wrapper(response.file)
-        else:
-            return []
+    def __call__(self, *args, **kwargs):
+        raise NotImplementedError("Subclasses must implement `__call__`")
 
     def add_files(self, root, prefix=None):
         root = os.path.abspath(root)