Договір API

Публічна віддача — без API взагалі

Файл шукається на диску вебсервером. Не знайшли — 404, а не «згенеруй на льоту».

GET https://img.example.com/i/<шлях варіанта>
GET https://v.keepix.cloud/v/<шлях>/master.m3u8

Заголовки віддачі однакові для всіх орендарів і не змінюються:

cache-control: public, max-age=31536000, immutable
x-content-type-options: nosniff
content-security-policy: default-src 'none'; sandbox
cross-origin-resource-policy: cross-origin
access-control-allow-origin: *

Жодної Set-Cookie: на хості віддачі немає ні сесій, ні JavaScript.

Підпис

Кожен запит приватного API підписується. Чотири заголовки:

X-Media-Tenant: <код орендаря>
X-Media-Key-Id: <ідентифікатор ключа>
X-Media-Ts:     <час unix, секунди>
X-Media-Sign:   hex(HMAC-SHA256(secret, METHOD "\n" PATH "\n" TS "\n" sha256(тіло)))

PATH — шлях разом із рядком запиту (/api/v1/put?kind=prodimg&key=42). Інакше параметри залишилися б непідписаними і підміну kind чи key ніхто б не помітив. Тіло порожнього запиту хешується як порожній рядок (e3b0c442…), а не як літерал "".

Вікно — 300 секунд. Секрет — ASCII-рядок із 64 шістнадцяткових знаків; ним і підписують, декодувати нічого не треба.

Мінімальний клієнт, що підписує

#!/bin/bash
METHOD=$1; PATHQ=$2; BODY=$3
TS=$(date +%s)
BH=$( [ -f "$BODY" ] && sha256sum "$BODY" | cut -d' ' -f1 \
                     || printf '' | sha256sum | cut -d' ' -f1 )
SIG=$(printf '%s\n%s\n%s\n%s' "$METHOD" "$PATHQ" "$TS" "$BH" \
      | openssl dgst -sha256 -hmac "$KP_SECRET" -hex | sed 's/.*= //')
curl -H "X-Media-Tenant: $KP_TENANT" -H "X-Media-Key-Id: $KP_KEYID" \
     -H "X-Media-Ts: $TS"           -H "X-Media-Sign: $SIG" \
     --data-binary @"$BODY" -X "$METHOD" "https://keepix.cloud$PATHQ"

Точки

Звірка: переконатися, що долетіло все

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

Як це робиться

1. Нарізаєте свій список на пачки по 1000 і на кожну шлете POST /api/v1/reconcile зі своїми розмірами й хешами.
2. Дивитеся на summary: якщо ok дорівнює числу записів — пачка зійшлася, читати решту нема сенсу.
3. Не зійшлося — в items лежить, що саме й чому. З "only":"problems" ті, що зійшлися, не повертаються зовсім: відповідь на вдалу пачку в тисячу записів — близько 270 байтів.

Що означає кожна відповідь

status	що сталося
ok	Є, і розмір із хешем сходяться. Якщо ви не надіслали ні розміру, ні хеша, ok означає лише «є».
missing	Такого ключа (або такого варіанта в нього) у сервісу немає. Це і є те, що треба дослати.
mismatch	Є, але не те: у why написано, розмір розійшовся чи хеш.
pending	Об’єкт прийнято, варіант ще робиться — відео в черзі. Дослати нічого, треба зачекати.
unverified	Є, але звірити з вашим хешем нічим. Таке буває у файлів, прийнятих до 4 вересня 2026 року.

Відбиток пачки

У відповіді є digest — sha256 за рядками kind|key|variant|bytes|sha256, відсортованими як рядки і склеєними через \n. Порахуйте його в себе тим самим способом: якщо збігся, пачка зійшлася цілком, і розбирати тисячу відповідей не треба. Порядок записів у запиті на відбиток не впливає.

Звірка не вважається операцією і не витрачає пакет. Перевіряти, що ваші файли на місці, можна не озираючись на рахунок.

З чим саме порівнюється

Сервіс знімає EXIF і GPS з усього, що приймає. Отже файл, який лежить у нас, байт у байт не дорівнює надісланому, якщо в ньому були метадані. Порівняння тому йде з тим, що ви надіслали: розмір і хеш запам’ятовуються до чистки. У відповіді bytes і sha256 — надіслане, stored_bytes — те, що лежить на диску.

Застереження для старих файлів: для прийнятих до 4 вересня 2026 року, 02:54, хеш надісланого не записувався і обчислений зі збереженої копії заднім числом. Якщо такий файл ніс метадані, наш хеш — хеш очищеної копії, і звірка покаже mismatch законно. Перевіряється просто: надішліть файл заново, приймання ідемпотентне.

Відмови

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

{ "ok": false, "error": { "code": "sign_stale",
    "message": "The signature is older than 300 s (clocks differ by 4000 s). Check the clock on your machine." } }

Відмова завжди пояснює причину словами і ніколи не переказує виняток бібліотеки: машинний рядок читає наш оператор у журналі, а не ви у відповіді.

Адмін-API

Окрема точка входу /api/admin/v1/* зі своїм конфігом, своїм журналом і своїм підписом. Нею користується лише спільна панель керування. Ключі підпису орендарів до панелі не віддаються: це право писати в чуже сховище.