Metadata-Version: 2.4
Name: kaya-cors
Version: 0.0.3
Summary: CORS support for the Kaya lightweight ASGI web framework
Author-email: Walter Oggioni <oggioni.walter@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/woggioni/kaya
Project-URL: Bug Tracker, https://github.com/woggioni/kaya/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Topic :: Utilities
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Developers
Classifier: Environment :: Console
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: kaya-core
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: ipdb; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Requires-Dist: httpx-ws; extra == "dev"
Requires-Dist: kaya-rsgi; extra == "dev"

# kaya-cors

CORS (Cross-Origin Resource Sharing) support for the Kaya web framework.

Provides `CorsMixin`, a `KayaMixin` that adds CORS response headers to outgoing
responses and answers CORS preflight (`OPTIONS`) requests, with the same
configuration parameters and semantics as FastAPI/Starlette's `CORSMiddleware`.

## Usage

```python
from kaya.core import KayaApp, HttpContext
from kaya.cors import CorsMixin

app = KayaApp(mixins=[
    CorsMixin(
        allow_origins=['https://example.com'],
        allow_methods=('GET', 'POST'),
        allow_headers=('X-Custom-Header',),
        allow_credentials=True,
        max_age=600,
    )
])

@app.GET('/')
async def home(ctx: HttpContext):
    await ctx.send_str(200, 'Hello World!')
```

## Parameters

- `allow_origins`: list of origins allowed to make cross-origin requests.
  Use `['*']` to allow any origin.
- `allow_origin_regex`: optional regex string matched (fullmatch) against the
  request origin.
- `allow_methods`: HTTP methods allowed for cross-origin requests
  (default `('GET',)`); use `'*'` to allow all standard methods.
- `allow_headers`: request headers allowed in cross-origin requests
  (default `()`); use `'*'` to mirror back any requested headers.
- `allow_credentials`: allow cookies/credentials in cross-origin requests
  (default `False`). When enabled, the allowed origin is always echoed
  explicitly instead of `'*'`.
- `expose_headers`: response headers made accessible to the browser.
- `max_age`: seconds browsers may cache the preflight response
  (default `600`).

## Behavior

- Requests without an `Origin` header pass through untouched.
- Simple cross-origin requests with an allowed origin get
  `Access-Control-Allow-Origin` (plus `Access-Control-Allow-Credentials` and
  `Access-Control-Expose-Headers` when configured) added to the response.
  Headers already set by the handler are never overwritten.
- Preflight requests (`OPTIONS` with `Origin` and
  `Access-Control-Request-Method` headers) are answered directly by the mixin
  with `200 OK` (or `400` with a `Disallowed CORS ...` body when the origin,
  method or headers are not allowed). The preflight response is the only one
  delivered to the client: if the routing tree matches the request anyway
  (including user-registered `OPTIONS` handlers or the 404 fallback), its
  output is discarded.

`CorsMixin` is a `KayaMixin`, so the app stays a `KayaApp` and both ASGI and
RSGI keep working.
