buffalo

🦬 Buffalo - Multi-Language Protobuf/gRPC Build System

Buffalo — это мощная кросс-платформенная система сборки для protobuf/gRPC проектов с поддержкой множества языков программирования. Интеллектуальное кэширование, параллельная компиляция и инкрементальные сборки делают Buffalo идеальным выбором для современных микросервисных архитектур.

---

✨ Основные возможности

🚀 Поддержка множества языков

• Python - полная поддержка protobuf и gRPC
• Go - нативная интеграция с Go toolchain
• Rust - современная кодогенерация с Tonic
• C++ - оптимизированная компиляция

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

• Интеллектуальное кэширование - пересборка только измененных файлов
• Параллельная компиляция - максимальное использование CPU
• Инкрементальные сборки - минимальное время сборки

🎯 Гибкость

• Система плагинов - расширение функциональности
• Гибкая конфигурация - YAML/TOML/JSON + environment variables
• Шаблонизация - кастомизация генерируемого кода
• Dependency management - автоматическое управление зависимостями

🔧 Продвинутые функции

• Workspace management - управление монорепозиториями
• Граф зависимостей - визуализация и анализ
• Permissions/RBAC - генерация кода авторизации
• Auto-upgrade - автоматическое обновление

---

📦 Установка

Быстрая установка

Linux/macOS

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

Windows (PowerShell)

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

Проверка установки

buffalo --version

Альтернативные способы

С помощью Go

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

Из исходников

git clone https://github.com/massonsky/buffalo.git
cd buffalo
make install
``

---

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

### 1. Инициализация проекта

```bash
# Создать новый проект Buffalo
buffalo init myproject
cd myproject

Это создаст структуру:

myproject/
├── buffalo.yaml          # Конфигурация
├── protos/              # .proto файлы
│   └── service.proto
└── generated/           # Сгенерированный код (создается автоматически)

2. Создание proto файла

// protos/service.proto
syntax = "proto3";

package myservice;

service Greeter {
  rpc SayHello (HelloRequest) returns (HelloReply) {}
}

message HelloRequest {
  string name = 1;
}

message HelloReply {
  string message = 1;
}

3. Конфигурация buffalo.yaml

version: "1.0"

project:
  name: myproject
  proto_root: protos
  output_root: generated

languages:
  python:
    enabled: true
    output: generated/python
    plugins:
      - grpc
  
  go:
    enabled: true
    output: generated/go
    module: github.com/myorg/myproject
    plugins:
      - grpc

4. Сборка

# Собрать все языки
buffalo build

# Собрать конкретный язык
buffalo build --lang python

# Watch mode - автоматическая пересборка
buffalo watch

# Параллельная сборка с 8 воркерами
buffalo build --jobs 8

---

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

Python проект

# buffalo.yaml
version: "1.0"

project:
  name: python-service
  proto_root: protos
  output_root: generated

languages:
  python:
    enabled: true
    output: generated/python
    plugins:
      - grpc
      - mypy
    options:
      mypy_enabled: true

buffalo build --lang python
cd generated/python
python -m pip install -e .

Go проект

# buffalo.yaml
version: "1.0"

project:
  name: go-service
  proto_root: protos
  output_root: generated

languages:
  go:
    enabled: true
    output: generated/go
    module: github.com/myorg/go-service
    plugins:
      - grpc
      - grpc-gateway
      - validate

buffalo build --lang go
cd generated/go
go mod tidy
go build ./...

Мультиязычный проект

# buffalo.yaml
version: "1.0"

project:
  name: polyglot-service
  proto_root: protos
  output_root: generated

languages:
  python:
    enabled: true
    output: generated/python
  
  go:
    enabled: true
    output: generated/go
    module: github.com/myorg/polyglot
  
  rust:
    enabled: true
    output: generated/rust
    crate: polyglot_service
  
  cpp:
    enabled: true
    output: generated/cpp

# Собрать все языки параллельно
buffalo build --jobs 4

# Использовать watch mode для всех языков
buffalo watch

---

🔧 Основные команды

Сборка и компиляция

buffalo build                    # Собрать все включенные языки
buffalo build --lang python      # Собрать только Python
buffalo build --jobs 8           # Использовать 8 воркеров
buffalo build --no-cache         # Пересобрать все без кэша
buffalo rebuild                  # Полная пересборка (очистка + сборка)

Разработка

buffalo watch                    # Автоматическая пересборка при изменениях
buffalo watch --lang go          # Watch для конкретного языка
buffalo check                    # Проверка готовности проекта к сборке
buffalo check -v                 # Детальная проверка с выводом всех компонентов
buffalo validate                 # Валидация proto файлов
buffalo doctor                   # Диагностика окружения (все языки)
buffalo doctor --config-only     # Проверка только включенных языков

Управление проектом

buffalo init myproject           # Создать новый проект
buffalo deps install             # Установить зависимости
buffalo deps update              # Обновить зависимости
buffalo list                     # Показать доступные языки и плагины

Кэш и очистка

buffalo clear cache              # Очистить кэш
buffalo clear generated          # Удалить сгенерированные файлы
buffalo clear all                # Очистить всё

Метрики и диагностика

buffalo metrics                  # Показать метрики сборки
buffalo stats                    # Статистика проекта
buffalo doctor                   # Диагностика окружения
buffalo diff                     # Показать изменения proto файлов

Плагины и шаблоны

buffalo plugin list              # Список доступных плагинов
buffalo plugin install <name>    # Установить плагин
buffalo template list            # Список шаблонов
buffalo template generate        # Генерация из шаблона

---

�️ Установка языковых инструментов (buffalo tools)

Buffalo требует различные инструменты для генерации кода в зависимости от целевых языков. Команда buffalo tools позволяет легко устанавливать и проверять эти инструменты.

Проверка инструментов

# Проверить статус всех инструментов
buffalo tools check

# Проверить инструменты для конкретных языков
buffalo tools check go python

# Проверить только языки из конфигурации
buffalo tools check

Пример вывода:

📋 Tool Installation Status
═══════════════════════════════════════════════════

Core Tools:
──────────────────────────────────────────────────
  ✅ protoc * - libprotoc 3.21.12

Go:
──────────────────────────────────────────────────
  ✅ go * - go version go1.24.0 linux/amd64
  ❌ protoc-gen-go *
     Install: go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
  ❌ protoc-gen-go-grpc *
     Install: go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest

Python:
──────────────────────────────────────────────────
  ✅ python3 * - Python 3.12.3
  ✅ pip * - pip 24.0
  ❌ grpcio-tools *
     Install: pip3 install grpcio-tools

❌ Some critical tools are missing!
   Run 'buffalo tools install' to install them.

Установка инструментов

# Установить все необходимые инструменты для включенных языков
buffalo tools install

# Установить инструменты для конкретных языков
buffalo tools install go python

# Установить все инструменты (включая опциональные)
buffalo tools install --all

# Принудительная переустановка
buffalo tools install --force

# Посмотреть что будет установлено (без установки)
buffalo tools install --dry-run

# Интерактивный режим (подтверждение для каждого)
buffalo tools install --interactive

Список доступных инструментов

# Показать все доступные инструменты
buffalo tools list

# Показать инструменты для конкретного языка
buffalo tools list go

# Включить опциональные инструменты
buffalo tools list --all

Пример вывода:

📦 Available Tools for Protobuf/gRPC Development
═══════════════════════════════════════════════════

Core (Required):
────────────────────────────────────────────────────────────
  ✅ protoc * (libprotoc 3.21.12)
     Protocol Buffers Compiler

Go:
────────────────────────────────────────────────────────────
  ✅ go * (go version go1.24.0)
     Go Programming Language
  ❌ protoc-gen-go *
     Go Protocol Buffers Generator
     Install: go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
  ❌ protoc-gen-go-grpc *
     Go gRPC Generator
     Install: go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
  ❌ protoc-gen-grpc-gateway
     gRPC-Gateway Generator (REST API proxy)
     Install: go install github.com/grpc-ecosystem/grpc-gateway/v2/protoc-gen-grpc-gateway@latest

Поддерживаемые инструменты

Язык	Инструмент	Описание	Критичный
Core	protoc	Protocol Buffers Compiler	✅
Go	go	Go Language	✅
Go	protoc-gen-go	Go Protobuf Generator	✅
Go	protoc-gen-go-grpc	Go gRPC Generator	✅
Go	protoc-gen-grpc-gateway	REST API Gateway	❌
Go	protoc-gen-openapiv2	OpenAPI Generator	❌
Go	protoc-gen-validate	Validation Generator	❌
Python	python3	Python Language	✅
Python	pip	Package Installer	✅
Python	grpcio-tools	Python gRPC Tools	✅
Python	grpcio	gRPC Runtime	✅
Python	protobuf	Protobuf Library	✅
Python	mypy-protobuf	Type Stubs	❌
Rust	rustc	Rust Compiler	✅
Rust	cargo	Package Manager	✅
Rust	protobuf-codegen	Code Generator	✅
C++	g++	C++ Compiler	✅
C++	cmake	Build System	✅
C++	libprotobuf-dev	Protobuf Dev Files	✅
C++	grpc-dev	gRPC Dev Files	✅

---

�📊 Граф зависимостей (buffalo graph)

Визуализация и анализ зависимостей между proto файлами.

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

# Показать дерево зависимостей в терминале
buffalo graph

# Экспорт в Graphviz DOT формат
buffalo graph --format dot --output deps.dot

# Экспорт в Mermaid для README
buffalo graph --format mermaid --output deps.md

# Экспорт в JSON
buffalo graph --format json --output deps.json

# Экспорт в PlantUML
buffalo graph --format plantuml --output deps.puml

Уровни анализа

# Зависимости на уровне файлов (по умолчанию)
buffalo graph --scope file

# Зависимости на уровне пакетов
buffalo graph --scope package

# Связи между сообщениями
buffalo graph --scope message

# Связи между сервисами
buffalo graph --scope service

# Полный анализ
buffalo graph --scope full

Анализ конкретного файла

# Анализ одного proto файла
buffalo graph --file protos/user.proto

Расширенный анализ

# Обнаружение циклических зависимостей
buffalo graph analyze --cycles

# Поиск orphan файлов (не импортируются никем)
buffalo graph analyze --orphans

# Анализ связности (coupling metrics)
buffalo graph analyze --coupling

# Поиск "hub" файлов (много входящих зависимостей)
buffalo graph analyze --hubs

# Полный анализ
buffalo graph analyze --all

Статистика графа

# Показать статистику
buffalo graph --stats

# Или через подкоманду
buffalo graph stats

Пример вывода:

📊 Dependency Graph Statistics
════════════════════════════════════════
Total files:        42
Total dependencies: 156
Average deps/file:  3.7
Max dependencies:   12 (common/types.proto)
Orphan files:       2
Circular deps:      0

Top 5 most imported:
  1. common/types.proto     (23 imports)
  2. common/errors.proto    (18 imports)
  3. auth/auth.proto        (12 imports)
  4. user/user.proto        (8 imports)
  5. api/common.proto       (7 imports)

---

🔄 Автообновление (buffalo upgrade)

Автоматическое обновление Buffalo с миграцией конфигурации.

Проверка обновлений

# Проверить доступные обновления
buffalo upgrade --check

Пример вывода:

🔍 Checking for updates...

Current version: 1.4.0
Latest version:  1.5.0

📋 Changelog:
  • Added workspace management
  • Added permissions module
  • Improved graph visualization
  • Bug fixes and performance improvements

Run 'buffalo upgrade' to update.

Обновление

# Обновить до последней версии
buffalo upgrade

# Обновить до конкретной версии
buffalo upgrade --to 1.5.0

# Пропустить подтверждение
buffalo upgrade --force

# Показать что изменится (без применения)
buffalo upgrade --dry-run

Опции миграции

# Только обновить бинарник, без миграции конфигов
buffalo upgrade --skip-config

# Только мигрировать конфиги, без обновления бинарника
buffalo upgrade --skip-binary

# Отключить создание резервной копии
buffalo upgrade --backup=false

Откат

# Откатиться к предыдущей версии
buffalo upgrade --rollback

Просмотр изменений

# Показать changelog между версиями
buffalo upgrade --changelog

---

🏢 Workspace Management (buffalo workspace)

Управление монорепозиториями с множеством proto проектов.

Инициализация workspace

# Создать workspace с автоматическим обнаружением проектов
buffalo workspace init --discover

# Создать workspace с именем
buffalo workspace init --name "my-monorepo"

# Создать workspace в конкретной директории
buffalo workspace init --dir /path/to/monorepo

Конфигурация buffalo-workspace.yaml

workspace:
  name: my-monorepo
  description: "Multi-service protobuf monorepo"
  version: "1.0"

projects:
  - name: user-service
    path: services/user
    tags: [backend, core]
    depends_on: [common]

  - name: order-service
    path: services/order
    tags: [backend, commerce]
    depends_on: [common, user-service]

  - name: common
    path: libs/common
    tags: [library, shared]

  - name: api-gateway
    path: services/gateway
    tags: [frontend, api]
    depends_on: [user-service, order-service]

policies:
  consistent_versions: true
  shared_dependencies: true
  no_circular_deps: true

Сборка проектов

# Собрать все проекты (в правильном порядке зависимостей)
buffalo workspace build

# Собрать конкретные проекты
buffalo workspace build user-service order-service

# Собрать проекты с определенным тегом
buffalo workspace build --tag backend

# Параллельная сборка
buffalo workspace build --parallel 4

# Принудительная пересборка
buffalo workspace build --force

# Показать что будет собрано (dry run)
buffalo workspace build --dry-run

Список проектов

# Показать все проекты
buffalo workspace list

# Фильтр по тегу
buffalo workspace list --tag backend

# Вывод в JSON
buffalo workspace list --format json

Пример вывода:

NAME                 PATH                         BUILD                TAGS
────────────────────────────────────────────────────────────────────────────────
common               libs/common                  make build           library, shared
user-service         services/user                make build           backend, core
order-service        services/order               make build           backend, commerce
api-gateway          services/gateway             make build           frontend, api

Total: 4 projects

Граф зависимостей проектов

# ASCII граф
buffalo workspace graph

# Graphviz DOT формат
buffalo workspace graph --format dot

# Mermaid формат
buffalo workspace graph --format mermaid

Пример ASCII вывода:

Project Dependencies:

  common (no dependencies)
  user-service
    └── common
  order-service
    ├── common
    └── user-service
  api-gateway
    ├── user-service
    └── order-service

Affected проекты

Определение проектов, затронутых изменениями:

# Показать затронутые проекты с последнего коммита
buffalo workspace affected

# С конкретной точки отсчета
buffalo workspace affected --since HEAD~5

Пример вывода:

Affected projects (2):
  • user-service
  • order-service

Changed files (3):
  - services/user/protos/user.proto
  - services/user/protos/profile.proto
  - libs/common/types.proto

Выполнение команд во всех проектах

# Запустить команду во всех проектах
buffalo workspace exec -- go mod tidy

# Только в проектах с тегом
buffalo workspace exec --tag backend -- make test

# Продолжить при ошибке
buffalo workspace exec --continue-on-error -- make lint

Валидация workspace

buffalo workspace validate

---

🔐 Permissions Management (buffalo permissions)

Управление RBAC/ABAC аннотациями в proto файлах.

Аннотации в proto файлах

syntax = "proto3";

package users;

import "buffalo/permissions.proto";

option (buffalo.permissions.resource) = "users";

service UserService {
  // Публичный эндпоинт
  rpc GetPublicProfile (GetProfileRequest) returns (Profile) {
    option (buffalo.permissions) = {
      action: "users:read_public"
      public: true
      rate_limit: { requests: 100, window: "1m" }
    };
  }
  
  // Требует аутентификации
  rpc GetUser (GetUserRequest) returns (User) {
    option (buffalo.permissions) = {
      action: "users:read"
      roles: ["admin", "user"]
      scopes: ["users:read"]
      allow_self: true
      conditions: [
        { field: "user_id", operator: "eq", source: "auth.user_id" }
      ]
    };
  }
  
  // Требует MFA для админов
  rpc DeleteUser (DeleteUserRequest) returns (Empty) {
    option (buffalo.permissions) = {
      action: "users:delete"
      roles: ["admin"]
      require_mfa: true
      audit_log: true
    };
  }
}

Генерация кода

# Генерация Go кода
buffalo permissions generate --framework go --output pkg/permissions/permissions.go

# Генерация Casbin политик
buffalo permissions generate --framework casbin --output config/policy.csv

# Генерация OPA политик
buffalo permissions generate --framework opa --output policies/authz.rego

# С константами для actions/roles/scopes
buffalo permissions generate --framework go --constants --output permissions.go

Пример сгенерированного Go кода:

// Code generated by Buffalo. DO NOT EDIT.
package permissions

var Permissions = map[string]Permission{
    "users.UserService.GetPublicProfile": {
        Action:  "users:read_public",
        Public:  true,
        RateLimit: &RateLimit{Requests: 100, Window: "1m"},
    },
    "users.UserService.GetUser": {
        Action:    "users:read",
        Roles:     []string{"admin", "user"},
        Scopes:    []string{"users:read"},
        AllowSelf: true,
    },
    "users.UserService.DeleteUser": {
        Action:     "users:delete",
        Roles:      []string{"admin"},
        RequireMFA: true,
        AuditLog:   true,
    },
}

// Permission action constants
const (
    ActionUsersReadPublic = "users:read_public"
    ActionUsersRead       = "users:read"
    ActionUsersDelete     = "users:delete"
)

// Role constants
const (
    RoleAdmin = "admin"
    RoleUser  = "user"
)

Матрица доступа

# Текстовая матрица
buffalo permissions matrix

# HTML матрица
buffalo permissions matrix --format html --output matrix.html

# Markdown матрица
buffalo permissions matrix --format markdown --output PERMISSIONS.md

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

═══════════════════════════════════════════════════════════════════════════════
Method                        admin       user        s:users:read Public
───────────────────────────────────────────────────────────────────────────────

[users.UserService]
GetPublicProfile              —           —           —            ✓ʳ
GetUser                       ✓           ✓           ✓            —
DeleteUser                    ✓ᴹ          —           —            —

Legend: ✓ = allowed, M = requires MFA, C = has conditions, R = rate limited

Аудит безопасности

# Полный аудит
buffalo permissions audit

# Только ошибки
buffalo permissions audit --severity error

# JSON вывод
buffalo permissions audit --format json

Пример вывода:

Errors (1):
  [NO_ROLES_OR_SCOPES] users.UserService.InternalMethod
    Method has no roles or scopes defined
    Fix: Add roles, scopes, or mark as public: true

Warnings (2):
  [ADMIN_NO_MFA] orders.OrderService.CancelAllOrders
    Admin access does not require MFA
    Fix: Add require_mfa: true for admin operations

  [SENSITIVE_NO_AUDIT] users.UserService.UpdatePassword
    Sensitive operation does not have audit logging enabled
    Fix: Add audit_log: true for sensitive operations

Info (1):
  [MISSING_RATE_LIMIT] public.HealthService.Check
    Public endpoint has no rate limit configured
    Fix: Add rate_limit: { requests: 100, window: "1m" }

Total: 1 errors, 2 warnings, 1 info

Сравнение изменений

# Сравнить permissions между двумя директориями
buffalo permissions diff old-protos/ new-protos/

Пример вывода:

+ users.UserService.GetUserActivity
  Action: users:read_activity
  Roles: [admin, user]

~ users.UserService.GetUser
  Roles: [admin] -> [admin, user]
  AllowSelf: false -> true

- users.UserService.DeprecatedMethod

Summary: +1 added, ~1 modified, -1 removed

Статистика

buffalo permissions summary

Пример вывода:

Permission Summary
════════════════════════════════════════
Services:        5
Methods:         42
Public Methods:  3

Methods by Role:
  admin           28
  user            15
  guest           3

Methods by Scope:
  users:read      12
  users:write     8
  orders:read     6
  orders:write    4

---

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

buffalo.yaml структура

version: "1.0"

# Настройки проекта
project:
  name: myproject              # Имя проекта
  proto_root: protos           # Корневая папка .proto файлов
  output_root: generated       # Корневая папка для генерации
  
# Настройки сборки
build:
  parallel: true               # Параллельная компиляция
  jobs: 4                      # Количество воркеров
  incremental: true            # Инкрементальные сборки
  cache_enabled: true          # Использовать кэш
  
# Языки программирования
languages:
  python:
    enabled: true
    output: generated/python
    version: "3.8+"
    plugins:
      - grpc
      - mypy
    options:
      mypy_enabled: true
      package_name: myservice
  
  go:
    enabled: true
    output: generated/go
    module: github.com/myorg/myproject
    version: "1.21+"
    plugins:
      - grpc
      - grpc-gateway
      - validate
    options:
      go_package_prefix: github.com/myorg/myproject
  
  rust:
    enabled: false
    output: generated/rust
    crate: myproject
    plugins:
      - tonic
  
  cpp:
    enabled: false
    output: generated/cpp
    std: "c++17"

# Зависимости
dependencies:
  - name: googleapis
    url: https://github.com/googleapis/googleapis
    version: master
    path: google/api

# Плагины
plugins:
  - name: custom-validator
    path: ./plugins/validator
    enabled: true

# Шаблоны
templates:
  enabled: true
  path: ./templates
  
# Метрики
metrics:
  enabled: true
  output: .buffalo/metrics.json

Переменные окружения

BUFFALO_CONFIG=./custom.yaml    # Путь к конфигурации
BUFFALO_VERBOSE=true            # Подробный вывод
BUFFALO_JOBS=8                  # Количество воркеров
BUFFALO_NO_CACHE=true           # Отключить кэш
BUFFALO_LOG_LEVEL=debug         # Уровень логирования

---

🔌 Система плагинов

Buffalo поддерживает расширяемую систему плагинов для кастомизации генерации кода.

Встроенные плагины

• grpc - генерация gRPC кода
• grpc-gateway - REST API gateway для gRPC (Go)
• validate - валидация сообщений
• mypy - типизация для Python
• tonic - современный gRPC фреймворк для Rust

Создание собственного плагина

// plugins/custom/plugin.go
package custom

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

type CustomPlugin struct {
    plugin.BasePlugin
}

func (p *CustomPlugin) Name() string {
    return "custom-plugin"
}

func (p *CustomPlugin) Execute(ctx plugin.Context) error {
    // Ваша логика плагина
    return nil
}

Подробнее: Plugin Development Guide

---

📊 Метрики и мониторинг

Buffalo собирает детальные метрики о процессе сборки:

# Показать метрики последней сборки
buffalo metrics

# Экспорт метрик в JSON
buffalo metrics --format json > metrics.json

# Статистика проекта
buffalo stats

Пример вывода:

📊 Build Metrics
═══════════════════════════════════════
Total files:        42
Changed files:      3
Build time:         2.34s
Cache hit rate:     92.3%
Workers used:       8
Peak memory:        156MB

📈 Performance by language:
Python:   0.89s  (38%)
Go:       1.12s  (48%)
Rust:     0.33s  (14%)

---

🐳 Docker интеграция

Использование официального образа

FROM ghcr.io/massonsky/buffalo:1.5.0 AS builder

WORKDIR /workspace
COPY protos ./protos
COPY buffalo.yaml .

RUN buffalo build

# Копировать сгенерированный код в ваш образ
FROM python:3.11-slim
COPY --from=builder /workspace/generated/python /app/proto

Docker Compose

version: '3.8'

services:
  buffalo-build:
    image: ghcr.io/massonsky/buffalo:1.5.0
    volumes:
      - .:/workspace
    working_dir: /workspace
    command: buffalo build

---

🛠️ Разработка

Требования

• Go 1.24+
• Make (опционально)
• Git

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

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

# Сборка
make build

# Тестирование
make test

# Проверка кода
make check

# Установка
make install

Запуск тестов

make test              # Все тесты
make test-unit         # Unit тесты
make test-integration  # Integration тесты
make coverage          # С покрытием кода

Подробнее: Development Guide

---

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

Мы приветствуем вклад сообщества! Вот как вы можете помочь:

1. 🐛 Сообщайте о багах через GitHub Issues
2. 💡 Предлагайте новые функции в Discussions
3. 🔧 Отправляйте Pull Requests
4. 📖 Улучшайте документацию
5. ⭐ Ставьте звезды проекту на GitHub

Перед началом работы прочитайте Contributing Guide.

---

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

• Quick Start - быстрый старт за 5 минут
• Installation Guide - детальная инструкция по установке
• Architecture - архитектура системы
• Configuration Guide - полное руководство по конфигурации
• Plugin Development - создание плагинов
• Development Guide - руководство для разработчиков
• CLI Reference - справочник по командам
• CI/CD Integration - интеграция с CI/CD
• Metrics Guide - работа с метриками

---

🎯 Use Cases

Микросервисная архитектура

Buffalo идеален для проектов с множеством микросервисов на разных языках:

• Централизованное управление proto-контрактами
• Консистентная генерация кода для всех сервисов
• Быстрые итерации благодаря инкрементальным сборкам

CI/CD пайплайны

Интеграция с популярными CI/CD системами:

# .github/workflows/build.yml
name: Build Proto
on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Install Buffalo
        run: curl -sSL https://raw.githubusercontent.com/massonsky/buffalo/main/install.sh | bash
      
      - name: Build
        run: buffalo build
      
      - name: Audit Permissions
        run: buffalo permissions audit --severity error
      
      - name: Upload artifacts
        uses: actions/upload-artifact@v3
        with:
          name: generated-code
          path: generated/

Монорепозитории

Buffalo отлично работает с монорепо через workspace:

# .github/workflows/workspace.yml
name: Workspace Build
on:
  push:
    branches: [main]
  pull_request:

jobs:
  affected:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Install Buffalo
        run: curl -sSL https://raw.githubusercontent.com/massonsky/buffalo/main/install.sh | bash
      
      - name: Build affected projects
        run: |
          AFFECTED=$(buffalo workspace affected --since ${{ github.event.before }})
          if [ -n "$AFFECTED" ]; then
            buffalo workspace build $(echo $AFFECTED | tr '\n' ' ')
          fi

---

🔍 Сравнение с альтернативами

Функция	Buffalo	Buf	Prototool	Ручная сборка
Мультиязычность	✅ Python, Go, Rust, C++	✅ Множество	⚠️ Ограничено	✅ Любой
Интеллектуальное кэширование	✅	⚠️ Базовое	❌	❌
Параллельная компиляция	✅	✅	⚠️	❌
Система плагинов	✅	✅	⚠️	⚠️
Watch mode	✅	❌	✅	❌
Dependency management	✅	✅	❌	❌
Workspace management	✅	⚠️	❌	❌
Permissions/RBAC	✅	❌	❌	❌
Граф зависимостей	✅	⚠️	❌	❌
Auto-upgrade	✅	❌	❌	❌
Метрики	✅	❌	❌	❌

---

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

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

Бенчмарки (проект с 100 proto файлов)

Полная сборка (без кэша):
Buffalo:        12.3s
Buf:            18.7s
Manual (make):  34.2s

Инкрементальная сборка (5% изменений):
Buffalo:        0.9s  (93% faster)
Buf:            4.2s  (77% faster)
Manual (make):  34.2s (no cache)

Параллельная сборка (4 языка):
Buffalo:        15.4s (4 workers)
Sequential:     58.6s
Speedup:        3.8x

---

🗺️ Roadmap

v1.6.0 (Q2 2026)

• Поддержка TypeScript
• Улучшенная система шаблонов
• Remote caching
• Web UI для управления проектами

v2.0.0 (Q3 2026)

• Cloud-native build service
• Integration с популярными IDE
• Advanced dependency resolution
• Built-in proto registry

Полный roadmap: GitHub Projects

---

📄 Лицензия

Buffalo распространяется под лицензией MIT License.

---

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

Buffalo создан с использованием отличных open-source проектов:

• Protocol Buffers - Google's data interchange format
• gRPC - High performance RPC framework
• Cobra - CLI framework
• Viper - Configuration management
• fsnotify - File system notifications

---

💬 Поддержка и сообщество

• 📧 Email: support@buffalo-build.dev
• 💬 Discussions: GitHub Discussions
• 🐛 Issues: GitHub Issues
• 📖 Wiki: GitHub Wiki

---