Модули

Chute поддерживает внешние файлы модулей (.sgmodule) для расширения конфигурации с помощью многоразовых правил, скриптов, хостов MitM и сопоставлений DNS, которыми можно делиться. Модули следуют формату модулей Surge.

Модули определяются в разделе [Module]:

[Module]
https://example.com/my-module.sgmodule
/Users/me/.chute/custom-module.sgmodule
~/.chute/another-module.sgmodule

Модули http:// и https:// загружаются удалённо; локальный файл записывается голым путём — /path/to/local-module.sgmodule или ~/.chute/local-module.sgmodule, — и в этом же виде он сохраняется обратно в конфигурацию. URL вида file:/// тоже работает. Локальный файл модуля, который не удалось прочитать, пропускается с предупреждением в журнале.

Структура файла модуля

Файл .sgmodule следует тому же синтаксису, что и основной файл конфигурации. Поддерживаемые разделы:

Для совместимости раздел [DNS] в модуле принимается как псевдоним [Host].

Метаданные модуля

Модули могут включать директивы метаданных (строки, начинающиеся с #!):

#!name = My Custom Module
#!desc = Blocks ads and trackers for example.com
#!system = ios,macos

#!system — это информационные метаданные, отображаемые в редакторе модулей; в настоящее время они не ограничивают загрузку — модуль применяется на всех платформах.

#!arguments может встречаться несколько раз; более поздние объявления переопределяют более ранние. Заполнители {{{variable}}} в теле модуля заменяются значением по умолчанию, которое #!arguments объявляет для переменной, или пустой строкой, если оно не объявлено. Сейчас ни одно приложение не даёт переопределить аргументы модуля, поэтому всегда действуют объявленные значения по умолчанию.

Строка с префиксом #!IOS-ONLY, #!MACOS-ONLY или #!TVOS-ONLY действует только на этой платформе и отбрасывается на остальных, где бы она ни стояла — и в модуле, и в самом файле конфигурации:

[Rule]
#!IOS-ONLY DOMAIN-SUFFIX,mobile-ads.example,REJECT
#!MACOS-ONLY PROCESS-NAME,Updater,REJECT

При сохранении конфигурации приложением префикс остаётся как написан: строка, исключённая на этой платформе, не удаляется из файла и не превращается в комментарий, так что тот же профиль продолжает работать на остальных платформах.

Пример модуля

#!name = Ad Block Module
#!desc = Block common ad domains
#!system = ios,macos

[Rule]
DOMAIN-SUFFIX,doubleclick.net,REJECT
DOMAIN-SUFFIX,googlesyndication.com,REJECT
DOMAIN-SUFFIX,googleadservices.com,REJECT

[Host]
localhost = 127.0.0.1

[MITM]
hostname = *.google-analytics.com

[URL Rewrite]
^https://example\.com/old-api https://example.com/new-api 302

Директивы %APPEND% / %INSERT% внутри значения hostname в модуле удаляются, а сами имена хостов объединяются со списком MitM; префикс исключения - в начале имени хоста сохраняется.

Раздел [General] модуля может расширять пять списковых параметров работающей конфигурации — skip-proxy, tun-excluded-routes, tun-included-routes, dns-server и always-real-ip — с помощью %APPEND% (добавить в конец) или %INSERT% (добавить в начало). Объединение происходит для всех пяти; какие платформы читают два списка маршрутов в своих туннелях, описано в разделах Включенные маршруты и Исключенные маршруты. Значения объединяются при применении модуля и убираются при его удалении или отключении. Значение без директивы тоже добавляется в конец с уведомлением, поскольку замена списка целиком не поддерживается; любой другой ключ [General] игнорируется с уведомлением.

[General]
skip-proxy = %APPEND% *.corp.example, 10.20.0.0/16

Жизненный цикл модуля

• Модули загружаются после разбора основной конфигурации.
• Правила, скрипты, хосты MitM и хосты DNS из модулей добавляются в менеджеры времени выполнения.
• Строки [Rule] из модулей выполняются после автоматических правил Tailscale и до собственных правил конфигурации, в порядке загрузки модулей — как в Surge, так что REJECT модуля блокировки рекламы не перекрывается более ранним правилом профиля.
• Объединения [Map Local], [Body Rewrite] и [General] из модулей применяются заново после перезагрузки конфигурации.
• Когда модуль удалён или отключён, все его правила, скрипты и хосты отменяются.
• Содержимое удалённых модулей загружается при запуске туннеля и повторно загружается только при изменении списка URL в [Module] при перезагрузке конфигурации.