docs.rs failed to build buildkit-client-0.1.2
Please check the build logs for more information.
See Builds for ideas on how to fix a failed build, or Metadata for how to configure docs.rs builds.
If you believe this is docs.rs' fault, open an issue.

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:

Run cargo fmt and cargo clippy
Ensure all tests pass: cargo test
Add tests for new features
Update documentation as needed

buildkit-client 0.1.2