Package xyz.tcheeric.cashu.voucher.nostr.config

Class NostrRelayConfig

java.lang.Object
xyz.tcheeric.cashu.voucher.nostr.config.NostrRelayConfig
public class NostrRelayConfig extends Object
Configuration for Nostr relay connections.

This class encapsulates all configuration needed to connect to and manage Nostr relays, including URLs, timeouts, retry policies, and health check settings.

Design Philosophy

This is an immutable configuration object that follows the builder pattern for flexible construction. It provides sensible defaults while allowing full customization for production deployments.

Configuration Categories

  • Relay URLs: List of WebSocket relay endpoints
  • Connection Settings: Timeouts, retry attempts, backoff strategy
  • Operation Settings: Publish/query timeouts, batch sizes
  • Health Checks: Ping intervals, failure thresholds

Usage Example

 // Default configuration with custom relays
 NostrRelayConfig config = NostrRelayConfig.builder()
     .relayUrl("wss://relay.damus.io")
     .relayUrl("wss://relay.cashu.xyz")
     .build();

 // Production configuration with custom timeouts
 NostrRelayConfig config = NostrRelayConfig.builder()
     .relayUrl("wss://relay1.example.com")
     .relayUrl("wss://relay2.example.com")
     .connectionTimeoutMs(10000L)
     .publishTimeoutMs(8000L)
     .queryTimeoutMs(15000L)
     .maxRetries(5)
     .build();

 // Use with NostrClientAdapter
 NostrClientAdapter adapter = new NostrClientAdapter(
     config.getRelayUrls(),
     config.getConnectionTimeoutMs(),
     config.getMaxRetries()
 );

Default Values

  • Connection timeout: 5000ms (5 seconds)
  • Publish timeout: 5000ms (5 seconds)
  • Query timeout: 10000ms (10 seconds)
  • Max retries: 3
  • Retry backoff: Exponential (1s, 2s, 4s)
  • Health check interval: 60000ms (1 minute)
  • Max consecutive failures: 3

Thread Safety

This class is immutable and thread-safe. All collections are defensively copied and returned as unmodifiable views.

See Also:

  • Field Details

    • DEFAULT_CONNECTION_TIMEOUT_MS

      public static final long DEFAULT_CONNECTION_TIMEOUT_MS
      Default connection timeout in milliseconds.
      See Also:

    • DEFAULT_PUBLISH_TIMEOUT_MS

      public static final long DEFAULT_PUBLISH_TIMEOUT_MS
      Default publish timeout in milliseconds.
      See Also:

    • DEFAULT_QUERY_TIMEOUT_MS

      public static final long DEFAULT_QUERY_TIMEOUT_MS
      Default query timeout in milliseconds.
      See Also:

    • DEFAULT_MAX_RETRIES

      public static final int DEFAULT_MAX_RETRIES
      Default maximum retry attempts.
      See Also:

    • DEFAULT_HEALTH_CHECK_INTERVAL_MS

      public static final long DEFAULT_HEALTH_CHECK_INTERVAL_MS
      Default health check interval in milliseconds.
      See Also:

    • DEFAULT_MAX_CONSECUTIVE_FAILURES

      public static final int DEFAULT_MAX_CONSECUTIVE_FAILURES
      Default maximum consecutive failures before marking relay as unhealthy.
      See Also:

    • DEFAULT_BATCH_SIZE

      public static final int DEFAULT_BATCH_SIZE
      Default batch size for bulk operations.
      See Also:

    • WELL_KNOWN_RELAYS

      public static final List<String> WELL_KNOWN_RELAYS
      Well-known public Nostr relays (for convenience).

    • CASHU_RELAYS

      public static final List<String> CASHU_RELAYS
      Cashu-specific relay suggestions.

  • Constructor Details

    • NostrRelayConfig

      public NostrRelayConfig()

  • Method Details

    • getRelayUrls

      public List<String> getRelayUrls()
      Gets an unmodifiable copy of the relay URLs.
      Returns:
      unmodifiable list of relay URLs

    • getRelayCount

      public int getRelayCount()
      Gets the number of configured relays.
      Returns:
      relay count

    • hasMinimumRelays

      public boolean hasMinimumRelays()
      Checks if the configuration has at least the minimum required relays.
      Returns:
      true if minimum relay requirement is met

    • validate

      public void validate()
      Validates the configuration.
      Throws:
      IllegalStateException - if configuration is invalid

    • defaultConfig

      public static NostrRelayConfig defaultConfig()
      Creates a default configuration with Cashu relays.
      Returns:
      default NostrRelayConfig

    • testConfig

      public static NostrRelayConfig testConfig()
      Creates a configuration for testing with localhost relay.
      Returns:
      test NostrRelayConfig

    • productionConfig

      public static NostrRelayConfig productionConfig(@NonNull @NonNull List<String> relayUrls)
      Creates a configuration for production with custom relays.
      Parameters:
      relayUrls - list of production relay URLs
      Returns:
      production NostrRelayConfig

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object