Barbacane Documentation

Barbacane is a spec-driven API gateway. Define your API using OpenAPI, add Barbacane extensions for routing and middleware, compile to an artifact, and deploy.

Why Barbacane?

• Spec as config — Your OpenAPI 3.x or AsyncAPI 3.x specification is the single source of truth. No separate gateway DSL to maintain.
• Compile-time safety — Misconfigurations, ambiguous routes, and missing plugins are caught at compile time, not at 3 AM.
• Fast and predictable — Built on Rust, Tokio, and Hyper. No garbage collector, no latency surprises.
• Secure by default — Memory-safe runtime, TLS via Rustls, sandboxed WASM plugins, secrets never baked into artifacts.
• Extensible — Write plugins in any language that compiles to WebAssembly. They run in a sandbox, so a buggy plugin can’t take down the gateway.
• Observable — Prometheus metrics, structured JSON logging, and distributed tracing with W3C Trace Context and OTLP export.

Quick Start

With Docker

The standalone image bundles the binary and all official plugins:

# Compile your OpenAPI spec (all plugins are pre-bundled)
docker run --rm -v $(pwd):/work ghcr.io/barbacane-dev/barbacane-standalone \
  compile --spec /work/api.yaml --manifest /etc/barbacane/plugins.yaml --output /work/api.bca

# Run the gateway
docker run --rm -p 8080:8080 -v $(pwd)/api.bca:/config/api.bca ghcr.io/barbacane-dev/barbacane-standalone \
  serve --artifact /config/api.bca --listen 0.0.0.0:8080

Also available on Docker Hub as barbacane/barbacane-standalone. To build locally:

git clone https://github.com/barbacane-dev/barbacane.git
cd barbacane
make docker-build-standalone

Playground

Full demo environment with observability stack (Prometheus, Grafana, Loki, Tempo) and control plane UI:

git clone https://github.com/barbacane-dev/barbacane.git
cd barbacane/playground
docker-compose up -d

# Gateway:       http://localhost:8080
# Grafana:       http://localhost:3000 (admin/admin)
# Control Plane: http://localhost:3001

From source

git clone https://github.com/barbacane-dev/barbacane.git
cd barbacane
cargo build --release
make plugins

# Compile your OpenAPI spec
./target/release/barbacane compile --spec api.yaml --manifest barbacane.yaml --output api.bca

# Run the gateway
./target/release/barbacane serve --artifact api.bca --listen 0.0.0.0:8080

Documentation

User Guide

• Getting Started - First steps with Barbacane
• Spec Configuration - Configure routing and middleware in your OpenAPI spec
• Dispatchers - Route requests to backends
• Middlewares - Add authentication, rate limiting, and more
• Secrets - Manage secrets in plugin configurations
• Observability - Metrics, logging, and distributed tracing
• Control Plane - REST API for spec and artifact management
• Web UI - Web-based management interface

Reference

• CLI Reference - Command-line tools
• Spec Extensions - Complete x-barbacane-* reference
• Artifact Format - .bca file format
• Reserved Endpoints - /__barbacane/* endpoints

Contributing

• Architecture - System design and crate structure
• Development Guide - Setting up and building
• Plugin Development - Creating WASM plugins

Supported Spec Versions

AsyncAPI Support

Barbacane supports AsyncAPI 3.x for event-driven APIs. AsyncAPI send operations are accessible via HTTP POST requests, enabling a sync-to-async bridge pattern where HTTP clients can publish messages to Kafka or NATS brokers.

License

Apache 2.0 - See LICENSE