Versions Compared

Old Version 1

changes.mady.by.user Filip Kuzmin

Saved on

compared with

New Version Current

changes.mady.by.user Filip Kuzmin

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents

1. Вказання версії в API-запитах до ЦБД

...

2. Обробка авторизації та обмежень

2.1. Використання та обробка токену доступу

Майданчик отримує токен доступу, який є сталим протягом усього періоду інтеграції (Токен майданчика не змінюється за виключенням специфічних ситуацій, про які обовʼязково відбувається окрема комунікація).

Права доступу (permissions) для виконання окремих дій визначаються на рівні самого токену та можуть бути змінені у будь-який момент (маючи обгрунтування) зі сторони Prozorro.Sale.

  • У разі спроби виконання дії, на яку токен не має відповідних прав (наприклад, публікація об’єкта без відповідного permission), API повертає код помилки 403 Forbidden.

  • Майданчик зобов’язаний реалізувати коректну обробку відповіді 403 Forbidden:

    • не робити автоматизовані повторення запиту з тим самим токеном без уточнення прав

    • логувати інцидент з вказанням дії, що була заборонена

    • за необхідності — ініціювати звернення до служби підтримки для уточнення прав доступу у відповідному каналі Slack

Усі запити до API мають супроводжуватись актуальним токеном, а система майданчика має бути здатна гнучко реагувати на зміну прав доступу без необхідності оновлення самого токену.

2.2. Дотримання обмежень на кількість запитів (Rate Limits)

Майданчик має дотримуватись обмежень на кількість запитів до API, які реалізовано за допомогою механізму rate limiting у NGINX.

У випадку отримання відповіді з кодом 429 Too Many Requests, клієнт має:

  • реалізувати механізм повторних спроб із застосуванням затримки перед наступним запитом (exponential backoff або фіксоване очікування)

  • не виконувати негайні повторні запити без очікування

  • враховувати, що час відновлення можливості надсилати запити не передається сервером явно, і має бути визначений клієнтом відповідно до логіки обмеження частоти (наприклад, очікування 1 секунди або більше).

2.2.1. Поточні налаштування рейт-лімітів

  • Запити на секунду: 100 запитів на секунду
  • Запити на хвилину: 2000 запитів на хвилину
  • Активні з'єднання: 300 з'єднань з однієї IP-адреси


Expand
titleДетально про рейт-ліміти

2.2.2. Що це таке і навіщо?

Обмеження частоти запитів (rate limit) — це один з основних інструментів захисту вебресурсів від DDoS-атак.

У випадку взаємодії з системою, цей механізм також допомагає контролювати навантаження та запобігати збоїв у роботі через помилки або некоректну поведінку клієнтів системи.

2.2.3. Мета використання рейт-лімітів

У зв'язку з постійними змінами у роботі системи та програмного забезпечення майданчиків, можуть виникати ситуації, коли через помилкові дії або збій сторонніх сервісів генерується надмірна кількість запитів до системи.

Щоб запобігти перевантаженню нової системи та мінімізувати можливі наслідки таких помилок, вводиться обмеження на кількість запитів і активних з'єднань з боку однієї IP-адреси.

2.2.4.Поточні налаштування рейт-лімітів

  • Запити на секунду: 100 запитів на секунду.
  • Запити на хвилину: 2000 запитів на хвилину.
  • Активні з'єднання: 300 з'єднань з однієї IP-адреси.

2.2.5. Як працюють рейт-ліміти?

  • Ліміти обчислюються для кожного середовища (домену) окремо. Наприклад, якщо з однієї IP-адреси взаємодіють з декількома середовищами, то кількість запитів розраховується для кожного з них окремо.
  • Блокування IP-адреси також виконується окремо для кожного середовища.

2.2.6. Запобігання блокуванню при раптових стрибках активності

Для того, щоб система не блокувала IP-адресу при короткочасних стрибках активності користувачів, дозволяється тимчасове перевищення ліміту запитів у 5 разів. Це дає змогу системі справлятися з піковими навантаженнями. Однак, якщо активність залишається високою у наступній секунді або хвилині, система почне блокувати запити.

2.2.7. Що відбувається у разі блокування IP-адреси?

Якщо кількість запитів перевищує встановлені ліміти, система повертає відповідь з HTTP кодом 429 ("Too Many Requests").

2.2.8. Як уникати блокування?

Є декілька основних причин чому майданчик може бути заблокованим:

  • Генерування великої кількості однакових запитів майданчиком через помилку на стороні майданчика або неочікувану відповідь від ЦБД.  

Логіка роботи ПЗ майданчика має унеможливлювати надмірну частоту повторів будь яких запитів на нову систему за будь-яких умов.

  • Синхронізація або ресинхронізація великої кількості об'єктів через ендпоінти пошуку, чи процедури а не механізми Mirror.

Mirror використовує постійне з'єднання на основі протоколу WebSocket, що дозволяє отримувати зміни в режимі реального часу.

Це означає, що немає необхідності виконувати повторні підключення або надсилати окремі запити для отримання актуальних даних.

Інформація передається автоматично через це постійне з'єднання, що знижує навантаження на систему та спрощує процес синхронізації.

  • Невикористовувані з'єднання, які залишаються відкритими.

Логіка роботи ПЗ майданчика має унеможливлювати завислі з'єднання які невикористовуються.

Зі свого боку, нова система примусово закриває з'єднання в яких протягом 350 секунд не передавалася інформація.

Дотримання цих рекомендацій допоможе уникнути блокування та забезпечити стабільну роботу з новою системою.

...

  • ПЗ майданчика має забезпечувати окреме логування всіх запитів до API ЦБД, незалежно від логів роботи самого ПЗ.

  • Логи мають бути доступними Prozorro.Sale на запит.за запитом

4.2. Вміст логів

Лог кожного запиту до ЦБД повинен включати:

  • HTTP-метод (GET, POST тощо)
  • Повний URI запиту (

  • дату та час запиту (у UTC),

  • повний URI запиту з query-параметрами (, але без чутливої інформації, наприклад, access token),

  • HTTP-метод (GET, POST, PUT, DELETE тощо),

  • статус відповіді ЦБД,

  • Дату та час запиту та відповіді (у UTC)

  • Статус відповіді ЦБД

  • Унікальний ідентифікатор X-Request-ID, який ЦБД повернуло у заголовку відповідізначення заголовка request-id, що повертається ЦБД.

4.3. Доступ до логів

  • НЕПРОД: доступ можуть отримати тестувальники, розробники, DevOps за запитом.

  • ПРОД: доступ можливий лише через офіційне звернення бізнес-сторони (через наявність конфіденційних даних).

4.4. Формат і доступ

  • Логи можуть надаватися у вигляді:

    • текстових файлів (обов’язково — з можливістю фільтрації),

    • бажано — через інтерфейс для самостійного аналізу (наприклад, Kibana).

...

Майданчик має забезпечити можливість фільтрації логів:

  • за часовим інтервалом,

  • за значенням request-id, X-Request-ID

  • за API-ендпоінтом,

  • за HTTP-статусом відповіді,

  • за HTTP-методом.

4.6. Зберігання логів

  • НЕПРОД: щонайменше 14 днів,

  • ПРОД: щонайменше 30 днів.

  • Логи мають бути чітко розділені за середовищами ЦБД (наприклад: stagingsandbox, production), не об’єднані в одну стрічку.один рядок

5. Базові вимоги до процедур взаємодії

5.1. Обов’язкове використання Mirror-сервісу

  • Майданчик зобов’язаний інтегруватися з Mirror-сервісом для синхронізації з ЦБД.

  • ПЗ має підтримувати постійне з'єднання з Mirror-сервісом і забезпечувати неперервну синхронізацію.

  • Заборонено використовувати Mirror-сервіс у вигляді періодичного cron-сценарію (наприклад, раз на годину/добу)


Info

Для забезпечення стабільності синхронізації даних, майданчики повинні коректно обробляти об'єкти великого розміру. 

Вимоги до налаштування майданчиків

Переконайтеся, що налаштування вашого WebSocket-клієнта дозволяють передачу пакетів розміром до 7.5 Мб.

Базовий тесткейс

Цей сценарій є обов'язковим для проходження при підключенні нових майданчиків або оновленні логіки роботи з Mirror.

Кроки тестування:

  1. Створення даних (Create):

    • Створити процедуру кожного доступного типу з наповненням (текст, метадані), що сумарно складає 7.5 Мб

    • Створити кожен об'єкт реєстру (Registry Object) розміром 7.5 Мб

    • Створити кожен об'єкт джоббера розміром 7.5 Мб

    • Очікуваний результат: Об'єкт успішно валідується, передається в ЦБД та стає доступним для інших учасників через Mirror

  2. Отримання даних (Sync):

    • У ЦБД (на середовищі Sandbox) створюється об'єкт процедури розміром 7.5 Мб.

    • Очікуваний результат: Клієнт Mirror майданчика не розриває з'єднання, успішно парсить отриманий JSON та оновлює локальну базу даних.


Для перевірки роботи міррора, протестувати створення наступних сутностей

  • процедури (з будь-якого напрямку)
  • процедури dgf
  • об'єкт реєстра (registry)
  • Announcement з послідуючим створенням процедури великого обʼєму (більше 6 Мб)

можна розбити на наступні етапи (якщо потрібно) - 2, 5, 7.5 метри об'єкт


Майданчик у себе перевіряє роботу клієнту (опрацювання помилки 1009 або схожих в залежності від реалізації клієнту) і також можливість швидко налаштувати максимальний розмір повідомлення яке Майданчик може отримувати з Mirror

Для тестувальників: тестувальник перевіряє, що об'єкт був синхронізований і корректно відображається на фронті Майданчика (публічний перегляд, кабінет організатора і учасника) при створенні об'єкту і його редагуванні як зі сторони самого Майданчика, так і зі сторони, коли обʼєкт створено іншим Майданчиком

5.2. Генерація мініатюр

  • ПЗ майданчика має використовувати генератор мініатюр для ілюстрацій, що відображаються в інтерфейсі.

6. Використання VPN для

...

авторизованих HTTP-запитів

...

Усі POST та PUT запити до API ЦБД у ПРОД середовищі мають виконуватись через захищене VPN-з’єднання.

...

  • Підключення до API з використанням AUTH токена дозволене лише всередині VPN-з'єднання, яке попередньо сертифіковане Prozorro.Sale

  • Заборонено виконання авторизованих запитів без VPN, навіть якщо передача відбувається по HTTPS

  • Винятком можуть бути лише публічні GET-запити, які не потребують авторизації, якщо інше не зазначено окремо

Мета: Забезпечення безпеки та конфіденційності авторизованої взаємодії з API ЦБД, запобігання перехопленню або компрометації токенів авторизації сторонніми особами.

6.1. Отримання доступу до VPN

Для підключення до захищеного середовища необхідно попередньо отримати сертифікат VPN.
Заявка на отримання сертифікату VPN подається через Service Desk Prozorro.Sale за посиланням: https://jira-sale.prozorro.org/servicedesk/customer/portal/33/create/481

7. Додатково

Загальні вимоги до процедур описані за

...

посиланням Базові вимоги до майданчиків