Zum Inhalt

Options API Reference

Der Typ Options ermöglicht die Konfiguration des Verhaltens des Socket.IO-Clients.

Inhaltsverzeichnis

Definition

type Options struct {
  Auth              map[string]interface{}
  Headers           map[string]string
  ReconnectAttempts int
  ReconnectDelay    time.Duration
  ReconnectDelayMax time.Duration
  Timeout           time.Duration
  AckTimeout        time.Duration
}

Alle Optionen sind optional. Wenn sie nicht angegeben werden, werden vernünftige Standardwerte verwendet.

Authentifizierungsoptionen

Auth

Auth map[string]interface{}

Authentifizierungsdaten, die während des initialen Handshakes gesendet werden. Nützlich für JWT-Token, Anmeldedaten usw.

Typ: map[string]interface{} Standardwert: nil (ohne Authentifizierung)

Beispiel:

client := socketio.New("ws://localhost:3000", socketio.Options{
  Auth: map[string]interface{}{
    "token": "eyJhbGciOiJIUzI1NiIs...",
  },
})

Beispiel mit JWT:

client := socketio.New("ws://localhost:3000", socketio.Options{
  Auth: map[string]interface{}{
    "token": jwtToken,
    "userId": "user-123",
  },
})

Beispiel mit Anmeldedaten:

client := socketio.New("ws://localhost:3000", socketio.Options{
  Auth: map[string]interface{}{
    "username": "juan",
    "password": "secreto",
  },
})

Headers

Headers map[string]string

Benutzerdefinierte HTTP-Header, die während der initialen Verbindung gesendet werden.

Typ: map[string]string Standardwert: nil (ohne benutzerdefinierte Header)

Beispiel:

client := socketio.New("ws://localhost:3000", socketio.Options{
  Headers: map[string]string{
    "Authorization": "Bearer token-123",
    "X-API-Key": "api-key-456",
    "User-Agent": "MiApp/1.0",
  },
})

Wiederverbindungsoptionen

ReconnectAttempts

ReconnectAttempts int

Maximale Anzahl von Wiederverbindungsversuchen, bevor aufgegeben wird.

Typ: int Standardwert: 5 Spezieller Wert: -1 = unendliche Versuche

Beispiel:

// 10 Wiederverbindungsversuche
client := socketio.New("ws://localhost:3000", socketio.Options{
  ReconnectAttempts: 10,
})

// Unendliche Versuche (mit Vorsicht verwenden)
client := socketio.New("ws://localhost:3000", socketio.Options{
  ReconnectAttempts: -1,
})

// Ohne automatische Wiederverbindung
client := socketio.New("ws://localhost:3000", socketio.Options{
  ReconnectAttempts: 0,
})

ReconnectDelay

ReconnectDelay time.Duration

Anfängliche Wartezeit vor dem ersten Wiederverbindungsversuch. Dieser Wert wird bei jedem Versuch exponentiell erhöht.

Typ: time.Duration Standardwert: 1 * time.Second

Beispiel:

// 2 Sekunden vor dem ersten Versuch warten
client := socketio.New("ws://localhost:3000", socketio.Options{
  ReconnectDelay: 2 * time.Second,
})

// Schnelle Wiederverbindung (500ms)
client := socketio.New("ws://localhost:3000", socketio.Options{
  ReconnectDelay: 500 * time.Millisecond,
})

ReconnectDelayMax

ReconnectDelayMax time.Duration

Maximale Wartezeit zwischen Wiederverbindungsversuchen. Der exponentielle Backoff überschreitet diesen Wert nicht.

Typ: time.Duration Standardwert: 5 * time.Second

Beispiel:

// Maximale Verzögerung auf 10 Sekunden begrenzen
client := socketio.New("ws://localhost:3000", socketio.Options{
  ReconnectDelay:    time.Second,
  ReconnectDelayMax: 10 * time.Second,
})

Verhalten des exponentiellen Backoffs:

// Mit ReconnectDelay = 1s und ReconnectDelayMax = 5s:
// Versuch 1: wartet 1s
// Versuch 2: wartet 2s
// Versuch 3: wartet 4s
// Versuch 4: wartet 5s (begrenzt durch ReconnectDelayMax)
// Versuch 5: wartet 5s

Timeout-Optionen

Timeout

Timeout time.Duration

Timeout für die Herstellung der initialen Verbindung.

Typ: time.Duration Standardwert: 20 * time.Second

Beispiel:

// 30-Sekunden-Timeout für langsame Verbindung
client := socketio.New("ws://localhost:3000", socketio.Options{
  Timeout: 30 * time.Second,
})

// Kurzer Timeout für schnelles Fehlschlagen (5 Sekunden)
client := socketio.New("ws://localhost:3000", socketio.Options{
  Timeout: 5 * time.Second,
})

AckTimeout

AckTimeout time.Duration

Globaler Timeout zum Warten auf Acknowledgments. Wenn der Server nicht innerhalb dieser Zeit antwortet, erhält der Acknowledgment-Callback nil.

Typ: time.Duration Standardwert: 5 * time.Second

Beispiel:

// 10-Sekunden-Timeout für langsame Operationen
client := socketio.New("ws://localhost:3000", socketio.Options{
  AckTimeout: 10 * time.Second,
})

client.EmitWithAck("slow-operation", func(response ...interface{}) {
  if response == nil {
    fmt.Println("Timeout: Operation dauerte länger als 10 Sekunden")
    return
  }
  fmt.Println("Antwort:", response[0])
}, "datos")

Verbindungsoptionen

Path

Hinweis: Diese Option ist nicht im aktuellen Struct implementiert, kann aber in Zukunft hinzugefügt werden.

Der Pfad des Socket.IO-Endpunkts auf dem Server.

Standardwert: /socket.io/

Beispiele

Grundlegende Konfiguration

client := socketio.New("ws://localhost:3000", socketio.Options{
  ReconnectAttempts: 5,
  Timeout: 30 * time.Second,
})

Konfiguration mit Authentifizierung

client := socketio.New("ws://api.example.com", socketio.Options{
  Auth: map[string]interface{}{
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "userId": "user-123",
  },
  Headers: map[string]string{
    "Authorization": "Bearer token-456",
  },
})

Konfiguration für aggressive Wiederverbindung

client := socketio.New("ws://localhost:3000", socketio.Options{
  ReconnectAttempts: 10,
  ReconnectDelay:    500 * time.Millisecond, // Schnell versuchen
  ReconnectDelayMax: 3 * time.Second,        // Aber nicht lange warten
})

Konfiguration für langsame Verbindungen

client := socketio.New("ws://slow-server.example.com", socketio.Options{
  Timeout:    60 * time.Second, // Langer Timeout für Verbindung
  AckTimeout: 30 * time.Second, // Langer Timeout für Antworten
})

Konfiguration ohne Wiederverbindung

// Für Fälle, in denen keine automatische Wiederverbindung gewünscht ist
client := socketio.New("ws://localhost:3000", socketio.Options{
  ReconnectAttempts: 0, // Wiederverbindung deaktivieren
})

client.OnDisconnect(func(reason string) {
  fmt.Println("Getrennt, ohne Wiederverbindungsversuche")
  // Benutzerdefinierte Logik hier implementieren
})

Vollständige Konfiguration

client := socketio.New("wss://api.example.com", socketio.Options{
  // Authentifizierung
  Auth: map[string]interface{}{
    "token": getAuthToken(),
    "userId": getCurrentUserId(),
    "deviceId": getDeviceId(),
  },

  // Benutzerdefinierte Header
  Headers: map[string]string{
    "Authorization": "Bearer " + getJWT(),
    "X-API-Key": "api-key-123",
    "X-Client-Version": "1.0.0",
  },

  // Konfigurierte Wiederverbindung
  ReconnectAttempts: 10,
  ReconnectDelay:    time.Second,
  ReconnectDelayMax: 5 * time.Second,

  // Konfigurierte Timeouts
  Timeout:    30 * time.Second,
  AckTimeout: 10 * time.Second,
})

Dynamische Konfiguration

func createClient(userType string) *socketio.Socket {
  opts := socketio.Options{
    ReconnectAttempts: 5,
    Timeout: 20 * time.Second,
  }

  // Spezifische Konfiguration nach Benutzertyp
  switch userType {
  case "admin":
    opts.Auth = map[string]interface{}{
      "token": getAdminToken(),
      "role": "admin",
    }
    opts.ReconnectAttempts = 10 // Mehr Versuche für Admins

  case "guest":
    opts.Auth = nil // Ohne Authentifizierung
    opts.ReconnectAttempts = 3 // Weniger Versuche für Gäste

  default:
    opts.Auth = map[string]interface{}{
      "token": getUserToken(),
      "role": "user",
    }
  }

  return socketio.New("ws://localhost:3000", opts)
}

Konfiguration mit Validierung

func newClientWithValidation(url string, opts socketio.Options) (*socketio.Socket, error) {
  // Optionen validieren
  if opts.ReconnectDelay > opts.ReconnectDelayMax {
    return nil, fmt.Errorf("ReconnectDelay kann nicht größer als ReconnectDelayMax sein")
  }

  if opts.Timeout < time.Second {
    return nil, fmt.Errorf("Timeout muss mindestens 1 Sekunde betragen")
  }

  if opts.AckTimeout < 100*time.Millisecond {
    return nil, fmt.Errorf("AckTimeout zu kurz")
  }

  return socketio.New(url, opts), nil
}

Konfiguration nach Umgebung

func getOptions(env string) socketio.Options {
  opts := socketio.Options{}

  switch env {
  case "development":
    opts.Timeout = 60 * time.Second // Lange Timeouts für Debugging
    opts.AckTimeout = 30 * time.Second
    opts.ReconnectAttempts = 10

  case "staging":
    opts.Timeout = 30 * time.Second
    opts.AckTimeout = 10 * time.Second
    opts.ReconnectAttempts = 5

  case "production":
    opts.Timeout = 20 * time.Second
    opts.AckTimeout = 5 * time.Second
    opts.ReconnectAttempts = 5
    opts.Headers = map[string]string{
      "X-Environment": "production",
    }

  default:
    // Standardwerte
    opts.Timeout = 20 * time.Second
    opts.ReconnectAttempts = 5
  }

  return opts
}

// Verwendung
client := socketio.New("ws://localhost:3000", getOptions(os.Getenv("ENV")))

Standardwerte

Wenn keine Option angegeben wird, sind dies die Standardwerte:

Options{
  Auth:              nil,
  Headers:           nil,
  ReconnectAttempts: 5,
  ReconnectDelay:    1 * time.Second,
  ReconnectDelayMax: 5 * time.Second,
  Timeout:           20 * time.Second,
  AckTimeout:        5 * time.Second,
}

Best Practices

1. Timeouts an das Netzwerk anpassen

// Für mobile oder instabile Netzwerke
opts := socketio.Options{
  Timeout:    30 * time.Second, // Verbindung kann dauern
  AckTimeout: 10 * time.Second, // Antworten können dauern
  ReconnectDelay: 2 * time.Second, // Nicht zu schnell wiederverbinden
}

2. Sichere Authentifizierung verwenden

// Immer Token verwenden, niemals direkte Anmeldedaten
opts := socketio.Options{
  Auth: map[string]interface{}{
    "token": getSecureToken(), // JWT oder ähnlich
  },
}

// Dies in der Produktion vermeiden
opts := socketio.Options{
  Auth: map[string]interface{}{
    "username": "admin", // ❌ Unsicher
    "password": "1234",  // ❌ Sehr unsicher
  },
}

3. Wiederverbindung nach Anwendungsfall konfigurieren

// Kritische Anwendung: viele Versuche
criticalApp := socketio.Options{
  ReconnectAttempts: 20,
  ReconnectDelayMax: 30 * time.Second,
}

// Temporäre Anwendung: wenige Versuche
temporaryApp := socketio.Options{
  ReconnectAttempts: 3,
  ReconnectDelayMax: 5 * time.Second,
}

4. Konfiguration in der Entwicklung protokollieren

opts := socketio.Options{
  ReconnectAttempts: 5,
  Timeout: 30 * time.Second,
}

if os.Getenv("DEBUG") == "true" {
  fmt.Printf("Socket.IO-Optionen:\n")
  fmt.Printf("  ReconnectAttempts: %d\n", opts.ReconnectAttempts)
  fmt.Printf("  Timeout: %v\n", opts.Timeout)
  fmt.Printf("  AckTimeout: %v\n", opts.AckTimeout)
}

client := socketio.New("ws://localhost:3000", opts)

Siehe auch