RNDSOFT Technology Blog

Пишем декларативный Package.swift: DSL для модульной архитектуры iOS проекта

2026-03-18T05:37:29.356Z

Swift Package Manager сегодня является стандартным инструментом для модульной архитектуры iOS-проектов. Он позволяет разделять код на независимые модули,
ускорять сборку и явно описывать зависимости. Однако по мере роста проекта файл Package.swift часто превращается в длинный список строковых зависимостей:

.target(
    name: "SomeFeature",
    dependencies: [
        "Core",
        "UI",
        "Resources"
    ]
)

Меня всегда раздражала одна особенность Package.swift:

мы описываем зависимости, но не описываем архитектуру, из-за этого:

переименование модулей усложняется;
архитектурные правила не проверяются компилятором;
количество повторяющегося кода быстро растёт.

В этой статье вместо того, чтобы рассматривать Package.swift как простой конфигурационный файл, превратим его в типобезопасный DSL для модульной архитектуры, где:

модули описываются через enum;
фичи генерируются декларативно;
архитектурные правила фиксируются в коде.

В итоге объявление зависимостей будет выглядеть так:

Libraries.allCases.map { $0.info.buildDependency() }

Local.Core.target()
Local.UI.target(deps: [.module(.Core)])
Local.DI.target(deps: [.module(.Core)])
Local.Resources.target()

featureTargets(module: { .SomeFeature($0)})

Погнали!

Ключевая особенность SwiftPM в том, что манифесты — это обычные Swift-файлы. Это значит, что мы можем использовать возможности языка для описания архитектуры, пусть и с некоторыми ограничениями.

и при попытке сделать проект с многомодульной архитектурой я получал примерно следующее:

.target(
    name: "NewsPresentation",
    dependencies: [
        "NewsDomain",
        "Core",
        "UI",
        "Resources"
    ]
)
.target(
    name: "NewsDomain",
    dependencies: [
        "NewsData",
        "Core"
    ]
)
.target(
    name: "NewsData",
    dependencies: [
        "Core"
    ]
)

Если в проекте пять фич — это уже 15 объявлений target. Если десять — то 30.

Используя DSL, ту же архитектуру можно выразить одной строкой:

featureTargets(module: { .News($0)})

при этом будут сгенерированы следующие слои:

News_Presentation
News_Domain
News_Data

с уже правильно настроенным графом зависимостей

пример схемы зависимостей фичи

Проектируем DSL

Основная идея очень простая: большинство модульных архитектур следуют предсказуемым шаблонам. Вместо того чтобы повторять эти шаблоны в Package.swift, мы можем описать их прямо на Swift.

Объявление сторонних библиотек:

enum RemotePackages: CaseIterable {
    case Alamofire

    var spec: RemotePackageSpec {
        switch self {
        case .Alamofire:
            return .init(
                "https://github.com/Alamofire/Alamofire.git",
                packageName: "Alamofire",
                version: "5.10.0"
            )
        }
    }
}

Теперь список зависимостей можно сгенерировать декларативно:

RemotePackages.allCases.map { $0.info.buildDependency() }

Объявление локальных модулей:

enum Local {
    case Core
    case UI
    case DI
    case Resources
    case Networking
}

После этого объявление target выглядит так:

Local.Core.target()
Local.UI.target(deps: [.module(.Core)])
Local.DI.target(deps: [.module(.Core)])

Объявление feature-модулей

enum Local {
    case Core
    case UI
    case DI
    case Resources
    case Networking

    case News(_ layer: FeatureLayer) // обьявляем фича модуль
}

Фича состоит из нескольких слоев:

enum FeatureLayer: String {
    case Presentation
    case Domain
    case Data
}

Эти слои будут использоваться для автоматической генерации target-модулей.
Настоящая же ценность DSL — в кодировании правил зависимостей между слоями:

func featureTargets(
    module: ( _ layer: FeatureLayer) -> Local,
    presentationExtra: [Target.Dependency] = [],
    domainExtra: [Target.Dependency] = [],
    dataExtra: [Target.Dependency] = []
) -> [Target] {

    let presentation = module(.Presentation)
    let domain = module(.Domain)
    let data = module(.Data)

    return [
        presentation.target(deps: [
            .module(domain.name),
            .module(.Core),
            .module(.UI),
            .module(.Resources)
        ] + presentationExtra),

        domain.target(deps: [
            .module(data.name),
            .module(.Core)
        ] + domainExtra),

        data.target(deps: [
            .module(.Core),
            .module(.Networking)
        ] + dataExtra)
    ]
}

И теперь объявление feature-модуля выглядит так:

featureTargets(module: { .Authorisation($0)} ])
featureTargets(module: { .News($0)} )

Настройка FeatureLayer

Еще одно преимущество такого подхода — структура слоев полностью настраиваемая. Команда может выбирать ее в зависимости от архитектуры проекта.

Например, можно разделить фичу на API и реализацию:

FeatureApi
FeatureImpl

Или использовать более детализированную структуру, например VIPER:

View
Presenter
Interactor
Router
DataStore

Важно не количество слоев, а правила зависимостей между ними.
Именно эти правила DSL позволяет зафиксировать в коде.

Полный текст package.swift

// swift-tools-version: 5.9
import PackageDescription
import Foundation

// MARK: - Declarations
enum ProjectPaths {
    static let sources = "Sources"
}

// MARK: Local Modules
enum Local {
    case Core
    case UI
    case DI
    case Resources
    case Networking
    
    case Router(_ layer: FeatureImplLayer)
    case MainScreen(_ layer: FeatureLayer)
    case DetailScreen(_ layer: FeatureLayer)
    
}

// MARK: Remote Packages
enum RemotePackages: CaseIterable {
    case Alamofire
    var spec: RemotePackageSpec {
        switch self {
         case .Alamofire:
             return .init(
                 "https://github.com/Alamofire/Alamofire.git",
                 packageName: "Alamofire",
                 version: "5.8.0"
             )
        }
    }
}

// MARK: Feature Layering System (Optional)
enum FeatureLayer: String {
    case Presentation, Domain, Data
}

enum FeatureImplLayer: String {
    case Impl, Api
}

// MARK: - Package Formation 
let packageName = "DemoApp"
let package = buildPackage(
    name: packageName,
    defaultLocalization: "en",
    platforms: [.iOS(.v15)]
) {
    [
        Local.Router(.Impl).product(),
        Local.Router(.Api).product(),
        Local.Core.product()
    ]
} dependencies: {
    RemotePackages.allCases.map { $0.spec.buildDependency() }
} targets: {
    // Base modules
    Local.Networking.target(deps: [.module(.Core), .library(.Alamofire)])
    Local.UI.target(deps: [.module(.Core)])
    Local.DI.target(deps: [.module(.Core)])
    Local.Core.target()
    
    Local.Resources.target(resources: [
        .process("Resources.xcassets")
    ])
    
    featureTargets(module: { .Router($0) }, implementationExtra: [
        .module(.MainScreen(.Presentation)),
        .module(.DetailScreen(.Presentation))
    ])
    featureTargets(module: { .MainScreen($0)},
                   presentationExtra:  [ .module(Local.DI)] )
    
    featureTargets(module: { .DetailScreen($0)},
                   presentationExtra:  [ .module(Local.DI)] )
}

// MARK: - Feature configuration
func featureTargets(
    module: ( _ layer: FeatureLayer) -> Local,
    presentationExtra: [Target.Dependency] = [],
    domainExtra: [Target.Dependency] = [],
    dataExtra: [Target.Dependency] = []
) -> [Target] {

    let presentation = module(.Presentation)
    let domain = module(.Domain)
    let data = module(.Data)

    return [
        presentation.target(deps: [
            .module(domain.name),
            .module(.Core),
            .module(.UI),
            .module(.Resources)
        ] + presentationExtra),

        domain.target(deps: [
            .module(data.name),
            .module(.Core)
        ] + domainExtra),

        data.target(deps: [
            .module(.Core),
            .module(.Networking)
        ] + dataExtra)
    ]
}

func featureTargets(
    module: ( _ layer: FeatureImplLayer) -> Local,
    implementationExtra: [Target.Dependency] = [],
    apiExtra: [Target.Dependency] = []
) -> [Target] {

    let implementation = module(.Impl)
    let api = module(.Api)
    
    return [
        implementation.target(deps: [
            .module(api),
            .module(.Core)
        ] + implementationExtra),
        api.target(deps: apiExtra)
    ]
}
// DSL PART 
// MARK: - Helpers превращает enum Local в рабочее описание модуля
extension Local {
    var name: String {
        let parsed = parsedDescription
        if let layer = parsed.layer {
            return "\(parsed.base)_\(layer)"
        }
        return parsed.base
    }
    
    private var path: String {
        let parsed = parsedDescription
        if let layer = parsed.layer {
            return "\(ProjectPaths.sources)/Features/\(parsed.base)/\(layer)"
        }
        return "\(ProjectPaths.sources)/\(parsed.base)"
    }
    
    private func module(_ resources: [Resource]?) -> TargetSpec {
       return TargetSpec(name: name, path: path, resources: resources)
    }
    private var module: TargetSpec { TargetSpec(name: name, path: path) }
    
    func target(deps: [Target.Dependency] = [], resources: [Resource]? = nil) -> Target {
        module(resources).target(deps: deps)
    }
    
    func product() -> Product {
        module.product()
    }
}

//Упрощает объявление зависимостей
extension Target.Dependency {
    static func module(_ m: Local) -> Target.Dependency {
        .target(name: m.name)
    }
    
    static func module(_ name: String) -> Target.Dependency {
        .target(name: name)
    }
    
    static func library(_ lib: RemotePackages) -> Target.Dependency {
        .product(name: lib.spec.productName,
                 package: lib.spec.packageName)
    }
}

// MARK: - DSL Core
// Позволяет декларативно собирать список Target
@resultBuilder
enum TargetsBuilder {
    static func buildBlock(_ parts: [Target]...) -> [Target] {
        parts.flatMap { $0 }
    }
    static func buildExpression(_ t: Target) -> [Target] { [t] }
    static func buildExpression(_ ts: [Target]) -> [Target] { ts }
}
// Позволяет декларативно собирать список Product
@resultBuilder
enum ProductsBuilder {
    static func buildBlock(_ parts: [Product]...) -> [Product] {
        parts.flatMap { $0 }
    }
    static func buildExpression(_ p: Product) -> [Product] { [p] }
    static func buildExpression(_ ps: [Product]) -> [Product] { ps }
}
// Позволяет декларативно собирать список Package.Dependency.
@resultBuilder
enum DependenciesBuilder {
    static func buildBlock(_ parts: [Package.Dependency]...) -> [Package.Dependency] {
        parts.flatMap { $0 }
    }
    static func buildExpression(_ d: Package.Dependency) -> [Package.Dependency] { [d] }
    static func buildExpression(_ ds: [Package.Dependency]) -> [Package.Dependency] { ds }
}
// Обёртка над Package, чтобы собирать package через твой DSL
func buildPackage(
    name: String,
    defaultLocalization: LanguageTag? = nil,
    platforms: [SupportedPlatform] = [],
    @ProductsBuilder products: () -> [Product],
    @DependenciesBuilder dependencies: () -> [Package.Dependency],
    @TargetsBuilder targets: () -> [Target]
) -> Package {
    PackageSpec(
        name: name,
        defaultLocalization: defaultLocalization,
        platforms: platforms,
        products: products(),
        dependencies: dependencies(),
        targets: targets()
    ).build()
}

// MARK: - Specs
// Промежуточная модель для сборки Package
struct PackageSpec {
    var name: String
    var defaultLocalization: LanguageTag?
    var platforms: [SupportedPlatform] = []
    var products: [Product] = []
    var dependencies: [Package.Dependency] = []
    var targets: [Target] = []
    
    func build() -> Package {
        Package(
            name: name,
            defaultLocalization: defaultLocalization,
            platforms: platforms,
            products: products,
            dependencies: dependencies,
            targets: targets
        )
    }
}
// Модель для описания внешнего пакета
struct RemotePackageSpec {
    let url: String
    let packageName: String
    let productName: String
    let version: Version
    
    init(_ url: String,
         packageName: String,
         productName: String? = nil,
         version: Version) {
        self.url = url
        self.packageName = packageName
        self.productName = productName ?? packageName
        self.version = version
    }
    
    func buildDependency() -> Package.Dependency {
        .package(url: url, from: version)
    }
}
// Модель для описания target
struct TargetSpec {
    private let name: String
    private let path: String
    private let resources: [Resource]?
    init(name: String, path: String, resources: [Resource]? = nil) {
        self.name = name
        self.path = path
        self.resources = resources
    }
    
    func target(deps: [Target.Dependency] = []) -> Target {
        .target(
            name: name,
            dependencies: deps,
            path: path,
            resources: resources
        )
    }
    
    func testTarget(deps: [Target.Dependency] = []) -> Target {
        .testTarget(
            name: name,
            dependencies: deps,
            path: path
        )
    }
    
    func product() -> Product {
        .library(name: name, targets: [name])
    }
}

// MARK: - Helper to automatically generate the feature path and name for import
extension Local {
    private var parsedDescription: (base: String, layer: String?) {
        let description = String(describing: self)

        guard
            let start = description.firstIndex(of: "("),
            let end = description.firstIndex(of: ")")
        else {
            return (description, nil)
        }

        let base = String(description[..<start])
        var layer = String(description[description.index(after: start)..<end])

        // remove type prefix like "Main.FeatureLayer."
        if let last = layer.split(separator: ".").last {
            layer = String(last).capitalizedFirst
        }

        return (base, layer)
    }
}

extension String {
    var capitalizedFirst: String {
        prefix(1).uppercased() + dropFirst()
    }
}

Все что используется для настройки проекта, находится до "DSL PART"

Код демо-проекта

Если хотите попробовать DSL в реальном проекте:

GitHub

P.S. Архитектура в каждой команде "немного" своя. Поэтому, пример в статье намеренно упрощён — чтобы было легче увидеть саму идею DSL.

Developer 2.0: почему Big Tech автоматизирует не то

2026-01-21T09:52:52.625Z

Big Tech любит говорить, что ИИ «меняет разработку».

Он пишет код.
Он ускоряет delivery.
Он «повышает продуктивность разработчиков».

Но если посмотреть внимательнее, становится заметно другое:
мы автоматизируем не самую дорогую часть процесса.

Под «стоимостью разработки» дальше я буду понимать не деньги как таковые и не абстрактную «сложность», а совокупность времени, внимания и когнитивной нагрузки, которые тратятся на принятие решений внутри команды.

Это не только время конкретного разработчика, но и стоимость переключений контекста, синхронизации людей и задержек между обнаружением проблемы и осмысленным решением. В этом смысле самая дорогая часть разработки — не написание кода, а интерпретация сигналов и выбор между допустимыми вариантами.

Именно здесь инструменты почти не эволюционировали.

Автоматизация не там, где болит

Современная разработка построена вокруг бинарных систем:

правило либо выполняется, либо нет;
проверка либо проходит, либо падает;
CI либо пускает merge, либо блокирует его.

Big Tech довёл эту модель до технического совершенства. Но когнитивного масштабирования так и не произошло.

По мере роста проектов происходит одно и то же:

добавляются новые линтеры;
новые политики;
новые best practices;
новые запреты.

Каждый из них по отдельности логичен.
В сумме — они превращают разработку в постоянную интерпретацию сигналов.
Инструменты говорят: «Это неправильно».
И на этом их ответственность заканчивается.

Проблема, которую чувствовал каждый

По мере роста проектов количество правил неизбежно увеличивается.

Мы добавляем линтеры, style guides, CI-проверки, политики, дополнительные гейты.
Всё это необходимо.
И всё это работает...
До определённого момента.

Потому что большинство инструментов отвечают только на один вопрос:
Это допустимо или нет?

Они отлично находят ошибки. Но почти не помогают понять, что делать дальше. Этот недостающий шаг перекладывается на разработчика.
Каждое предупреждение становится задачей на интерпретацию.
Каждое нарушение требует контекста.
Каждая упавшая проверка превращается в решение, с которым инструмент не помогает.
Со временем это накапливается — не как одна большая проблема, а как постоянная фоновая нагрузка.

Мы больше не просто пишем код.

Мы:

переводим правила в намерения;
превращаем гайдлайны в решения;
вручную связываем сигналы, которые никогда не проектировались для связи.

Именно здесь возникает реальная стоимость разработки — во времени, внимании и синхронизации людей.

Дальше я буду использовать две условные модели - Developer 1.0 и Developer 2.0.
Эти модели показывают два разных подхода к принятию решений в разработке. Они намеренно упрощены - чтобы проиллюстрировать предел текущей инструментальной модели.

Developer 1.0 — модель, на которой индустрия застряла

Developer 1.0 — это инженер, работающий в мире статических правил:

детерминированная логика;
формальные условия;
предсказуемый результат.

Эта модель не устарела. Она перестала быть достаточной в условиях растущей сложности систем.

Статический анализ, линтеры, style guides, CI — всё это построено вокруг идеи: чёткое правило даёт чёткий результат.

Эта модель - фундамент в текущей разработке.

Я вижу проблему в другом: мы продолжали наращивать правила, не меняя способ принятия решений.

Где статические правила перестают масштабироваться

В какой-то момент правила перестают быть защитой и становятся просто сигналами. Линтер ругается на хардкодную строку. Анализатор жалуется на сложность. Гайдлайн запрещает «плохой паттерн».

Формально — всё верно.
Практически — недостаточно.

Потому что правило не понимает намерения.
Оно не знает:

где используется строка;
что видит пользователь;
почему решение было принято именно так;
насколько это критично именно сейчас.

Интерпретация снова ложится на разработчика.
Каждая проверка предполагает, что человек сам «соединит точки».
Здесь статические правила перестают масштабироваться — не технически, а когнитивно.

Developer 2.0 — поверх логики

Developer 2.0 — это модель, в которой разработчик больше не принимает норму, что детерминированная логика и формальные условия — единственное, с чем он работает.

Он начинает работать с интерпретационным слоем, расположенным между формальным сигналом и инженерным решением.

Он не ждёт, что ИИ «напишет код за него».
Он требует другого:

объяснять сигналы, а не просто фиксировать нарушения;
связывать контекст, а не механически запрещать;
сокращать путь от обнаружения проблемы к осмысленному решению.

В своей статье я буду показывать это на примере с CI, он — самый наглядный, но далеко не единственный.
Интерпретационный слой — это не фича линтера, а вполне архитектурный приём.

Он может быть встроен:

в бизнес-логику;
в слои валидации;
в правила принятия решений внутри системы.

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

Пример: хардкодные строки

Хардкодные строки — классическая проблема мобильных проектов.
Линтер прав: их быть не должно.

Это намеренно упрощённый пример. Не потому, что он критичен сам по себе, а потому, что на нём наглядно видна разница подходов.

Developer 1.0:

обнаружил нарушение;
сообщил о проблеме;
переложил всю интерпретацию на разработчика.

Developer 2.0

обнаружил нарушение;
проанализировал место использования;
учёл UI-контекст;
проверил, есть ли уже в ресурсах подобные строки;
предложил варианты нейминга;
сопоставил с существующими решениями в коде;
опционально можно сделать автозамену тех вариантов, что выберет разработчик.

Нарушение остаётся нарушением. Но путь от сигнала к решению становится короче и понятнее.

ИИ это умеет.
Большинство инструментов — до сих пор нет.

Важно уточнить: для реализации такого интерпретационного шага не требуется ни облачный ИИ, ни тяжёлая инфраструктура.

В моём случае для подобной проверки было достаточно локального запуска через LM Studio и легковесной модели уровня Qwen или даже LLaMA-2 7B (GGUF).

Речь не идёт о генерации кода «с нуля». Модель используется для анализа уже существующего кода и ресурсов проекта, включая просмотр файлов репозитория, но в строго ограниченной, целенаправленной задаче — сопровождении конкретного инженерного решения.

Это делает стоимость такого интерпретационного слоя принципиально иной:
он не требует передачи коммерческого контекста во внешний сервис
и может быть встроен локально — как инструмент сопровождения решений, а не как автономный агент.

Вывод

Подход Developer 2.0 — это не про ИИ.
Это про сдвиг ответственности в разработке.

Разработчик больше не отвечает только за написание кода и настройку строгих инструментов его сохранности.

Он также проектирует интерпретационный слой — набор механизмов, которые связывают формальные сигналы системы с инженерным решением, сохраняя когнитивный контекст, договоренности и гайдлайны там, где правила и проверки перестают быть самодостаточными.

P.S. В следующей части я разберу другой побочный эффект этой модели: ситуацию, в которой формально «зелёный» CI начинает подменять инженерное качество и постепенно разрушает само мышление, на котором это качество должно держаться.

Обзор протоколов обработки и хранения данных

2025-05-13T17:30:31.360Z

And now for something completely different.... Летающий цирк Монти Пайтона о формате Parquet

Введение

В ландшафте современной инженерии данных выбор правильного протокола сериализации и обработки данных является критическим решением, которое влияет на производительность, взаимодействие и масштабируемость системы. Эти протоколы определяют, как данные структурируются, сериализуются, хранятся и передаются между различными системами в различных языках программирования.

В этой статье мы рассмотрим пять протоколов обработки данных, которые стали отраслевыми стандартами: MessagePack, Apache Avro, Protocol Buffers (protobuf), Apache Thrift и Apache Parquet. Каждый из них предлагает определенные преимущества и оптимизирован для конкретных случаев использования: от коммуникации в реальном времени до аналитики больших данных.

Независимо от того, создаете ли вы микросервисы, проектируете конвейеры данных или внедряете аналитические системы, понимание этих протоколов поможет вам принимать обоснованные архитектурные решения.

MessagePack

Общее описание

MessagePack — это формат бинарной сериализации, который описывает себя как "JSON, но быстрый и компактный". MessagePack обеспечивает эффективное бинарное представление данных, оптимизированное для передачи и хранения. В отличие от JSON, MessagePack предлагает значительные улучшения как в размере, так и в скорости обработки.

Ключевые концепции реализации

Бинарный формат: данные кодируются в компактном бинарном формате, а не в текстовом.
Отсутствие схемы: предварительно определенная схема не требуется, подобно JSON.
Сохранение типов: автоматически сохраняет типы данных при сериализации.
Минимальные накладные расходы: разработан для минимизации затрат на сериализацию.

Поддерживаемые типы данных

MessagePack поддерживает большое кол-во различных типов данных:

Nil (null)
Boolean (логический)
Integer (целое число, со знаком/без знака, 8/16/32/64-бит)
Float (с плавающей точкой, 32/64-бит)
Raw bytes (сырые байты, бинарный формат)
String (строка, UTF-8)
Array (массив)
Map (пары ключ-значение)
Extension types (типы расширений для пользовательских структур данных)

Использование

MessagePack отлично подходит в сценариях, где:

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

MessagePack используется в Redis в качестве протокола сериализации данных, а также в Fluentd в качестве внутреннего представления данных, увеличивая производительность при передаче логов.

Полезные рекомендации

1. Используйте для простых структур: MessagePack работает лучше всего с относительно плоскими структурами данных.

2. Используйте сжатие: для больших нагрузок комбинируйте MessagePack с алгоритмами сжатия.

3. Версионируйте свои данные: включайте поле версии в структуру данных для обработки изменений формата.

Apache Avro

Общее описание

Apache Avro — это система сериализации данных, разработанная в рамках проекта Apache Hadoop. Apache Avro обеспечивает компактный, быстрый, бинарный формат данных с богатыми структурами данных и формат файла-контейнера для хранения метаданных. Одной из отличительных особенностей Avro является его надежные возможности эволюции схемы, что делает его идеальным для систем, где структуры данных изменяются со временем.

Ключевые концепции реализации:

На основе схемы: требует JSON-схемы для определения структуры данных. Файлы данных включают свою схему, что делает их самодокументируемыми.
Эволюция схемы: поддерживает добавление, удаление и изменение полей с сохранением совместимости.
Бинарное кодирование: использует компактное бинарное кодирование для эффективного хранения и передачи.
Богатые структуры данных: поддерживает сложные вложенные типы данных.
Файлы-контейнеры (Object Container Files): встроенная поддержка файловых контейнеров с метаданными.
Поддержка сжатия (поддерживаемые кодеки сжатия deflate, xz, snappy, zstandard, bzip2).

Поддерживаемые типы данных

Avro поддерживает следующие примитивные типы:

null
boolean (логический)
int (32-битное со знаком)
long (64-битное со знаком)
float (32-битное IEEE 754)
double (64-битное IEEE 754)
bytes (последовательность 8-битных беззнаковых байтов)
string (последовательность символов Unicode)

Сложные типы включают:

record (похоже на объекты/структуры)
enum (перечисляемые значения)
array (упорядоченные коллекции)
map (неупорядоченные пары ключ/значение)
union
fixed (байтовый массив фиксированного размера)

Более подробно прочитать про типы можно на странице спецификации

Использование

Avro особенно хорошо подходит для:

обработки больших данных в экосистемах Hadoop,
платформ потоковой передачи событий (особенно с Kafka),
систем, требующих эволюции схемы,
хранения больших наборов данных с самоописательными схемами.

Schema Registry от Confluent для Apache Kafka использует Avro для обеспечения управления схемами в платформах потоковой передачи данных.

Полезные рекомендации

Следуйте правилам эволюции схемы: придерживайтесь правил совместимости Avro при развитии схем.
Добавляйте значения по умолчанию: предоставляйте значения по умолчанию для новых полей, чтобы поддерживать обратную совместимость.

Protocol Buffers (protobuf)

Общее описание

Protocol Buffers (protobuf) — это нейтральный к языку, нейтральный к платформе, расширяемый механизм для сериализации структурированных данных. Один из наиболее широко используемых форматов бинарной сериализации. Он определяет структуры сообщений в файлах .proto, которые компилируются в код, специфичный для языка, который обрабатывает сериализацию, десериализацию и проверку типов.

Ключевые концепции реализации

Язык определения интерфейса: использует файлы .proto для определения структур сообщений.
Генерация кода: компилирует схемы в код, специфичный для языка.
Бинарный формат: компактный бинарный формат для эффективной передачи.
Обратная/прямая совместимость: разработан для эволюции схемы через нумерацию полей.
Строгая типизация: обеспечивает типы данных через сгенерированный код.
Номера полей: каждое поле имеет уникальный номер, используемый в бинарном кодировании.
Вложенные сообщения: поддерживает сложные вложенные структуры данных.
Определения сервисов: может определять RPC-сервисы (особенно с gRPC).

Поддерживаемые типы данных

Protocol Buffers поддерживает следующие скалярные типы:

double, float (числа с плавающей точкой)
int32, int64, uint32, uint64 (целые числа)
sint32, sint64 (целые числа со знаком, кодируются более эффективно чем int32, int64)
fixed32, fixed64, sfixed32, sfixed64 (целые числа фиксированной ширины)
bool (логическое значение)
string (текст в кодировке UTF-8)
bytes (произвольные последовательности байтов)

Сложные типы включают:

enum (перечисляемые значения)
message (композитный тип)
repeated fields (массивы/списки)
map (пары ключ-значение)
oneof (тип объединения)

Использование

Protocol Buffers лучше всего подходит для:

коммуникации микросервисов (особенно с gRPC),
мобильных приложений с ограниченной пропускной способностью,
систем, требующих строгой типизации и валидации,
кросс-языковых сервисов с последовательными интерфейсами.

Полезные рекомендации

1. Тщательно планируйте номера полей: оставляйте пробелы в нумерации полей для будущих добавлений.

2. Никогда не изменяйте номера полей: после назначения номера полей никогда не должны меняться.

3. Документируйте определения сообщений: добавляйте ясные комментарии к файлам .proto.

4. Используйте известные типы: используйте стандартные определения для общих понятий (временные метки и т.д.).

Более подробно про все рекомендации можно прочитать на странице проекта

Apache Thrift

Общее описание

Apache Thrift — это фреймворк для масштабируемой разработки кросс-языковых сервисов. Thrift объединяет программный стек с механизмом генерации кода для создания сервисов, которые эффективно работают на нескольких языках программирования. Он использует свой собственный язык определения интерфейса (Interface Definition Language (IDL)) для определения типов данных и интерфейсов сервисов, которые затем компилируются в код на целевых языках.

Картинка взята с https://thrift.apache.org/docs/concepts.html

Ключевые концепции реализации

Многоуровневая архитектура: Разделяет транспорт, протокол, процессор и сервер.
Идентификаторы полей: числовые идентификаторы для полей, обеспечивающие обратную совместимость.
Абстракция транспорта: множество вариантов транспорта (TCP, HTTP и т.д.).
Абстракция протокола: множество протоколов связи (бинарный, компактный, JSON).
Обработка исключений: встроенная поддержка для определения и передачи исключений.
Поддержка версионирования: механизмы для обработки различий в версиях.

Поддерживаемые типы данных

Thrift поддерживает следующие базовые типы:

bool (логическое значение)
byte (8-битное целое число со знаком)
i16 (16-битное целое число со знаком)
i32 (32-битное целое число со знаком)
i64 (64-битное целое число со знаком)
double (64-битное число с плавающей точкой)
string (текст, кодированный в UTF-8)
binary (некодированные последовательности байтов)

Контейнерные типы:

list (упорядоченный список элементов)
set (неупорядоченное множество уникальных элементов)
map (пары ключ-значение)

Пользовательские типы:

struct (похоже на классы или записи)
enum (перечисляемые значения)
union (подобно C-объединениям)
exception (для обработки ошибок)
typedef (псевдонимы типов)

Использование

построение архитектур микросервисов с использование различных языков,
кросс-языковые RPC-системы,
высокопроизводительные интерфейсы сервисов,
системы, требующие как определения данных, так и интерфейсов сервисов.

Полезные рекомендации

1. Тщательно проектируйте сервисы: инвестируйте время в продуманное проектирование интерфейса.

2. Используйте подходящие идентификаторы полей: назначайте идентификаторы полей с запасом для будущего расширения.

3. Выбирайте правильный протокол: выбирайте между бинарным, компактным или JSON в зависимости от потребностей.

Придерживайтесь стандарта, рекомендованного при использовании Thrift.

Apache Parquet

Общее описание

Apache Parquet — это формат столбцового хранения, разработанный для эффективной обработки и хранения данных. Parquet оптимизирован для работы со сложными структурами данных в больших объемах. В отличие от других обсуждаемых нами протоколов, которые в основном предназначены для сериализации сообщений, Parquet специально создан для аналитических рабочих нагрузок, где распространено чтение только определенных столбцов данных. Apache Parquet получил самое широкое распространение в большом количестве популярных фреймворков (apache iceberg, apache hudi), библиотеках (apache arrow) и аналитических БД (duckdb, clickhouse).

Картинка взята с https://parquet.apache.org/docs/file-format/

Ключевые концепции реализации

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

Поддерживаемые типы данных

Parquet поддерживает следующие примитивные типы:

boolean (логический)
int32/int64 (целые)
int96 (для временных меток)
float/double (с плавающей точкой)
byte array (для строк и бинарных данных)
fixed length byte array (байтовый массив фиксированной длины)

Использование

Parquet полезен в следующих случаях:

хранилищах данных и аналитике,
обработке больших данных с Hadoop/Spark,
хранении больших наборов данных для пакетной обработки,
системах с колоночно-ориентированными шаблонами запросов,
озерах данных и холодном хранилище.

Кроме того, стоит отметить, что в сообществе Prometheus идет активное обсуждение внедрения поддержки формата Parquet.

Заключение

MessagePack

Лучше всего подходит для простой и эффективной замены JSON, где важна гибкость схемы.

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

Apache Avro

Лучше всего подходит для систем, требующих эволюции схемы.

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

Protocol Buffers

Лучше всего подходит для строго типизированных интерфейсов сервисов с кросс-языковой совместимостью.

Преимущества: отличный инструментарий, сильная безопасность типов, эффективное кодирование.
Ограничения: меньшая гибкость схемы, чем у Avro, нет встроенного RPC (нужен gRPC).
Сценарии использования: микросервисы, определения и описания API, мобильные бэкенды.

Apache Thrift

Лучше всего подходит для полных RPC-фреймворков, охватывающих несколько языков программирования.

Преимущества: встроенная поддержка RPC, несколько протоколов, комплексное решение.
Ограничения: более сложный, чем другие протоколы.
Идеальные сценарии: мультиязычные сервисные архитектуры, кросс-языковые RPC.

Apache Parquet

Лучше всего подходит для аналитических рабочих нагрузок с колоночно-ориентированными шаблонами доступа.

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

При выборе учитывайте:

1. Шаблоны доступа: колоночные или строчные.

2. Потребности в эволюции: как часто ваши структуры данных будут меняться.

3. Языковые требования: какие языки программирования вам необходимо поддерживать.

4. Безопасность типов: насколько важна строгая типизация для вашего случая использования.

Говоря про Parquet, мы не рассмотрели такой формат для аналитики, как ORC (Optimized Row Columnar), но он используется по большей части в экосистеме Hadoop и является более узкоспециализированным.

Дополнительные материалы

Обсуждение использования Parquet в Prometheus - https://docs.google.com/document/d/1dutHwZXibnq3_gIeMLMZh9uFkWToQ2TwazdoqFJzlEs/edit?tab=t.0#heading=h.6tqrdajo7je9
Apache Thrift - https://thrift.apache.org/docs/
Apache Avro - https://avro.apache.org/docs/
Protobuf - https://protobuf.dev/
Apache Parquet - https://parquet.apache.org/docs/
MessagePack - https://msgpack.org/
Статья про форматы файлов и данных - https://habr.com/ru/companies/vk/articles/741702/
Книга - Designing Data-Intensive Applications by Martin Kleppmann - https://www.oreilly.com/library/view/designing-data-intensive-applications/9781491903063/ (в декабре 2025 года планируется выход 2 издания этой книги https://www.oreilly.com/library/view/designing-data-intensive-applications/9781098119058/)

Конфигурационный полиглот или обзор языков конфигураций

2025-05-08T20:08:47.224Z

Конфигурационный Вавилон наших дней: KCL, KDL, Jsonnet и Cue lang — словно ручейки многоязычной реки Финнегана, текущие сквозь цифровую Лиффи современности. Riverrun, через конфиги и абстракции, от схем к значениям мы приходим...

Джеймс Джойс о языках конфигураций

Введение

В данной статье мы рассмотрим не такие популярные языки конфигураций, как YAML, JSON, XML, INI, HCL, но более экзотические, но и не такие маргинальные. В данной статье рассмотрим cue-lang, dhall, kdl, jsonnet, KCL. Будем смотреть от простого к сложному.

Основные ограничения таких языков, как YAML, JSON, XML, INI, HCL:

отсутствие проверки типов,
отсутствие логических проверок,
отсутствие поддержки абстракций и ограниченных возможностей повторного использования (в HCL есть базовые возможности через блоки и переменные; в YAML - якоря, но имеют ограничения использования в рамках одного файла, а также затрудняют чтение при сложных вложенных структурах),
отсутствующие или ограниченные возможности программирования,
склонность к синтаксическим ошибкам (отступы в YAML, скобочки и запятые в JSON),
проверка осуществляется внешними инструментами (Json schema, XML schema),
проверка происходит постфактум, после создания конфигурации.

Эти ограничения становятся особенно проблематичными по мере роста сложности и масштаба конфигураций инфраструктуры и приложений.

KDL

Этот претендент сильно выбивается из нашего short list конфигурационных монстров, но должны же мы порадовать тех, кому хочется выбрать хороший язык конфигурации для своего pet проекта.

Основные характеристики KDL:

Структура на основе узлов: все в KDL — это узел с именем, необязательными свойствами и необязательными дочерними элементами.
Типы данных: строки, числа, логические значения (boolean) и null.
Поддерживает многострочные выражения.
Комментарии: поддерживает как строчные, так и блочные комментарии.
Аннотации: предоставляет метаданные об узлах с использованием синтаксиса (аннотаций).
Поддержка Unicode: полная поддержка Unicode, включая идентификаторы.
Библиотеки, есть почти для всех языков программирования

Примеры использования KDL:

1. Конфигурация приложения

KDL отлично подходит для определения настроек приложения, благодаря своей интуитивно понятной структуре:

config {
  server {
    port 8080
    host "0.0.0.0"
    timeout 30s
  }
  database {
    url "postgres://localhost:5432/myapp"
    max-connections 100
    (sensitive) password "my-password"
  }
}

2. Сериализация данных

KDL можно использовать для обмена данными, аналогично JSON, но с дополнительной выразительностью

users {
  user {
    id 1
    name "Alice"
    roles ["admin", "user"]
  }
  user {
    id 2
    name "Bob"
    roles ["user"]
  }
}

Есть руководства по тому, как JSON конвертировать в KDL,

а также XML в KDL

Спецификация языка описана здесь

JSONNET

Является языком шаблонизации, который расширяет JSON такими фичами, как переменные, функции и условия.

// Простой пример
{
  person: {
    name: "Alice",
    greeting: "Hello " + self.name + "!",
  },

  // Используем локальные переменные
  local tax = 0.07,
  prices: {
    item: 100,
    withTax: self.item * (1 + tax),
  },
}

Основные сферы применения:

Управление ресурсами Kubernetes.
В утилитах из категории IaC, в т.ч. Terraform, Pulumi.
Конфигурирование приложений, централизованное управление конфигурацией.
CI/CD пайплайны: шаблонизация конфигурационных файлов (Gitlab CI, Github Actions), стандартизация пайплайнов между проектами.

Например, такие проекты как Tanka, Qbec используют jsonnet для конфигурации Kubernetes.

Dhall

Основные свойства языка Dhall: он полностью функциональный язык конфигураций, а также в нем сделан упор на безопасность.

Основные характеристики Dhall:

Строгая система типов: Dhall статически типизирован, перехватывает ошибки во время компиляции, а не во время выполнения.
Полные функции: все функции завершаются, предотвращая бесконечные циклы.
Dhall неполный по Тьюрингу язык, что по замыслу позволяет избегать проблем полных по Тьюрингу языков (проверка типов за конечное время, отсутствие рекурсии).
Нормализация: выражения можно нормализовать до стандартной формы, что упрощает сравнение конфигураций.
Безопасные импорты пакетов с проверкой целостности.
Биндинги для различных языков.
Есть различные пакеты для поддержки конфигурации Dhall в популярных инструментах ansible, kubernetes.

Пример:

let Config : Type =
  {- What happens if you add another field here? -}
  { home : Text
  , privateKey : Text
  , publicKey : Text
  }

let makeUser : Text -> Config = \(user : Text) ->
  let home       : Text   = "/home/${user}"
  let privateKey : Text   = "${home}/.ssh/id_ed25519"
  let publicKey  : Text   = "${privateKey}.pub"
  let config     : Config = { home, privateKey, publicKey }
  in  config

let configs : List Config =
  [ makeUser "bill"
  , makeUser "jane"
  ]
in  configs

KCL

KCL - это язык конфигураций на основе ограничений с возможностями проверки, модульности и применения политик.

Основные характеристики KCL:

Строгая статическая типизация с выводом типов, перехватом ошибок до времени выполнения.
Проверка на основе схемы для определения структурированных конфигураций с правилами проверки.
Политика как код для определения и обеспечения соблюдения организационных стандартов.
Неизменяемость (иммутабельность) - переменные по умолчанию неизменяемы, что способствует более безопасным конфигурациям.
Богатая стандартная библиотека со встроенными функциями.
Система импорта, обеспечивающая модульную конфигурацию с пакетами.

Хорошо интегрируется с большим количеством DevOps инструментов, в т.ч. Kubernetes (есть специальная спецификация https://github.com/kcl-lang/krm-kcl), Terraform, CI/CD пайплайны, GitOps (ArgoCD, FluxCD).

Расширяемость за счет написания собственных плагинов

Поддержка больше 10 SDK для разных языков

Библиотека с несколькими сотнями модулей

Большая библиотека примеров для различных случаев использования

Картинка взята с https://www.kcl-lang.io/

Пример простого конфига

server.k

title = "KCL Example"
owner = {
  name = "The KCL Authors"
  data = "2020-01-02T03:04:05"
}
database = {
  enabled = True
  ports = [8000, 8001, 8002]
  data = [["delta", "phi"], [3.14]]
  temp_targets = {cpu = 79.5, case = 72.0}
}

servers = [
  {ip = "10.0.0.1", role = "frontend"}
  {ip = "10.0.0.2", role = "backend"}
]

В результате выполнения

kcl server.k

получим следующий YAML файл

title: KCL Example
owner:
  name: The KCL Authors
  data: "2020-01-02T03:04:05"
database:
  enabled: true
  ports:
    - 8000
    - 8001
    - 8002
  data:
    - - delta
      - phi
    - - 3.14
temp_targets:
  cpu: 79.5
  case: 72.0
servers:
  - ip: 10.0.0.1
  role: frontend
  - ip: 10.0.0.2
  role: backend

- ip: 10.0.0.2

Пример описания схемы

schema DatabaseConfig:
  enabled: bool = True
  ports: [int] = [8000, 8001, 8002]
  data: [[str|float]] = [["delta", "phi"], [3.14]]
  temp_targets: {str: float} = {cpu = 79.5, case = 72.0}

CUE LANG

Cue lang - это язык проверки данных с механизмом вывода, основанным на логическом программировании. Ключевая вещь, которая отличает Cue от других языков то, что Cue объединяет типы и значения в единую концепцию.

Основные характеристики Cue lang:

Унификация схем и данных, CUE рассматривает схемы и данные как одно и тоже, что позволяет объединить их посредством унификации.
Декларативная природа языка и идемпотентность: повторение ограничений не меняет результат.
Отделение вычислений от конфигурации: данные, которые необходимо вычислить, могут быть вычислены отдельно и помещены в файл.
Ограничения (constraints) CUE действуют как валидаторы данных, а также как механизм для сокращения шаблонного кода.
Система типов на основе решеток: значения в CUE образуют решетку, где любые два значения имеют уникальное наиболее конкретное значение, которое обобщает оба (наименьшая верхняя граница), и уникальное наиболее общее значение, которое специализируется на обоих (наибольшая нижняя граница).

Cue может быть использован для управления конфигурацией kubernetes, terraform, управление конфигурацией CI/CD gitlab, github.

У CUE есть поддержка интеграций с YAML, JSON, Jsonschema, OpenAPI, Go (для Go есть даже кодогенерация и извлечение данных), Protobuf и Java.

Пример валидации IP адреса

package example

import "net"

[_]: net.IPv4

v4String: "198.51.100.14"
v4Bytes: [198, 51, 100, 14]

// невалидные ip адреса
tooManyOctets: "198.51.100.14.0"
octetTooLarge: [300, 51, 100, 14]
v6NotV4: "2001:0db8:85a3::8a2e:0370:7334"

В терминале вводим

cue vet -c
octetTooLarge: invalid value [300,51,100,14] (does not satisfy net.IPv4):
    ./file.cue:6:6
    ./file.cue:14:16
tooManyOctets: invalid value "198.51.100.14.0" (does not satisfy net.IPv4):
    ./file.cue:6:6
    ./file.cue:13:16
v6NotV4: invalid value "2001:0db8:85a3::8a2e:0370:7334" (does not satisfy net.IPv4):
    ./file.cue:6:6
    ./file.cue:15:10

Пример валидации конфигурации с использованием CUE

check.cue

Workflow: {
  jobs: deploy: {
    environment!: string
    // для окружения production запускать нужно на ubuntu-latest
    if environment == "production" {
      "runs-on"!: "ubuntu-latest"
    }
  }
}

.github/workflows/deploy-to-ecs.yml

name: Deploy to Amazon ECS

on:
  push:
  branches: [ $default-branch ]
  
env:
  AWS_REGION: MY_AWS_REGION
  ECR_REPOSITORY: MY_ECR_REPOSITORY
  ECS_SERVICE: MY_ECS_SERVICE
  ECS_CLUSTER: MY_ECS_CLUSTER
  ECS_TASK_DEFINITION: MY_ECS_TASK_DEFINITION
  CONTAINER_NAME: MY_CONTAINER_NAME
  
permissions:
  contents: read

jobs:
  deploy:
    name: Deploy
    runs-on: ubuntu-20.04
    environment: production
    steps:
    - name: Checkout
      uses: actions/checkout@v3
      
    - name: Configure AWS credentials
      uses: aws-actions/configure-aws-credentials@v1
      with:
        aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
        aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        aws-region: ${{ env.AWS_REGION }}
        
    - name: Login to Amazon ECR
      id: login-ecr
      uses: aws-actions/amazon-ecr-login@v1
     
    - name: Build, tag, and push image to Amazon ECR
      id: build-image
      env:
        ECR_REGISTRY: ${{ steps.login-ecr.outputs.registry }}
        IMAGE_TAG: ${{ github.sha }}
      run: |
        docker build -t $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG .
        docker push $ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG
        echo "image=$ECR_REGISTRY/$ECR_REPOSITORY:$IMAGE_TAG" >> $GITHUB_OUTPUT

    - name: Fill in the new image ID in the Amazon ECS task definition
      id: task-def
      uses: aws-actions/amazon-ecs-render-task-definition@v1
      with:
        task-definition: ${{ env.ECS_TASK_DEFINITION }}
        container-name: ${{ env.CONTAINER_NAME }}
        image: ${{ steps.build-image.outputs.image }}
        
    - name: Deploy Amazon ECS task definition
      uses: aws-actions/amazon-ecs-deploy-task-definition@v1
      with:
        task-definition: ${{ steps.task-def.outputs.task-definition }}
        service: ${{ env.ECS_SERVICE }}
        cluster: ${{ env.ECS_CLUSTER }}
        wait-for-service-stability: true

Запуск cue

$ cue vet -c check.cue .github/workflows/deploy-to-ecs.yml -d 'Workflow'
jobs.deploy."runs-on": conflicting values "ubuntu-latest" and "ubuntu-20.04":
    .github/workflows/deploy-to-ecs.yml:22:14
    ./check.cue:6:3
    ./check.cue:7:16

Итоги

KDL: простой синтаксис со структурой на основе узлов. Отлично подходит для сценариев, где удобство чтения человеком имеет первостепенное значение. Простота KDL - его сильная сторона.
JSONNET подходит для конфигураций с большим количеством шаблонов.
Dhall больше подходит для конфигураций, где корректность и безопасность имеют решающее значение, а также там, где для разработчиков будет более близким и знакомым функциональный стиль программирования.
KCL подойдет для cloud-native приложений со сложными требованиями к проверке.
CUE подойдет в случаях, где требуется унифицированная схема и конфигурация со строгими ограничениями.

Дополнительные материалы

Как описать 100 Gitlab джоб в 100 строк JSONNET https://habr.com/ru/articles/483626/
Развертывание программных систем в Kubernetes c помощью JSONNET https://habr.com/ru/articles/720556/
Официальный сайт KDL https://kdl.dev/
Официальный сайт JSONNET https://jsonnet.org/
Официальный сайт KCL https://www.kcl-lang.io/
Официальный сайт CUE https://cuelang.org/
Cтатья по конфигурации Kubernetes c использованием CUE - https://engineering.mercari.com/en/blog/entry/20220127-kubernetes-configuration-management-with-cue/

Руководство пасечника или обзор инструментария eBPF

2025-04-29T19:34:35.611Z

Я во время съемок фильма Пчеловод 3 раза запустил bpftrace и ни разу об это не пожалел.

Джейсон Стейтем

Введение

Ранее мы уже рассказывали кратко про то, что такое eBPF. В этой статье мы посмотрим на экосистему вокруг eBPF и на инструментарий, который используется для эксплуатации и разработки программ eBPF. Вкратце постараемся привести некоторые примеры использования данных инструментов.

bpftrace

Начнем с самой простой утилиты, которая используется для того, чтобы взаимодействовать с eBPF. Брендан Грегг в своем блоге ставит эту утилиту на первое место по легкости освоения. Поставить bpftrace, ни у кого думаю, не составит труда. После установки в /usr/sbin появятся небольшие файлы примеров с расширением .bt, с которыми можно поиграться. Исходный код и небольшие описания есть на github проекта.

Также хороший cheat sheet есть на сайте Брендана Грегга:

Картинка взята из репозитория bpftrace https://github.com/bpftrace/bpftrace/blob/master/images/bpftrace_probes_2018.png

Картинка взята из книги BPF Performance Tools Brendan Gregg 2019

bpftrace предоставляет простой синтаксис для написания однострочных команд или более сложных скриптов, позволяющих отслеживать и анализировать поведение ядра и приложений в режиме реального времени.

С помощью bpftrace можно:

Мониторить системные вызовов
Анализировать задержки ввода-вывода
Профилировать использование CPU и памяти
Отслеживать сетевую активность
Диагностировать проблемы производительности

Давайте теперь взглянем на bpftrace в действии.

Этот скрипт в реальном времени мониторит создание новых процессов. Команда печатает текущее время, имя процесса, PID и родительский PID, str(args->filename) конвертирует указатель на файл в строку

bpftrace -e 'tracepoint:sched:sched_process_exec {time("%H:%M:%S "); printf("Process exec: %s (PID: %d, PPID: %d)\n", str(args->filename), pid, curtask->parent->pid); }'

Профилирование системных вызовов по процессу.

Этот скрипт профилирует системный вызов sys_enter и с интервалом каждые 10 секунд выводит кол-во системных вызовов sys_enter, а также PID процесса и имя процесса.

bpftrace -e 'tracepoint:raw_syscalls:sys_enter {@syscalls[pid, comm, args->id] = count();} interval:s:10 { print(@syscalls); clear(@syscalls); }'

Этот скрипт мониторит кол-во переключений контекста между 2-мя процессами prev_comm - процесс, который запущен перед переключением контекста, а next_comm - процесс, что будет запущен после переключения контекста.

bpftrace -e 'tracepoint:sched:sched_switch {@task_switches[args->prev_comm, args->next_comm] = count();}'

Несколько полезных замечаний:

У bpftrace есть флаг -d для запуска в режиме dry-run.
Для сложных скриптов лучше создавать отдельные файлы .bt. Загляните как это сделано в файлах /usr/sbin/*.bt
Для длинных сессий сбора данных используйте interval

Когда использовать bpftrace:

быстрый обзор системы по проблеме производительности
однострочные и простые скрипты
когда достаточно будет простых агрегаций, которые может предоставить bpftrace: подсчет, гистограммы и простая статистика
с bpftrace не нужно иметь опыт программирования

Кроме того у bpftrace есть свой сайт, где есть страничка с однострочниками, туториалом по однострочникам, страничка с практическими занятиями

bcc

BCC (BPF Compiler Collection) - это набор инструментов и библиотек для создания эффективных программ eBPF. BCC предоставляет Python и Lua интерфейсы для написания программ, которые компилируются в eBPF-код "на лету" при запуске.

Инструкцию по установке для различных дистрибутивов можно найти по ссылке.

Также как и для bpftrace на основе BCC написано множество полезных утилит с исходным кодом, ознакомиться можно по ссылке. А огромное кол-во примеров для этих утилит можно найти здесь.

Также есть полезный туториал для bcc.

Отдельно для Python разработчиков.

Ниже на скрине представлены области применения готовых BCC инструментов:

Картинка взята из репозитория bcc https://github.com/iovisor/bcc/blob/master/images/bcc_tracing_tools_2019.png

execsnoop

инструмент из набора BCC, который отслеживает все новые системные вызовы exec(). Он показывает в реальном времени, какие программы запускаются, кем они запускаются (PID, PPID) и с какими аргументами. Это полезно для понимания того, что происходит в системе, особенно когда программы запускаются автоматически или через скрипты.

biolatency -D 5

biolatency измеряет время выполнения блочных операций ввода-вывода и отображает их в виде гистограммы. Опция -D 5 указывает выводить обновленную гистограмму каждые 5 секунд. Это помогает выявить проблемы с дисковой подсистемой, такие как медленные диски или неэффективные шаблоны доступа к данным.

Если у Вас debian, то возможно придется воспользоваться подсказкой, иначе будете получать ошибку:

Traceback (most recent call last):
File "/path/of/bitehist.py", line 17, in <module>
ImportError: cannot import name 'BPF' from 'bcc' 
(/opt/python/3.9.6/lib/python3.9/site-packages/bcc/__init__.py)

Далее напишем, что-нибудь свое:

from bcc import BPF
from time import sleep

# Определяем BPF программу
# Импортируем необходимые заголовочные файлы
bpf_text = """
#include <uapi/linux/ptrace.h>
#include <linux/sched.h>

// Определяем структуру для хранения PID и имени процесса
struct key_t {
  u32 pid;
  char comm[TASK_COMM_LEN];
};

// Создаем хэш мапу для хранения последнего timestamp для каждого PID
BPF_HASH(last_time, u32);

// Создаем хэш мапу для хранения времени выполнения
BPF_HASH(data, struct key_t, u64);

// Аттачимся к точке трассировки sched_switch в планировщике ядра, 
// которая срабатывает, когда происходит переключение планировщика между 
// процессами
TRACEPOINT_PROBE(sched, sched_switch) {

// получаем PID следующего для запуска процесса
// получаем текущий timestamp в наносекундах
// получаем последнюю временную метку для этого PID
u32 pid = args->next_pid;
u64 ts = bpf_ktime_get_ns();
u64 *last = last_time.lookup(&pid);
  
// проверяем если есть предыдущий timestamp для PID, то вычисляем дельту 
// между текущим timestamp и последним запуском, создаем key c PID и 
// именем процесса, сохраняем дельту в data
if (last) {
  u64 delta = ts - *last;
  struct key_t key = {};
  key.pid = pid;
  bpf_get_current_comm(&key.comm, sizeof(key.comm));
  data.update(&key, &delta);
}

// Обновляем последний timestamp для этого PID
last_time.update(&pid, &ts);
return 0;
}
"""
# Загружаем BPF программу, тут ранее написанная BPF программа компилируется 
# и загружается в ядро.
b = BPF(text=bpf_text)

print("Отслеживание времени выполнения процессов... Нажмите Ctrl+C для завершения.")

# Запускаем в бесконечном цикле и выводим PID, COMMAND и RUNTIME (в миллисекундах). Итерируемся по data хэш мапе.
try:
  while True:
    sleep(1)
    print("\n%-6s %-16s %-16s" % ("PID", "COMM", "RUNTIME (ms)"))
    for k, v in b["data"].items():
      print("%-6d %-16s %-16.2f" % (k.pid, k.comm.decode('utf-8', 'replace'), v.value / 1000000))
      b["data"].clear()
except KeyboardInterrupt:
  print("Выходим...")

Этот скрипт отслеживает время выполнения процессов, используя точку трассировки shed_switch, которая вызывается при переключении задач. Для каждого процесса скрипт сохраняет время последнего запуска и вычисляет разницу между текущим и предыдущим запуском. Результаты выводятся каждую секунду, показывая PID процесса, имя процесса и время его выполнения в миллисекундах.

Несколько полезных замечаний:

Используйте готовые инструменты BCC для стандартных задач трассировки
Используйте агрегацию данных (карты, гистограммы) вместо трассировки каждого события
Учитывайте, что BCC требует установленных заголовков ядра и компилятора LLVM/Clang

Когда использовать bcc:

Когда нужен более сложный анализ, чем могут дать однострочники bpftrace
Когда нужны долгосрочные решения для мониторинга, в т.ч. утилиты для многократного использования
Если нужно интегрировать eBPF инструменты с другими системами, в т.ч. с системами мониторинга

libbpf

libbpf - это C библиотека для работы с eBPF программами, которая позволяет загружать, верифицировать и управлять eBPF программами из пользовательского пространства. В отличие от BCC, libbpf не требует компилятора во время выполнения, что делает ее более подходящей для производственных сред. libbpf нужен, когда нужно выжать максимум из тех возможностей, которые предоставляет eBPF

Высокопроизводительная обработка сетевого трафика
Долгосрочный мониторинг системы
Обнаружение аномалий и угроз безопасности
Сбор метрик производительности с минимальными накладными расходами
Расширение возможностей ядра без модификации исходного кода

Для примера libbpf возьмем простейший пример из репозитория

Нужно установить сперва пакеты, которые нужны для компиляции

apt-get install -y build-essential clang llvm libelf-dev libcap-dev

клонируем репозиторий

git clone https://github.com/libbpf/libbpf-bootstrap.git

заходим в папку

cd libbpf-bootstrap/examples/c/

Рассмотрим более подробно исходный код нашего примера

minimal.bpf.c

// SPDX-License-Identifier: GPL-2.0 OR BSD-3-Clause
/* Copyright (c) 2020 Facebook */
// Импортируем заголовочные файлы
#include <linux/bpf.h>
#include <bpf/bpf_helpers.h>

// Это строка необходима для загрузки eBPF программы. Ядро загружает 
// программы только с совместимой лицензией.
char LICENSE[] SEC("license") = "Dual BSD/GPL";

// Переменная, которая нам потребуется в пользовательском пространстве
int my_pid = 0;

// Это прикрепляет программу к точки трассировки, которая
// срабатывает, когда процесс вызывает системный вызов write()
SEC("tp/syscalls/sys_enter_write")

// Функция, которая будет вызываться при каждом достижении точки трассировки.
// Функция извлекает PID текущего процесса, проверяет, что PID соответствует целевому PID my_pid, 
// если они совпадают, то логирует сообщение, используя bpf_printk, которая пишет в trace pipe
int handle_tp(void *ctx)
{
  int pid = bpf_get_current_pid_tgid() >> 32;
  if (pid != my_pid)
    return 0;
  bpf_printk("BPF triggered from PID %d.\n", pid);
  return 0;
}

minimal.c - это программа пользовательского пространства ядра, которая будет загружать и управлять eBPF программой.

Как видно мы импортируем minimal.skel.h это файл, который во время компиляции автоматически генерируется BPFTool, его мы не будем рассматривать, он после компиляции находится в каталоге рядом .output

minimal.c

// SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause)
/* Copyright (c) 2020 Facebook */
// Импортируем заголовочные файлы
#include <stdio.h>
#include <unistd.h>
#include <sys/resource.h>
#include <bpf/libbpf.h>
#include "minimal.skel.h"

/* Функция callback, которая принимает libbpf log level, строку
format и переменные аргументы. Перенаправляет libbpf логи в
stderr */
static int libbpf_print_fn(enum libbpf_print_level level, const char *format, va_list args)
{
  return vfprintf(stderr, format, args);
}

int main(int argc, char **argv)
{
/* Определяем указатель на skeleton структуру и целое число для
хранения кода ошибки. */
  struct minimal_bpf *skel;
  int err;

/* Регистрируем нашу функцию callback для обработки сообщений libbpf */
  libbpf_set_print(libbpf_print_fn);
  
/* Открываем BPF приложение */
  skel = minimal_bpf__open();
  if (!skel) {
    fprintf(stderr, "Failed to open BPF skeleton\n");
    return 1;
}

/* Убеждаемся, что BPF программа обрабатывает только системные вызовы write() */
  skel->bss->my_pid = getpid();

/* Загружаем программу (на этом этапе также проходит проверка верификатором ядра, чтобы гарантировать безопасность BPF программы */
  err = minimal_bpf__load(skel);
  if (err) {
    fprintf(stderr, "Failed to load and verify BPF skeleton\n");
    goto cleanup;
}

/* Прикрепляем загруженную BPF программу к точки трассировки в ядре */

  err = minimal_bpf__attach(skel);
  if (err) {
    fprintf(stderr, "Failed to attach BPF skeleton\n");
    goto cleanup;
  }

  printf("Successfully started! Please run `sudo cat /sys/kernel/debug/tracing/trace_pipe` "
"to see output of the BPF programs.\n");
  for (;;) {
    /* Пишем в файл из нашей BPF программы */
    fprintf(stderr, ".");
    sleep(1);
}

/* cleanup блок, в который переходим в случае ошибки или прерывания программы */
cleanup:
  minimal_bpf__destroy(skel);
  return -err;
}

Исходный код рассмотрели, теперь компилируем

make

и запускаем

./minimal

После запуска

cat /sys/kernel/debug/tracing/trace_pipe

minimal-1064528 [002] d..31 1761398.028307: bpf_trace_printk: BPF triggered from PID 1064528.
minimal-1064528 [002] d..31 1761399.028377: bpf_trace_printk: BPF triggered from PID 1064528.
minimal-1064528 [002] d..31 1761400.028446: bpf_trace_printk: BPF triggered from PID 1064528.
minimal-1064528 [002] d..31 1761401.028530: bpf_trace_printk: BPF triggered from PID 1064528.
minimal-1064528 [002] d..31 1761402.028585: bpf_trace_printk: BPF triggered from PID 1064528.
minimal-1064528 [002] d..31 1761403.028679: bpf_trace_printk: BPF triggered from PID 1064528.
minimal-1064528 [002] d..31 1761404.028765: bpf_trace_printk: BPF triggered from PID 1064528.
minimal-1064528 [002] d..31 1761405.028851: bpf_trace_printk: BPF triggered from PID 1064528.
minimal-1064528 [002] d..31 1761406.028941: bpf_trace_printk: BPF triggered from PID 1064528.
minimal-1064528 [002] d..31 1761407.029029: bpf_trace_printk: BPF triggered from PID 1064528.
minimal-1064528 [002] d..31 1761408.029124: bpf_trace_printk: BPF triggered from PID 1064528.
minimal-1064528 [002] d..31 1761409.029218: bpf_trace_printk: BPF triggered from PID 1064528.
minimal-1064528 [002] d..31 1761410.029309: bpf_trace_printk: BPF triggered from PID 1064528.

Заключение

bpftrace

bpftrace — идеальный инструмент для быстрой диагностики проблем и создания ad-hoc инструментов трассировки. Его простой синтаксис и мощные возможности делают его незаменимым для системных администраторов и разработчиков, которым необходимо оперативно выяснить причину проблем производительности. Однако, bpftrace не лучший выбор для долгосрочных решений мониторинга или продакшен-окружений из-за потенциальных накладных расходов.

BCC Tools

BCC Tools предоставляет богатый набор готовых инструментов и Python API для создания собственных eBPF программ. Это делает его популярным среди разработчиков, которым нужна гибкость и возможность быстрого создания прототипов. BCC Tools лучше всего подходит для глубокой трассировки и исследования работы системы. Главным недостатком является зависимость от LLVM/Clang во время выполнения, что может быть проблематично в некоторых производственных средах.

libbpf

libbpf — наиболее эффективное и производительное решение для работы с eBPF. Отсутствие зависимостей от компилятора во время выполнения и поддержка CO-RE делают его идеальным выбором для продакшен-систем и встраиваемых устройств. libbpf предлагает самый низкоуровневый API, что требует более глубокого понимания eBPF и C, но взамен даёт максимальный контроль и производительность. Это лучший выбор для долгосрочных решений мониторинга и наблюдаемости.

Дополнительные материалы

https://github.com/cloudflare/ebpf_exporter - ebpf exporter
https://github.com/eunomia-bpf/bpf-developer-tutorial/tree/main - огромное кол-во уроков по ebpf
https://habr.com/ru/articles/683566/ - хорошая статья про bcc tools и мониторинг dns запросов
https://eunomia.dev/tutorials/ - очень много туториалов по libbpf
https://nakryiko.com/posts/libbpf-bootstrap/ - статья про libbpf-bootstrap от разработчика ядра BPF
https://nakryiko.com/posts/bpf-core-reference-guide/ - Руководство по BPF CO-RE от разработчика ядра BPF
https://www.piter.com/collection/linux/product/proizvoditelnost-sistem - легендарная книга System Performance от Брендана Грегга
https://cilium.isovalent.com/hubfs/Learning-eBPF%20-%20Full%20book.pdf - бесплатная книга Learning eBPF автор Liz Rice
https://www.sobyte.net/post/2022-07/c-ebpf/ - хорошая статья про libbpf
Также у Брендана Грегга есть еще одна книга BPF Performance Tools Linux System and Application Observability
https://github.com/eunomia-bpf/GPTtrace - интересный проект, который совмещает LLM и eBPF, трассировка и исследование linux с использованием естественного языка
https://tetragon.io/ - интересный проект для observability, безопасности и трассировки на основе eBPF от создателей Cilium CNI для Kubernetes
https://www.brendangregg.com/ebpf.html - блог Брендана Грегга по теме eBPF
https://github.com/cloudflare/ebpf_exporter - ebpf_exporter для создания кастомных метрик на базе eBPF
https://bpfman.io/main/ - свежий проект под покровительством CNCF, ПО для запуска и управления eBPF программ
https://nvd.codes/post/monitor-any-command-typed-at-a-shell-with-ebpf/ - статья, как мониторить все команды, вводимые в shell
https://medium.com/all-things-ebpf - блог исключительно про eBPF
https://www.trackawesomelist.com/zoidbergwill/awesome-ebpf/readme/ - большой список дополнительных материалов по eBPF

DevSecOps подкрался незаметно, хотя заметен был издалека…

2025-02-11T12:34:47.613Z

DevSecOps уверенно шагает по нашей индустрии, и горе тому, кто попадёт под его поступь… Эта статья про ~~ультимативную~~ сборку базовых образов для Ruby для удовлетворения самых параноидальных потребностей ИБ. Да, именно об этом мы и расскажем - что такое "инсталляция ruby", где, что, почему лежит и как с этим жить нашему пайплайну сборки и самому приложению.

Статья подойдёт тем, кто хочет более глубоко понимать, какие процессы происходят в системе, когда вызывается gem install, bundle install или (не дай Бог) gem update –system

Как было до?

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

Это было очень удобно и позволяло быть максимально (насколько это вообще возможно) уверенным в работоспособности, однако имело ряд серьёзных минусов, с которыми мы прекрасно жили достаточно долгое время:

размер образа был большим - от 1 ГБ;
образ включал большое количество неиспользуемого (в проде) ПО.

Сканеры сканировали, сканировали, да не высканировали…

И вот однажды один (на данный момент уже далеко не один) наш клиент захотел устранения всех замечаний, которые смог выявить сканнер Trivy. А их, как не трудно догадаться, было достаточно много. И главная проблема заключается в том, что большая часть замечаний никак не связана с непосредственными зависимостями вашего приложения (теми, которые фиксируются в Gemfile.lock).
Так откуда же они берутся?

Если коротко отвечать - отовсюду :) При сборке проекта необходимо поставить его зависимости - это план минимум. Кроме того, часто появляется необходимость установить bundle определенной версии или даже обновить ruby целиком, выполнив команду gem update --system. В результате этих действий в ваш образ в разнообразные папки ставятся разнообразные гемы, но

старые версии гемов и сама базовая "инсталляция ruby" остаётся в системе со всеми своими "устаревшими" и "уязвимыми" версиями. И эти версии очень нравятся сканерам для того, чтобы поднять тревогу.

И еще два слова о том, что же именно сканирует Trivy (касательно ruby конечно):

сканирует .gemspec файлы на всей файловой системе и не важно, установлен гем или нет - если в .gemspec указана версия "с уязвимостью" - алярм;
сканирует .gem файлы на всей файловой системе и не важно, установлен гем, лежит просто в папке cache, используется или нет в вашем приложении.

Значит для удовлетворения хотелок сканера, надо сделать так, чтоб нигде не лежало ничего лишнего или не используемого, включая stdlib - стандартную библиотеку ruby.

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

Немного удручающее зрелище, особенно для ИБ клиента

Что такое инсталляция ruby?

Если мы возьмём любой дистрибутив с установленным там ruby, то увидим, что само ruby будет находиться где-то в районе:

/usr/lib/ruby - например в alpine после apk add ruby
/usr/local/lib/ruby - например в ruby:alpine, где руби собирается отдельно от apk

А дальше начинается интересное. Если посмотреть в финальный образ, в котором сделано много различных операций (обновление ruby, установка гемов через gem install, установка через bundle install), то в корневой папке ruby обнаружится несколько папок, по которым тем или иным способом будут распределены установленные вами гемы:

/usr/local/lib/ruby
├── 3.2.0
├── gems/3.2.0
├── site_ruby/3.2.0
└── vendor_ruby/3.2.0

Сразу добавим к этому списку другие папки (которые можно посмотреть в выводе команды gem env):

 - INSTALLATION DIRECTORY: /usr/local/bundle
 - USER INSTALLATION DIRECTORY: /root/.local/share/gem/ruby/3.3.0
 - SPEC CACHE DIRECTORY: /root/.cache/gem/specs
 - GEM PATHS:
    - /usr/lib/ruby/gems/3.3.0
    - /root/.local/share/gem/ruby/3.3.0

И вишенкой на торте будет настройка вашего bundle, если вы используете кеширование сборки (bundle cache или bundle config set cache_path vendor/cache), и используемые в этом зоопарке переменные окружения GEM_HOME, BUNDLE_CACHE_PATH, BUNDLE_PATH и скорее всего еще какие-то скрытые в глубинах экосистемы ruby.

Немного путано и в результате беспорядочных ~~связей~~ установок и обновлений во всех этих папках могут (и будут) появляться гемы. Надо исправить!

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

/usr/local/lib/ruby/3.3.0

Именно в этой папке установлены основные файлы ruby и stdlib, а также компилируемые расширения в папке x86_64-linux-musl (в нашем случае собранные alpine для x86_64). Эти файлы принадлежат условной "системе" и никак не будут изменяться при дальнейших модификациях, например при установке или обновлении гемов через gem install. Вместо этого библиотеки будут ставиться в папку /usr/local/lib/ruby/gems/3.3.0

/usr/local/lib/ruby/gems/3.3.0

Тут собрано всё, что вы ставите (без модификации GEM_PATH) командами gem install, включая компилируемые расширения.

/usr/local/lib/ruby/vendor_ruby/3.3.0

Сюда должны ставиться дополнительные гемы и/или патчи от команды мейнтейнеров дистрибутива. Об этом сложно найти информацию, но несколько слов есть в книге The Ruby Programming Language или, что интереснее, в changelog для NEWS for Ruby 1.8.7 (да, окаменелое…):

vendor_ruby directory
A new library directory named vendor_ruby is introduced in addition to site_ruby. The idea is to separate libraries installed by the package system (vendor) from manually (site) installed libraries preventing the former from getting overwritten by the latter, while preserving the user option to override vendor libraries with site libraries. (site_ruby takes precedence over vendor_ruby)
If you are a package maintainer, make each library package configure the library passing the --vendor option to extconf.rb so that the library files will get installed under vendor_ruby.
You can change the directory locations using configure options such as --with-sitedir=DIR and --with-vendordir=DIR.

/usr/local/lib/ruby/site_ruby/3.3.0

Сюда будут ставиться "системные" файлы, но не от OS, а от самого ruby, например после выполнения gem update –system:

site_ruby/
└── 3.4.0
   ├── bundler
   ├── rubygems
   └── x86_64-linux-musl

/usr/local/lib/ruby/gems/3.3.0/specifications/

…а также INSTALLATION DIRECTORY /usr/local/bundle/specifications…
…а также USER INSTALLATION DIRECTORY: /root/.local/share/gem/ruby/3.3.0…
…а также SPEC CACHE DIRECTORY /root/.cache/gem/specs…
…а также BUNDLE_CACHE_PATH …

Сюда ставятся .gemspec файлы, которые собственно и говорят пакетному менеджеру ruby (gem и bundle), какие именно версии каких гемов установлены.

/usr/local/lib/ruby/gems/3.3.0/specifications/default

Default, Карл… Default - это особое состояние гема, и эти гемы нельзя удалить. Если вы обновили гем до новой версии, то старая всё равно останется, и Trivy вам этого не простит. Весьма вредная папка с точки зрения сканирования.

/usr/local/lib/ruby/gems/3.3.0/cache/

…а также INSTALLATION DIRECTORY /usr/local/bundle/cache…
…а также BUNDLE_PATH …

Сюда пакетный менеджер ruby (gem или bundle) скачивает гемы (допустим вы ставите faraday.gem) перед установкой. Этот кеш очень часто используется для ускорения сборки, например в вашем Gitlab.

Что здесь у вас происходит?!

После того как мы в процессе исследования детально разобрались и увидели всё это многообразие мест, где могут находиться файлы, вызывающие панические атаки у Trivy, мы решили радикально решить эту проблему: свести все файлы, все гемы и все спеки (.gemspec) в одно место. Это позволит легко следить за всеми (всеми!) фактическими зависимостями и эффективно пользоваться командами gem cleanup и bundle clean. Тут надо отметить, что для вашей рабочей OS (системы общего назначения) такое решение приведёт к поломке системного пакетного менеджера (Gentoo Portage, dpkg/apt, rpm/zypper и пр.), но мы ведь говорим о конкретной сборке ruby под ваш конкретный проект - и тут никаких проблем не будет.

Для того чтобы узнать что куда, когда и зачем ставится, мы использовали git прямо на корне файловой системы внутри контейнера (ruby:alpine, просто alpine, ruby:debian и другие образы для сравнения) и фиксировали изменения после различных команд ⏳

Но это еще не всё. Остаётся еще проблема с default gemspec, но её относительно легко решить:

mv /usr/local/lib/ruby/gems/3.3.0/specifications/default/* /usr/local/lib/ruby/gems/3.3.0/specifications/

Теперь мы можем сформулировать План:

Все дороги ведут в Рим - делаем ссылочки для vendor_ruby, site_ruby и пр. Также явно прописываем системные переменные GEM_HOME и BUNDLE_APP_CONFIG.
Разбираемся с default gems.
Обновляем ruby (имеется в виду stdlib) до последней требуемой версии.
Обновляем bundle до нужной версии.
Удаляем лишние гемы (например rdoc).
Переставляем (!) системные (на текущий момент сборки базового образа - все) гемы, потому что, как оказалось, mv для default gemspec имеет не очень хорошие последствия.
profit!

Сказано - сделано, и добро пожаловать под кат!

ARG BASE_RUBY=3.2
ARG BASE_ALPINE=alpine3.16
ARG BASE_IMAGE=ruby:${BASE_RUBY}-${BASE_ALPINE}

FROM ${BASE_IMAGE}

ARG BASE_RUBY=3.2

ARG RUBYGEMS_VERSION=3.5.20
ARG BUNDLER_VERSION=2.5.20

# эта переменная есть в старом alpine но нет в debian и новом
# добавляем потому что она очень нужна для работы с папочками
ENV RUBY_MAJOR=${BASE_RUBY}

ENV RUBYGEMS_VERSION=${RUBYGEMS_VERSION} \
    BUNDLER_VERSION=${BUNDLER_VERSION}

RUN apk update && apk upgrade

# Это наш костыльный скрипт который удаляет всякие лишние кеши,
# man-файлы и прочий мусор. 
COPY common/scripts/cleanallbuilds.sh /usr/bin/

# dumb-init всегда используем как PID-1 но это немного другая история
RUN set -ex \
 && apk add dumb-init \
 && cleanallbuilds.sh

###### 
# Надругиваемся над диструбутивом, чтоб иметь строго
# одну версию руби в систему и управлять ею целиком через gem/bundle

# все пути ведут в Рим
ENV GEM_HOME=/usr/local/lib/ruby/gems/${RUBY_MAJOR}.0/
ENV BUNDLE_APP_CONFIG=/usr/local/lib/ruby/gems/${RUBY_MAJOR}.0/

# Сводим vendor_ruby, site_ruby и GEM_HOME в одно место
RUN set -ex \
 && rm -rf /usr/local/lib/ruby/site_ruby /usr/local/lib/ruby/vendor_ruby \
 && ln -sf /usr/local/lib/ruby /usr/local/lib/ruby/site_ruby \
 && ln -sf /usr/local/lib/ruby /usr/local/lib/ruby/vendor_ruby \
 && mkdir -p /root/.local/share/gem/ruby/ \
 && ln -sf ${GEM_HOME} /root/.local/share/gem/ruby/${RUBY_MAJOR}.0

# Чутка тюним bundle config чтоб в дальнейшем не забыть
RUN set -ex \
 && bundle config --local disable_version_check true \
 && bundle config --local clean false \
 && bundle config --local no_prune false \
 && bundle config --local disable_local_branch_check true \
 && bundle config --local jobs 2 \
 && bundle config --local allow_offline_install true

# настраиваем .gemrc чтоб не было ничего лишнего, вклюячая rdoc
RUN set -ex \
 && echo 'gem: --no-document' > /usr/local/etc/gemrc \
 && echo 'update_sources: false' >> /usr/local/etc/gemrc \
 && echo 'verbose: false' >> /usr/local/etc/gemrc \
 && echo 'update: --no-suggestions' >> /usr/local/etc/gemrc \
 && echo 'install: --no-suggestions --conservative' >> /usr/local/etc/gemrc

# пытаемся удалить ненужные гемы с самого начала - попытка не пытка
RUN set -ex \
 && gem uninstall -a -x --quiet --force `gem list | cut -f 1 -d " "` \
 && gem cleanup

RUN set -ex \
 && apk add --virtual .build-deps \
   autoconf \
   bison \
   bzip2 \
   bzip2-dev \
   coreutils \
   curl-dev \
   dpkg-dev dpkg \
   g++ \
   gcc \
   gdbm-dev \
   git \
   glib-dev \
   libc-dev \
   libffi-dev \
   libxml2-dev \
   libxslt-dev \
   linux-headers \
   make \
   ncurses-dev \
   procps \
   readline-dev \
   tar \
   xz \
   yaml-dev \
   zlib-dev \
   shared-mime-info \
 && mv /usr/local/lib/ruby/gems/${RUBY_MAJOR}.0/specifications/default/* /usr/local/lib/ruby/gems/${RUBY_MAJOR}.0/specifications/ \
 && gem cleanup \
 && gem update --system "${RUBYGEMS_VERSION}" \
 && gem uninstall bundler --all --silent || true \
 && gem install bundler -v "${BUNDLER_VERSION}" \
 && gem uninstall rdoc --all --silent || true \
 && GMS=`gem list | sed s/default:\ // | sed -E 's/\ \((.*)\)/:\1/' | sort` \
 && DEBUG_FLAGS="-Wno-calloc-transposed-args" gem pristine --all --extensions \
 && commands=$(for x in $GMS; do \
   g=$(echo "$x" | cut -f 1 -d ":"); \
   v=$(echo "$x" | cut -f 2 -d ":"); \
   echo gem pristine $g --version "$v"; \
 done) \
 && echo -e "$commands" | xargs -I CMD -P 3 bash -c CMD\
 && gem cleanup \
 && rm -rf root/.local/share/gem/specs \
 && apk del .build-deps \
 && cleanallbuilds.sh

WORKDIR /home/app
RUN set -ex \
 && adduser -D -s /sbin/nologin app \
 && chown -R app:app /home/app

ENTRYPOINT ["/usr/bin/entrypoint.sh"]
SHELL   ["/bin/sh", "-c"]

Самое интересное, конечно, находится в одном слое самого пухленького RUN, и по некоторым командам надо дать пояснения:

GMS=`gem list | sed s/default:\ // | sed -E 's/\ $(.*)$/:\1/' | sort` - получаем список установленных гемов с версиями в формате "yaml:0.4.0 zlib:3.2.1". Это нам потребуется дальше из-за странного поведения gem pristine
gem pristine --all --extensions - должен для всех установленных гемов сделать "чистовую" установку, включая скачивание и перекомпиляцию расширений. Но нет. На самом деле он делает не для всех и не всё :(
DEBUG_FLAGS="-Wno-calloc-transposed-args" - мы используем один Dockerfile для сборки базовых образов ruby 2.7, 3.0, 3.1, 3.2, и по умолчанию все расширения должны компилироваться без единого ~~разрыва~~ ворнинга компиляции, но для некоторых версий руби (кажется 3.0) это не так, и именно этот ворнинг всё портит, поэтому его подавляем без затей.
commands=$(for x in $GMS; do … - а вы знали, что в bash тоже есть пул потоков? Строго говоря, он пул процессов, и не в баше, а в xargs, но это не важно. В общем тут список $GMS в виде "yaml:0.4.0 zlib:3.2.1" трансформируется в список $commands, потому что в такой форме gem pristine работает именно так как надо:

gem pristine yaml --version "0.4.0"
gem pristine zlib --version "3.2.1"
...

echo -e "$commands" | xargs -I CMD -P 3 bash -c CMD - отправляем $commands в пул из трех процессов для одновременной установки гемов.
cleanallbuilds.sh - зовём в самом конце кустарный скрипт, который удаляет всякий мусор из системы:

#!/bin/sh

# ruby (alpine + debian)
# Скрипт единый идля debian и для alpine, поэтому ошибки,
# возникающие из-за разницы дистрибутивов просто игнорируем
rm -rf /usr/src/ruby/ || true
rm -rf /root/.local/share/gem/specs/ || true
rm -rf /root/.local/state/ || true
rm -rf /root/.cache/gem/ || true
rm -rf /usr/local/lib/ruby/gems/3.2.0/cache/ || true
rm -rf /root/.bundle/cache/ || true
gem cleanup || true

# alpine
apk cache clean || true

# debian
apt-get clean autoclean || true
apt-get autoclean --yes || true
apt-get autoremove --yes || true

find /var/log/ -type f -delete || true
find /var/lib/log/ -type f -delete || true
find /usr/share/doc/ -type f -delete || true

Результат

Старый образ занимал 900MB, новый - 152MB (не спрашивайте...)

Значительно лучше. Особенно для базового образа

Что дальше?

Теперь эти базовые образы надо начать использовать непосредственно в CI пайплайнах боевых сервисов и, конечно, процедуру сборки и тестирования придётся поменять. Точнее, мы уже перешли на новые образы и сборку уже пару недель назад - дело теперь только за статьёй. А в качестве приманки приведу результаты перехода для одного из самых "толстых" наших сервисов:

image:old       size:1.49GB   vulns:255
image:new-prod  size:259MB    vulns:1 (Вчерашняя!! СVE-2025-25186)
image:new-test  size:269MB    vulns:1 (СVE-2025-25186)

Если взглянуть ретроспективно, то совсем не весело - так что:

профилируйте чаще не только ваш код и инфраструктуру сборки.

#docker

#devsecops

#ruby

#cicd

Selenium. Как заставить браузер работать на вас

2024-12-25T05:52:13.522Z

Всем привет! Сегодня я расскажу, что такое Selenium, как его запустить, зачем он нужен, и какие у него есть плюсы и минусы.

Небольшая вводная

Selenium — это инструмент для автоматизации веб-браузеров. Он позволяет разработчикам и тестировщикам писать скрипты, которые могут управлять браузером, имитируя действия пользователя, такие как клики, ввод текста и навигация по страницам.

Selenium поддерживает множество языков программирования, включая Python, Java, Ruby и другие, и может работать с различными браузерам. Это делает его популярным выбором для автоматизации тестирования веб-приложений и выполнения рутинных задач в браузере.

Задачи, решаемые Selenium

Можно разделить на 2 большие группы. Это тестирование и парсинг (скрейпинг). Парсинг - это процесс извлечения и обработки данных из целевых ресурсов.

К тестированию можно отнести такие подгруппы как:

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

В простых случаях можно обойтись и без Selenium. Например получать html страницы с помощью простых инструментов, таких как curl.

Но бывает более сложные случаи, когда Selenium становится нашим лучшим другом:

Динамически загружаемые страницы. SPA приложению требуется js.
Обход ограничений. Современные сайты часто содержат механизмы защиты от парсинга. Например, проверка cookie, user-agent и, конечно же, captcha.

Для обхода капчи часто используется комбинация Selenium, который позволяет выполнять js на странице и прогрузить капчу, и специального механизма для решения капчи. К таким механизмам относятся:

Сторонние платные сервисы. Принимают изображение или аудиофайл через API и возвращают готовое решение.
Обученные нейронные сети. Запускаются локально и самостоятельно распознают капчи.

После получения ответа от выбранного механизма Selenium используется для ввода решения в поле или для выполнения требуемых действий, например, выбора объектов вроде "светофоров" или “мостов”.

Конфигурирование приложения для работы с Selenium

Рассмотрим конфигурирование на примере Ruby on Rails приложения.

В первую очередь нам необходимо поставить гемы. Для этого добавляем в Gemfile следующие строки:

gem 'selenium-webdriver'
gem 'webdrivers'

И устанавливаем гемы:

bundle install

Работа с Selenium

Пример парсинга данных:

require 'selenium-webdriver'
require 'webdrivers'

driver = Selenium::WebDriver.for :chrome
driver.navigate.to 'http://example.com/products'
products = driver.find_elements(class: 'product-item')

products.each do |product|
  name = product.find_element(class: 'product-name').text
  price = product.find_element(class: 'product-price').text
  Rails.logger.info { "Название: #{name}, Цена: #{price}" }
end

driver.quit

Функционально пример выше найдет названия и цену товаров на воображаемом сайте и напечатает их в логах. Но этот код можно улучшить.

Во-первых, нужно учитывать то, что Selenium - это браузер, а значит нам стоит ждать загрузки страницы. Поэтому модифицируем код, и при попытке получить список товаров, ждем 5 секунд и только потом падаем с ошибкой.

products = Selenium::WebDriver::Wait.new(timeout: 5).until do
  driver.find_elements(class: 'product-item')
end

Во-вторых, нужно хоть немного замаскироваться от систем сайта, которые ограничивают работу парсеров. Для этого добавим немного “человечности” нашему браузеру.

options = Selenium::WebDriver::Chrome::Options.new
options.add_argument('--disable-blink-features=AutomationControlled')
options.add_argument('--user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36')
options.add_argument('--headless=new')
options.add_argument('--disable-gpu')
options.add_argument('window-size=1200x800')

driver = Selenium::WebDriver.for(:chrome, options: options)

Небольшое пояснение к опциям:

--disable-blink-features=AutomationControlled. Отключает некоторые функции Blink, которые указывают на то, что браузер управляется автоматизированным инструментом. Может помочь избежать обнаружения автоматизации на некоторых сайтах.
--user-agent=Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/51.0.2704.103 Safari/537.36. Устанавливает пользовательский агент (User-Agent) для браузера. Пользовательский агент сообщает веб-сайтам, какую версию браузера и операционной системы использует пользователь. Установка пользовательского агента может помочь в обходе блокировок или в получении контента, оптимизированного для определенного браузера.
--headless=new. Запускает браузер в "безголовом" режиме, что означает, что он будет работать без графического интерфейса. Нужно для автоматизации и тестирования.
--disable-gpu. Отключает использование графического процессора (GPU). Полезно в безголовом режиме, так как некоторые функции, зависящие от GPU, могут вызывать проблемы или не поддерживаться.

По итогу получится такой код:

require 'selenium-webdriver'
require 'webdrivers'

def wait(time)
  Selenium::WebDriver::Wait.new(timeout: time)
end

def parse
  options = Selenium::WebDriver::Chrome::Options.new
  options.add_argument('--disable-blink-features=AutomationControlled')
  options.add_argument('--user-agent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36')
  options.add_argument('--headless=new')
  options.add_argument('--disable-gpu')

  driver = Selenium::WebDriver.for(:chrome, options: options)

  driver.navigate.to 'https://example.com/products'
  products = wait(5).until { driver.find_elements(class: 'product-item') }
  products.each do |product|
    name = product.find_element(class: 'product-name').text
    price = product.find_element(class: 'product-price').text
    Rails.logger.info { "Название: #{name}, Цена: #{price}" }
  end
rescue Selenium::WebDriver::Error::TimeoutError
  'Элемент с классом product-name не найден'
ensure
  driver.quit
end

И еще пара советов:

В браузер можно подгружать плагины:

options.add_extension(Rails.root.join('plugin.crx'))

Обязательно надо закрывать за собой браузер, чтобы избегать утечек памяти:

driver.quit

Иногда требуется работа с cookie. В этом помогут следующие команды:

driver.manage.all_cookies # получить все куки
driver.manage.cookie_named # получить куку по названию
driver.manage.add_cookie # записать куку

Альтернативы Selenium

Самые популярные инструменты для работы с виртуальными браузерами это:

Selenium. Старейший представитель. Поддержка множества браузеров и библиотек на различных языках. Большое и активное сообщество. Более сложное api, чем у остальных.
Puppeteer. Работает только на Node.js. Поддержка Chrome и Firefox. Сообщество растет, но меньше по сравнению с Selenium. Простое и интуитивно понятное api.
Playwright. Самый молодой представитель в этом списке. Поддержка множества браузеров и есть библиотеки на различных языках. Удобное и современное api. Встроенная поддержка мобильных устройств. Сообщество активно развивается.

Вывод

Selenium является одним из самых популярных инструментов для автоматизации браузеров и тестирования веб-приложений. Широкая поддержка различных браузеров и языков программирования упрощает процесс написания кода для реализации задач, будь то тестирование или парсинг.

Долговечность и стабильность подтверждают его надежность и эффективность.

С большой вероятностью проблема, которую вы пытаетесь решить, уже кем-то была решена, и в интернете можно найти гайд, который поможет.

Таким образом, Selenium остается одним из лучших инструментов для автоматизации браузеров. Используем его у себя в работе и вам советуем 🙂

Простейший AI ассистент или Tools or not tools

2024-12-12T15:43:22.413Z

Нужно бежать со всех ног, чтобы только оставаться на месте, а чтобы куда-то попасть, надо бежать как минимум вдвое быстрее! Льюис Кэролл Алиса в Cтране Чудес

Вступление

В данной статье мы продемонстрируем, как можно построить простейшего AI ассистента. Давайте сперва определимся с терминами. Обычно под AI ассистентом подразумевают способности Больших языковых моделей (далее по тексту LLM) не просто выдавать готовый текстовый ответ, но и совершать какую-то автономную работу по вызову сторонних функций, отправку запросов в API и на основании полученной информации из сторонних сервисов (но иногда нужно получить именно точный ответ в заданном формате), промпта, а также запроса пользователя выдавать итоговый ответ. Так, с терминами определились. Теперь вкратце о чем будет статья: в статье мы покажем, как 2мя способами LLM заставить взаимодействовать с внешним миром и с информацией, полученной не от пользователя, а из внешнего мира. В данной статье мы будем обогащать вывод LLM информацией из поиска, т.к. основной проблемой LLM является то, что в них информация заморожена на определенный момент времени, и с течением времени она устаревает и требует переобучения модели. Переобучение модели является очень дорогостоящим мероприятием, т.о. чтобы актуализировать информацию можно делать запросы в интернет, чтобы получать свежую информацию, а LLM будет нам, используя информацию из своего пространства знаний, а также дополняя информацией из поиска, выдавать достаточно свежий результат. На основе скриптов из этой статьи можно будет уже делать первые попытки для построения собственных мини-ассистентов.

Инструменты

В данной статье будут использованы следующие технологии:

В качестве поискового движка будем использовать Tavily, т.к. у него простое API, а также они заявляют, что оптимизируют свой поиск как раз для использования с LLM (подробней можно почитать в документации к tavily)
LLM YandexGPT 4 Pro 32k RC
Python, Gradio

Нужно получить API ключи для YandexGPT API и ключ для Tavily

Промптинг

В первом способе будем использовать результаты вызова функции в промпте для получения окончательного ответа от LLM как самый примитивный способ.

Ниже представлен код скрипта yc-search-prompt.py

#!/usr/bin/env python3
import httpx
import os
import gradio as gr
from tavily import TavilyClient

BASE_YC_GPT_URL = "https://llm.api.cloud.yandex.net/foundationModels/v1/completion"

def format_search_results(search_results):
  formatted_results = "\nRelevant search results:\n"
  for result in search_results['results']:
formatted_results += f"- {result['title']}: - URL: {result['url']}  \n {result['content'][:200]}...\n"

def create_prompt_with_search(user_message, search_results):
  search_context = format_search_results(search_results)
  prompt = f"""Here is some relevant context from a web search:
  {search_context}
  Using the above context, please answer the following question:
  {user_message}
  Please provide a comprehensive answer based on both the search results and your knowledge.
  And add at the end of final answer all titles and URL links at format Title - Url from above context."""
  return prompt
  
def make_search_request(text):
  tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"] )
  response = tavily_client.search(text, max_results=8)
  return response
  
def make_request_yc_gpt(text, history):
  with httpx.Client() as client:
  headers = {'Authorization': "Api-Key " + os.environ['YC_API_KEY'], 
  'content-type':'application/json'}
  r = client.post(BASE_YC_GPT_URL, timeout=None, 
  json={"modelUri": "gpt://"+os.environ['YC_FOLDER_ID'] + "/yandexgpt-32k/rc",
  "completionOptions": {
  "stream": False,
  "temperature": "0.3",
  "maxTokens": "2000"
  },"messages": [{"role": "user","text": text}]}, headers=headers)
  return r.json()["result"]["alternatives"][0]["message"]["text"]

def chatbot_function(message, chat_history, model_choice):
  try:
    if model_choice == "YandexGPT+Tavily":
      search_results = make_search_request(message)
      enhanced_prompt = create_prompt_with_search(message, search_results)
      print(enhanced_prompt)
      bot_message = f"You selected the {model_choice} model.\n" + make_request_yc_gpt(enhanced_prompt, chat_history)
      chat_history.append((message, bot_message))
    else:
      bot_message = f"You selected the {model_choice} model.\n" + make_request_yc_gpt(message, chat_history)
      chat_history.append((message, bot_message))
    return "", chat_history
  except Exception as e:
    error_message = f"An error occurred: {str(e)}"
    chat_history.append((message, error_message))
    return "", chat_history
with gr.Blocks() as demo:
  gr.Markdown("AI prompting with internet search")
  with gr.Row():
    with gr.Column(scale=4):
      chatbot = gr.Chatbot()
      msg = gr.Textbox(label="Сообщение")
      submit = gr.Button("Отправить")
      clear = gr.Button("Очистить")
    with gr.Column(scale=1):
      model = gr.Radio(
          ["YandexGPT+Tavily", "YandexGPT"],
          label="Выберите модель",
          value="YandexGPT+Tavily"
        )
  submit.click(chatbot_function, inputs=[msg, chatbot, model], outputs=[msg, chatbot])
  msg.submit(chatbot_function, inputs=[msg, chatbot, model], outputs=[msg, chatbot])
  clear.click(lambda: None, None, chatbot, queue=False)
demo.launch()

Примечание: Помните: при запросах к YandexGPT и Tavily могут списываться денежные средства. Перед запуском скрипта читайте актуальные правила использования сервисов.

Запускать скрипт следующим образом

YC_FOLDER_ID=folder_id YC_API_KEY=YANDEX_API_KEY TAVILY_API_KEY=TAVILY_KEY  python3 yc-search-prompt.py

Принцип работы скрипта: В UI Gradio на вход скрипт принимает текст от пользователя, в зависимости от того выбран ли вариант использования вместе с Tavily (YandexGPT+Tavily), тогда отправляется запрос в поиск Tavily, потом результат поиска отдается YandexGPT с промптом и просьбой сформировать окончательный ответ из собственных знаний, а также результатов поиска, а также в ответ добавить ссылки на источники из поиска.

Function calling (Tools)

Второй способ также будет использовать промпт для получения окончательного ответа, но для получения результатов поиска мы будем использовать функционал function calling. Наверное стоит остановиться подробней, для чего это нужно, т.к. кода стало почти в 2 раза больше, а результат такой же. Function calling (Tools) - это способность LLM вызывать сторонние приложения, это могут быть скрипты, обращения к различным API. В большинстве случаев это необходимо, когда для LLM нужно получить конкретный ответ (конечно, пример с использованием поиска не очень подходящий, но хотелось сделать примеры максимально похожими, больше здесь подходит, например, вызов функции, которая использует калькулятор), что-то посчитать, а т.к. LLM не предназначены для конкретных вычислений, то для этого используется функционал function calling. При этом если Tools будет много, то LLM может и сама принимать решение, когда и какой Tool ей вызывать (у anthropic есть прямо определение поведения LLM для выбора Tools. Важный момент: нужно делать хорошее описание для tools. Вот примеры хороших и плохих описаний tools от одного из лидеров индустрии.

Примечания:

в YandexGPT API на момент написания статьи функционал Tools находился в режиме бета-тестирования, может быть непредвиденное поведение.
На момент написания статьи в скриптах использовалась версия релиз кандидат YandexGPT RC 32k, подробней про жизненный цикл моделей читайте в документации

Ниже представлен код скрипта yc-search-tools.py

#!/usr/bin/env python3

import httpx
import os
import json
from tavily import TavilyClient
import gradio as gr

BASE_YC_GPT_URL = "https://llm.api.cloud.yandex.net/foundationModels/v1/completion"
search_tool = {
  "function": {
    "name": "search_tavily",
    "description": "Search the web for current information",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {
            "type": "string",
            "description": "The search query"
          }
        },
        "required": ["query"]
      }
  }
}

def format_search_results(search_results):
  formatted_results = "\nRelevant search results:\n"
  for result in search_results['results']:
    formatted_results += f"- {result['title']}: - URL: {result['url']}  \n {result['content'][:200]}...\n"
  return formatted_results

def create_prompt_with_search(user_message, search_results):
  search_context = format_search_results(search_results)
  prompt = f"""Here is some relevant context from a web search:
{search_context}

Using the above context, please answer the following question:
{user_message}

Please provide a comprehensive answer based on both the search results and your knowledge.
And add at the end of final answer all titles and URL links at format Title - Url from above context."""
  return prompt

def make_request_yc_gpt(text, is_tool_call=True):
  with httpx.Client() as client:
    headers = {'Authorization': "Api-Key " + os.environ['YC_API_KEY'], 
    'content-type':'application/json'}
    payload = {
      "modelUri": f"gpt://{os.environ['YC_FOLDER_ID']}/yandexgpt-32k/rc",
      "completionOptions": {
        "stream": False,
        "temperature": 0.0,
        "maxTokens": 8000
      },
      "messages": text
    }
    
    if is_tool_call:
      payload["tools"] = [search_tool]

    r = client.post(
    BASE_YC_GPT_URL,
    timeout=None,
    json=payload,
    headers=headers
    )
    
    response = r.json()
  return response

def handle_tool_calls(toolCalls):
  results = []
  for tool_call in toolCalls:
    if toolCalls[0]["functionCall"]["name"] == "search_tavily":
      result = make_search_request(tool_call["functionCall"]["arguments"]["query"])
  return result
def make_search_request(text):
  tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"] )
  response = tavily_client.search(text, max_results=8)
  return response

def process_conversation(user_input, history):
  conversation = [
    {
      "role": "system",
      "text": "You are a helpful bot that helps the user. You can use tools at your discretion to generate answers, but you don't always need to use them."
    },
    {
      "role": "user",
      "text": user_input
    }
  ]
  initial_response = make_request_yc_gpt(conversation)
  
  if "toolCalls" in initial_response['result']['alternatives'][0]['message']['toolCallList']:
    tool_results = handle_tool_calls(
      initial_response['result']['alternatives'][0]['message']['toolCallList']["toolCalls"]
    )
    
    enhanced_prompt = create_prompt_with_search(user_input, tool_results)
    
    final_conversation = [
      {
        "role": "user",
        "text": enhanced_prompt
      }
    ]
    
    final_response = make_request_yc_gpt(final_conversation, is_tool_call=False)
    return final_response['result']['alternatives'][0]['message']['text']
  else:
    return initial_response['result']['alternatives'][0]['message']['text']
    
def chatbot_function(message, chat_history, model_choice):
  try:
    response_list = process_conversation(message, chat_history)
    
    if isinstance(response_list, list):
      formatted_responses = [item['text'] for item in response_list if isinstance(item, dict) and 'text' in item] 
      bot_message = f"You selected the {model_choice} model.\n" + "\n".join(formatted_responses)
    else:
      bot_message = f"You selected the {model_choice} model.\n" + str(response_list)
    chat_history.append((message, bot_message))
    return "", chat_history 
  except Exception as e: 
    error_message = f"An error occurred: {str(e)}" 
    chat_history.append((message, error_message)) 
    return "", chat_history
with gr.Blocks() as demo:
  gr.Markdown("AI function calling tools internet search") 
    with gr.Row(): 
      with gr.Column(scale=4): 
        chatbot = gr.Chatbot() 
        msg = gr.Textbox(label="Сообщение") 
        submit = gr.Button("Отправить") 
        clear = gr.Button("Очистить") 
      with gr.Column(scale=1):
        model = gr.Radio( 
          ["YandexGPT+Tavily"], 
          label="Модель", 
          value="YandexGPT+Tavily" 
        ) 
  submit.click(chatbot_function, inputs=[msg, chatbot, model], outputs=[msg, chatbot]) 
  msg.submit(chatbot_function, inputs=[msg, chatbot, model], outputs=[msg, chatbot]) 
  clear.click(lambda: None, None, chatbot, queue=False) 
demo.launch()

Примечание: Помните, при запросах к YandexGPT и Tavily могут списываться денежные средства. Перед запуском скрипта читайте актуальные правила использования сервисов.

Запускать скрипт следующим образом

YC_FOLDER_ID=folder_id YC_API_KEY=YANDEX_API_KEY TAVILY_API_KEY=TAVILY_KEY python3 yc-search-tools.py

Вкратце принцип работы скрипта: В UI Gradio на вход скрипт принимает текст от пользователя, вызывает tool tavily_search, после этого результаты поиска отдается YandexGPt с промптом и просьбой сформировать окончательный ответ из собственных знаний, результатов поиска, а также в ответ добавить ссылки на источники из поиска.

Итоги и дополнительные материалы

В итоге мы получили простенький аналог perplexity.ai, сделанный своими руками. Несколько скринов как это выглядит.

Ответ YandexGPT, дополненный информацией из Tavily

YandexGPT дополненный информацией из Tavily

И ниже ответ дополняется ссылками (блок Titles and URLs) в поиске

YandexGPT дополненный информацией из Tavily

Ответ YandexGPT без дополнения ответа результатами из поиска, как видно внизу без ссылок на результаты поиска

YandexGPT без дополненным ответом из поиска

Приводим аналогичные скрины с использованием функционала Tools

YandexGPT + Tavily + Function calling (Tools)

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

Не пренебрегайте промптами, если у вас нет других инструментов для контроля LLM. Хороший материал на тему prompt engineering
Кроме промптинга есть фреймворки для работы с промптами, например, dspy, к сожалению, из коробки поддержки YandexGPT там нет, но можно пробовать использовать адаптер для совместимости с OpenAI API + dspy (сами, честно говоря, еще не пробовали) и проголосовать за фичу в Yandex Cloud
Помимо коммерческих реализаций есть также уже много open source моделей, в которых реализован функционал tools, например, у ollama. Кажется, скоро эта фича станет стандартной в LLM.
Кроме промптинга есть еще возможность заставить LLM четко следовать формату ответа, это т.н. structured output, вот хорошая статья с библиотеками, большинство библиотек в этом списке тоже не поддерживают YandexGPT (а также почти все нестабильных версий 0.x.x), но чтобы этот мир стал еще лучше, можете проголосовать за эту фичу
Фреймворки для построения агентов и мультиагентских систем

LangGraph кандидат, чтобы стать стандартом в индустрии (там готовится целая экосистема библиотек для работы с LLM LangChain, LangSmith, LangGraph), самая большая поддержка различных LLM. Очень нестабильно. Но в документации к LangGraph можно почерпнуть много хороших идей для построения агентов Tutorials и How-To, это прямо must read! Для построения MVP и быстрого прототипирования подходит отлично.
Llamaindex Тоже довольно большая библиотека для работы с LLM. Подробней что-то рассказать сложно, сами не пользовались.
AutoGen библиотека для построения мультиагентских систем. Огромное кол-во примеров под разные use cases.

Совсем недавно в Yandex cloud появился новый функционал AI assistant, который с использованием их ML SDK тоже позволяет строить LLM приложения и прячет некоторые вещи “под капот”, которые обычно используются в LLM приложениях: RAG, сохранение контекста.
Также совсем недавно anthropic выпустил Model Context Protocol, для более глубокой интеграции LLM, tools и источников данных. Посмотрим, сможет ли MCP стать стандартом в будущем.
Также аналогичный функционал, скорей всего, можно реализовать более простым способом, использовав лишь один инструмент Search API в Yandex Cloud (на момент написания статьи функционал был в Preview режиме)

Использование Mock-тестирования при интеграции с внешними системами

2024-12-03T05:37:28.565Z

У нас в RNDSOFT довольно часто случается ситуация: при разработке приложения специалистам нужно взаимодействовать с внешними веб-сервисами или сторонними API. А когда такие взаимодействия несут потенциально опасные действия, хотелось бы как-то защититься и разрабатывать в некой безопасной среде.

Как бэкенд разработчик я могу воспользоваться mock-тестированием, это когда реальные объекты заменяются на контролируемые имитации.

Например, в ruby, используя gem webmock, я могу перехватить реальный HTTP запрос от моего приложения и имитировать нужный мне ответ.

Или с помощью gem vcr один раз записать HTTP запросы и ответы в файлы (кассеты) и в дальнейшем проигрывать эти кассеты вместо реальных запросов

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

А теперь представим, что вы QA специалист, и в некоторых случаях нужно изолировать тестируемый код от внешних зависимостей, ведь они могут замедлить или усложнить тестирование.

Скорей всего, вы не можете легко получить контроль над сторонними API, чтобы воспроизвести нужные сценарии. Конечно, некоторые сервисы предоставляют тестовое окружение, и тогда это может быть выходом из ситуации. А если нет такого тестового окружения или оно не предоставляет вам необходимую гибкость в реализации сценариев тестирования? Например, для проверки поведения системы нужно протестировать сценарии с ошибками или недоступностью компонентов.

На помощь нам тоже приходит Mock-тестирование, но только реализовывается оно иначе, т.к. у тестировщика меньше возможностей вмешиваться в работу тестируемого кода.

Необходимо поднять mock-сервер, который будет имитировать ответы внешнего API и настроить тестируемое приложение таким образом, чтобы оно обращалось к mock-серверу вместо реального. Обычно все URL для внешних API выносятся в переменные окружения у контейнера, тогда им легко управлять.

В некоторых случаях можно организовать обратный прокси, чтобы имитировать только часть запросов, а остальные перенаправлять на внешнее API.

В интернете есть большое количество инструментов для mock-тестирования, принцип работы у них следующий:

Создаете ваше Mock API, разница в том, как это сделано:

Можно сгенерировать на основе OpenAPI Specification.
Через графический интерфейс создать шаблоны запросов и ответов.
Создать шаблоны, используя интерфейс управления на основе REST API.
Записать шаблоны на основе реальных запросов и отредактировать.

Развернуть Mock-сервер локально или в некотором окружении, некоторые инструменты предлагают платные облака для развертывания mock-серверов.
Далее нужно реализовать у вашего приложения возможность конфигурировать адреса внешних сервисов и перенаправить запросы на mock-сервер.
Используя возможности управления mock-сервером, проводить тестирования различных сценариев.

Вот кратко про некоторые из инструментов для mock-тестирования:

Postman - в основном используется для API тестирования, но у него есть возможность поднять mock-сервер, хорошо подходит для разовых mock сценариев тестирования.
SwaggerHub - моки создаются на основе OpenAPI Specification, и есть возможность по документации сгенерировать код готового mock-сервера под разные микрофреймворки.
CastleMock - поднимается через докер, есть панель управления, можно загрузить OpenAPI Specification.
Mockoon - работает локально, есть удобный GUI, можно загрузить OpenAPI Specification, есть возможность настроить обратный прокси и создавать моки на основе логов.
MockServer - можно поднять в докере, есть небольшая панель управления, основное управление осуществляется через REST API.

Это далеко не полный список и есть еще много других под разные стеки технологий!

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

Мы в качестве решения взяли mockoon, из-за его особенностей он подходит под наши потребности. У него достаточно хорошая документация и мощный функционал.

Это бесплатное opensource кроссплатформенное приложение с графическим интерфейсом, есть версии для Linux, Windows и MacOS.

Наша инфраструктура позволяет перенаправлять запросы с тестового контура на внутренние ip-адреса сотрудников, что упрощает развертывание mock-сервера. Поднял локально, сделал перенаправление с тестируемого приложения на свой IP и выбранный порт, и можно работать!

Либо можно подготовить коллекцию и поднять mockoon в докере на удаленной машине:

$ docker run -d --mount type=bind,source=/data-file.json,target=/data,readonly 
             -p 3000:3000 mockoon/cli:latest 
             -d data -p 3000/

Есть возможность сохранять коллекции шаблонов в json-файле, причем в виде, адаптированном под git, т.е. каждое ключ-значение на отдельной строке, а не сплошным месивом. Это позволяет держать коллекции для mock-сервера в репозитории проекта, обновлять его по мере разработки и использования разных частей внешнего API.

Так же это позволяет на этапе разработки подготовить шаблоны запросов, которыми уже будет пользоваться тестировщик при прогоне разных сценариев.

Для подготовки шаблонов есть возможность импортировать файл с OpenAPI Specification или настроить обратный прокси и создать шаблоны на основе полученных логов запросов, сервер работает таким образом, что сначала ищет варианты ответа среди созданных шаблонов, а если не нашел, то уже идет реальный запрос к стороннему API.

В принципе, можно в рамках одной коллекции настроить отображение разных сценариев, есть возможность создавать последовательности ответов, динамический шаблон ответа, настраивать условия в зависимости от параметров.

Заключение

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

Но надо сказать, что у данной технологии есть и недостатки. Шаблоны могут недостаточно полно имитировать поведение реальной системы. Поэтому вы можете не найти некоторые ошибки, которые возникают при реальном использовании системы.

А неправильно настроенные шаблоны могут выдавать ложные результаты и, соответственно, приведут к ошибкам в процессе разработки.

Несмотря на недостатки, это быстрый и дешевый метод протестировать различные сценарии поведения вашей системы, а на этапе разработки подготовить коллекции и поделиться с командой и тем самым снизить потенциальные временные затраты на поддержку зависимости от внешнего сервиса.

Сладость или гадость? Или жуткая и правдивая SQL-история

2024-10-30T12:49:06.170Z

Сегодня мы расскажем вам о проблеме Хэллоуина. Но для начала у меня для вас плохая новость: в этой истории нет ни призраков, ни зомби, ни даже вампиров.
Но сегодня Хэллоуин, так что мне показалось подходящим временем поднять эту тему после прочтения этой статьи. К тому же для тех, кто работает с реляционными базами данных, эта история не менее жуткая, потому как она о том, как простая SQL операция может преследовать вашу базу данных весьма неожиданным образом.

Итак, давайте поговорим о «проблеме Хэллоуина» и выясним, действительно ли она так страшна. Или всё-таки нет?

Но для начала отмотаем на пару десятков лет назад.

Почему она так называется?

Это был обычный день в темной и жуткой комнате в 1975 году, когда группа инженеров обнаружила проблему с базой данных, выполняя довольно тривиальную задачу. Звали их Доном Чемберлином, Патрицией Сэлинджер и Мортоном Астраханом.

Они создали запрос в базе данных, предназначенный для увеличения зарплаты каждого сотрудника, зарабатывающего менее 25 000 долларов, на 10 процентов.

На первый взгляд, изменения в базе данных работали и не выдавали никаких ошибок. Но всё оказалось не так просто. Запрос не просто обновил зарплату на 10 процентов - он продолжал циклически просматривать базу данных, постоянно увеличивая каждую зарплату на 10 процентов, пока все не стали зарабатывать 25 000 долларов в год.

А произошел данный инцидент в пятницу 31 октября. Поэтому было решено увековечить его проблемой Хэллоуина.

Что такое «проблема Хэллоуина»?

Так что же пошло не так? Давайте разбираться. Для этого предлагаю использовать тот же пример, что рассматривали Сэлинджер и Астрахан, когда обнаружили неладное.

Представьте, что у нас есть таблица сотрудников и зарплат, в которой первые несколько строк выглядят примерно так:

Нам нужно обновить таблицу так, чтобы предоставить 10%-ную надбавку тем, кто зарабатывает менее 25 000 долларов в год. Да это же элементарно, подумаете вы и, скорее всего, набросаете вот такой sql запрос:

UPDATE employee SET salary = salary * 1.1 WHERE salary < 25000;

Мы ожидаем, что результатом этого запроса будет обновленная таблица, в которой зарплата Владимира не изменится, но зарплата Сергея обновится до 19360 долларов, а зарплата Александра обновится до 13530 долларов и т.д.

Однако, если наш запрос обрабатывается с использованием некластеризованного индекса, зарплаты могут обновляться постоянно, пока не достигнут 25000 долларов.

Но как такое возможно? Представьте, что это наш некластеризованный индекс, отсортированный по возрастанию по значениям в столбце «Зарплата»:

Если наш запрос будет выполняться итеративно с использованием этого индекса, то сначала будет просмотрена строка для Александра. Поскольку это значение ниже 25000, оно будет обновлено - согласно нашему запросу умножено на 1,1, так что новое значение составит 13530. Обновление этой строки также обновит индекс:

Поскольку запрос выполняется итеративно, следующим шагом будет обновление строки Сергея, но мы уже видим здесь проблему: наше обновление строки Александра также изменило ее положение в индексе. И поскольку его значение все еще меньше 25000, обновление будет применено к нему снова, когда сканирование индекса достигнет этой точки в индексе.

Строки с зарплатами Сергея и Александра будут постоянно обгонять друг друга в индексе, оставаясь на шаг впереди сканирования индекса, пока оба значения не перейдут отметку 25000.

Подведем итог:

Проблема Хэллоуина описывает явление, при котором запросы INSERT, UPDATE, DELETE и MERGE в SQL при определенных обстоятельствах могут привести к тому, что строки обновляются несколько раз во время операции, хотя должны обновляться только один раз. Или, возможно, даже обновляться в бесконечном цикле. Вот это поистине страшно!

Как победить проблему Хэллоуина?

Оговоримся сразу, что в PostgreSQL этой проблемы нет. Проблема Хэллоуина - это ошибка в проектировании базы данных, и любая база данных с такой проблемой не надежна. Однако, некоторые СУБД по-прежнему имеют потенциал для возникновения подобных проблем.

Так как мы в примере говорили о том, как проблема Хэллоуина применяется к UPDATE запросам, то и решение будет описано конкретно для этого случая.

Одним из простых решений проблемы является физическое разделение курсоров чтения и записи в запросе с UPDATE с помощью оператора блокировки. Например, это может быть как активная буферизация, так и сортировка. Вставка оператора блокировки в середину плана UPDATE гарантирует, что курсор чтения отработает полностью и получит все нужные строки прежде, чем курсор записи начнет изменять соответствующие строки. К сожалению, вставка оператора блокировки в такой план запроса потребует получения всех строк из курсора чтения, а это обычно обходится довольно дорого. К счастью, во многих случаях SQL Server может определить, что курсор записи не влияет на курсор чтения и не станет добавлять оператор блокировки.

Почему проблема Хэллоуина – это головная боль, даже если она не особенно страшная?

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

Если вы хотите вникнуть в суть этой концепции, я рекомендую серию из четырех прекрасных статей Уайта. В цикле статей Пол Уайт объяснил многочисленные нюансы этой проблемы, а также трудности, которые она создает с точки зрения производительности при выполнении запросов к базе данных SQL без случайного изменения данных.