Metadata-Version: 2.1
Name: asgi-cors-middleware
Version: 0.0.1
Summary: Whitelist urls on ASGI applications allowing for cross origin requests
Home-page: https://github.com/mrkiura/asgi-cors-middleware
Author: Alex Kiura
Author-email: kiuraalex@gmail.com
License: MIT
Description: # asgi-cors-middleware
        
        Python package that allows whitelisting of urls on ASGI applications making it possible to perform cross origin requests from the browser.
        
        ## CORS in a nutshell
        
        **Cross-Origin Resource Sharing (CORS)** allows a server to define any
         origins other than its own that are safe for the browser to load resources from.
        
        Mozilla does a good job of explaining CORS [here](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
        
        ## Background
        
        Assuming you have a web application that follows a client-server architecture, it's possible the frontend would be running on a server
        different from the API. If the frontend application made a request to the API, this kind of request would be blocked by the browser.
        
        For security reasons, browsers block cross origin requests by default.
        
        A cross origin request is a request made to a server with a different url/ origin. To mitigate around this, we could simply add the url of the frontend application as an allowed origin on the API server.
        Most web frameworks provide a way to do this or have third party libraries that achieve the same.
        
        **asgi-cors-middleware** aims to provide a simple way to achieve the above for ASGI applications.
        
        ## Features
        
        * Simple
        * Works with most ASGI frameworks (Django, Starlette, FastAPI, channels)
        * Works with Ariadne
        
        ## Installation
        
        Can be installed via pip
        
        ```bash
        pip install asgi-cors-middleware
        ```
        
        ## Usage
        
        To use the middleware, just import it like so:
        
        ```python
        from asgi_cors_middleware import CorsASGIApp
        ```
        
        To start whitelisting origins, just wrap your asgi application instance with
        `CorsASGIApp`.
        
        ```python
        
        app = CorsASGIApp(
            app=asgi_app_instance,
            origins=["www.example.com"]
        )
        ```
        
        ## Example
        
        A simple HelloWorld application that whitelists the origins below:
        * www.example.com
        * localhost:9000
        
        ### Install an ASGI server
        
        ```bash
        pip install uvicorn
        ```
        
        Create a file called example.py and update it with the code below:
        
        ```python
        from asgi_cors_middleware import CorsASGIApp
        
        class HelloWorld:
            def __init__(self, scope):
                pass
        
            async def __call__(self, receive, send):
                await send({
                    'type': 'http.response.start',
                    'status': 200,
                    'headers': [
                        [b'content-type', b'text/plain'],
                    ]
                })
                await send({
                    'type': 'http.response.body',
                    'body': b'Hello, world!',
                })
        
        app = CorsASGIApp(
            app=HelloWorld,
            origins=[
                "www.example.com",
                "localhost:9000"
            ]
        )
        ```
        
        That's it. For real, that's really it. Now your application is all set to allow requests from www.example.com and localhost:9000.
        
        ### Run the app
        
        ```bash
        uvicorn example:app
        ```
        
        ## Contributing
        
        For guidance and instructions, please see [CONTRIBUTING.md](CONTRIBUTING.md)
        
Platform: UNKNOWN
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Description-Content-Type: text/markdown
