BuildKit Rust Client

A full-featured Rust client library and CLI for interacting with moby/buildkit to build container images via gRPC.

Features • Installation • Quick Start • Usage • Documentation • Contributing

---

Features

• Complete gRPC Implementation - Direct integration with BuildKit's gRPC API
• Multiple Build Sources - Support for local Dockerfiles and GitHub repositories
• Authentication Support - GitHub private repositories and Docker Registry authentication
• Advanced Build Options - Build args, target stages, multi-platform builds
• Real-time Progress - Live build progress and log streaming
• Cache Management - Support for cache import/export
• Registry Push - Automatic push of built images to registries
• Session Protocol - Full implementation of BuildKit's bidirectional session protocol
• HTTP/2 Tunneling - HTTP/2-over-gRPC for file synchronization

Prerequisites

• Rust 1.70+
• Docker or BuildKit daemon
• Git (for fetching proto files)

Installation

As a Library

Add to your Cargo.toml:

[dependencies]
buildkit-client = "0.1" # or bkit if you like
tokio = { version = "1", features = ["full"] }
anyhow = "1.0"

As a CLI Tool

git clone https://github.com/corespeed-io/buildkit-client.git
cd buildkit-client
cargo install --path .

Proto files are automatically managed during build - no manual setup required.

Quick Start

See Usage Guide for detailed CLI and library usage examples.

Project Structure

buildkit-client/
├── src/
│   ├── main.rs          # CLI tool entry point
│   ├── lib.rs           # Library entry point
│   ├── client.rs        # BuildKit gRPC client
│   ├── builder.rs       # Build configuration
│   ├── solve.rs         # Build execution logic
│   ├── progress.rs      # Progress handling
│   ├── session/         # Session protocol implementation
│   │   ├── mod.rs       # Session lifecycle & metadata
│   │   ├── grpc_tunnel.rs  # HTTP/2-over-gRPC tunnel
│   │   ├── filesync.rs  # File synchronization
│   │   └── auth.rs      # Registry authentication
│   └── proto.rs         # Protobuf generated code
├── proto/               # BuildKit protobuf definitions
├── examples/            # Sample Dockerfiles
├── tests/               # Comprehensive test suite
├── docker-compose.yml   # Test environment setup
└── README.md

BuildKit gRPC API

This project directly uses BuildKit's gRPC API:

• Control.Solve - Execute build operations
• Control.Status - Stream build status updates
• Control.Info - Get BuildKit information
• Control.Session - Bidirectional session stream

All protobuf definitions are fetched from the moby/buildkit repository.

Documentation

• Quick Start Guide - Get up and running quickly
• Usage Guide - CLI and library usage examples with configuration options
• Architecture Guide - Complete architecture and protocol documentation
• Development Guide - Development workflows, testing, and proto management
• Testing Guide - Complete testing documentation (unit, integration, GitHub builds)
• Implementation Notes - Detailed implementation notes for contributors

Troubleshooting

BuildKit Connection Failed

# Check if BuildKit is running
docker-compose ps

# View BuildKit logs
docker-compose logs buildkitd

# Restart services
docker-compose restart

Registry Push Failed

Ensure the registry allows insecure connections (for localhost):

# docker-compose.yml
services:
  buildkitd:
    environment:
      - BUILDKIT_REGISTRY_INSECURE=true

Proto Compilation Errors

If you encounter protobuf compilation errors:

# Force rebuild (will redownload proto files)
cargo clean
PROTO_REBUILD=true cargo build

# Or use clone mode if download fails
PROTO_FETCH_MODE=clone cargo build

Proto files are now automatically managed by build.rs. See Development Guide for details.

Development

For detailed development workflows, testing strategies, and proto management, see Development Guide.

Quick commands:

make build         # Build project
make test          # Run tests
make up            # Start docker-compose services
cargo fmt          # Format code
cargo clippy       # Run linter

Architecture

This project implements a complete BuildKit gRPC client with:

• Bidirectional gRPC streaming for real-time communication
• HTTP/2-over-gRPC tunneling for BuildKit callbacks
• DiffCopy protocol for efficient file synchronization
• Session management with proper metadata handling
• Registry authentication support

For detailed architecture documentation, see Architecture Guide.

License

This project is dual-licensed under MIT OR Apache-2.0.

Acknowledgments

• moby/buildkit - BuildKit project
• tonic - Rust gRPC library
• prost - Protocol Buffers implementation
• h2 - HTTP/2 implementation

Contributing

Contributions are welcome! Please feel free to submit Issues and Pull Requests.

Before submitting a PR:

1. Run cargo fmt and cargo clippy
2. Ensure all tests pass: cargo test
3. Add tests for new features
4. Update documentation as needed

Related Links

• BuildKit Documentation
• BuildKit API Reference
• Docker Buildx
• Container Image Specification

---

⬆ back to top

Made with ❤️ by AprilNEA