Moves subscription management from Ammolite to Quatrz

.gitignore

@@ -14,6 +14,7 @@
 /.idea/studiobot.xml
 /.idea/other.xml
 /.idea/runConfigurations.xml
+/.idea/ChatHistory_schema_v2.xml
 .DS_Store
 /build
 /captures

amethyst/src/main/java/com/vitorpamplona/amethyst/model/Account.kt

@@ -101,7 +101,7 @@ import com.vitorpamplona.quartz.nip01Core.hints.EventHintProvider
 import com.vitorpamplona.quartz.nip01Core.hints.PubKeyHintProvider
 import com.vitorpamplona.quartz.nip01Core.metadata.MetadataEvent
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
-import com.vitorpamplona.quartz.nip01Core.relay.client.acessories.downloadFirstEvent
+import com.vitorpamplona.quartz.nip01Core.relay.client.accessories.downloadFirstEvent
 import com.vitorpamplona.quartz.nip01Core.relay.client.single.IRelayClient
 import com.vitorpamplona.quartz.nip01Core.relay.filters.Filter
 import com.vitorpamplona.quartz.nip01Core.relay.normalizer.NormalizedRelayUrl

amethyst/src/main/java/com/vitorpamplona/amethyst/service/relayClient/CacheClientConnector.kt

@@ -23,8 +23,8 @@ package com.vitorpamplona.amethyst.service.relayClient
 import com.vitorpamplona.amethyst.model.LocalCache
 import com.vitorpamplona.quartz.nip01Core.core.HexKey
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
-import com.vitorpamplona.quartz.nip01Core.relay.client.acessories.EventCollector
+import com.vitorpamplona.quartz.nip01Core.relay.client.accessories.EventCollector
-import com.vitorpamplona.quartz.nip01Core.relay.client.acessories.RelayInsertConfirmationCollector
+import com.vitorpamplona.quartz.nip01Core.relay.client.accessories.RelayInsertConfirmationCollector
 import com.vitorpamplona.quartz.nip01Core.relay.normalizer.NormalizedRelayUrl
 
 class CacheClientConnector(

amethyst/src/main/java/com/vitorpamplona/amethyst/service/relayClient/authCommand/model/AuthCoordinator.kt

@@ -24,7 +24,7 @@ import android.util.Log
 import com.vitorpamplona.amethyst.isDebug
 import com.vitorpamplona.amethyst.model.Account
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
-import com.vitorpamplona.quartz.nip01Core.relay.client.acessories.RelayAuthenticator
+import com.vitorpamplona.quartz.nip01Core.relay.client.accessories.RelayAuthenticator
 
 class ScreenAuthAccount(
     val account: Account,

amethyst/src/main/java/com/vitorpamplona/amethyst/service/relayClient/eoseManagers/BaseEoseManager.kt

@@ -23,9 +23,9 @@ package com.vitorpamplona.amethyst.service.relayClient.eoseManagers
 import android.util.Log
 import com.vitorpamplona.amethyst.isDebug
 import com.vitorpamplona.ammolite.relays.BundledUpdate
-import com.vitorpamplona.ammolite.relays.datasources.SubscriptionController
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.single.newSubId
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.SubscriptionController
 import com.vitorpamplona.quartz.nip01Core.relay.normalizer.NormalizedRelayUrl
 import kotlinx.coroutines.Dispatchers
 

amethyst/src/main/java/com/vitorpamplona/amethyst/service/relayClient/eoseManagers/PerUniqueIdEoseManager.kt

@@ -22,10 +22,10 @@ package com.vitorpamplona.amethyst.service.relayClient.eoseManagers
 
 import com.vitorpamplona.amethyst.service.relays.EOSEByKey
 import com.vitorpamplona.amethyst.service.relays.SincePerRelayMap
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.groupByRelay
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.normalizer.NormalizedRelayUrl
 import kotlin.collections.distinctBy
 

amethyst/src/main/java/com/vitorpamplona/amethyst/service/relayClient/eoseManagers/PerUserAndFollowListEoseManager.kt

@@ -23,10 +23,10 @@ package com.vitorpamplona.amethyst.service.relayClient.eoseManagers
 import com.vitorpamplona.amethyst.model.User
 import com.vitorpamplona.amethyst.service.relays.EOSEAccountKey
 import com.vitorpamplona.amethyst.service.relays.SincePerRelayMap
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.groupByRelay
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.normalizer.NormalizedRelayUrl
 import kotlin.collections.distinctBy
 

amethyst/src/main/java/com/vitorpamplona/amethyst/service/relayClient/eoseManagers/PerUserEoseManager.kt

@@ -23,10 +23,10 @@ package com.vitorpamplona.amethyst.service.relayClient.eoseManagers
 import com.vitorpamplona.amethyst.model.User
 import com.vitorpamplona.amethyst.service.relays.EOSEAccountFast
 import com.vitorpamplona.amethyst.service.relays.SincePerRelayMap
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.groupByRelay
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.normalizer.NormalizedRelayUrl
 import kotlin.collections.distinctBy
 

amethyst/src/main/java/com/vitorpamplona/amethyst/service/relayClient/notifyCommand/model/NotifyCoordinator.kt

@@ -21,7 +21,7 @@
 package com.vitorpamplona.amethyst.service.relayClient.notifyCommand.model
 
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
-import com.vitorpamplona.quartz.nip01Core.relay.client.acessories.RelayNotifier
+import com.vitorpamplona.quartz.nip01Core.relay.client.accessories.RelayNotifier
 
 class NotifyCoordinator(
     client: NostrClient,

amethyst/src/main/java/com/vitorpamplona/amethyst/service/relayClient/reqCommand/account/metadata/AccountMetadataEoseManager.kt

@@ -24,9 +24,9 @@ import com.vitorpamplona.amethyst.model.User
 import com.vitorpamplona.amethyst.service.relayClient.eoseManagers.PerUserEoseManager
 import com.vitorpamplona.amethyst.service.relayClient.reqCommand.account.AccountQueryState
 import com.vitorpamplona.amethyst.service.relays.SincePerRelayMap
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.FlowPreview
 import kotlinx.coroutines.Job

amethyst/src/main/java/com/vitorpamplona/amethyst/service/relayClient/reqCommand/account/nip01Notifications/AccountNotificationsEoseManager.kt

@@ -24,9 +24,9 @@ import com.vitorpamplona.amethyst.model.User
 import com.vitorpamplona.amethyst.service.relayClient.eoseManagers.PerUserEoseManager
 import com.vitorpamplona.amethyst.service.relayClient.reqCommand.account.AccountQueryState
 import com.vitorpamplona.amethyst.service.relays.SincePerRelayMap
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.FlowPreview
 import kotlinx.coroutines.Job

amethyst/src/main/java/com/vitorpamplona/amethyst/service/relayClient/reqCommand/account/nip59GiftWraps/AccountGiftWrapsEoseManager.kt

@@ -24,9 +24,9 @@ import com.vitorpamplona.amethyst.model.User
 import com.vitorpamplona.amethyst.service.relayClient.eoseManagers.PerUserEoseManager
 import com.vitorpamplona.amethyst.service.relayClient.reqCommand.account.AccountQueryState
 import com.vitorpamplona.amethyst.service.relays.SincePerRelayMap
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.FlowPreview
 import kotlinx.coroutines.Job

amethyst/src/main/java/com/vitorpamplona/amethyst/service/relays/EOSE.kt

@@ -21,7 +21,6 @@
 package com.vitorpamplona.amethyst.service.relays
 
 import androidx.collection.LruCache
-import com.vitorpamplona.amethyst.model.LocalCache.users
 import com.vitorpamplona.amethyst.model.User
 import com.vitorpamplona.ammolite.relays.filters.MutableTime
 import com.vitorpamplona.quartz.nip01Core.relay.normalizer.NormalizedRelayUrl
@@ -56,10 +55,6 @@ class EOSERelayList {
     ) = addOrUpdate(relay, time)
 }
 
-class EOSEFollowList(
-    cacheSize: Int = 200,
-) : EOSEByKey<String>(cacheSize)
-
 open class EOSEByKey<U : Any>(
     cacheSize: Int = 200,
 ) {
@@ -89,10 +84,6 @@ open class EOSEByKey<U : Any>(
     ) = addOrUpdate(listCode, relayUrl, time)
 }
 
-class EOSEAccount(
-    cacheSize: Int = 20,
-) : EOSEAccountKey<String>(cacheSize)
-
 open class EOSEAccountKey<U : Any>(
     cacheSize: Int = 20,
 ) {

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/chats/rooms/datasource/DMsFromUserFilterSubAssembler.kt

@@ -23,9 +23,9 @@ package com.vitorpamplona.amethyst.ui.screen.loggedIn.chats.rooms.datasource
 import com.vitorpamplona.amethyst.model.User
 import com.vitorpamplona.amethyst.service.relayClient.eoseManagers.PerUserEoseManager
 import com.vitorpamplona.amethyst.service.relays.SincePerRelayMap
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.FlowPreview
 import kotlinx.coroutines.Job

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/chats/rooms/datasource/FollowingEphemeralChatSubAssembler.kt

@@ -23,9 +23,9 @@ package com.vitorpamplona.amethyst.ui.screen.loggedIn.chats.rooms.datasource
 import com.vitorpamplona.amethyst.model.User
 import com.vitorpamplona.amethyst.service.relayClient.eoseManagers.PerUserEoseManager
 import com.vitorpamplona.amethyst.service.relays.SincePerRelayMap
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.FlowPreview
 import kotlinx.coroutines.Job

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/chats/rooms/datasource/FollowingPublicChatSubAssembler.kt

@@ -23,9 +23,9 @@ package com.vitorpamplona.amethyst.ui.screen.loggedIn.chats.rooms.datasource
 import com.vitorpamplona.amethyst.model.User
 import com.vitorpamplona.amethyst.service.relayClient.eoseManagers.PerUserEoseManager
 import com.vitorpamplona.amethyst.service.relays.SincePerRelayMap
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.FlowPreview
 import kotlinx.coroutines.Job

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/discover/datasource/DiscoveryFollowsDiscoverySubAssembler1.kt

@@ -26,9 +26,9 @@ import com.vitorpamplona.amethyst.service.relays.SincePerRelayMap
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.discover.nip23LongForm.makeLongFormFilter
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.discover.nip90DVMs.makeContentDVMsFilter
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.discover.nip99Classifieds.makeClassifiedsFilter
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.FlowPreview
 import kotlinx.coroutines.Job

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/discover/datasource/DiscoveryFollowsDiscoverySubAssembler2.kt

@@ -25,9 +25,9 @@ import com.vitorpamplona.amethyst.service.relayClient.eoseManagers.PerUserAndFol
 import com.vitorpamplona.amethyst.service.relays.SincePerRelayMap
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.discover.nip51FollowSets.makeFollowSetsFilter
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.discover.nip53LiveActivities.makeLiveActivitiesFilter
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.FlowPreview
 import kotlinx.coroutines.Job

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/discover/datasource/DiscoveryFollowsDiscoverySubAssembler3.kt

@@ -25,9 +25,9 @@ import com.vitorpamplona.amethyst.service.relayClient.eoseManagers.PerUserAndFol
 import com.vitorpamplona.amethyst.service.relays.SincePerRelayMap
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.discover.nip28Chats.makePublicChatsFilter
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.discover.nip72Communities.makeCommunitiesFilter
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.FlowPreview
 import kotlinx.coroutines.Job

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/home/datasource/nip65Follows/HomeOutboxEventsEoseManager.kt

@@ -37,9 +37,9 @@ import com.vitorpamplona.amethyst.ui.screen.loggedIn.home.datasource.nip01Core.f
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.home.datasource.nip01Core.filterHomePostsByHashtags
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.home.datasource.nip72Communities.filterHomePostsByAllCommunities
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.home.datasource.nip72Communities.filterHomePostsByCommunity
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.FlowPreview
 import kotlinx.coroutines.Job

amethyst/src/main/java/com/vitorpamplona/amethyst/ui/screen/loggedIn/video/datasource/subassemblies/VideoOutboxEventsFilterSubAssembler.kt

@@ -39,9 +39,9 @@ import com.vitorpamplona.amethyst.ui.screen.loggedIn.video.datasource.subassembl
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.video.datasource.subassemblies.nip65Follows.filterPictureAndVideoByFollows
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.video.datasource.subassemblies.nip72Communities.filterPictureAndVideoByAllCommunities
 import com.vitorpamplona.amethyst.ui.screen.loggedIn.video.datasource.subassemblies.nip72Communities.filterPictureAndVideoByCommunity
-import com.vitorpamplona.ammolite.relays.datasources.Subscription
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
 import com.vitorpamplona.quartz.nip01Core.relay.client.pool.RelayBasedFilter
+import com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions.Subscription
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.FlowPreview
 import kotlinx.coroutines.Job

gradle/libs.versions.toml

@@ -1,7 +1,7 @@
 [versions]
 accompanistAdaptive = "0.37.3"
 activityCompose = "1.10.1"
-agp = "8.11.0"
+agp = "8.11.1"
 android-compileSdk = "36"
 android-minSdk = "26"
 android-targetSdk = "36"

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/client/NostrClient.kt

@@ -46,7 +46,29 @@ import kotlinx.coroutines.flow.sample
 import kotlinx.coroutines.flow.stateIn
 
 /**
- * The Nostr Client manages a relay pool, keeps active subscriptions and manages re-sending of events.
+ * The NostrClient manages Nostr relay operations, subscriptions, and event delivery. It maintains:
+ * - A RelayPool for managing connections to a collection of Nostr relays
+ * - Active subscriptions tracking through PoolSubscriptionRepository
+ * - An event outbox for managing unsent events and retry logic
+ * - Automatic relay pool reconciliation based on subscription and event needs
+ *
+ * Core responsibilities include:
+ * - Initializing and managing relay connections using WebSocket builders
+ * - Coordinating subscription state across multiple relays
+ * - Handling event and filter resending when relays disconnect and reconnect
+ * - Aggregating relay status from the pool's state flow
+ * - Maintaining listeners for propagating relay events and state changes
+ *
+ * Features:
+ * - Reactive updating of relay sets based on subscription and outbox activity
+ * - Relayer reconnection strategy that processes pending requests
+ * - Filter comparison logic to detect significant subscription changes and avoid redundant requests
+ * - Integration with RelayStats for tracking relay performance
+ * - Thread-safe reconnection methods using coroutine flows
+ *
+ * The class combines flows from active subscriptions and the event outbox to ensure relays
+ * are connected to all necessary endpoints. It also listens to relay state changes to update
+ * subscriptions and message retries when connections are re-established.
  */
 class NostrClient(
     private val websocketBuilder: WebsocketBuilder,

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/client/accessories/EventCollector.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.quartz.nip01Core.relay.client.acessories
+package com.vitorpamplona.quartz.nip01Core.relay.client.accessories
 
 import android.util.Log
 import com.vitorpamplona.quartz.nip01Core.core.Event

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/client/accessories/NostrClientSendAndWaitExt.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.quartz.nip01Core.relay.client.acessories
+package com.vitorpamplona.quartz.nip01Core.relay.client.accessories
 
 import android.util.Log
 import com.vitorpamplona.quartz.nip01Core.core.Event

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/client/accessories/NostrClientSingleDownloadExt.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.quartz.nip01Core.relay.client.acessories
+package com.vitorpamplona.quartz.nip01Core.relay.client.accessories
 
 import com.vitorpamplona.quartz.nip01Core.core.Event
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/client/accessories/RelayAuthenticator.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.quartz.nip01Core.relay.client.acessories
+package com.vitorpamplona.quartz.nip01Core.relay.client.accessories
 
 import android.util.Log
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/client/accessories/RelayInsertConfirmationCollector.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.quartz.nip01Core.relay.client.acessories
+package com.vitorpamplona.quartz.nip01Core.relay.client.accessories
 
 import android.util.Log
 import com.vitorpamplona.quartz.nip01Core.core.HexKey

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/client/accessories/RelayLogger.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.quartz.nip01Core.relay.client.acessories
+package com.vitorpamplona.quartz.nip01Core.relay.client.accessories
 
 import android.util.Log
 import com.vitorpamplona.quartz.nip01Core.core.Event

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/client/accessories/RelayNotifier.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.quartz.nip01Core.relay.client.acessories
+package com.vitorpamplona.quartz.nip01Core.relay.client.accessories
 
 import android.util.Log
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/client/pool/RelayPool.kt

@@ -41,7 +41,25 @@ val UnsupportedRelayCreation: (url: NormalizedRelayUrl) -> IRelayClient = {
 }
 
 /**
- * RelayPool manages the connection to multiple Relays and lets consumers deal with simple events.
+ * RelayPool manages a collection of Nostr relays, abstracting individual connections and providing
+ * unified methods for sending events, managing subscriptions, and tracking relay states.
+ *
+ * Key features:
+ * - Maintains a cache of relays using LargeCache for efficient relay management
+ * - Propagates event notifications to a shared listener across all relays
+ * - Provides state tracking through RelayPoolStatus (connected/available relays)
+ * - Supports relay lifecycle operations like connect/disconnect/reconnect
+ * - Maintains an immutable createNewRelay function for custom relay creation
+ *
+ * Listens to relay events and:
+ * 1. Forwards callbacks to parent listener
+ * 2. Updates statusFlow when relay connectivity or events change
+ * 3. Automatically reconnects relays that need reconnection
+ *
+ * Common use cases:
+ * - Sending events to multiple relays simultaneously (send method)
+ * - Managing subscriptions across the relay pool (sendRequest/closed methods)
+ * - Maintaining optimal relay connections (updatePool/addRelay/removeRelay methods)
  */
 class RelayPool(
     val listener: IRelayClientListener = EmptyClientListener,

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/client/single/basic/BasicRelayClient.kt

@@ -52,6 +52,24 @@ import com.vitorpamplona.quartz.utils.bytesUsedInMemory
 import java.util.concurrent.atomic.AtomicBoolean
 import kotlin.coroutines.cancellation.CancellationException
 
+/**
+ * A base implementation for a relay client that establishes and manages a WebSocket connection to a Nostr relay.
+ * This class provides fundamental connection handling, message parsing, reconnection logic, and event dispatching.
+ *
+ * @property url The relay's normalized URL.
+ * @property socketBuilder Provides the WebSocket instance for connection.
+ * @property listener Interface to notify the application of relay events and errors.
+ * @property stats Tracks operational statistics of the relay connection.
+ * @property defaultOnConnect Callback executed after a successful connection, allowing subclasses to add initialization logic.
+ *
+ * Reconnection Strategy:
+ * - Uses exponential backoff to retry connections, starting with [DELAY_TO_RECONNECT_IN_MSECS] (500ms).
+ * - Doubles the delay between reconnection attempts in case of failure.
+ *
+ * Message Handling:
+ * - Processes relay messages (e.g., `EVENT`, `EOSE`, `OK`, `AUTH`) and delegates to appropriate callbacks.
+ * - Dispatches received events, notices, and subscription closures via the [listener].
+ */
 open class BasicRelayClient(
     override val url: NormalizedRelayUrl,
     val socketBuilder: WebsocketBuilder,

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/client/subscriptions/Subscription.kt

@@ -18,12 +18,11 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.ammolite.relays.datasources
+package com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions
 
 import com.vitorpamplona.quartz.nip01Core.relay.client.single.newSubId
 import com.vitorpamplona.quartz.nip01Core.relay.filters.Filter
 import com.vitorpamplona.quartz.nip01Core.relay.normalizer.NormalizedRelayUrl
-import kotlin.contracts.ExperimentalContracts
 
 data class Subscription(
     val id: String = newSubId(),
@@ -41,9 +40,6 @@ data class Subscription(
 
     fun filters() = filters
 
-    @OptIn(ExperimentalContracts::class)
-    fun isActive() = filters != null
-
     fun callEose(
         time: Long,
         relay: NormalizedRelayUrl,

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/client/subscriptions/SubscriptionController.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.ammolite.relays.datasources
+package com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions
 
 import com.vitorpamplona.quartz.nip01Core.core.Event
 import com.vitorpamplona.quartz.nip01Core.relay.client.NostrClient
@@ -29,8 +29,22 @@ import com.vitorpamplona.quartz.nip01Core.relay.normalizer.NormalizedRelayUrl
 import com.vitorpamplona.quartz.utils.LargeCache
 
 /**
- * Semantically groups Nostr filters and subscriptions in data source objects that
+ * Manages Nostr subscriptions using a [NostrClient], allowing subscriptions to be created, modified,
- * maintain the desired active filter with the relay.
+ * and synchronized with relay filters. Subscriptions are stored in a cache and processed through
+ * [updateRelays] to update relay filters dynamically. Also tracks event statistics and EOSE (End of
+ * Stored Events) events, and provides utility methods to interact with subscriptions like dismissal.
+ *
+ * Key responsibilities:
+ * 1. Maintain a cache of active [Subscription] instances.
+ * 2. Handle client events (onEvent, onEOSE) using [clientListener].
+ * 3. Synchronize relay filters via [updateRelays] when subscriptions change.
+ * 4. Provide methods to create, dismiss, and inspect subscriptions.
+ *
+ * Usage:
+ * - Use [requestNewSubscription] to create subscriptions.
+ * - Modify filters on [Subscription] at will and call [updateRelays] to apply changes.
+ * - Update filters based on EOSE callbacks on each subscription
+ * - Dismiss subscriptions with [dismissSubscription].
  */
 class SubscriptionController(
     val client: NostrClient,

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/client/subscriptions/SubscriptionStats.kt

@@ -18,7 +18,7 @@
  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
-package com.vitorpamplona.ammolite.relays.datasources
+package com.vitorpamplona.quartz.nip01Core.relay.client.subscriptions
 
 import android.util.Log
 import com.vitorpamplona.quartz.utils.LargeCache

quartz/src/main/java/com/vitorpamplona/quartz/nip01Core/relay/filters/Filter.kt

@@ -24,6 +24,23 @@ import android.util.Log
 import com.vitorpamplona.quartz.nip01Core.core.Event
 import com.vitorpamplona.quartz.nip01Core.tags.addressables.Address
 
+/**
+ * A filter for Nostr events used in relay subscriptions. Supports various criteria
+ * to match events based on IDs, authors, kinds, tags, time ranges, search terms, and limits.
+ *
+ * Parameters:
+ * - ids: Optional list of event IDs to match (must be 64 characters).
+ * - authors: Optional list of author public keys (must be 64 characters).
+ * - kinds: Optional list of event kinds to include.
+ * - tags: Optional map of tag names to values arrays (common tags like 'p', 'e', 'a' are validated).
+ * - since: Optional timestamp for filtering events with publication time ≥ this value.
+ * - until: Optional timestamp for filtering events with publication time ≤ this value.
+ * - limit: Optional maximum number of events to request.
+ * - search: Optional string to search within event content.
+ *
+ * This class performs validation on construction to ensure all string-based identifiers
+ * follow Nostr requirements (64-char hex, onion addresses) and logs errors for invalid inputs.
+ */
 class Filter(
     val ids: List<String>? = null,
     val authors: List<String>? = null,
@@ -49,6 +66,9 @@ class Filter(
         search: String? = this.search,
     ) = Filter(ids, authors, kinds, tags, since, until, limit, search)
 
+    /**
+     * Returns true if this filter contains any non-null and non-empty criteria.
+     */
     fun isFilledFilter() =
         (ids != null && ids.isNotEmpty()) ||
             (authors != null && authors.isNotEmpty()) ||