feat(translator): add resilience and recovery strategies

Add translation recovery with direct hit, fallback chain, and
auto-detect strategies for robust format conversion.
This commit is contained in:
Finessse
2025-12-28 07:07:35 +07:00
parent 40c46acc08
commit 2874e52a2a
2 changed files with 682 additions and 0 deletions
+346
View File
@@ -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()
}
+336
View File
@@ -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
}