From 2874e52a2a25252ccadfa6aa817f90cdc0490a58 Mon Sep 17 00:00:00 2001 From: Finessse Date: Sun, 28 Dec 2025 07:07:35 +0700 Subject: [PATCH] feat(translator): add resilience and recovery strategies Add translation recovery with direct hit, fallback chain, and auto-detect strategies for robust format conversion. --- sdk/translator/resilience.go | 346 ++++++++++++++++++++++++++++++ sdk/translator/resilience_test.go | 336 +++++++++++++++++++++++++++++ 2 files changed, 682 insertions(+) create mode 100644 sdk/translator/resilience.go create mode 100644 sdk/translator/resilience_test.go diff --git a/sdk/translator/resilience.go b/sdk/translator/resilience.go new file mode 100644 index 00000000..7a72ee0a --- /dev/null +++ b/sdk/translator/resilience.go @@ -0,0 +1,346 @@ +package translator + +import ( + "fmt" + "strings" + "sync/atomic" +) + +// Unregister removes a translator pair from the registry. +func (r *Registry) Unregister(from, to Format) { + r.mu.Lock() + defer r.mu.Unlock() + + if byTarget, ok := r.requests[from]; ok { + delete(byTarget, to) + if len(byTarget) == 0 { + delete(r.requests, from) + } + } + + if byTarget, ok := r.responses[from]; ok { + delete(byTarget, to) + if len(byTarget) == 0 { + delete(r.responses, from) + } + } + + // Also remove lazy loaders + if byTarget, ok := r.lazyRequests[from]; ok { + delete(byTarget, to) + if len(byTarget) == 0 { + delete(r.lazyRequests, from) + } + } + + if byTarget, ok := r.lazyResponses[from]; ok { + delete(byTarget, to) + if len(byTarget) == 0 { + delete(r.lazyResponses, from) + } + } +} + +// Unregister removes a translator pair from the default registry. +func Unregister(from, to Format) { + defaultRegistry.Unregister(from, to) +} + +// Clone creates a deep copy of the Registry. +// Note: Transform functions are shared (not deep copied) as they are typically stateless. +func (r *Registry) Clone() *Registry { + r.mu.RLock() + defer r.mu.RUnlock() + + newReg := NewRegistry() + + // Copy requests + for from, targets := range r.requests { + newReg.requests[from] = make(map[Format]RequestTransform) + for to, fn := range targets { + newReg.requests[from][to] = fn + } + } + + // Copy responses + for from, targets := range r.responses { + newReg.responses[from] = make(map[Format]ResponseTransform) + for to, fn := range targets { + newReg.responses[from][to] = fn + } + } + + // Copy lazy requests + for from, targets := range r.lazyRequests { + newReg.lazyRequests[from] = make(map[Format]*lazyRequestEntry) + for to, entry := range targets { + entry.loadMu.Lock() + newReg.lazyRequests[from][to] = &lazyRequestEntry{ + loader: entry.loader, + loaded: entry.loaded, + isLoaded: entry.isLoaded, + } + entry.loadMu.Unlock() + } + } + + // Copy lazy responses + for from, targets := range r.lazyResponses { + newReg.lazyResponses[from] = make(map[Format]*lazyResponseEntry) + for to, entry := range targets { + entry.loadMu.Lock() + newReg.lazyResponses[from][to] = &lazyResponseEntry{ + loader: entry.loader, + loaded: entry.loaded, + isLoaded: entry.isLoaded, + } + entry.loadMu.Unlock() + } + } + + // Copy debug/dry-run settings + newReg.debugMode.Store(r.debugMode.Load()) + newReg.dryRunMode.Store(r.dryRunMode.Load()) + newReg.loadedCount.Store(r.loadedCount.Load()) + newReg.lazyCount.Store(r.lazyCount.Load()) + + return newReg +} + +// CloneRegistry creates a deep copy of the default registry. +func CloneRegistry() *Registry { + return defaultRegistry.Clone() +} + +// registryPtr holds a pointer to the current default registry for atomic swap. +var registryPtr atomic.Pointer[Registry] + +func init() { + registryPtr.Store(defaultRegistry) +} + +// ReplaceRegistry atomically swaps the default registry with a new one. +// Returns the old registry. +func ReplaceRegistry(newRegistry *Registry) *Registry { + if newRegistry == nil { + return nil + } + old := registryPtr.Swap(newRegistry) + defaultRegistry = newRegistry + return old +} + +// HasRequestTransformer indicates whether a request translator exists. +// Alias for HasRequestTranslator for consistency with HasResponseTransformer. +func (r *Registry) HasRequestTransformer(from, to Format) bool { + return r.HasRequestTranslator(from, to) +} + +// HasRequestTransformer inspects the default registry. +func HasRequestTransformer(from, to Format) bool { + return defaultRegistry.HasRequestTransformer(from, to) +} + +// TranslationError provides detailed information about a failed translation attempt. +type TranslationError struct { + From Format + To Format + AttemptedPaths [][]Format + DetectedFormat Format + Cause error +} + +func (e *TranslationError) Error() string { + var sb strings.Builder + sb.WriteString(fmt.Sprintf("translation failed from %s to %s", e.From, e.To)) + if e.DetectedFormat != "" { + sb.WriteString(fmt.Sprintf(" (detected: %s)", e.DetectedFormat)) + } + if len(e.AttemptedPaths) > 0 { + sb.WriteString("; attempted paths: ") + for i, path := range e.AttemptedPaths { + if i > 0 { + sb.WriteString(", ") + } + sb.WriteString("[") + for j, f := range path { + if j > 0 { + sb.WriteString("->") + } + sb.WriteString(string(f)) + } + sb.WriteString("]") + } + } + if e.Cause != nil { + sb.WriteString(fmt.Sprintf("; cause: %v", e.Cause)) + } + return sb.String() +} + +func (e *TranslationError) Unwrap() error { + return e.Cause +} + +// TranslationResult contains the result of a translation with recovery. +type TranslationResult struct { + Payload []byte + UsedPath []Format + Detected Format + Success bool + DirectHit bool + FallbackHit bool + AutoDetectHit bool +} + +// TranslateRequestWithRecovery attempts translation with multiple recovery strategies: +// 1. Direct translation +// 2. Fallback chains +// 3. Auto-detect format and retry +func (r *Registry) TranslateRequestWithRecovery( + from, to Format, + model string, + rawJSON []byte, + stream bool, + fallbackReg *FallbackRegistry, +) (*TranslationResult, error) { + if fallbackReg == nil { + fallbackReg = DefaultFallbackRegistry() + } + + result := &TranslationResult{ + Payload: rawJSON, + } + var attemptedPaths [][]Format + + // Strategy 1: Try direct translation + if r.HasRequestTransformer(from, to) { + translated := r.TranslateRequest(from, to, model, rawJSON, stream) + result.Payload = translated + result.UsedPath = []Format{from, to} + result.Success = true + result.DirectHit = true + return result, nil + } + attemptedPaths = append(attemptedPaths, []Format{from, to}) + + // Strategy 2: Try fallback chains + if chain := fallbackReg.GetChain(from, to); chain != nil { + path := buildFullPath(from, to, chain) + + // Verify all steps in the chain exist + chainValid := true + for i := 0; i < len(path)-1; i++ { + if !r.HasRequestTransformer(path[i], path[i+1]) { + chainValid = false + break + } + } + + if chainValid { + translated := r.TranslateRequestViaChain(path, model, rawJSON, stream) + result.Payload = translated + result.UsedPath = path + result.Success = true + result.FallbackHit = true + return result, nil + } + attemptedPaths = append(attemptedPaths, path) + } + + // Strategy 3: Auto-detect format and retry + detected := DetectFormat(rawJSON) + result.Detected = detected + + if detected != "" && detected != from { + // Try direct translation from detected format + if r.HasRequestTransformer(detected, to) { + translated := r.TranslateRequest(detected, to, model, rawJSON, stream) + result.Payload = translated + result.UsedPath = []Format{detected, to} + result.Success = true + result.AutoDetectHit = true + return result, nil + } + attemptedPaths = append(attemptedPaths, []Format{detected, to}) + + // Try fallback chain from detected format + if chain := fallbackReg.GetChain(detected, to); chain != nil { + path := buildFullPath(detected, to, chain) + + chainValid := true + for i := 0; i < len(path)-1; i++ { + if !r.HasRequestTransformer(path[i], path[i+1]) { + chainValid = false + break + } + } + + if chainValid { + translated := r.TranslateRequestViaChain(path, model, rawJSON, stream) + result.Payload = translated + result.UsedPath = path + result.Success = true + result.FallbackHit = true + result.AutoDetectHit = true + return result, nil + } + attemptedPaths = append(attemptedPaths, path) + } + } + + // All strategies failed + return result, &TranslationError{ + From: from, + To: to, + AttemptedPaths: attemptedPaths, + DetectedFormat: detected, + Cause: ErrNoTranslator, + } +} + +// TranslateRequestWithRecovery is a helper on the default registry. +func TranslateRequestWithRecovery(from, to Format, model string, rawJSON []byte, stream bool) (*TranslationResult, error) { + return defaultRegistry.TranslateRequestWithRecovery(from, to, model, rawJSON, stream, nil) +} + +// ListRegisteredPairs returns all registered (from, to) pairs for requests. +func (r *Registry) ListRegisteredPairs() [][2]Format { + r.mu.RLock() + defer r.mu.RUnlock() + + var pairs [][2]Format + for from, targets := range r.requests { + for to := range targets { + pairs = append(pairs, [2]Format{from, to}) + } + } + // Include lazy registered pairs + for from, targets := range r.lazyRequests { + for to := range targets { + pairs = append(pairs, [2]Format{from, to}) + } + } + return pairs +} + +// ListRegisteredPairs returns all registered pairs from the default registry. +func ListRegisteredPairs() [][2]Format { + return defaultRegistry.ListRegisteredPairs() +} + +// Clear removes all registered translators from the registry. +func (r *Registry) Clear() { + r.mu.Lock() + defer r.mu.Unlock() + + r.requests = make(map[Format]map[Format]RequestTransform) + r.responses = make(map[Format]map[Format]ResponseTransform) + r.lazyRequests = make(map[Format]map[Format]*lazyRequestEntry) + r.lazyResponses = make(map[Format]map[Format]*lazyResponseEntry) +} + +// Clear removes all registered translators from the default registry. +func Clear() { + defaultRegistry.Clear() +} diff --git a/sdk/translator/resilience_test.go b/sdk/translator/resilience_test.go new file mode 100644 index 00000000..fa197763 --- /dev/null +++ b/sdk/translator/resilience_test.go @@ -0,0 +1,336 @@ +package translator + +import ( + "errors" + "testing" +) + +func TestTranslateRequestWithRecovery_DirectHit(t *testing.T) { + reg := NewRegistry() + reg.Register(FormatOpenAI, FormatClaude, func(model string, data []byte, stream bool) []byte { + return append([]byte("translated:"), data...) + }, ResponseTransform{}) + + result, err := reg.TranslateRequestWithRecovery(FormatOpenAI, FormatClaude, "model", []byte("test"), false, nil) + + if err != nil { + t.Fatalf("Unexpected error: %v", err) + } + if !result.Success { + t.Error("Result should be successful") + } + if !result.DirectHit { + t.Error("Should be a direct hit") + } + if result.FallbackHit { + t.Error("Should not be a fallback hit") + } + if string(result.Payload) != "translated:test" { + t.Errorf("Payload = %q, want %q", string(result.Payload), "translated:test") + } + if len(result.UsedPath) != 2 { + t.Error("UsedPath should have 2 elements") + } +} + +func TestTranslateRequestWithRecovery_FallbackChain(t *testing.T) { + reg := NewRegistry() + + // Register indirect path: OpenAI -> Gemini -> Claude + reg.Register(FormatOpenAI, FormatGemini, func(model string, data []byte, stream bool) []byte { + return append(data, []byte("-gemini")...) + }, ResponseTransform{}) + reg.Register(FormatGemini, FormatClaude, func(model string, data []byte, stream bool) []byte { + return append(data, []byte("-claude")...) + }, ResponseTransform{}) + + // Register fallback chain + fallbackReg := NewFallbackRegistry() + fallbackReg.RegisterChain(FormatOpenAI, FormatClaude, []Format{FormatGemini}) + + result, err := reg.TranslateRequestWithRecovery(FormatOpenAI, FormatClaude, "model", []byte("test"), false, fallbackReg) + + if err != nil { + t.Fatalf("Unexpected error: %v", err) + } + if !result.Success { + t.Error("Result should be successful") + } + if result.DirectHit { + t.Error("Should not be a direct hit") + } + if !result.FallbackHit { + t.Error("Should be a fallback hit") + } + if string(result.Payload) != "test-gemini-claude" { + t.Errorf("Payload = %q, want %q", string(result.Payload), "test-gemini-claude") + } +} + +func TestTranslateRequestWithRecovery_AutoDetect(t *testing.T) { + reg := NewRegistry() + + // Register Claude -> OpenAI translator + reg.Register(FormatClaude, FormatOpenAI, func(model string, data []byte, stream bool) []byte { + return append([]byte("from-claude:"), data...) + }, ResponseTransform{}) + + // Payload that will be auto-detected as Claude format + payload := []byte(`{"model": "claude-3", "messages": [], "anthropic_version": "2023-06-01"}`) + + // Request translation from unknown format to OpenAI + // The auto-detect should identify it as Claude and use that translator + result, err := reg.TranslateRequestWithRecovery("unknown", FormatOpenAI, "model", payload, false, nil) + + if err != nil { + t.Fatalf("Unexpected error: %v", err) + } + if !result.Success { + t.Error("Result should be successful via auto-detect") + } + if !result.AutoDetectHit { + t.Error("Should be an auto-detect hit") + } + if result.Detected != FormatClaude { + t.Errorf("Detected = %v, want %v", result.Detected, FormatClaude) + } +} + +func TestTranslateRequestWithRecovery_AllStrategiesFail(t *testing.T) { + reg := NewRegistry() + // Empty registry - no translators + + result, err := reg.TranslateRequestWithRecovery(FormatOpenAI, FormatClaude, "model", []byte("test"), false, nil) + + if err == nil { + t.Error("Should return error when all strategies fail") + } + if result.Success { + t.Error("Result should not be successful") + } + + // Check it's a TranslationError + var translationErr *TranslationError + if !errors.As(err, &translationErr) { + t.Error("Error should be a TranslationError") + } +} + +func TestTranslationError_Error(t *testing.T) { + err := &TranslationError{ + From: FormatOpenAI, + To: FormatClaude, + AttemptedPaths: [][]Format{{FormatOpenAI, FormatClaude}, {FormatOpenAI, FormatGemini, FormatClaude}}, + DetectedFormat: FormatGemini, + Cause: ErrNoTranslator, + } + + errStr := err.Error() + + if !containsStr(errStr, "openai") { + t.Error("Error message should contain source format") + } + if !containsStr(errStr, "claude") { + t.Error("Error message should contain target format") + } + if !containsStr(errStr, "detected: gemini") { + t.Error("Error message should contain detected format") + } + if !containsStr(errStr, "attempted paths") { + t.Error("Error message should mention attempted paths") + } +} + +func TestTranslationError_Unwrap(t *testing.T) { + cause := errors.New("root cause") + err := &TranslationError{ + From: FormatOpenAI, + To: FormatClaude, + Cause: cause, + } + + unwrapped := err.Unwrap() + if unwrapped != cause { + t.Error("Unwrap should return the cause") + } +} + +func TestUnregister(t *testing.T) { + reg := NewRegistry() + + reg.Register(FormatOpenAI, FormatClaude, func(model string, data []byte, stream bool) []byte { + return data + }, ResponseTransform{}) + + // Verify they exist + if !reg.HasRequestTranslator(FormatOpenAI, FormatClaude) { + t.Fatal("Request translator should exist before unregister") + } + + reg.Unregister(FormatOpenAI, FormatClaude) + + // Verify they're gone + if reg.HasRequestTranslator(FormatOpenAI, FormatClaude) { + t.Error("Request translator should be removed after unregister") + } +} + +func TestCloneRegistry(t *testing.T) { + reg := NewRegistry() + + reg.Register(FormatOpenAI, FormatClaude, func(model string, data []byte, stream bool) []byte { + return data + }, ResponseTransform{}) + reg.SetDebugMode(true) + reg.SetDryRunMode(true) + + clone := reg.Clone() + + // Verify clone has same translators + if !clone.HasRequestTranslator(FormatOpenAI, FormatClaude) { + t.Error("Clone should have the same translators") + } + + // Verify clone has same settings + if !clone.debugMode.Load() { + t.Error("Clone should have same debug mode") + } + if !clone.dryRunMode.Load() { + t.Error("Clone should have same dry-run mode") + } + + // Modify original, clone should be unaffected + reg.Unregister(FormatOpenAI, FormatClaude) + + if !clone.HasRequestTranslator(FormatOpenAI, FormatClaude) { + t.Error("Clone should be independent of original") + } +} + +func TestReplaceRegistry(t *testing.T) { + // Save original + original := defaultRegistry + + newReg := NewRegistry() + newReg.Register("test", "test2", func(model string, data []byte, stream bool) []byte { + return data + }, ResponseTransform{}) + + old := ReplaceRegistry(newReg) + + if old != original { + t.Error("ReplaceRegistry should return the old registry") + } + + if !defaultRegistry.HasRequestTranslator("test", "test2") { + t.Error("New registry should be active") + } + + // Restore original + ReplaceRegistry(original) +} + +func TestReplaceRegistry_Nil(t *testing.T) { + result := ReplaceRegistry(nil) + if result != nil { + t.Error("ReplaceRegistry(nil) should return nil") + } +} + +func TestListRegisteredPairs(t *testing.T) { + reg := NewRegistry() + + reg.Register(FormatOpenAI, FormatClaude, func(model string, data []byte, stream bool) []byte { + return data + }, ResponseTransform{}) + reg.Register(FormatClaude, FormatGemini, func(model string, data []byte, stream bool) []byte { + return data + }, ResponseTransform{}) + + pairs := reg.ListRegisteredPairs() + + if len(pairs) != 2 { + t.Errorf("Expected 2 pairs, got %d", len(pairs)) + } + + foundPairs := make(map[string]bool) + for _, p := range pairs { + key := string(p[0]) + "->" + string(p[1]) + foundPairs[key] = true + } + + if !foundPairs["openai->claude"] { + t.Error("Should contain openai->claude pair") + } + if !foundPairs["claude->gemini"] { + t.Error("Should contain claude->gemini pair") + } +} + +func TestClear(t *testing.T) { + reg := NewRegistry() + + reg.Register(FormatOpenAI, FormatClaude, func(model string, data []byte, stream bool) []byte { + return data + }, ResponseTransform{}) + + reg.Clear() + + pairs := reg.ListRegisteredPairs() + if len(pairs) != 0 { + t.Error("Clear should remove all translators") + } +} + +func TestHasRequestTransformer(t *testing.T) { + reg := NewRegistry() + + reg.Register(FormatOpenAI, FormatClaude, func(model string, data []byte, stream bool) []byte { + return data + }, ResponseTransform{}) + + // HasRequestTransformer is an alias for HasRequestTranslator + if !reg.HasRequestTransformer(FormatOpenAI, FormatClaude) { + t.Error("HasRequestTransformer should return true for registered translator") + } + if reg.HasRequestTransformer(FormatClaude, FormatOpenAI) { + t.Error("HasRequestTransformer should return false for unregistered translator") + } +} + +func TestPackageLevelResilienceFunctions(t *testing.T) { + // Test package-level Unregister (on default registry) + // This just verifies it doesn't panic + Unregister("nonexistent", "format") + + // Test package-level HasRequestTransformer + _ = HasRequestTransformer(FormatOpenAI, FormatClaude) + + // Test package-level ListRegisteredPairs + pairs := ListRegisteredPairs() + if pairs == nil { + t.Error("ListRegisteredPairs should not return nil") + } + + // Test package-level TranslateRequestWithRecovery + result, _ := TranslateRequestWithRecovery(FormatOpenAI, FormatClaude, "model", []byte("test"), false) + if result == nil { + t.Error("TranslateRequestWithRecovery should not return nil result") + } + + // Test package-level CloneRegistry + clone := CloneRegistry() + if clone == nil { + t.Error("CloneRegistry should not return nil") + } +} + +// Helper function +func containsStr(s, substr string) bool { + for i := 0; i <= len(s)-len(substr); i++ { + if s[i:i+len(substr)] == substr { + return true + } + } + return false +}