9bdcbe0447
Major integrations and fixes: - Added BACKBEAT SDK integration for P2P operation timing - Implemented beat-aware status tracking for distributed operations - Added Docker secrets support for secure license management - Resolved KACHING license validation via HTTPS/TLS - Updated docker-compose configuration for clean stack deployment - Disabled rollback policies to prevent deployment failures - Added license credential storage (CHORUS-DEV-MULTI-001) Technical improvements: - BACKBEAT P2P operation tracking with phase management - Enhanced configuration system with file-based secrets - Improved error handling for license validation - Clean separation of KACHING and CHORUS deployment stacks 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
110 lines
3.5 KiB
Go
110 lines
3.5 KiB
Go
// Package sdk provides the BACKBEAT Go SDK for enabling CHORUS services
|
|
// to become BACKBEAT-aware with beat synchronization and status emission.
|
|
//
|
|
// The BACKBEAT SDK enables services to:
|
|
// - Subscribe to cluster-wide beat events with jitter tolerance
|
|
// - Emit status claims with automatic metadata population
|
|
// - Use beat budgets for timeout management
|
|
// - Operate in local degradation mode when pulse unavailable
|
|
// - Integrate comprehensive observability and health reporting
|
|
//
|
|
// # Quick Start
|
|
//
|
|
// config := sdk.DefaultConfig()
|
|
// config.ClusterID = "chorus-dev"
|
|
// config.AgentID = "my-service"
|
|
// config.NATSUrl = "nats://localhost:4222"
|
|
//
|
|
// client := sdk.NewClient(config)
|
|
//
|
|
// client.OnBeat(func(beat sdk.BeatFrame) {
|
|
// // Called every beat
|
|
// client.EmitStatusClaim(sdk.StatusClaim{
|
|
// State: "executing",
|
|
// Progress: 0.5,
|
|
// Notes: "Processing data",
|
|
// })
|
|
// })
|
|
//
|
|
// ctx := context.Background()
|
|
// client.Start(ctx)
|
|
// defer client.Stop()
|
|
//
|
|
// # Beat Subscription
|
|
//
|
|
// Register callbacks for beat and downbeat events:
|
|
//
|
|
// client.OnBeat(func(beat sdk.BeatFrame) {
|
|
// // Called every beat (~1-4 times per second depending on tempo)
|
|
// fmt.Printf("Beat %d\n", beat.BeatIndex)
|
|
// })
|
|
//
|
|
// client.OnDownbeat(func(beat sdk.BeatFrame) {
|
|
// // Called at the start of each bar (every 4 beats typically)
|
|
// fmt.Printf("Bar started: %s\n", beat.WindowID)
|
|
// })
|
|
//
|
|
// # Status Emission
|
|
//
|
|
// Emit status claims to report current state and progress:
|
|
//
|
|
// err := client.EmitStatusClaim(sdk.StatusClaim{
|
|
// State: "executing", // executing|planning|waiting|review|done|failed
|
|
// BeatsLeft: 10, // estimated beats remaining
|
|
// Progress: 0.75, // progress ratio (0.0-1.0)
|
|
// Notes: "Processing batch 5/10",
|
|
// })
|
|
//
|
|
// # Beat Budgets
|
|
//
|
|
// Execute functions with beat-based timeouts:
|
|
//
|
|
// err := client.WithBeatBudget(10, func() error {
|
|
// // This function has 10 beats to complete
|
|
// return performLongRunningTask()
|
|
// })
|
|
//
|
|
// if err != nil {
|
|
// // Handle timeout or task error
|
|
// log.Printf("Task failed or exceeded budget: %v", err)
|
|
// }
|
|
//
|
|
// # Health and Observability
|
|
//
|
|
// Monitor client health and metrics:
|
|
//
|
|
// health := client.Health()
|
|
// fmt.Printf("Connected: %v\n", health.Connected)
|
|
// fmt.Printf("Last Beat: %d\n", health.LastBeat)
|
|
// fmt.Printf("Reconnects: %d\n", health.ReconnectCount)
|
|
//
|
|
// # Local Degradation
|
|
//
|
|
// The SDK automatically handles network issues by entering local degradation mode:
|
|
// - Generates synthetic beats when pulse service unavailable
|
|
// - Uses fallback timing to maintain callback schedules
|
|
// - Automatically recovers when pulse service returns
|
|
// - Provides seamless operation during network partitions
|
|
//
|
|
// # Security
|
|
//
|
|
// The SDK implements BACKBEAT security requirements:
|
|
// - Ed25519 signing of all status claims when key provided
|
|
// - Required x-window-id and x-hlc headers
|
|
// - Agent identification for proper message routing
|
|
//
|
|
// # Performance
|
|
//
|
|
// Designed for production use with:
|
|
// - Beat callback latency target ≤5ms
|
|
// - Timer drift ≤1% over 1 hour without leader
|
|
// - Goroutine-safe concurrent operations
|
|
// - Bounded memory usage for metrics and errors
|
|
//
|
|
// # Examples
|
|
//
|
|
// See the examples subdirectory for complete usage patterns:
|
|
// - examples/simple_agent.go: Basic integration
|
|
// - examples/task_processor.go: Beat budget usage
|
|
// - examples/service_monitor.go: Health monitoring
|
|
package sdk |