asgi-cors

将CORS头应用于ASGI应用的ASGI中间件。

安装

pip install asgi-cors

关于CORS的一些背景知识

CORS代表跨源资源共享。这是一个允许应用选择允许运行在其他域上的JavaScript执行fetch()调用以从应用检索数据的网络标准。

有关更多背景信息，请参阅MDN的CORS文章。

允许运行在其他域上的脚本访问应用数据的简单方法是添加以下HTTP头

Access-Control-Allow-Origin: *

这将允许任何域上的脚本对应用执行fetch()调用。对于公共数据这通常没问题，但有些情况下这可能不是您想要做的：一个例子可能是运行在VPN后面的代码，它需要允许特定的、受信任的主机加载数据，而不必向互联网上的每个站点开放。

对于这些情况，服务器需要检查客户端的Origin头，并在上面的头中返回该Origin。例如，来自https://#:8000的传入请求可能被视为受信任的 - 在这种情况下，应用服务器需要像这样回复

Access-Control-Allow-Origin: https://#:8000

请注意，Access-Control-Allow-Origin头只能返回一个值。这意味着如果您想允许来自多个源的需求，您需要动态允许列表这些源，并根据传入请求返回不同的头值。

另外，如果应该允许特定的HTTP方法，应用应该添加

Access-Control-Allow-Methods: GET, OPTIONS

在这里，允许了GET和OPTIONS方法。

类似地，可以允许特定的头

Access-Control-Allow-Headers: content-type, Authorization

在这种情况下，允许在CORS请求中发送content-type和Authorization头。

除了GET之外的其他动词（例如POST）将触发预检请求。这是一个OPTIONS请求，浏览器发送给服务器以询问服务器是否接受该请求。

可以使用access-control-max-age头指定预检请求的结果可以缓存多久。这可以减少发送到服务器的请求数量。

如何使用此中间件

我们将假设您已经有一个名为app的现有ASGI应用。

首先，导入asgi_cors函数

from asgi_cors import asgi_cors

要为所有请求启用CORS头（通过将Access-Control-Allow-Origin: *头添加到每个请求），请执行以下操作

app = asgi_cors(app, allow_all=True)

如果您只想允许来自特定主机，请使用以下操作

app = asgi_cors(app, hosts=[
    "https://www.example.com"
])

现在在https://www.example.com上执行的JavaScript将能够调用您的API。您可以在浏览器中打开example.com，打开浏览器开发工具控制台，粘贴以下JavaScript进行测试

fetch("https://your-api.com/").then(r => r.json()).then(d => console.log(d))

可以在列表中包含多个主机。

如果您想对通过通配符定义的主机集合中的请求开放，请使用以下操作

app = asgi_cors(app, host_wildcards=[
    "https://#:800*",
    "http://*.example.com"
])

这将使本地主机服务器上端口8000到8009上运行的任何JavaScript或example.com的任何子域能够访问。

如果您需要执行无法使用hosts=或host_wildcards=参数表示的更复杂操作，可以使用callback=指定自定义函数。例如

def validate_origin(origin):
    return origin.startswith("https://")

app = asgi_cors(app, callback=validate_origin)

您的回调函数将接收浏览器传入的Origin头。支持常规和异步函数。

要添加特定的允许的头部或方法，可以使用headers=和methods=参数指定它们

app = asgi_cors(app, methods=[
    "GET", "OPTIONS"
], headers=[
    "Authorization","content-type"
])

要设置access-control-max-age头，请使用max_age=参数

app = asgi_cors(app, host_wildcards=["*"], max_age=3600)

将中间件用作装饰器

如果您直接将ASGI应用程序定义为函数，可以使用如下所示的asgi_cors_decorator函数装饰器

from asgi_cors import asgi_cors_decorator


@asgi_cors_decorator(allow_all=True)
async def my_asgi_app(scope, receive, send):
    # Your app goes here