Запуск міграції з Bitly: воркер, токен та 30-хвилинний бюджет

Перше джерело міграції для нашого розгортання інтеграцій Tier-3 вийшло сьогодні. Вставте Bitly Generic Access Token, оберіть групу, натисніть Start. За п'ять хвилин кожне посилання з'явиться на s.elido.me/<slug> (або на вашому власному домені) зі збереженим слагом Bitly.

Цей допис - технічний огляд: що є в коді, що ми свідомо залишили поза увагою і чому воркер наразі працює як внутрішній процес.

Чому спочатку Bitly#

У плані розгортання в черзі стоять п'ять провайдерів: Bitly, Rebrandly, Short.io, Dub.co, TinyURL. Bitly став першим, оскільки SEO та залучення аудиторії зосереджені на одному конкретному пошуковому запиті - «Bitly alternative». Усі інші джерела міграції отримають перевагу від використання спільної структури воркера, яку ми розробили для Bitly. Порядок визначено за зростанням вартості розробки; SEO став вирішальним фактором.

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

Модель даних#

Уся функція базується на одній таблиці:

CREATE TABLE import_jobs (
    id                  BIGSERIAL    PRIMARY KEY,
    workspace_id        BIGINT       NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
    source_vendor       TEXT         NOT NULL,
    source_token_id     BIGINT       REFERENCES service_tokens(id) ON DELETE SET NULL,
    target_domain_id    BIGINT       NOT NULL REFERENCES domains(id) ON DELETE CASCADE,
    status              TEXT         NOT NULL DEFAULT 'queued',
    conflict_strategy   TEXT         NOT NULL DEFAULT 'suffix',
    source_filter       JSONB        NOT NULL DEFAULT '{}'::jsonb,
    total_items         INT          NOT NULL DEFAULT 0,
    imported_items      INT          NOT NULL DEFAULT 0,
    skipped_items       INT          NOT NULL DEFAULT 0,
    failed_items        INT          NOT NULL DEFAULT 0,
    error_log           JSONB        NOT NULL DEFAULT '[]'::jsonb,
    -- timestamps + check constraints elided
);

Поле source_token_id може бути порожнім (nullable) навмисно. TinyURL не має публічного API для безкоштовних акаунтів, тому для нього передбачено завантаження CSV - без токена. Завантаження CSV все одно створює рядок у тій же таблиці, щоб панель керування відображала єдиний інтерфейс прогресу імпорту для всіх п'яти джерел.

source_filter - це JSONB-контейнер для специфічних даних провайдера: {group_guid: "..."} для Bitly, {project_slug: "..."} для Dub, {domain_id: 123} для Short.io. Ми зможемо розділити це на окремі типізовані колонки, коли зрозуміємо, які саме дані варіюються; до того часу JSONB дозволяє зберігати схему пласкою.

error_log - це JSONB-масив об'єктів {source_id, source_slug, reason}, завдяки чому панель керування може відобразити повідомлення «12 з 4 302 посилань не вдалося мігрувати» без окремої таблиці чи join. Воркер обрізає лог на 1 000 записах - якщо їх більше, це свідчить про структурну проблему, і сама кількість уже є достатнім сигналом для дій.

Воркер#

Одна goroutine на кожне запущене завдання. Воркер знаходиться в api-core (services/api-core/internal/imports/bitly.go) для версії v1 - менше рухомих частин, відсутність міжсервісної шини подій, а контекст кожного завдання обмежений 30-хвилинним таймаутом.

const (
    MaxLinksPerImport = 50_000
    ImportRunBudget   = 30 * time.Minute
    progressEvery     = 50
    errorLogCap       = 1_000
    bitlyPageSize     = 100
)

Ці чотири константи виконують основну роботу. Це не просто налаштування - це контракт.

MaxLinksPerImport - це запобіжник, а не ліміт продукту. Більшість користувачів мають менше 5 000 посилань bitlinks. Якщо їх понад 50 тисяч, ми хочемо використовувати розділену на частини міграцію з явними контрольними точками, тому воркер видає помилку з інструкцією написати на [email protected]. Завтра це посилання вестиме на платний консьєрж-сервіс; сьогодні воно просто спрямовує до поштової скриньки.

ImportRunBudget - це ліміт часу для зручності деплою. Акаунт із 50к посилань при швидкості ~5 вставок/сек потребує приблизно трьох годин; ми краще зупинимося раніше і перезапустимо процес, ніж будемо деплоїти поверх тривалої goroutine. Якщо посилань понад 50к або час перевищує 30 хвилин, дивіться TODO про можливість відновлення в кінці файлу.

Пагінація#

API Bitly працює передбачувано. GET /v4/groups/{guid}/bitlinks?size=100 повертає посилання та URL pagination.next. Порожній next означає завершення. Весь цикл виглядає так:

page := fmt.Sprintf("%s/v4/groups/%s/bitlinks?size=%d",
    BitlyAPIBase, url.PathEscape(opts.GroupGUID), bitlyPageSize)

for page != "" {
    resp, err := w.fetchPage(ctx, opts.Token, page)
    if err != nil { /* mark failed */ return }

    for _, link := range resp.Links {
        // ... resolve slug, insert, update counters ...
    }
    page = strings.TrimSpace(resp.Pagination.Next)
}

Ми довіряємо курсору пагінації Bitly. Якщо вони двічі повернуть той самий next URL, ми зациклимося, але під час тестування такого не траплялося - а 30-хвилинний бюджет обмежує можливі збитки.

Вирішення конфліктів#

Коли слаг Bitly конфліктує з посиланням Elido, яке вже існує на цільовому домені, воркер має зробити вибір. Користувач обирає стратегію під час запуску завдання:

• suffix (за замовчуванням): додавати суфікси mylink-2, mylink-3, … аж до 50. Після 50 ми вважаємо це помилкою - це свідчить про патологічне нагромадження конфліктів, і користувачу слід спочатку впорядкувати джерело.
• skip: залишити існуюче посилання Elido, записати рядок джерела в error_log, порахувати як пропущене.
• fail: зупинити все завдання при першому ж конфлікті. Для користувачів, яким потрібна сувора семантика 1:1.

Пошук здійснюється одним індексованим читанням за (domain_id, slug):

func (w *BitlyWorker) resolveSlug(ctx context.Context, domainID int64, desired, strategy string) (string, error) {
    if _, err := w.links.GetByDomainSlug(ctx, domainID, desired); err != nil {
        if errors.Is(err, pgx.ErrNoRows) {
            return desired, nil
        }
        return "", fmt.Errorf("slug lookup: %w", err)
    }
    switch strategy {
    case "skip": return "", nil
    case "fail": return "", fmt.Errorf("slug %q already exists", desired)
    case "suffix":
        for i := 2; i <= maxSuffix; i++ {
            candidate := fmt.Sprintf("%s-%d", desired, i)
            if _, err := w.links.GetByDomainSlug(ctx, domainID, candidate); err != nil {
                if errors.Is(err, pgx.ErrNoRows) { return candidate, nil }
                return "", err
            }
        }
        return "", fmt.Errorf("more than %d collisions, giving up", maxSuffix)
    }
    return "", fmt.Errorf("unknown conflict_strategy %q", strategy)
}

Це послідовний пошук, а не вставка з конфліктом. Ми платимо за додаткове читання кожного рядка, але отримуємо детермінований перебір суфіксів і набагато зрозуміліше повідомлення про помилку - альтернативою був би пошук порушення унікальності в pgx та вилучення імені обмеження (constraint name) з рядка помилки.

Що ми не мігруємо#

Історія кліків. Bitly не надає дані про окремі кліки для експорту - лише агреговані лічильники для кожного посилання, і лише в тарифах Pro. Тому ми повідомляємо про це на кожній поверхні, яку бачить користувач: сторінка налаштувань у панелі керування, маркетинговий лендинг, інтерфейс прогресу імпорту та розділ FAQ на /migrate-from/bitly. Нові кліки потраплятимуть в аналітику Elido з моменту переходу.

Ми розглядали можливість отримання /v4/bitlinks/{id}/clicks/summary для кожного посилання, щоб заповнити метрику «імпортована кількість кліків». Відмовилися: це потроює кількість викликів API й дає лише одне приблизне число, яке неможливо використати для реального аналізу. Якщо вам потрібна історія кліків, вона вам все одно потрібна в GA4 або у вашому власному сховищі даних.

Дизайн QR-кодів та кампанії Bitly також ігноруються. Це специфічні для провайдера структури, які неможливо чітко перенести. Імпортовані з Bitly посилання отримують тег imported:bitly, щоб ви могли фільтрувати їх масово - більшість користувачів використовують це для призначення стандартного CTA-оверлея Elido або кампанії вже після імпорту.

Обробка токенів#

Токен ніколи не зберігається на диску. HTTP-обробник приймає його в тілі запиту, додає до структури BitlyJobOptions і передає воркеру через запуск goroutine:

bgCtx := context.WithoutCancel(r.Context())
go h.worker.Run(bgCtx, job.ID, imports.BitlyJobOptions{
    Token:     req.Token,
    GroupGUID: req.GroupGUID,
})

source_token_id залишається NULL. Таблиця service_tokens існує, і ми підключимо міграції до неї для інтеграцій Tier-2 з використанням токенів (Mailchimp, Brevo, Klaviyo, …), де збереження токена має сенс для регулярного використання. Для одноразових міграцій операційна вигода не виправдовує ризики зберігання - користувач вставляє токен один раз, воркер запускається, токен зникає.

context.WithoutCancel - це нова для мене функція. Контекст запиту в обробнику зазвичай використовується в програмах на Go для поширення сигналу скасування. Нам же потрібно протилежне - воркер має продовжувати роботу після завершення HTTP-запиту, який його запустив. WithoutCancel (Go 1.21+) зберігає значення контексту (логер, ID трасування, без дедлайнів), але прибирає сигнал скасування.

Можливість відновлення та проблема деплою#

Воркер працює як внутрішній процес. Деплой під час імпорту зупиняє goroutine. Ми приймаємо це для версії v1, оскільки:

1. Більшість завдань завершуються менш ніж за п'ять хвилин. Деплої рідко відбуваються в пікові години для імпорту.
2. Рядок import_jobs фіксує last_progress_at. Планувальник кожні 5 хвилин перевіряє завдання: будь-яке завдання в статусі running без прогресу протягом останніх 30 хвилин переводиться в failed із чітким описом причини «воркер зупинився», щоб користувачі не гадали, що сталося.
3. Повторний запуск є ідемпотентним для стратегій suffix та skip - уже імпортовані посилання виявляються та обробляються згідно зі стратегією. Дані не пошкоджуються.

Це компроміс. Для акаунтів з понад 10 000 посилань можливість відновлення є виправданою - ми записуємо курсор пагінації Bitly в import_jobs.source_filter і продовжуємо з того місця, де зупинилися минулого разу. Це завдання для наступної ітерації.

Що можна виміряти#

Випустили функцію - додайте інструментарій для вимірювання. Обробник створює структуровані логи zap для кожної події життєвого циклу завдання:

• import: starting bitly run - workspace, target domain, conflict strategy, group GUID
• import: bitly run complete - imported, skipped, failed, total
• imports stuck-sweep flipped jobs to failed - count

Ми ще не будуємо графіки для цього в продакшні - перші запуски реальних користувачів покажуть, на що саме варто налаштувати сповіщення. Попереднє припущення: кількість stuck-sweep > 0 у будь-якому 1-годинному вікні є сигналом для сповіщення, оскільки це означає, що воркер перестав працювати, і інтерфейс користувача застряг на статусі running довше, ніж це допустимо.

Що далі#

Та сама база, ще чотири провайдери:

• Rebrandly - GET /v1/links?limit=25 з пагінацією. Slashtag → slug 1:1, коли слаг вільний.
• Short.io - GET /links?limit=150&domain_id=…. Пагінація на рівні домену; ми спочатку виводимо список доменів, щоб користувач міг обрати джерело.
• Dub.co - GET /api/links?projectSlug=…&limit=100. Папки + теги зберігаються; це найпростіша з чотирьох інтеграцій.
• TinyURL - тільки завантаження CSV. Публічний TinyURL не має API; плани Pro дозволяють експорт у CSV. Ми приймаємо CSV безпосередньо і пропускаємо етап запитів до провайдера.

Кожен із них використовуватиме той самий рядок import_jobs і той самий інтерфейс опитування в панелі керування. Специфічний для провайдера воркер залишається в services/api-core/internal/imports/<vendor>.go.

Якщо ви відкладали порівняння з Bitly через те, що історія з міграцією була непевною, тепер вона цілком конкретна. Спробуйте - шлях від токена до останнього імпортованого посилання займає менше десяти хвилин для типових акаунтів.

Схожі статті у блозі#

• Міграція з Bitly без розриву посилань: сценарій відмов
• Досягнення p95 < 15мс для редіректів із регіон ЄС, US East та Азійсько-Тихоокеанський регіон
• Чому ми використовуємо наше аналітичне сховище для аналітики кліків (а не Postgres)
• Міграція з Rebrandly: передача брендованого домену без втрати слагів