buffalo

module

v0.5.0 Latest Latest Go to latest Published: Jan 17, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/massonsky/buffalo

Links

Open Source Insights

README ¶

🦬 Buffalo

Кроссплатформенный мультиязычный сборщик protobuf/gRPC файлов

📊 Статус разработки

Текущая версия: v0.5.0 - Полнофункциональный CLI & Все компиляторы

✅ Завершено (v0.1.0 - v0.5.0):

Инфраструктура (v0.1.0):

pkg/logger - Система логирования с цветным выводом
pkg/errors - Обработка ошибок с контекстом
pkg/utils - Файловые утилиты и валидация
pkg/metrics - Система метрик

CLI & Конфигурация (v0.2.0):

internal/cli - CLI интерфейс с Cobra (14 команд)
internal/config - Конфигурация с Viper (YAML/TOML/JSON)
internal/version - Версионирование с git tags

Core Builder (v0.3.0):

internal/builder - Основной билдер
internal/scanner - Сканер proto файлов
internal/resolver - Разрешение зависимостей
internal/scheduler - Планировщик сборки
internal/cache - Кэширование для инкрементальной сборки

Компиляторы (v0.4.0 - v0.5.0):

internal/compiler/python - Python (protobuf + grpcio)
internal/compiler/golang - Go (protoc-gen-go + grpc)
internal/compiler/rust - Rust (prost + tonic)
internal/compiler/cpp - C++ (protobuf + grpc++)

CLI Команды (v0.5.0):

build - Сборка proto файлов
rebuild - Полная пересборка с очисткой кэша
watch - Автоматическая пересборка при изменениях
init - Инициализация проекта
check - Проверка конфигурации и зависимостей
list - Список proto файлов
stats - Статистика проекта
clear - Очистка кэша и сгенерированных файлов
lint - Проверка стиля proto файлов
format - Форматирование proto файлов
validate - Валидация синтаксиса через protoc
deps - Анализ зависимостей
version - Информация о версии
completion - Автодополнение для shell

🚧 В разработке (v0.6.0):

Система плагинов
Пользовательские шаблоны генерации
Расширенное кэширование

📋 Запланировано:

v0.7.0: CI/CD интеграция, GitHub Actions
v0.8.0: Расширенный watch mode с hot-reload
v0.9.0: Метрики и профилирование
v1.0.0: Стабильный релиз

✨ Особенности

🌍 Мультиязычность: Python, Go, Rust, C++ ✅
⚡ Высокая производительность: Параллельная компиляция ✅, инкрементальная сборка ✅
🔧 Гибкая настройка: Конфигурация через YAML/TOML/JSON ✅
🔌 Расширяемость: Система плагинов (v0.6.0)
📦 Кроссплатформенность: Windows, Linux, macOS ✅
🎯 Простота использования: 14 CLI команд ✅
🚀 Watch mode: Автоматическая пересборка ✅
💾 Кэширование: Умное кэширование ✅
📊 Метрики: Система метрик ✅
🐳 Docker ready: Docker + docker-compose ✅

🏗️ Текущая архитектура (v0.1.0)

Реализованные компоненты

pkg/logger

Полнофункциональная система логирования:

// Создание logger с цветным форматированием
log := logger.New(
    logger.WithFormatter(logger.NewColoredFormatter()),
    logger.WithLevel(logger.DEBUG),
)

// Structured logging
log.WithFields(logger.Fields{
    "user": "john",
    "action": "login",
}).Info("User logged in")

Возможности:

3 форматтера: JSON, Text, Colored (ANSI цвета)
2 типа вывода: Console (stdout/stderr), File (с ротацией)
Уровни: DEBUG, INFO, WARN, ERROR, FATAL
Поддержка Fields для structured logging

pkg/errors

Расширенная обработка ошибок:

// Создание ошибки с кодом
err := errors.New(errors.ErrInvalidInput, "неверный формат файла")

// Wrap существующей ошибки
wrapped := errors.Wrap(err, errors.ErrIO, "не удалось прочитать файл")

// Добавление контекста
wrapped.WithContext("file", "example.proto")

// 26 предопределённых кодов ошибок

pkg/utils

Набор утилит для работы с файлами, путями, хешированием:

// Поиск proto файлов
files, _ := utils.FindFiles("./protos", "*.proto", true)

// Валидация proto файла
result := utils.ValidateProtoFile("example.proto")

// Хеширование
hash, _ := utils.HashFile("example.proto") // SHA256 по умолчанию

// Параллельное выполнение
pool := utils.NewWorkerPool(4)
pool.Execute(tasks)

pkg/metrics

Система сбора метрик:

// Создание collector
collector := metrics.NewCollector()

// Counter для подсчёта
counter := collector.Counter("builds_total")
counter.Inc()

// Gauge для текущего значения
gauge := collector.Gauge("active_workers")
gauge.Set(10)

// Histogram для распределения значений
hist := collector.Histogram("build_duration_ms", nil)
hist.Observe(245.5)

// Экспорт в Prometheus
exporter := metrics.NewExporter(collector)
exporter.Export(metrics.FormatPrometheus, os.Stdout)

Возможности:

3 типа метрик: Counter, Gauge, Histogram
Thread-safe с атомарными операциями
Экспорт: Text, JSON, Prometheus
Глобальные labels
Snapshots для точки во времени

🚀 Быстрый старт

Установка

Способ 1: Автоматический скрипт (рекомендуется)

Linux/macOS:

curl -sSL https://raw.githubusercontent.com/massonsky/buffalo/dev/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/massonsky/buffalo/dev/install.ps1 | iex

Способ 2: Из исходников

git clone https://github.com/massonsky/buffalo.git
cd buffalo

# Linux/macOS
./build.sh install

# Windows
.\build.ps1 -Target install

Способ 3: Docker

docker build -t buffalo:latest .
docker run --rm -v $(pwd):/workspace buffalo:latest build

Способ 4: Через Go

go install github.com/massonsky/buffalo/cmd/buffalo@latest

Сборка и разработка

Linux/macOS

# Быстрая сборка
./build.sh build

# Все платформы
./build.sh build-all

# Тесты
./build.sh test

# С покрытием
./build.sh test-coverage

# Проверка кода (fmt, vet, lint, test)
./build.sh check

# Установка в систему
./build.sh install

# Очистка
./build.sh clean

# Справка
./build.sh help

Windows (PowerShell)

# Быстрая сборка
.\build.ps1 build

# Все платформы
.\build.ps1 build-all

# Тесты
.\build.ps1 test

# С покрытием
.\build.ps1 test-coverage

# Проверка кода
.\build.ps1 check

# Установка
.\build.ps1 install

# Очистка
.\build.ps1 clean

# Справка
.\build.ps1 help

Через Make (Unix/Linux/macOS)

# Сборка
make build

# Установка в систему
sudo make install-system

# Тесты
make test

# Покрытие
make coverage

# Docker
make docker-build

# Релиз
make release

# Справка
make help

Через CMake (альтернатива)

# Сборка
cmake -B build
cmake --build build --target build

# Установка
cmake --build build --target install

# Тесты
cmake --build build --target test

📖 Использование (планируется v0.2.0+)

Примечание: CLI команды ниже будут доступны в v0.2.0. Сейчас (v0.1.0) доступна только базовая инфраструктура.

Базовая команда

buffalo build

С конфигурационным файлом

buffalo build --config buffalo.yaml

Выбор языков

buffalo build --lang python,go,rust

Watch mode

buffalo watch

Dry run

buffalo build --dry-run

⚙️ Конфигурация

buffalo.yaml

version: 1.0

global:
  proto_path:
    - ./proto
  output_path: ./generated
  import_paths:
    - ./third_party/proto
  parallel: 4
  incremental: true

languages:
  python:
    enabled: true
    output: ./generated/python
    plugins:
      - grpc
    options:
      mypy_stubs: true
  
  go:
    enabled: true
    output: ./generated/go
    go_package_prefix: github.com/yourorg/project
    plugins:
      - grpc
  
  rust:
    enabled: true
    output: ./generated/rust
    plugins:
      - tonic
  
  cpp:
    enabled: true
    output: ./generated/cpp
    plugins:
      - grpc
    options:
      std: c++17

logging:
  level: info
  format: colored
  output: stdout

Больше примеров в docs/CONFIGURATION.md

🎯 Примеры

Python с gRPC

# Генерация Python кода с gRPC
buffalo build --lang python

# Использование сгенерированного кода
python -c "
from generated.python import service_pb2, service_pb2_grpc
# ... ваш код
"

Go с модулями

# Генерация Go кода
buffalo build --lang go

# Использование в Go проекте
go get github.com/yourorg/project/generated/go

Rust с Tonic

# Генерация Rust кода
buffalo build --lang rust

# Добавить в Cargo.toml
# [dependencies]
# generated = { path = "./generated/rust" }

C++ с CMake

# Генерация C++ кода
buffalo build --lang cpp

# CMakeLists.txt автоматически создан
mkdir build && cd build
cmake .. && make

Больше примеров в examples/

🏗️ Архитектура

┌─────────────┐
│     CLI     │  Интерфейс командной строки
└──────┬──────┘
       │
┌──────▼──────────────────────┐
│  Build Orchestrator         │  Координация процесса
└──────┬──────────────────────┘
       │
       ├──────────────┬──────────────┬──────────────┐
       ▼              ▼              ▼              ▼
┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│ Scanner  │   │ Resolver │   │Scheduler │   │  Cache   │
└──────────┘   └──────────┘   └──────────┘   └──────────┘
       │
       ├──────────────┬──────────────┬──────────────┐
       ▼              ▼              ▼              ▼
┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│  Python  │   │    Go    │   │   Rust   │   │   C++    │
│Compiler  │   │Compiler  │   │Compiler  │   │Compiler  │
└──────────┘   └──────────┘   └──────────┘   └──────────┘

Подробнее в docs/ARCHITECTURE.md

📚 Документация

📋 Roadmap - План развития проекта
🏛️ Архитектура - Детальная архитектура
📁 Структура проекта - Организация кода
🛠️ Руководство по разработке - Для контрибьюторов
⚙️ Конфигурация - Настройка Buffalo
📖 CLI Reference - Справка по командам
🔌 Разработка плагинов - Создание плагинов
🚀 Deployment - Развертывание
🔧 Troubleshooting - Решение проблем

🎓 Туториалы

🤝 Участие в разработке

Мы приветствуем вклад в проект! Прочитайте CONTRIBUTING.md для деталей.

Процесс:

Fork репозитория
Создайте feature branch (git checkout -b feature/amazing-feature)
Commit изменений (git commit -m 'feat: add amazing feature')
Push в branch (git push origin feature/amazing-feature)
Откройте Pull Request

Для разработчиков:

# Клонирование
git clone https://github.com/yourorg/buffalo.git
cd buffalo

# Установка зависимостей
make install-tools

# Запуск тестов
make test

# Сборка
make build

Подробнее в docs/DEVELOPMENT.md

🧪 Тестирование

# Все тесты
make test

# Unit тесты
make test-unit

# Integration тесты
make test-integration

# Coverage
make test-coverage

# Бенчмарки
make benchmark

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

📊 Производительность

Buffalo оптимизирован для производительности:

⚡ Параллельная компиляция
💾 Умное кэширование
🎯 Инкрементальная сборка
📦 Минимальное использование памяти

Бенчмарки:

100 proto файлов: ~5 секунд
Memory usage: ~50MB
Binary size: ~15MB

🐳 Docker

# Скачать образ
docker pull buffalo/buffalo:latest

# Запустить
docker run -v $(pwd):/workspace buffalo/buffalo build

# Docker Compose
docker-compose up

Docker образы доступны на:

🔌 Плагины

Buffalo поддерживает систему плагинов для расширения функциональности:

Официальные плагины:

buffalo-lint - Линтинг proto файлов
buffalo-validate - Валидация proto схем
buffalo-docs - Генерация документации
buffalo-typescript - TypeScript поддержка

Кастомные плагины:

package main

import "github.com/yourorg/buffalo/pkg/plugin"

type MyPlugin struct{}

func (p *MyPlugin) Execute(ctx context.Context, data *plugin.Data) error {
    // Ваша логика
    return nil
}

func main() {
    plugin.Register("my-plugin", &MyPlugin{})
}

Подробнее в docs/PLUGIN_DEVELOPMENT.md

🌟 Используется в проектах

Project A - Микросервисная архитектура
Project B - gRPC API gateway
Project C - Real-time платформа

📈 Roadmap

v1.0.0 (Current)

✅ Поддержка Python, Go, Rust, C++
✅ Параллельная сборка
✅ Инкрементальная сборка
✅ Система плагинов
✅ Watch mode

v1.1.0 (Planning)

🔄 TypeScript/JavaScript поддержка
🔄 Java/Kotlin поддержка
🔄 Remote cache
🔄 Web UI

v2.0.0 (Future)

📋 GraphQL поддержка
📋 Distributed builds
📋 Cloud integration

Полный roadmap в docs/ROADMAP.md

📄 Лицензия

Этот проект лицензирован под MIT License - см. LICENSE для деталей.

👥 Авторы

Your Name - Initial work - @yourname

См. также список contributors.

🙏 Благодарности

Protocol Buffers team
gRPC team
Go community
Все контрибьюторы

💬 Поддержка

📫 Email: buffalo@yourorg.com
💬 Discord: Join our Discord
🐛 Issues: GitHub Issues
💡 Discussions: GitHub Discussions

⭐ Star History

Made with ❤️ by the Buffalo team

GitHub • Website • Documentation • Twitter

Directories ¶

Path	Synopsis
cmd
buffalo command
internal
builder
cli
compiler Package compiler defines the common interface for language-specific compilers.	Package compiler defines the common interface for language-specific compilers.
compiler/cpp
compiler/golang
compiler/python Package python implements the Python protobuf compiler.	Package python implements the Python protobuf compiler.
compiler/rust
config
version Package version provides version information for Buffalo.	Package version provides version information for Buffalo.
versioning
pkg
errors Package errors provides enhanced error handling with codes, stack traces, and context.	Package errors provides enhanced error handling with codes, stack traces, and context.
logger Package logger provides a flexible, structured logging system for Buffalo.	Package logger provides a flexible, structured logging system for Buffalo.
metrics
utils

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL