SDKs · Go

CAVS for Go pipelines.

Drive the same Rust core the CLI uses from Go — through a stable C ABI via cgo, no shelling out. Analyze builds, preview update cost, pack, plan, apply, verify and benchmark, with context.Context cancellation and streaming progress events.

API on pkg.go.dev Full reference

Module

github.com/orelvis15/cavs-oss/sdks/go

Import .../sdks/go/cavs. Requires Go 1.21+ and a C toolchain (cgo).

Native core

libcavs_sdk

The compiled Rust library ships per platform (linux / macOS / windows, x86_64 & arm64) with a checksum.

License

Apache-2.0

Same repository and engine as the CLI. No CAVS-hosted infrastructure required.

Install

Add the module,
stage the native library.

Released builds ship the platform library; for a source checkout, make native builds and stages it from the Rust workspace. CAVS_SDK_LIBRARY overrides the path.

bash — install copy
# add the module to your project
$ go get github.com/orelvis15/cavs-oss/sdks/go@v1.2.0
# from a checkout: build & stage the native library once
$ make -C sdks/go native
Quickstart

Preview an update
from your release job.

package main

import (
    "context"
    "fmt"

    "github.com/orelvis15/cavs-oss/sdks/go/cavs"
)

func main() {
    client, err := cavs.New()
    if err != nil {
        panic(err)
    }
    defer client.Close()

    preview, err := client.Preview(context.Background(), cavs.PreviewRequest{
        OldPath: "Build_v1",
        NewPath: "Build_v2",
        Policy:  cavs.PolicyBalanced,
    })
    if err != nil {
        panic(err)
    }

    fmt.Println("Recommended route:", preview.RecommendedRoute)
    for _, r := range preview.Routes {
        fmt.Printf("  %-16s %d bytes\n", r.Name, r.NetworkBytes)
    }
}
The API

Eight operations,
one client.

Every method takes a context.Context (cancellation propagates to the native job) and a typed request, and returns a typed report. Pass cavs.WithProgress(fn) to stream ProgressEvents.

Analyze(ctx, AnalyzeRequest{OldPath, NewPath})
Inspect an old→new transition: sizes, estimated update bytes, reuse ratios, the worst files and layout findings with fixes.
PackDirectory(ctx, PackDirectoryRequest{InputDir, OutputCavs})
Package a directory tree into a deduplicated .cavs container. Options: Profile, Compression, SignKeyPath, Ignore globs.
Preview(ctx, PreviewRequest{OldPath, NewPath, Policy})
Estimate the wire cost across routes (full, SteamPipe-style, CAVS chunk, CAVS plan) and recommend the cheapest.
CreatePlan(ctx, CreatePlanRequest{OldPath, NewPath, OutputPlan})
Build a portable, BLAKE3-sealed .cavsplan — copy-ranges plus zstd fresh data. Returns reuse and op counts.
ApplyPlan(ctx, ApplyPlanRequest{OldPath, PlanPath, OutputPath})
Apply a plan with verification: atomic for artifacts, staged + journaled for directories. Returns byte-identical output.
VerifyInstall(ctx, VerifyRequest{Target, Signature})
Check an install against a .cavssig or manifest; reports modified / missing / extra files.
Benchmark(ctx, BenchmarkRequest{OldPath, NewPath})
A repeatable route-comparison report with measured diff/apply timings for the CAVS plan route.
EstimateSavings(ctx, SavingsRequest{PricePerGB, MonthlyDownloads, …})
Monthly egress cost of full downloads vs CAVS updates, and the savings — pure arithmetic over your pricing.
Progress & cancellation

Stream events,
cancel with context.

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

plan, err := client.CreatePlan(ctx, cavs.CreatePlanRequest{
    OldPath:    "Build_v1",
    NewPath:    "Build_v2",
    OutputPlan: "update.cavsplan",
}, cavs.WithProgress(func(e cavs.ProgressEvent) {
    fmt.Printf("[%s] %s\n", e.Type, e.Phase)
}))
if err != nil {
    // Typed errors carry the stable engine code.
    if cavs.IsCode(err, cavs.CodePathNotFound) {
        log.Fatal("old build not found")
    }
    panic(err)
}
fmt.Println("reused bytes:", plan.ReusedBytes)
CI/CD

Gate a release
in GitHub Actions.

# .github/workflows/cavs-preview.yml
name: CAVS Preview
on: [push]
jobs:
  preview:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with: { go-version: stable }
      - run: make -C sdks/go native
      - run: go run ./cmd/preview --old Build_v1 --new Build_v2

Fail the job when the estimated update exceeds a budget, or upload the preview as a build artifact — the report is plain structs you can marshal to JSON.

Kotlin SDK → Node SDK → Full Go reference