tripswitch

tripswitch-go

Official Go client SDK for Tripswitch - a circuit breaker management service.

v0.9.0 Breaking Changes: NewClient now accepts a context.Context and returns (*Client, error). The Ready method has been removed — initialization blocking is handled by NewClient. See Migration for details.

This SDK conforms to the Tripswitch SDK Contract v0.2.

Features

• Real-time state sync via Server-Sent Events (SSE)
• Automatic sample reporting with buffered, batched uploads
• Fail-open by default - your app stays available even if Tripswitch is unreachable
• Goroutine-safe - one client per project, safe for concurrent use
• Graceful shutdown with context-aware close and sample flushing

Installation

go get github.com/tripswitch-dev/tripswitch-go

Requires Go 1.22+ (uses math/rand/v2 for thread-safe random number generation)

Authentication

Tripswitch uses a two-tier authentication model introduced in v0.3.0:

Runtime Credentials (SDK)

For SDK initialization, you need two credentials from Project Settings → SDK Keys:

ts, err := tripswitch.NewClient(ctx, "proj_abc123",
    tripswitch.WithAPIKey("eb_pk_..."),    // Project key
    tripswitch.WithIngestKey("ik_..."),    // Ingest secret
)

Admin Credentials (Management API)

For management and automation tasks, use an Admin Key from Organization Settings → Admin Keys:

Admin keys are used with the Admin Client for creating projects, managing breakers, and other administrative tasks—not for runtime SDK usage.

Quick Start

package main

import (
    "context"
    "log"
    "net/http"
    "time"

    "github.com/tripswitch-dev/tripswitch-go"
)

func main() {
    // Create client (blocks until SSE state sync completes)
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    ts, err := tripswitch.NewClient(ctx, "proj_abc123",
        tripswitch.WithAPIKey("eb_pk_..."),
        tripswitch.WithIngestKey("ik_..."),
    )
    if err != nil {
        log.Fatal("tripswitch failed to initialize:", err)
    }
    defer ts.Close(context.Background())

    // Wrap operations with circuit breaker
    resp, err := tripswitch.Execute(ts, ctx, func() (*http.Response, error) {
        return http.Get("https://api.example.com/data")
    },
        tripswitch.WithBreakers("external-api"),              // Gate on breaker state
        tripswitch.WithRouter("my-router-id"),                // Route samples to this router
        tripswitch.WithMetrics(map[string]any{"latency": tripswitch.Latency}), // Report latency
    )
    if err != nil {
        if tripswitch.IsBreakerError(err) {
            // Circuit is open - return cached/fallback response
            log.Println("circuit open, using fallback")
            return
        }
        log.Println("request failed:", err)
        return
    }
    defer resp.Body.Close()
    // Process response...
}

Configuration Options

Client Options

Execute Options

Error Classification

Every sample includes an ok field indicating whether the task succeeded or failed. This is determined by the following evaluation order:

1. WithErrorEvaluator(fn) — if set, takes precedence over everything else. The function signature is func(error) bool. Return true if the error is a failure; return false if it should be treated as success.

   // Only count 5xx as failures; 4xx are "expected" errors
   tripswitch.WithErrorEvaluator(func(err error) bool {
       var httpErr *HTTPError
       if errors.As(err, &httpErr) {
           return httpErr.StatusCode >= 500
       }
       return true // non-HTTP errors are failures
   })
   

2. WithIgnoreErrors(errs...) — if the task error matches any of these (via errors.Is, so wrapped errors work), it is not counted as a failure.

   // sql.ErrNoRows is expected, don't count it
   tripswitch.WithIgnoreErrors(sql.ErrNoRows)
   

3. Default — any non-nil error is a failure; nil error is success.

Trace IDs

Trace IDs associate samples with distributed traces. Two ways to set them:

• WithTraceID(id) — explicit per-call trace ID. Takes precedence over the extractor.

• WithTraceIDExtractor(fn) (client option) — automatically extracts a trace ID from the context for every Execute call. Useful for OpenTelemetry integration:

  tripswitch.WithTraceIDExtractor(func(ctx context.Context) string {
      span := trace.SpanFromContext(ctx)
      if span.SpanContext().IsValid() {
          return span.SpanContext().TraceID().String()
      }
      return ""
  })
  

If both are set, WithTraceID wins.

API Reference

NewClient

func NewClient(ctx context.Context, projectID string, opts ...Option) (*Client, error)

Creates a new Tripswitch client. Starts background goroutines for SSE state sync and sample flushing, and blocks until the initial SSE sync completes (when an API key is configured). The context controls how long to wait for initialization. Returns an error if the context expires before sync completes.

Execute

func Execute[T any](c *Client, ctx context.Context, task func() (T, error), opts ...ExecuteOption) (T, error)

Runs a task end-to-end: checks breaker state, executes the task, and reports samples — all in one call.

• Use WithBreakers() to gate execution on breaker state (omit for pass-through)
• Use WithRouter() to specify where samples go (omit for no sample emission)
• Use WithMetrics() to specify what values to report

Returns ErrOpen if any specified breaker is open.

Note: This is a package-level generic function (not a method) because Go does not support generic methods.

Latency

var Latency = &latencyMarker{}

Sentinel value for WithMetrics that instructs the SDK to automatically compute and report task duration in milliseconds.

Close

func (c *Client) Close(ctx context.Context) error

Gracefully shuts down the client. The context controls how long to wait for buffered samples to flush.

Stats

func (c *Client) Stats() SDKStats

Returns a snapshot of SDK health metrics:

type SDKStats struct {
    DroppedSamples      uint64    // Samples dropped due to buffer overflow
    BufferSize          int       // Current buffer occupancy
    SSEConnected        bool      // SSE connection status
    SSEReconnects       uint64    // Count of SSE reconnections
    LastSuccessfulFlush time.Time // Timestamp of last successful flush
    LastSSEEvent        time.Time // Timestamp of last SSE event (zero if none received)
    FlushFailures       uint64    // Batches dropped after retry exhaustion
    CachedBreakers      int       // Number of breakers in local state cache
}

Breaker State Inspection

These methods expose the SDK's local breaker cache for debugging, logging, and health checks. For gating traffic on breaker state, use Execute with WithBreakers — it handles state checks, throttling, and sample reporting together.

type BreakerStatus struct {
    Name      string
    State     string  // "open", "closed", "half_open"
    AllowRate float64 // 0.0 to 1.0
}

func (c *Client) GetState(name string) *BreakerStatus
func (c *Client) GetAllStates() map[string]BreakerStatus

GetState returns the cached state of a single breaker, or nil if not found. GetAllStates returns a copy of all cached breaker states. Both return copies safe to hold without affecting internal state.

// Debug: why is checkout rejecting requests?
if status := ts.GetState("checkout"); status != nil {
    log.Printf("checkout breaker: state=%s allow_rate=%.2f", status.State, status.AllowRate)
}

// Health endpoint: expose all breaker states to monitoring
for name, status := range ts.GetAllStates() {
    log.Printf("breaker %s: %s", name, status.State)
}

Error Handling

var (
    ErrOpen                = errors.New("tripswitch: breaker is open")
    ErrConflictingOptions  = errors.New("tripswitch: conflicting execute options")
    ErrMetadataUnavailable = errors.New("tripswitch: metadata cache unavailable")
)

func IsBreakerError(err error) bool

Use IsBreakerError to check if an error is circuit breaker related:

result, err := tripswitch.Execute(ts, ctx, task,
    tripswitch.WithBreakers("my-breaker"),
)
if tripswitch.IsBreakerError(err) {
    // Breaker is open or request was throttled
    return fallbackValue, nil
}

Custom Metric Values

Latency is a convenience sentinel that auto-computes task duration in milliseconds. You can report any metric with any value:

tripswitch.WithMetrics(map[string]any{
    // Auto-computed latency (convenience)
    "latency": tripswitch.Latency,

    // Static numeric values
    "response_bytes": 4096,
    "queue_depth":    42.5,

    // Dynamic values via closure (called after task completes)
    "memory_mb": func() float64 {
        var m runtime.MemStats
        runtime.ReadMemStats(&m)
        return float64(m.Alloc / 1024 / 1024)
    },
})

Deferred Metrics

Use WithDeferredMetrics to extract metrics from the task's return value — useful when the interesting values are in the response (e.g., token counts from LLM APIs):

result, err := tripswitch.Execute(ts, ctx, func() (*anthropic.Response, error) {
    return anthropic.Complete(ctx, req)
},
    tripswitch.WithBreakers("anthropic-spend"),
    tripswitch.WithRouter("llm-router"),
    tripswitch.WithMetrics(map[string]any{"latency": tripswitch.Latency}),
    tripswitch.WithDeferredMetrics(func(res *anthropic.Response, err error) map[string]float64 {
        if res == nil {
            return nil
        }
        return map[string]float64{
            "prompt_tokens":     float64(res.Usage.PromptTokens),
            "completion_tokens": float64(res.Usage.CompletionTokens),
            "total_tokens":      float64(res.Usage.TotalTokens),
        }
    }),
)

Deferred metrics are resolved after the task completes and merged with eager metrics into the same sample batch. If the function panics, it is recovered and a warning is logged — eager metrics are still emitted.

Dynamic Selection

Use WithSelectedBreakers and WithSelectedRouter to choose breakers or routers at runtime based on cached metadata. The SDK periodically syncs metadata from the API (default 30s), and your selector receives the current snapshot.

// Gate on breakers matching a metadata property
result, err := tripswitch.Execute(ts, ctx, task,
    tripswitch.WithSelectedBreakers(func(breakers []tripswitch.BreakerMeta) []string {
        var names []string
        for _, b := range breakers {
            if b.Metadata["region"] == "us-east-1" {
                names = append(names, b.Name)
            }
        }
        return names
    }),
)

// Route samples to a router matching a metadata property
result, err := tripswitch.Execute(ts, ctx, task,
    tripswitch.WithSelectedRouter(func(routers []tripswitch.RouterMeta) string {
        for _, r := range routers {
            if r.Metadata["env"] == "production" {
                return r.ID
            }
        }
        return ""
    }),
    tripswitch.WithMetrics(map[string]any{"latency": tripswitch.Latency}),
)

Constraints:

• WithBreakers and WithSelectedBreakers are mutually exclusive — using both returns ErrConflictingOptions
• WithRouter and WithSelectedRouter are mutually exclusive — using both returns ErrConflictingOptions
• If the metadata cache hasn't been populated yet, returns ErrMetadataUnavailable
• If the selector returns an empty list/string, no gating or sample emission occurs

You can also access the metadata cache directly:

breakers := ts.GetBreakersMetadata() // []BreakerMeta
routers := ts.GetRoutersMetadata()   // []RouterMeta

Report

func (c *Client) Report(input ReportInput)

Send a sample independently of Execute. Use this for async workflows, result-derived metrics, or fire-and-forget reporting:

// Report token usage from an LLM API response
ts.Report(tripswitch.ReportInput{
    RouterID: "llm-router",
    Metric:   "total_tokens",
    Value:    float64(resp.Usage.TotalTokens),
    OK:       true,
})

// Background process metrics
ts.Report(tripswitch.ReportInput{
    RouterID: "worker-metrics",
    Metric:   "queue_depth",
    Value:    float64(queueLen),
    OK:       true,
    Tags:     map[string]string{"worker": "processor-1"},
})

Samples are buffered and batched the same way as Execute samples. Global tags are merged automatically.

Examples

See the examples directory for complete, runnable examples:

• HTTP Client Wrap - Wrap HTTP calls with circuit breaker
• Database Query - Ignore specific errors like sql.ErrNoRows
• Graceful Shutdown - Handle OS signals and flush samples
• Custom Error Evaluator - Ignore 4xx errors, count 5xx as failures
• OpenTelemetry Integration - Extract trace IDs from OTel context
• Per-Request Tags - Add diagnostic metadata to samples

Circuit Breaker States

How It Works

1. State Sync: The client maintains a local cache of breaker states, updated in real-time via SSE
2. Execute Check: Each Execute call checks the local cache (no network call)
3. Sample Reporting: Results are buffered and batched (500 samples or 15s, whichever comes first)
4. Graceful Degradation: If Tripswitch is unreachable, the client fails open by default

Admin Client

The admin package provides a client for management and automation tasks. This is separate from the runtime SDK and uses organization-scoped admin keys.

import "github.com/tripswitch-dev/tripswitch-go/admin"

client := admin.NewClient(
    admin.WithAPIKey("eb_admin_..."), // From Organization Settings → Admin Keys
)

// List all projects
projects, err := client.ListProjects(ctx)

// Create a project
project, err := client.CreateProject(ctx, admin.CreateProjectInput{
    Name: "prod-payments",
})

// Get project details
project, err := client.GetProject(ctx, "proj_abc123")

// Delete a project (requires name confirmation as a safety guard)
err = client.DeleteProject(ctx, "proj_abc123",
    admin.WithConfirmDeleteProjectName("prod-payments"),
)

// List breakers
page, err := client.ListBreakers(ctx, "proj_abc123", admin.ListParams{Limit: 100})

// Create a breaker
breaker, err := client.CreateBreaker(ctx, "proj_abc123", admin.CreateBreakerInput{
    Name:      "api-latency",
    Metric:    "latency_ms",
    Kind:      admin.BreakerKindP95,
    Op:        admin.BreakerOpGt,
    Threshold: 500,
})

Note: Admin keys (eb_admin_) are for management operations only. For runtime SDK usage, use project keys (eb_pk_) as shown in Quick Start.

Migration

v0.9.0: Synchronous NewClient

NewClient now takes a context.Context, blocks until SSE state sync completes, and returns (*Client, error). The Ready method has been removed.

// Before (v0.8.x)
ts := tripswitch.NewClient("proj_abc123",
    tripswitch.WithAPIKey("eb_pk_..."),
    tripswitch.WithIngestKey("ik_..."),
)
defer ts.Close(context.Background())
if err := ts.Ready(ctx); err != nil {
    log.Fatal(err)
}

// After (v0.9.0)
ts, err := tripswitch.NewClient(ctx, "proj_abc123",
    tripswitch.WithAPIKey("eb_pk_..."),
    tripswitch.WithIngestKey("ik_..."),
)
if err != nil {
    log.Fatal(err)
}
defer ts.Close(context.Background())

v0.7.0: WithMetrics map API

WithMetric was removed in favor of WithMetrics with a map:

// Before (v0.6.0)
tripswitch.WithMetric("latency", tripswitch.Latency),
tripswitch.WithMetric("count", 1),

// After (v0.7.0)
tripswitch.WithMetrics(map[string]any{
    "latency": tripswitch.Latency,
    "count":   1,
})

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

Apache License 2.0