Package xyz.tcheeric.cashu.voucher.nostr

Class NostrClientAdapter

java.lang.Object
xyz.tcheeric.cashu.voucher.nostr.NostrClientAdapter
public class NostrClientAdapter extends Object
Adapter for Nostr relay client operations.

This adapter provides a clean abstraction over Nostr relay interactions, handling connection management, event publishing, and subscription management. It's designed to work with any underlying Nostr library implementation.

Features

  • Multi-relay connection management
  • Automatic reconnection on failure
  • Async event publishing with confirmation
  • REQ/CLOSE subscription lifecycle
  • Connection pooling and health checks

Usage Example

 List<String> relays = List.of("wss://relay1.example.com", "wss://relay2.example.com");
 NostrClientAdapter client = new NostrClientAdapter(relays, 5000, 3);

 try {
     // Connect to relays
     client.connect();

     // Publish an event
     NostrEvent event = ...;
     boolean success = client.publishEvent(event, 3000);

     // Query events
     NostrFilter filter = NostrFilter.builder()
         .kinds(List.of(30078))
         .authors(List.of(pubkey))
         .build();

     List<NostrEvent> events = client.queryEvents(filter, 5000);

 } finally {
     client.disconnect();
 }

Thread Safety

This class is thread-safe. All connection state is managed using concurrent data structures and atomic operations.

See Also:
  • GenericEvent

  • Constructor Details

    • NostrClientAdapter

      public NostrClientAdapter(@NonNull @NonNull List<String> relayUrls, long connectionTimeoutMs, int maxRetries)
      Creates a NostrClientAdapter with specified configuration.
      Parameters:
      relayUrls - list of relay WebSocket URLs (must not be null or empty)
      connectionTimeoutMs - timeout for connection attempts in milliseconds
      maxRetries - maximum number of retry attempts for failed operations
      Throws:
      IllegalArgumentException - if parameters are invalid

  • Method Details

    • connect

      public void connect()
      Connects to all configured relays.

      This method attempts to connect to all relays in parallel. If some relays fail to connect, the adapter will still function with the available relays.

      Throws:
      VoucherNostrException - if all relays fail to connect

    • disconnect

      public void disconnect()
      Disconnects from all relays.

      This method closes all active connections and clears the connection pool. After calling this method, connect() must be called again before any operations can be performed.

    • publishEvent

      public boolean publishEvent(@NonNull @NonNull nostr.event.impl.GenericEvent event, long timeoutMs)
      Publishes an event to all connected relays.

      This method publishes the event to all relays in parallel and waits for confirmations. The operation is considered successful if at least one relay confirms receipt.

      Parameters:
      event - the event to publish (must not be null)
      timeoutMs - timeout for waiting for confirmations
      Returns:
      true if at least one relay confirmed receipt, false otherwise
      Throws:
      VoucherNostrException - if not connected or operation fails

    • queryEvents

      public List<nostr.event.impl.GenericEvent> queryEvents(@NonNull @NonNull String subscriptionId, long timeoutMs)
      Queries events from relays matching the given filter.

      This method sends a REQ message to all connected relays and collects matching events. Duplicate events (same ID) are automatically deduplicated.

      Parameters:
      subscriptionId - the subscription ID for this query
      timeoutMs - timeout for waiting for responses
      Returns:
      list of matching events (never null, may be empty)
      Throws:
      VoucherNostrException - if not connected or operation fails

    • isConnected

      public boolean isConnected()
      Checks if currently connected to at least one relay.
      Returns:
      true if connected, false otherwise

    • getConnectedRelayCount

      public int getConnectedRelayCount()
      Gets the number of currently connected relays.
      Returns:
      number of active connections

    • getConnectedRelays

      public List<String> getConnectedRelays()
      Gets the list of connected relay URLs.
      Returns:
      unmodifiable list of connected relay URLs