Artifact Format

Barbacane compiles OpenAPI specs into .bca (Barbacane Compiled Artifact) files. This document describes the artifact format.

Overview

A .bca file is a gzip-compressed tar archive containing:

artifact.bca (tar.gz)
├── manifest.json       # Artifact metadata
├── routes.json         # Compiled routing table
├── specs/              # Embedded source specifications
│   ├── api.yaml
│   └── ...
└── plugins/            # Bundled WASM plugins (optional)
    ├── rate-limit.wasm
    └── ...

File Structure

manifest.json

Metadata about the artifact.

{
  "barbacane_artifact_version": 2,
  "compiled_at": "2026-03-01T10:30:00Z",
  "compiler_version": "0.2.1",
  "source_specs": [
    {
      "file": "api.yaml",
      "sha256": "abc123...",
      "type": "openapi",
      "version": "3.1.0"
    }
  ],
  "bundled_plugins": [
    {
      "name": "rate-limit",
      "version": "1.0.0",
      "plugin_type": "middleware",
      "wasm_path": "plugins/rate-limit.wasm",
      "sha256": "789abc..."
    }
  ],
  "routes_count": 12,
  "checksums": {
    "routes.json": "sha256:def456..."
  },
  "artifact_hash": "sha256:a1b2c3d4e5f6...",
  "provenance": {
    "commit": "abc123def456",
    "source": "ci/github-actions"
  }
}

Fields

source_specs entry

bundled_plugins entry

routes.json

Compiled operations with routing information.

{
  "operations": [
    {
      "index": 0,
      "path": "/users",
      "method": "GET",
      "operation_id": "listUsers",
      "dispatch": {
        "name": "http",
        "config": {
          "upstream": "backend",
          "path": "/api/users"
        }
      }
    },
    {
      "index": 1,
      "path": "/users/{id}",
      "method": "GET",
      "operation_id": "getUser",
      "dispatch": {
        "name": "http",
        "config": {
          "upstream": "backend",
          "path": "/api/users/{id}"
        }
      }
    }
  ]
}

operation entry

specs/

Directory containing the original source specifications. These are embedded for:

• Serving via /__barbacane/specs endpoint
• Documentation and debugging
• Audit trail

Files retain their original names.

Version History

Inspecting Artifacts

List Contents

tar -tzf artifact.bca

Output:

manifest.json
routes.json
specs/
specs/api.yaml
plugins/
plugins/rate-limit.wasm

Extract and View

# Extract
tar -xzf artifact.bca -C ./extracted

# View manifest
cat extracted/manifest.json | jq .

# View routes
cat extracted/routes.json | jq '.operations | length'

Verify Checksums

# Extract
tar -xzf artifact.bca -C ./extracted

# Verify routes.json
sha256sum extracted/routes.json
# Compare with manifest.checksums["routes.json"]

Security Considerations

Integrity

• All embedded files have SHA-256 checksums in the manifest
• The gateway verifies checksums on load
• The artifact_hash provides a single combined fingerprint of all inputs for drift detection
• When connected to a control plane, hash mismatches trigger drift alerts

Contents

• Source specs are embedded and served publicly via /__barbacane/specs
• Do not include secrets in spec files
• Use environment variables or secret management for sensitive config

Programmatic Access

Rust

use barbacane_compiler::{load_manifest, load_routes, load_specs, load_plugins};
use std::path::Path;

let path = Path::new("artifact.bca");

// Load manifest
let manifest = load_manifest(path)?;
println!("Routes: {}", manifest.routes_count);

// Load routes
let routes = load_routes(path)?;
for op in &routes.operations {
    println!("{} {}", op.method, op.path);
}

// Load specs
let specs = load_specs(path)?;
for (name, content) in &specs {
    println!("Spec: {} ({} bytes)", name, content.len());
}

// Load plugins
let plugins = load_plugins(path)?;
for (name, wasm_bytes) in &plugins {
    println!("Plugin: {} ({} bytes)", name, wasm_bytes.len());
}

Best Practices

Naming

Use descriptive names:

my-api-v2.1.0.bca
gateway-prod-2025-01-29.bca

Version Control

Don’t commit .bca files to git. Instead:

• Commit source specs
• Build artifacts in CI/CD
• Store in artifact registry

CI/CD Pipeline

# Compile in CI with provenance
barbacane compile \
  --spec specs/*.yaml \
  --manifest barbacane.yaml \
  --output dist/gateway-${VERSION}.bca \
  --provenance-commit "$(git rev-parse HEAD)" \
  --provenance-source ci/github-actions

# Upload to registry
aws s3 cp dist/gateway-${VERSION}.bca s3://artifacts/

# Deploy
ssh prod "barbacane serve --artifact /opt/barbacane/gateway.bca"

# Verify provenance on running gateway
curl -s http://gateway:8081/provenance | jq '.artifact_hash'