Обробка помилок CORS і діагностика

CORS — це не просто дурнувате налаштування, яке змушувало тебе тричі перечитувати документацію. Це спроба захистити користувачів від злих хакерів, які хочуть відправляти запити від твого імені на чужі сайти. Але коли все налаштовано неправильно, браузер безжально кидає в обличчя повідомлення: Access to fetch at ... has been blocked by CORS policy. І це тільки початок забави.

Спойлер: Якщо ти нервуєш, побачивши "CORS Errors" у консолі браузера — це нормально. Сьогодні ми навчимося не просто розуміти ці помилки, а й виправляти їх.

Типові помилки CORS та їх причини

1. Помилка: The 'Access-Control-Allow-Origin' header is missing.
   Розшифровка помилки: браузер не знайшов заголовок, який дозволяє виконання крос-доменних запитів.
   • Чому це трапляється?
     • Ти забув увімкнути CORS у своєму FastAPI-застосунку.
     • Неправильна конфігурація джерел (наприклад, список дозволених доменів залишили порожнім, а браузер вимагає точного співпадіння origin).
   • Приклад:

   
   Access to XMLHttpRequest at 'http://api.example.com' from origin 'http://frontend.example.com' 
   has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.
   

2. Помилка: CORS preflight channel did not succeed.
   Розшифровка помилки: Preflight-запит повернув помилку до реального виконання методу (наприклад, POST або DELETE).
   • Чому це трапляється?
     • Сервер не дозволяє метод OPTIONS, який використовується для preflight-запиту.
     • Відповідь сервера не містить потрібних заголовків (Access-Control-Allow-Methods, Access-Control-Allow-Headers).
3. Помилка: The value of the 'Access-Control-Allow-Origin' header must not be the wildcard ('*') when the request's credentials mode is 'include'.
   Розшифровка помилки: сервер відповідає заголовком Access-Control-Allow-Origin: * (дозволяє всі джерела), але клієнтський запит містить "credentials" (cookies, HTTP-авторизація).
   • Чому це трапляється?
     • Ти працюєш з крос-доменними cookies, але дозволив доступ всім (*) замість конкретного джерела.
4. Помилка: Response to preflight request doesn't pass access control check.
   Розшифровка помилки: сервер відхилив preflight-запит, оскільки він не відповідає налаштуванням CORS.
   • Чому це трапляється?
     • Сервер не налаштований на обробку потрібних заголовків або методів.
     • Клієнтський запит містить нестандартні заголовки (наприклад, Authorization), які не включені в налаштування CORS.

Діагностика помилок CORS

Коли мова про CORS, браузери навмисне роблять процес менш прозорим: вони ховають тіло запиту і відповіді при помилці CORS. Тож ось твій план дій:

1. Використай DevTools у браузері
   • Відкрий вкладку Network у DevTools твого браузера.
   • Знайди проблемний запит.
   • Перевір заголовки запиту та відповіді.

   Усе, що тобі потрібно: наявність заголовка Access-Control-Allow-Origin у відповіді сервера. Якщо його немає — сервер не дозволяє крос-доменні запити.

2. Перевір preflight-запит.
   Якщо запит не проходить, переконайся, що сервер:
   1. Дозволяє метод OPTIONS (він обов'язковий для preflight-запитів).
   2. Повертає заголовок Access-Control-Allow-Methods, який включає твої HTTP-методи (GET, POST тощо).
   3. Обробляє всі обов'язкові заголовки через Access-Control-Allow-Headers.
3. Подвійна перевірка клієнта і сервера.
   • На клієнті перевір заголовок Origin — він має вказувати правильний домен.
   • На сервері переконайся, що список дозволених джерел (origins) налаштований коректно.

Виправлення помилок CORS у FastAPI

Переходимо до справи. Ось як позбутися згаданих помилок.

1. Базове налаштування CORS

Якщо ти зовсім забув про CORS, почни з увімкнення його в проєкті.

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Дозволені джерела
origins = [
    "http://localhost",
    "http://localhost:3000",  # Для фронтенду на React
    "https://myawesomeapp.com"  # Ваш продакшн-домен
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,  # Дозволені джерела
    allow_credentials=True,  # Для роботи з cookies
    allow_methods=["*"],  # Дозволені методи
    allow_headers=["*"],  # Дозволені заголовки
)

2. Налаштування preflight-запитів

Щоб усунути помилку preflight, перевір, що ти явно дозволяєш метод OPTIONS:

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_methods=["GET", "POST", "OPTIONS"],  # Переконайся, що OPTIONS дозволений
    allow_headers=["Content-Type", "Authorization"],  # Додай специфічні заголовки
)

3. Рішення проблеми з wildcard і credentials

Якщо ти працюєш з cookies, не можна використовувати *. Замість цього вкажи конкретний домен.

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],  # Вказуємо конкретний домен
    allow_credentials=True  # Вмикаємо роботу з cookies
)

4. Відлагодження нестандартних заголовків

Додай усі нестандартні заголовки до списку дозволених:

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_headers=["Authorization", "Content-Type", "X-Custom-Header"]
)

Поради з відладки CORS

1. Увімкни логування запитів і відповідей (наприклад, за допомогою logging).
2. Перевір, чи працює твій сервер через HTTPS (для production). Деякі браузери блокують крос-доменні запити без HTTPS.
3. Якщо помилки виникають тільки на фронтенді, спробуй тимчасово відключити CORS (наприклад, за допомогою розширень для браузера). Це допоможе підтвердити, що проблема на боці сервера.

Практика показує, що помилка CORS — найчастіше проблема конфігурації. Пам'ятай: чим простіше і конкретніше твоє налаштування (без загального *), тим менше шансів зламати решту системи.