Skip to content

Move retry policy in another package and add attempt info in the calllback - #45

Merged
aleksandar-apostolov merged 5 commits into
developfrom
move-retrypolicy-add-attemtps
Dec 24, 2025
Merged

aleksandar-apostolov merged 5 commits into
developfrom
move-retrypolicy-add-attemtps

Conversation

@aleksandar-apostolov

@aleksandar-apostolov aleksandar-apostolov commented Dec 22, 2025 •

Copy link
Copy Markdown
Collaborator

Goal

Move the retry policy in another package and also add attempt info in the callback as well as the giveUp function.

Implementation

Create new attempt info. Supply the attempt info when calling giveup or attempt fucntions.

Testing

Checklist

  • Issue linked (if any)
  • Tests/docs updated
  • I have signed the Stream CLA (required for external contributors)

Summary by CodeRabbit

  • Breaking Changes

    • Retry API callback signature changed: callers now receive a retry-attempt object with attempt index, delay, and previous error.
  • New Features

    • Retry callbacks provide detailed attempt info to improve handling and logging.
  • Chores

    • Retry-related code moved into a dedicated retry package; build files updated with license headers and an experimental opt-in.
  • Tests

    • Added comprehensive unit tests for retry policy behaviors.

✏️ Tip: You can customize this high-level summary in your review settings.

@github-actions

github-actions Bot commented Dec 22, 2025 •

Copy link
Copy Markdown
Contributor

PR checklist ✅

All required conditions are satisfied:

  • Title length is OK (or ignored by label).
  • At least one pr: label exists.
  • Sections ### Goal, ### Implementation, and ### Testing are filled.

🎉 Great job! This PR is ready for review.

@coderabbitai

coderabbitai Bot commented Dec 22, 2025 •

Copy link
Copy Markdown

Walkthrough

Introduces a new data class StreamRetryAttemptInfo and moves retry types into io.getstream.android.core.api.model.retry. StreamRetryProcessor.retry signature and its implementation now pass StreamRetryAttemptInfo into retry blocks. Several Gradle files received header/opt-in edits and tests for StreamRetryPolicy were added.

Changes

Cohort / File(s) Summary
Retry model and policy package
stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt
Package declaration changed to io.getstream.android.core.api.model.retry (namespace relocation of StreamRetryPolicy).
New retry attempt type
stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryAttemptInfo.kt
New public data class StreamRetryAttemptInfo(attempt: Int, currentDelay: Long, previousAttemptError: Throwable? = null, policy: StreamRetryPolicy) annotated @StreamInternalApi.
Retry processor API & impl
stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt, stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImpl.kt
retry API signature changed from block: suspend () -> T to block: suspend (attempt: StreamRetryAttemptInfo) -> T. Implementation constructs and supplies StreamRetryAttemptInfo on each invocation and propagates previousAttemptError.
Tests: policy & imports
stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt, stream-android-core/src/test/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImplTest.kt
New comprehensive unit tests for StreamRetryPolicy added. Test import for StreamRetryPolicy updated to the new package.
Build script headers & opt-ins
app/build.gradle.kts, build.gradle.kts, settings.gradle.kts, stream-android-core-annotations/build.gradle.kts, stream-android-core-lint/build.gradle.kts, stream-android-core/build.gradle.kts
License header comments added to multiple Gradle files; stream-android-core/build.gradle.kts also added @file:OptIn(ExperimentalAbiValidation::class) and import. No functional build logic changes.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 I nibble code in morning light,
New attempt info hops into sight,
Each retry counted, errors kept near,
Policies tidy, tests cheer!
🥕✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)
Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 16.22% which is insufficient. The required threshold is 80.00%. You can run @coderabbitai generate docstrings to improve docstring coverage.
✅ Passed checks (2 passed)
Check name Status Explanation
Title check ✅ Passed The title mentions moving retry policy to another package and adding attempt info to the callback, which aligns with the main changes in the PR.
Description check ✅ Passed The description covers the Goal, Implementation, and Checklist sections per the template, though Testing section is empty and not marked as incomplete.
✨ Finishing touches
  • 📝 Generate docstrings
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch move-retrypolicy-add-attemtps

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt (1)

25-58: Update KDoc to document the new attempt parameter in the block.

The interface KDoc and method KDoc should mention that the block lambda receives a StreamRetryAttemptInfo parameter, which provides access to attempt metrics and previous errors. This is a key part of the new API surface.

🔎 Suggested KDoc update
 /**
  * Strategy-based retry executor used inside the Stream SDK.
  *
  * A concrete implementation applies the supplied [policy] to repeatedly invoke the suspending
  * [operation] until the call succeeds, the retry policy decides to give up, or the surrounding
  * coroutine is cancelled.
  *
  * ### Behaviour
  * * **Success** → returns `Result.success(value)` from the first successful attempt.
  * * **Give-up / max retries** → returns `Result.failure(originalThrowable)`.
  * * **Cancellation** → re-throws `CancellationException`; the caller is responsible for handling
  *   it.
  *
  * Implementations **must** honour the timing and stop-conditions described by [StreamRetryPolicy]
  * (initial delay, back-off function, `giveUpFunction`, etc.).
  *
  * @param T The value type produced by [block] on success.
  * @param policy Retry/back-off parameters (exponential, linear, custom).
- * @param block The suspending operation to execute. It should throw on failure; the processor
- *   handles re-invocation.
+ * @param block The suspending operation to execute. Receives [StreamRetryAttemptInfo] with current
+ *   attempt metrics. It should throw on failure; the processor handles re-invocation.
  * @return A [Result] wrapping either the successful value or the final error after all retries have
  *   been exhausted.
  */

And update the method-level KDoc similarly:

     /**
      * Executes [block] with the supplied [policy], retrying on failure.
      *
      * @param T The value type produced by [block] on success.
      * @param policy Retry/back-off parameters (exponential, linear, custom).
-     * @param block The suspending operation to execute. It should throw on failure; the processor
-     *   handles re-invocation.
+     * @param block The suspending operation to execute. Receives [StreamRetryAttemptInfo] with
+     *   current attempt number, delay, previous error, and policy. Should throw on failure; the
+     *   processor handles re-invocation.
      */
🧹 Nitpick comments (2)
stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryAttemptInfo.kt (1)

4-4: Remove redundant import from the same package.

StreamRetryPolicy is in the same package (io.getstream.android.core.api.model.retry), so this import is unnecessary.

🔎 Proposed fix
 package io.getstream.android.core.api.model.retry
 
 import io.getstream.android.core.annotations.StreamInternalApi
-import io.getstream.android.core.api.model.retry.StreamRetryPolicy
stream-android-core/src/test/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImplTest.kt (1)

36-50: Consider adding test coverage for StreamRetryAttemptInfo.

While the existing tests continue to work (Kotlin allows omitting unused lambda parameters), they don't verify that StreamRetryAttemptInfo is correctly populated with attempt number, delay, previous error, and policy. Consider adding at least one test that validates these values.

Example test
@Test
fun `provides correct attempt info to block on each retry`() = runTest {
    val policy = StreamRetryPolicy.linear(
        minRetries = 1,
        maxRetries = 3,
        backoffStepMillis = 100,
        initialDelayMillis = 50
    )
    
    val capturedAttempts = mutableListOf<StreamRetryAttemptInfo>()
    var callCount = 0
    
    val res = retry.retry(policy) { attemptInfo ->
        capturedAttempts.add(attemptInfo)
        if (++callCount < 3) {
            throw RuntimeException("Attempt $callCount")
        }
        "success"
    }
    
    assertTrue(res.isSuccess)
    assertEquals(3, capturedAttempts.size)
    
    // Verify first attempt
    assertEquals(1, capturedAttempts[0].attempt)
    assertEquals(50, capturedAttempts[0].currentDelay)
    assertNull(capturedAttempts[0].previousAttemptError)
    
    // Verify second attempt
    assertEquals(2, capturedAttempts[1].attempt)
    assertEquals(100, capturedAttempts[1].currentDelay)
    assertNotNull(capturedAttempts[1].previousAttemptError)
    assertEquals("Attempt 1", capturedAttempts[1].previousAttemptError?.message)
}
📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

  • Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between d792a91 and 1ae386b.

📒 Files selected for processing (5)
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryAttemptInfo.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt
  • stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImpl.kt
  • stream-android-core/src/test/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImplTest.kt
🧰 Additional context used
📓 Path-based instructions (2)
**/*.kt

📄 CodeRabbit inference engine (AGENTS.md)

**/*.kt: Use Kotlin with JVM target 11 inside Gradle; toolchain 17 for builds
Use kotlinx coroutines 1.8+ for async workflows
Wrap most workflows with Coroutines; keep blocking I/O off main thread. Respect existing dispatcher usage and structured concurrency
Enable explicitApi() and avoid signature breaking changes to public/internal APIs without coordinating version bumps
Use tagged StreamLogger for logging; keep error logs actionable and avoid leaking secrets/tokens
Use Kotlin official code style enforced by Spotless: 4 spaces, no wildcard imports
Limit internal surface area; favour private helpers where possible
Public APIs require KDoc; significant internal flows get concise comments explaining the 'why'
Keep licence headers intact; regenerate via ./gradlew generateLicense if the year changes
Keep processor/queue behaviour documented via KDoc or dedicated docs when semantics evolve
Never hardcode API keys or tokens; use local.properties or env vars
Sanitise logs: token payloads, JWTs, or user IDs should not leak to release logs
Ensure cleanup/teardown paths handle cancellation and failure (important for sockets, queues, retries)
Keep concurrency deterministic—use structured coroutines and avoid global scope

Files:

  • stream-android-core/src/test/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImplTest.kt
  • stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImpl.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryAttemptInfo.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt
**/src/test/java/**/*.kt

📄 CodeRabbit inference engine (AGENTS.md)

**/src/test/java/**/*.kt: Use backtick test names for clarity in test functions (e.g., fun serial queue delivers items in order())
Unit tests live under each module's src/test/java; use MockK and coroutines-test to control timing
Prefer lightweight Robolectric tests only when Android primitives are involved; otherwise keep pure JVM tests

Files:

  • stream-android-core/src/test/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImplTest.kt
🧠 Learnings (4)
📚 Learning: 2025-12-22T14:01:09.549Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.549Z
Learning: Run module-scoped tests when iterating (e.g., :stream-android-core:test, :stream-android-core:detekt) to keep cycle fast; all public changes should pass ./gradlew check

Applied to files:

  • stream-android-core/src/test/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImplTest.kt
📚 Learning: 2025-12-22T14:01:09.549Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.549Z
Learning: Applies to **/*.kt : Keep concurrency deterministic—use structured coroutines and avoid global scope

Applied to files:

  • stream-android-core/src/test/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImplTest.kt
📚 Learning: 2025-12-22T14:01:09.548Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.548Z
Learning: Applies to **/*.kt : Keep licence headers intact; regenerate via `./gradlew generateLicense` if the year changes

Applied to files:

  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt
📚 Learning: 2025-12-22T14:01:09.548Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.548Z
Learning: Applies to **/*.kt : Use tagged StreamLogger for logging; keep error logs actionable and avoid leaking secrets/tokens

Applied to files:

  • stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt
🧬 Code graph analysis (1)
stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImpl.kt (1)
stream-android-core/src/main/java/io/getstream/android/core/api/utils/Catching.kt (1)
  • runCatchingCancellable (31-42)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)
  • GitHub Check: Lint
  • GitHub Check: Unit Tests
  • GitHub Check: Spotless
🔇 Additional comments (5)
stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryAttemptInfo.kt (1)

6-28: LGTM! Well-structured data class with clear documentation.

The StreamRetryAttemptInfo data class is well-designed with:

  • Clear KDoc explaining its purpose and usage
  • Properly documented properties
  • Appropriate default value for previousAttemptError (null for first attempt)
  • Correct @StreamInternalApi annotation
stream-android-core/src/test/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImplTest.kt (1)

21-21: LGTM! Import path correctly updated.

The import path for StreamRetryPolicy has been properly updated to reflect the new package structure.

stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt (1)

21-22: LGTM! Imports correctly updated.

The imports properly reflect the relocated StreamRetryPolicy and the newly introduced StreamRetryAttemptInfo.

stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImpl.kt (2)

20-21: LGTM! Imports correctly updated.

The imports properly reference the relocated types from the new retry package.


28-66: LGTM! Implementation correctly provides attempt information to the block.

The retry logic properly constructs and passes StreamRetryAttemptInfo on each attempt:

  • First attempt gets attempt=1, currentDelay=initialDelayMillis, previousError=null
  • Subsequent attempts receive updated values with the actual delay applied and the previous failure
  • The previousError tracking ensures callers can inspect what went wrong on the last attempt

The implementation correctly maintains structured concurrency and handles cancellation appropriately.

@gpunto gpunto left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we use this info in Video?

@aleksandar-apostolov

Copy link
Copy Markdown
Collaborator Author

Do we use this info in Video?

Not yet

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt (1)

226-235: Fix validation inconsistency: minRetries should allow 0.

The validation at Line 227 checks minRetries > 0, but the documentation at Line 36-37 explicitly states: "Set to 0 to disable retries." Additionally, the invariant comment at Line 32 states minRetries ≥ 0, and the error message itself says "minRetries must be ≥ 0".

This inconsistency prevents users from disabling retries as documented.

🔎 Proposed fix
-        require(minRetries > 0) { "minRetries must be ≥ 0" }
+        require(minRetries >= 0) { "minRetries must be ≥ 0" }
📜 Review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

  • Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 1ae386b and 1ed3b78.

⛔ Files ignored due to path filters (1)
  • config/license/generated/license-2025.txt is excluded by !**/generated/**
📒 Files selected for processing (11)
  • app/build.gradle.kts
  • build.gradle.kts
  • settings.gradle.kts
  • stream-android-core-annotations/build.gradle.kts
  • stream-android-core-lint/build.gradle.kts
  • stream-android-core/build.gradle.kts
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryAttemptInfo.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt
  • stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImpl.kt
  • stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt
✅ Files skipped from review due to trivial changes (3)
  • settings.gradle.kts
  • stream-android-core-annotations/build.gradle.kts
  • build.gradle.kts
🧰 Additional context used
📓 Path-based instructions (4)
**/*.kt

📄 CodeRabbit inference engine (AGENTS.md)

**/*.kt: Use Kotlin with JVM target 11 inside Gradle; toolchain 17 for builds
Use kotlinx coroutines 1.8+ for async workflows
Wrap most workflows with Coroutines; keep blocking I/O off main thread. Respect existing dispatcher usage and structured concurrency
Enable explicitApi() and avoid signature breaking changes to public/internal APIs without coordinating version bumps
Use tagged StreamLogger for logging; keep error logs actionable and avoid leaking secrets/tokens
Use Kotlin official code style enforced by Spotless: 4 spaces, no wildcard imports
Limit internal surface area; favour private helpers where possible
Public APIs require KDoc; significant internal flows get concise comments explaining the 'why'
Keep licence headers intact; regenerate via ./gradlew generateLicense if the year changes
Keep processor/queue behaviour documented via KDoc or dedicated docs when semantics evolve
Never hardcode API keys or tokens; use local.properties or env vars
Sanitise logs: token payloads, JWTs, or user IDs should not leak to release logs
Ensure cleanup/teardown paths handle cancellation and failure (important for sockets, queues, retries)
Keep concurrency deterministic—use structured coroutines and avoid global scope

**/*.kt: Use Result-based error handling for all public APIs, returning Result instead of throwing exceptions. Exception: CancellationException is rethrown (not captured in Result).
Use lambda-based logging for performance to avoid computing expensive strings when log level is disabled. Use logger.d { "message" } instead of logger.d("message").
Implement StreamStartableComponent interface for components that require lifecycle management. Always call start() before use and stop() when done.
Use SupervisorJob for coroutine scopes powering multiple components to prevent one component's failure from cancelling sibling components.
Always handle Result failures with onFailure or fold patterns. Never silently ignore failures as this leads to hard-to-debug ...

Files:

  • stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt
  • stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImpl.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryAttemptInfo.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt
**/src/test/java/**/*.kt

📄 CodeRabbit inference engine (AGENTS.md)

**/src/test/java/**/*.kt: Use backtick test names for clarity in test functions (e.g., fun serial queue delivers items in order())
Unit tests live under each module's src/test/java; use MockK and coroutines-test to control timing
Prefer lightweight Robolectric tests only when Android primitives are involved; otherwise keep pure JVM tests

Files:

  • stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt
**/*.{kt,kts}

📄 CodeRabbit inference engine (CLAUDE.md)

**/*.{kt,kts}: Use factory functions for component instantiation instead of direct instantiation of implementation classes. Prefer StreamSerialProcessingQueue(logger, scope) over StreamSerialProcessingQueueImpl(logger, scope).
Use explicit imports instead of wildcard imports. Organize imports with standard library first, then third-party, then local modules, with blank lines between groups.

Files:

  • stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt
  • stream-android-core-lint/build.gradle.kts
  • stream-android-core/build.gradle.kts
  • app/build.gradle.kts
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt
  • stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImpl.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryAttemptInfo.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt
**/*.gradle.kts

📄 CodeRabbit inference engine (AGENTS.md)

Use Gradle Kotlin DSL with shared logic in buildSrc/

Files:

  • stream-android-core-lint/build.gradle.kts
  • stream-android-core/build.gradle.kts
  • app/build.gradle.kts
🧠 Learnings (28)
📓 Common learnings
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to **/*.kt : Use giveUpFunction in StreamRetryPolicy to stop retries on non-retryable errors (UnauthorizedException, ForbiddenException, NotFoundException) rather than retrying indefinitely.
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to src/main/java/io/getstream/android/core/**/*.kt : Use StreamPublishedApi for stable public APIs exposed to product SDKs. Breaking changes require major version bump. Use StreamInternalApi for internal infrastructure. Use StreamDelicateApi for advanced/dangerous APIs.
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Stream Android Core is an internal foundational library not for public consumption. It powers all Stream Android SDKs (Chat, Video, Feeds) and must maintain backward compatibility for published APIs (StreamPublishedApi).
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to src/test/**/*.kt : Test class naming convention: <ClassUnderTest>Test.kt (e.g., StreamRetryProcessorImplTest.kt).
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to src/test/**/*.kt : Test class naming convention: <ClassUnderTest>Test.kt (e.g., StreamRetryProcessorImplTest.kt).

Applied to files:

  • stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to **/*.kt : Use giveUpFunction in StreamRetryPolicy to stop retries on non-retryable errors (UnauthorizedException, ForbiddenException, NotFoundException) rather than retrying indefinitely.

Applied to files:

  • stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt
  • stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImpl.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryAttemptInfo.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to src/test/java/io/getstream/android/core/**/*.kt : Use MockK library for mocking Kotlin classes and suspend functions in unit tests.

Applied to files:

  • stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt
  • stream-android-core-lint/build.gradle.kts
  • stream-android-core/build.gradle.kts
  • app/build.gradle.kts
📚 Learning: 2025-12-22T14:01:09.559Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.559Z
Learning: Run module-scoped tests when iterating (e.g., :stream-android-core:test, :stream-android-core:detekt) to keep cycle fast; all public changes should pass ./gradlew check

Applied to files:

  • stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt
  • stream-android-core-lint/build.gradle.kts
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to src/main/java/io/getstream/android/core/**/*.kt : Use StreamPublishedApi for stable public APIs exposed to product SDKs. Breaking changes require major version bump. Use StreamInternalApi for internal infrastructure. Use StreamDelicateApi for advanced/dangerous APIs.

Applied to files:

  • stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt
  • stream-android-core-lint/build.gradle.kts
  • stream-android-core/build.gradle.kts
  • app/build.gradle.kts
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt
  • stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImpl.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryAttemptInfo.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to src/test/**/*.kt : Always test both success and failure paths in unit tests. Use assertions to verify both positive and negative outcomes.

Applied to files:

  • stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Retry policies include exponential backoff (250ms-15s) and linear backoff (1s-30s) options. Use giveUpFunction to prevent retrying non-recoverable errors.

Applied to files:

  • stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt
📚 Learning: 2025-12-22T14:01:09.559Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.559Z
Learning: Add deterministic tests for concurrency tools (batcher, single-flight, retry) covering edge cases like cancellation, dedupe, and failure retries

Applied to files:

  • stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt
📚 Learning: 2025-12-22T14:01:09.559Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.559Z
Learning: Applies to **/*.kt : Keep licence headers intact; regenerate via `./gradlew generateLicense` if the year changes

Applied to files:

  • stream-android-core-lint/build.gradle.kts
  • stream-android-core/build.gradle.kts
  • app/build.gradle.kts
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Stream Android Core is an internal foundational library not for public consumption. It powers all Stream Android SDKs (Chat, Video, Feeds) and must maintain backward compatibility for published APIs (StreamPublishedApi).

Applied to files:

  • stream-android-core-lint/build.gradle.kts
  • stream-android-core/build.gradle.kts
  • app/build.gradle.kts
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryAttemptInfo.kt
  • stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt
📚 Learning: 2025-12-22T14:01:09.559Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.559Z
Learning: Applies to **/*.kt : Use Kotlin with JVM target 11 inside Gradle; toolchain 17 for builds

Applied to files:

  • stream-android-core-lint/build.gradle.kts
  • stream-android-core/build.gradle.kts
  • app/build.gradle.kts
📚 Learning: 2025-12-22T14:01:09.559Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.559Z
Learning: Applies to **/*.kt : Use kotlinx coroutines 1.8+ for async workflows

Applied to files:

  • stream-android-core-lint/build.gradle.kts
  • app/build.gradle.kts
📚 Learning: 2025-12-22T14:01:09.559Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.559Z
Learning: Applies to **/*.gradle.kts : Use Gradle Kotlin DSL with shared logic in buildSrc/

Applied to files:

  • stream-android-core-lint/build.gradle.kts
  • app/build.gradle.kts
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to **/*.kt : Implement StreamStartableComponent interface for components that require lifecycle management. Always call start() before use and stop() when done.

Applied to files:

  • stream-android-core-lint/build.gradle.kts
  • app/build.gradle.kts
📚 Learning: 2025-12-22T14:01:09.559Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.559Z
Learning: Applies to **/src/test/java/**/*.kt : Unit tests live under each module's src/test/java; use MockK and coroutines-test to control timing

Applied to files:

  • stream-android-core-lint/build.gradle.kts
  • app/build.gradle.kts
📚 Learning: 2025-12-22T14:01:09.559Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.559Z
Learning: Applies to **/*.kt : Keep concurrency deterministic—use structured coroutines and avoid global scope

Applied to files:

  • stream-android-core-lint/build.gradle.kts
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to build.gradle.kts : Build configuration must enable explicit API mode with kotlin { explicitApi() } to require explicit visibility modifiers on all public declarations.

Applied to files:

  • stream-android-core/build.gradle.kts
  • app/build.gradle.kts
📚 Learning: 2025-12-22T14:01:09.559Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.559Z
Learning: Applies to **/*.kt : Enable explicitApi() and avoid signature breaking changes to public/internal APIs without coordinating version bumps

Applied to files:

  • stream-android-core/build.gradle.kts
  • app/build.gradle.kts
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Use explicit API mode (kotlin { explicitApi() }) in the build configuration. All public APIs must be explicitly declared with visibility modifiers.

Applied to files:

  • stream-android-core/build.gradle.kts
  • app/build.gradle.kts
📚 Learning: 2025-12-22T14:01:09.559Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.559Z
Learning: Applies to **/src/test/java/**/*.kt : Prefer lightweight Robolectric tests only when Android primitives are involved; otherwise keep pure JVM tests

Applied to files:

  • stream-android-core/build.gradle.kts
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to build.gradle.kts : Configure KSP for Moshi code generation and set JVM target to 11 in the build configuration.

Applied to files:

  • stream-android-core/build.gradle.kts
  • app/build.gradle.kts
📚 Learning: 2025-12-22T14:01:09.559Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: AGENTS.md:0-0
Timestamp: 2025-12-22T14:01:09.559Z
Learning: Applies to **/*.kt : Use tagged StreamLogger for logging; keep error logs actionable and avoid leaking secrets/tokens

Applied to files:

  • app/build.gradle.kts
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to **/*.kt : All public APIs must be thread-safe. Android Lifecycle operations must run on the main thread using runOnMainLooper internally.

Applied to files:

  • app/build.gradle.kts
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to **/*.kt : Use onTokenError extension to handle token refresh on StreamEndpointException with codes 40, 41, or 42. Invalidate token and retry with refreshed token.

Applied to files:

  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to **/*.kt : Check token error codes 40, 41, 42 from StreamEndpointErrorData.code for token authentication failures, NOT HTTP status codes 401/403.

Applied to files:

  • stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryPolicy.kt
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to **/*.kt : Use Result-based error handling for all public APIs, returning Result<T> instead of throwing exceptions. Exception: CancellationException is rethrown (not captured in Result).

Applied to files:

  • stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImpl.kt
📚 Learning: 2025-12-23T15:52:48.955Z
Learnt from: CR
Repo: GetStream/stream-core-android PR: 0
File: CLAUDE.md:0-0
Timestamp: 2025-12-23T15:52:48.955Z
Learning: Applies to **/*.kt : Use CancellationException rethrow pattern in Result handling to preserve coroutine cancellation semantics.

Applied to files:

  • stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt
🧬 Code graph analysis (1)
stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImpl.kt (2)
stream-android-core/src/main/java/io/getstream/android/core/api/utils/Catching.kt (1)
  • runCatchingCancellable (31-42)
stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamSerialProcessingQueueImpl.kt (1)
  • block (39-42)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
  • GitHub Check: Spotless
  • GitHub Check: Lint
  • GitHub Check: Unit Tests
  • GitHub Check: Compile
🔇 Additional comments (13)
app/build.gradle.kts (1)

1-16: LGTM! License header added correctly.

The license header follows the correct format and includes the appropriate copyright year range (2014-2025).

stream-android-core-lint/build.gradle.kts (1)

1-16: LGTM! License header added correctly.

The license header follows the correct format and includes the appropriate copyright year range (2014-2025).

stream-android-core/build.gradle.kts (1)

1-20: LGTM! License header and experimental API opt-in properly added.

The license header follows the project standard, and the @file:OptIn(ExperimentalAbiValidation::class) annotation correctly enables usage of experimental ABI validation features in the Kotlin DSL script.

stream-android-core/src/main/java/io/getstream/android/core/api/model/retry/StreamRetryAttemptInfo.kt (1)

17-43: LGTM! Well-designed attempt info type.

The StreamRetryAttemptInfo data class provides a clear snapshot of retry state with appropriately typed properties and comprehensive KDoc. The nullable previousAttemptError with a default of null correctly handles the first attempt case.

stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt (5)

29-92: Excellent test coverage for exponential backoff behavior.

The tests comprehensively verify default parameters, custom parameters, backoff progression, clamping, and giveUp behavior. The descriptive backtick test names make the test intent clear.


107-130: Good coverage of linear backoff progression and capping.

The tests correctly verify linear growth and maxBackoffMillis enforcement.


137-157: Good coverage of fixed delay behavior.

The tests verify that fixed delays remain constant across retries and respect maxBackoffMillis.


164-219: Excellent coverage of custom policy behavior.

The tests verify callback invocation, clamping to min/max bounds, and properly track callback invocation counts.


225-368: Comprehensive validation test coverage.

The validation tests thoroughly cover all require statements across exponential, linear, fixed, and custom factory functions, ensuring boundary conditions are properly enforced.

stream-android-core/src/main/java/io/getstream/android/core/api/processing/StreamRetryProcessor.kt (2)

21-22: LGTM! Import paths updated to new retry package.

The imports correctly reference the relocated retry types in io.getstream.android.core.api.model.retry.


58-61: LGTM! Breaking change to provide attempt context is well-designed.

The updated signature allows retry blocks to access StreamRetryAttemptInfo, enabling callers to log, track metrics, or make decisions based on attempt count, delay, and previous errors. This is a valuable enhancement that justifies the breaking change.

stream-android-core/src/main/java/io/getstream/android/core/internal/processing/StreamRetryProcessorImpl.kt (2)

20-21: LGTM! Import paths updated to new retry package.

The imports correctly reference the relocated retry types.


28-65: LGTM! Solid implementation of retry processor with attempt info.

The implementation correctly:

  • Tracks previousError and passes it via StreamRetryAttemptInfo to provide context to retry blocks
  • Preserves coroutine cancellation semantics by rethrowing CancellationException
  • Enforces minRetries before consulting giveUpFunction
  • Clamps computed delays to policy bounds using coerceIn
  • Includes defensive IllegalStateException at end of loop for safety

Comment on lines +225 to +233
@Test(expected = IllegalArgumentException::class)
fun `exponential throws when minRetries is negative`() {
StreamRetryPolicy.exponential(minRetries = -1)
}

@Test(expected = IllegalArgumentException::class)
fun `exponential throws when minRetries is zero`() {
StreamRetryPolicy.exponential(minRetries = 0)
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

Fix validation tests: minRetries = 0 should be valid.

These tests expect minRetries = 0 to throw IllegalArgumentException, but the StreamRetryPolicy documentation at lines 36-37 explicitly states: "Set to 0 to disable retries." The invariant at line 32 also documents minRetries ≥ 0.

Once the validation bug in StreamRetryPolicy.kt line 227 is fixed to allow minRetries >= 0, these tests should be removed or updated to verify that minRetries = 0 is accepted.

Affected test lines:

  • Line 230-233: exponential throws when minRetries is zero
  • Line 256-258: linear throws when minRetries is zero
  • Line 281-283: fixed throws when minRetries is negative (this one is testing -1, which is correct)
  • Line 306-316: custom throws when minRetries is zero
🔎 Recommended action

After fixing the validation in StreamRetryPolicy.kt, remove these four tests (or convert them to verify that minRetries = 0 is accepted):

  • exponential throws when minRetries is zero (lines 230-233)
  • linear throws when minRetries is zero (lines 256-258)
  • custom throws when minRetries is zero (lines 306-316)

Keep the tests for negative values (e.g., minRetries = -1) as those should correctly throw.

Also applies to: 256-258, 281-283, 306-316

🤖 Prompt for AI Agents
In
stream-android-core/src/test/java/io/getstream/android/core/api/model/retry/StreamRetryPolicyTest.kt
around lines 225-233 (and similarly at 256-258 and 306-316), the tests assert
that minRetries = 0 should throw, but the policy and docs specify minRetries ≥ 0
and 0 disables retries; update the implementation in StreamRetryPolicy.kt
(around line 227) to accept minRetries >= 0, then remove or convert the tests
that expect an exception for minRetries = 0 to instead verify that constructing
the policy with minRetries = 0 succeeds (or simply remove those three tests),
while keeping tests that assert negative values (e.g., -1) still throw.

@sonarqubecloud

Copy link
Copy Markdown

@aleksandar-apostolov
aleksandar-apostolov merged commit 0d67079 into develop Dec 24, 2025
6 checks passed
@aleksandar-apostolov
aleksandar-apostolov deleted the move-retrypolicy-add-attemtps branch December 24, 2025 08:16
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

pr:breaking-change Breaking change pr:new-feature New feature

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants