Aegis Go SDK Guide

Prerequisites

• Go runtime/toolchain 1.25.7+ on operator hosts (required for current stdlib CVE closure).
• Axis endpoint URL (default https://axis.velikey.com).
• One supported auth mode: API key, bearer token, or NextAuth session cookie.
• Rollout operations require an owner/admin session cookie with tenant write permissions.

Expected output: each command below should return tool versions or existing environment variable values.

# manual-only example
command -v go

go version

printenv AXIS_BASE_URL
printenv VELIKEY_API_KEY
printenv AXIS_SESSION_COOKIE

Runtime Closure Gate

Before live rollouts, enforce minimum runtime patch level to close Go stdlib advisories surfaced by govulncheck.

Expected output: runtime gate prints PASS when current Go runtime is at or above 1.25.7; otherwise it prints FAIL and the lane should be blocked.

# manual-only example
cd /path/to/velikey-go-sdk
GO_SDK_MIN_RUNTIME_VERSION=1.25.7 bash scripts/check-go-runtime.sh

If your host default go binary is older, run the gate against an explicit patched toolchain path.

# manual-only example
cd /path/to/velikey-go-sdk
GO_BINARY=/path/to/go1.25.7 GO_SDK_MIN_RUNTIME_VERSION=1.25.7 bash scripts/check-go-runtime.sh

Validated Live Lane Command (C5)

The live Go lane was validated on runtime go1.25.7 using session-cookie auth with an explicit AXIS_BASE_URL.

Expected output: lane emits go-sdk-e2e-receipt.json with result=pass, hasSessionCookie=true, and metering consistency fields.

# manual-only example
git clone https://github.com/sgreysond/velikey_test-env.git
cd velikey_test-env
export AXIS_BASE_URL="${AXIS_BASE_URL:-https://axis.velikey.com}"
export AXIS_SESSION_COOKIE="next-auth.session-token=<redacted>"
GO_SDK_MIN_RUNTIME_VERSION=1.25.7 bash scripts/sdk-e2e/run_go_sdk_e2e.sh

Install and Minimal Example

Use module mode and pin your app module to a reviewed SDK version in production.

Expected output: module add succeeds and health status prints healthy or degraded.

# executable example
rm -rf .tmp/velikey-sdk-smoke
mkdir -p .tmp/velikey-sdk-smoke
cd .tmp/velikey-sdk-smoke
go mod init example.com/velikey-sdk-smoke
go get github.com/sgreysond/velikey-go-sdk@v0.2.0
go mod tidy

package main

import (
  "context"
  "fmt"
  "log"
  "os"

  velikey "github.com/sgreysond/velikey-go-sdk"
)

func main() {
  client := velikey.NewClient(velikey.Config{
    BaseURL:       "https://axis.velikey.com",
    APIKey:        os.Getenv("VELIKEY_API_KEY"),
    BearerToken:   os.Getenv("VELIKEY_BEARER_TOKEN"),
    SessionCookie: os.Getenv("AXIS_SESSION_COOKIE"),
  })

  health, err := client.GetHealth(context.Background())
  if err != nil {
    log.Fatal(err)
  }

fmt.Printf("status=%s version=%s\n", health.Status, health.Version)
}

Production Client Configuration

Set explicit timeout and retry budgets. Keep retries bounded to protect upstream stability.

Expected output: your service starts with deterministic transport behavior under transient 429/5xx conditions.

client := velikey.NewClient(velikey.Config{
  BaseURL:          "https://axis.velikey.com",
  SessionCookie:    os.Getenv("AXIS_SESSION_COOKIE"),
  Timeout:          20 * time.Second,
  MaxRetries:       3,
  RetryMinBackoff:  250 * time.Millisecond,
  RetryMaxBackoff:  2 * time.Second,
  UserAgent:        "my-rollout-operator/1.0",
})

Canary Rollout and Rollback

Start with plan and dry-run apply. Execute live apply/rollback only in approved change windows.

Expected output: you should receive plan_id from plan, then rollout_id and optionally rollback_token from live apply.

canaryPercent := 10
plan, err := client.Rollouts.Plan(ctx, velikey.PlanRolloutRequest{
  PolicyID:      policyID,
  CanaryPercent: &canaryPercent,
  Explain:       true,
})
if err != nil {
  return err
}

applyDryRun, err := client.Rollouts.Apply(ctx, velikey.ApplyRolloutRequest{
  PlanID: plan.Data.PlanID,
  DryRun: true,
})
if err != nil {
  return err
}

_ = applyDryRun // inspect response and proceed only after operator sign-off

// manual-only live path
// liveApply, _ := client.Rollouts.Apply(ctx, velikey.ApplyRolloutRequest{PlanID: plan.Data.PlanID, DryRun: false})
// rollback, _ := client.Rollouts.Rollback(ctx, velikey.RollbackRolloutRequest{RollbackToken: liveApply.Data.RollbackToken})

Telemetry and Metering Readback

Record pre/post usage snapshots around rollout or traffic drills and attach both values to evidence receipts.

Expected output: usage API returns current.telemetryGB and current.estimatedCost; telemetry ingest returns accepted/queued state.

before, err := client.Usage.Get(ctx, "current")
if err != nil {
  return err
}

_, err = client.Telemetry.Ingest(ctx, velikey.TelemetryIngestRequest{
  Event: "sdk.go.rollout.validation",
  Properties: map[string]interface{}{
    "policy_id": policyID,
    "lane": "go",
  },
})
if err != nil {
  return err
}

after, err := client.Usage.Get(ctx, "current")
if err != nil {
  return err
}

fmt.Printf("telemetry_before=%.6f telemetry_after=%.6f\n", before.Current.TelemetryGB, after.Current.TelemetryGB)

Troubleshooting

• 401 Unauthorized: verify the route auth mode (API key vs bearer token vs session cookie) matches endpoint contract.
• 403 Forbidden: rollout endpoints require owner/admin privileges.
• 400 Validation errors: ensure rollout confirmation fields are present for non-dry-run apply/rollback.
• 429 / 5xx responses: use bounded retries and inspect upstream Axis health.

Expected output: after correcting auth and input contract, responses should move from 4xx to 2xx with valid JSON payloads.

Security Notes

• Do not log API keys, bearer tokens, session cookies, or rollback tokens.
• Use dedicated tenant-scoped credentials for automation lanes.
• Run live apply/rollback only with explicit approval and captured receipts.
• Rotate credentials after test runs and evidence publication.

Navigate Docs

Docs Index • Aegis Overview • Rollouts and Rollback • Axis Alerts and Audit