negentropy.go raw

   1  // Package negentropy defines the interface for NIP-77 negentropy operations.
   2  package negentropy
   3  
   4  import (
   5  	"context"
   6  
   7  	commonv1 "next.orly.dev/pkg/proto/orlysync/common/v1"
   8  )
   9  
  10  // ClientSession represents an active client negentropy session.
  11  type ClientSession struct {
  12  	SubscriptionID string
  13  	ConnectionID   string
  14  	CreatedAt      int64
  15  	LastActivity   int64
  16  	RoundCount     int32
  17  }
  18  
  19  // Handler defines the interface for handling NIP-77 negentropy messages.
  20  // This interface is implemented by both the gRPC client and the embedded handler.
  21  type Handler interface {
  22  	// HandleNegOpen processes a NEG-OPEN message from a client.
  23  	// Returns: message, haveIDs, needIDs, complete, errorStr, error
  24  	HandleNegOpen(ctx context.Context, connectionID, subscriptionID string, filter *commonv1.Filter, initialMessage []byte) ([]byte, [][]byte, [][]byte, bool, string, error)
  25  
  26  	// HandleNegMsg processes a NEG-MSG message from a client.
  27  	// Returns: message, haveIDs, needIDs, complete, errorStr, error
  28  	HandleNegMsg(ctx context.Context, connectionID, subscriptionID string, message []byte) ([]byte, [][]byte, [][]byte, bool, string, error)
  29  
  30  	// HandleNegClose processes a NEG-CLOSE message from a client.
  31  	HandleNegClose(ctx context.Context, connectionID, subscriptionID string) error
  32  
  33  	// ListSessions returns active client negentropy sessions.
  34  	ListSessions(ctx context.Context) ([]*ClientSession, error)
  35  
  36  	// CloseSession forcefully closes a client session.
  37  	CloseSession(ctx context.Context, connectionID, subscriptionID string) error
  38  
  39  	// Ready returns a channel that closes when the handler is ready.
  40  	Ready() <-chan struct{}
  41  
  42  	// Close cleans up resources.
  43  	Close() error
  44  }
  45