Skip to content

Terry Configuration

Goal

Terry должен быть конфигурируемой платформой, где поведение pipeline задаётся декларативно, а не хардкодится под каждый source.

Current Persisted Shape

Текущий Terry baseline уже хранит source catalog в PostgreSQL:

  • terry.workspaces задаёт верхний ownership boundary;
  • terry.domains задаёт logical source owner внутри workspace;
  • terry.data_sources хранит source identity/policy и pointer на текущую активную config version.
  • terry.loader_configs хранит versioned runtime config и history/statistics по каждой версии.
  • data_sources.expiration_days хранит retention policy для raw payload artifacts этого источника.

На этом этапе persisted source-of-truth для universal loader runtime это связка data_sources + loader_configs.

Configuration Domains

Source configuration

Описывает:

  • тип source;
  • transport details;
  • auth/secrets references;
  • polling или trigger strategy;
  • формат входного payload.

В текущем коде source/runtime configuration вынесена в versioned loader_configs:

  • loader_settings
  • auth_settings
  • validator_settings
  • freshness_settings
  • processor_settings
  • fingerprint
  • incremental
  • schedule_settings
  • expiration_days

Для source.type=sdk текущий Terry runtime ожидает transport-specific блок source.sdk:

  • client идентифицирует биржу или SDK-backed provider;
  • operation выбирает Terry registry operation;
  • method остаётся legacy fallback для старого config shape, если operation не задан;
  • params передаёт per-operation runtime arguments;
  • SDK credentials по-прежнему берутся из environment, а не из Terry config.

Для binance:coins.snapshot runtime использует официальный Go SDK github.com/binance/binance-connector-go и прокидывает source.sdk.params.recv_window в Binance recvWindow, если параметр задан.

Current supported Terry SDK operations:

  • binance:coins.snapshot
  • kucoin:coins.snapshot
  • kucoin:loans.snapshot
  • bybit:coins.snapshot
  • bybit:loans.snapshot
  • gate:loans.snapshot
  • whitebit:loans.snapshot

Current loader output contract для Terry сейчас JSON-only:

  • LoaderOutput.body сериализуется как JSON payload, а не как бинарный []byte;
  • для sdk fetcher это означает, что workflow result в Temporal CLI показывает обычный JSON body вместо base64 строки;
  • если source не может вернуть валидный JSON payload, такой transport shape сейчас считается вне активного Terry scope.

Для source-level throttling Terry runtime ожидает source.rate_limit:

  • requests_per_second, burst и optional window описывают limiter policy;
  • bucket_key позволяет нескольким data_source делить один limiter bucket;
  • если bucket_key не задан, runtime fallback-ит к auth.credentials_ref, а затем к data_source_id;
  • domain.rate_limit_rps остаётся domain metadata и не используется loader runtime как active throttling policy.

Job configuration

Описывает:

  • какой source использует job;
  • какой parser или extractor применяется;
  • какие validation rule включены;
  • какой набор transformation применяется;
  • какой sink является целевым;
  • какие notification policies привязаны к outcome.

Notification configuration

Описывает:

  • какие события порождают нотификацию;
  • какой notification template использовать;
  • в какие delivery channel отправлять;
  • dedup/rate-limit policy;
  • fallback channel при delivery errors.

Suggested Config Shape

На уровне документации разумно исходить из следующих logical blocks:

job
source
parser
validation
transformation
sink
notification
operations

Для текущего persisted catalog это можно читать так:

workspace
domain
data_source
  current_loader_config_id
loader_config(versioned)
  source
  auth
  validation
  freshness
  processing
  fingerprint
  incremental
  scheduling

Configuration Principles

  • config должен описывать intent, а не внутренние runtime классы;
  • secrets и credentials не хранятся inline в job config;
  • validation и transformation должны быть composable;
  • notification rules должны ссылаться на pipeline outcome, а не на transport-specific payload;
  • любой config должен поддерживать dry-run или validation mode до production запуска.

Дополнительно для текущей реализации:

  • runtime должен уметь однозначно загрузить config по data_source_id;
  • source_type и transport-specific source.type не должны расходиться;
  • ownership chain workspace -> domain -> data_source должна быть консистентной на уровне БД;
  • data_source принадлежит workspace транзитивно через domain, без отдельного workspace_id в строке источника.

Evolution Rules

  • новые поля должны добавляться backward-compatible способом;
  • deprecated keys должны иметь документированный migration path;
  • shared vocabulary из Terry должен использоваться в names и описаниях ключей.