Довідник хуків

Хуки та вебхуки

Запускайте shell-команди на етапах життєвого циклу синхронізації та після завершення обробки об'єктів. Надсилайте один JSON-звіт про запуск на кожен налаштований вебхук.

Хуки життєвого циклу

Хуки життєвого циклу огортають команду sync. Хук start є блокувальним. Хуки success, error і finally виконуються за принципом best-effort.

godwit sync \
  --source ./data \
  --destination ./backup \
  --on-start "./hooks/check.sh" \
  --on-success "./hooks/complete.sh" \
  --on-error "./hooks/failed.sh" \
  --on-finally "./hooks/cleanup.sh"

Прапорець	Ключ конфігурації	Поведінка
`--on-start`	`hooks.on_start`	Виконується перед синхронізацією. Ненульовий код виходу зупиняє запуск.
`--on-success`	`hooks.on_success`	Виконується після того, як синхронізація завершилася без помилки. Успішний запуск лише з плануванням повідомляє статус planned.
`--on-error`	`hooks.on_error`	Виконується після того, як синхронізація повернула помилку. Збій хука не замінює помилку синхронізації.
`--on-finally`	`hooks.on_finally`	Виконується після того, як операція синхронізації завершилася успіхом або помилкою. Не виконується, якщо --on-start перервав роботу до початку синхронізації. Збій хука не змінює код виходу процесу.

Godwit Sync викликає командні хуки через sh в Unix і cmd у Windows. Вивід хука надсилається до стандартного потоку помилок.

Змінні середовища життєвого циклу

Командні хуки отримують метадані запуску через змінні середовища GODWIT_*. Статистика встановлюється для фаз success, error і finally.

Змінна	Значення
`GODWIT_PHASE`	start, success, error, finally або object
`GODWIT_RUN_ID`	Ідентифікатор поточного запуску
`GODWIT_STATUS`	Порожній на старті; completed, failed або planned після операції
`GODWIT_SOURCE`	URI джерела
`GODWIT_DESTINATION`	URI призначення
`GODWIT_OBJECTS_TOTAL`	Кількість об'єктів у знімку запуску
`GODWIT_OBJECTS_TRANSFERRED`	Успішно перенесені об'єкти
`GODWIT_OBJECTS_SKIPPED`	Пропущені об'єкти
`GODWIT_OBJECTS_FAILED`	Об'єкти з помилками
`GODWIT_BYTES_TRANSFERRED`	Перенесені байти без урахування байтів із помилками
`GODWIT_DURATION_SECONDS`	Витрачений час у секундах як десяткове значення
`GODWIT_ERROR`	Текст помилки синхронізації у фазі error

Хуки на рівні об'єкта

--on-key спрацьовує після завершених і невдалих задач перенесення. Пропущені та виключені об'єкти не викликають цей хук.

godwit sync \
  --source ./data \
  --destination ./backup \
  --on-key "./hooks/index-object.sh"

Змінна	Значення
`GODWIT_KEY`	Ключ об'єкта
`GODWIT_SIZE`	Розмір об'єкта в байтах
`GODWIT_VERSION_ID`	Ідентифікатор версії S3, якщо задача-джерело його містить; інакше не встановлено
`GODWIT_STATUS`	completed або failed
`GODWIT_ERROR`	Текст помилки об'єкта для невдалих задач; інакше не встановлено

Команди на рівні об'єкта виконуються синхронно в горутинах робітників перенесення. Повільні команди знижують пропускну здатність. Збої команд обробляються за принципом best-effort і не призводять до збою перенесення.

Сповіщення через вебхуки

Повторюйте --notify, щоб надсилати підсумок завершеного запуску методом POST на кілька HTTP-ендпоінтів. Корисне навантаження містить поле text, сумісне зі Slack, і структуровані поля.

godwit sync \
  --source ./data \
  --destination ./backup \
  --notify https://hooks.example.com/godwit \
  --notify https://monitoring.example.com/runs

Корисне навантаження

{
  "text": "Godwit run `daily-backup` completed: 142 objects (5.0 GiB) transferred in 47s, 0 failures",
  "run_id": "daily-backup",
  "status": "completed",
  "source": "./data",
  "destination": "./backup",
  "objects_total": 142,
  "objects_transferred": 142,
  "objects_skipped": 0,
  "objects_failed": 0,
  "bytes_transferred": 5368709120,
  "duration_seconds": 47.3,
  "finished_at": "2026-07-22T14:22:01Z"
}

Властивість	Поведінка
Надсилання	Лише завершальні фази success або error. Фази start, finally та object не надсилають вебхуків. Переривання хуком start не надсилає вебхука.
Тайм-аут	10 секунд на кожен HTTP-запит.
Повторна спроба	Одна повторна спроба через 2 секунди для транспортних помилок і HTTP 5xx. Для HTTP 4xx повтор не виконується.
Кілька URL	URL обробляються послідовно.
Збій доставки	Журналюється як hook_failed. Збій доставки не змінює код виходу синхронізації.

Посібники з налаштування

Slack

Надсилайте підсумок запуску до каналу Slack через вхідний вебхук.

Налаштувати сповіщення Slack

Discord

Надсилайте підсумок запуску до каналу Discord через його вебхук-ендпоінт, сумісний зі Slack.

Налаштувати сповіщення Discord

Конфігурація YAML

Секція hooks напряму відповідає прапорцям хуків команди sync.

source:
  url: ./data
destination:
  url: ./backup
hooks:
  on_start: ./hooks/check.sh
  on_success: ./hooks/complete.sh
  on_error: ./hooks/failed.sh
  on_finally: ./hooks/cleanup.sh
  on_key: ./hooks/index-object.sh
  notify:
    - https://hooks.example.com/godwit

Явно вказаний прапорець хука в CLI замінює відповідне значення з конфігурації. Явно вказаний список --notify замінює hooks.notify.