buffalo

module

v0.1.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.1.0 - Базовая инфраструктура

✅ Завершено:

pkg/logger - Система логирования (54.7% coverage, 16 tests)
pkg/errors - Обработка ошибок (92.2% coverage, 20 tests)
pkg/utils - Утилиты (67.3% coverage, 46 tests)
pkg/metrics - Метрики (90.9% coverage, 20 tests)

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

CLI интерфейс с Cobra
Система конфигурации с Viper
Базовая структура builder

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

v0.3.0: Core builder реализация
v0.4.0-v0.7.0: Компиляторы Python/Go/Rust/C++
v0.8.0: Система плагинов
v0.9.0-v1.0.0: Watch mode, инкрементальная сборка, кэширование

См. ROADMAP.md для деталей.

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

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

🏗️ Текущая архитектура (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 для точки во времени

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

Сборка из исходников

# Клонирование репозитория
git clone git@github.com:massonsky/buffalo.git
cd buffalo

# Сборка
make build

# Запуск
./bin/buffalo --version

# Тесты
make test

# Coverage
make coverage

Разработка

# Линтеры
make lint

# Форматирование
make fmt

# Сборка для всех платформ
make cross-compile

# Очистка
make clean

📖 Использование (планируется 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
version Package version provides version information for Buffalo.	Package version provides version information for Buffalo.
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