TRIAGE-608: Add max persistence age override option

[junias-rokt]

Background

The iOS mParticle SDK exposes MParticleOptions.persistenceMaxAgeSeconds, which caps the age of locally persisted events, batches, and sessions to prevent unbounded on-device storage growth. The Android SDK had no equivalent — once data was written to the SQLite store it would sit there until the app either uploaded it or was uninstalled. For apps that batch heavily, go long stretches offline, or see users who rarely background the app, this can produce noticeable storage bloat and a slow drift toward larger database files. TRIAGE-608 was opened to close this feature-parity gap and document it on the Android configuration guide.

The companion iOS implementation lives in MPBackendController.cleanUp: and MPPersistenceController deleteRecordsOlderThan:, which is the behavioral spec this change mirrors.

What Has Changed

Public API

• Adds MParticleOptions.Builder#persistenceMaxAgeSeconds(int seconds) and the matching getter MParticleOptions#getPersistenceMaxAgeSeconds(). Units are seconds, values must be positive; zero or negative values log a warning and fall back to the default.

Wiring

• Threads the value through ConfigManager so the upload pipeline can read it at runtime.

Age-based sweep

• New MParticleDBManager#deleteRecordsOlderThan(long cutoffMillis) orchestrator wraps three new static helpers in a single transaction:
  • MessageService#deleteMessagesOlderThan — deletes from MessageTableColumns.TABLE_NAME where created_at < ?
  • UploadService#deleteUploadsOlderThan — deletes from UploadTableColumns.TABLE_NAME where created_at < ?
  • SessionService#deleteSessionsOlderThan — deletes from SessionTableColumns.TABLE_NAME where end_time < ?
• UploadHandler#upload() now calls maybePrunePersistedRecords(now) at the start of each cycle. The sweep is throttled to run at most once every 24 hours and defaults to a 90-day retention window when persistenceMaxAgeSeconds is unset — matching the iOS defaults precisely.

Tests

• MParticleOptionsTest#testPersistenceMaxAgeSeconds covers null/positive/zero/negative inputs on the builder.
• MessageServiceTest#testDeleteMessagesOlderThan verifies the SQL cutoff semantics (strictly < cutoff are deleted; rows at or newer than the cutoff are retained).

Screenshots/Video

N/A — this is a configuration/storage-hygiene change with no UI surface.

Checklist

• I have performed a self-review of my own code.
• I have made corresponding changes to the documentation.
• I have added tests that prove my fix is effective or that my feature works.
• I have tested this locally.

Local validation against JDK 17: `trunk check`, `./gradlew build`, `./gradlew test`, `./gradlew ktlintCheck`, and `./gradlew lint` all pass. `connectedAndroidTest` was not run locally (no emulator available) — will rely on CI.

Additional Notes

• Defaults are intentionally conservative. With no opt-in, behavior changes from never-delete to delete rows older than 90 days, applied at most once per 24 hours. This matches long-standing iOS behavior and is the same floor SonarCloud/Bugbot flagged as low-risk on this PR.
• Hook site. The sweep runs inside the existing upload cycle rather than in a dedicated lifecycle hook. If apps are observed that never trigger an upload (e.g., very short-lived sessions with no events), a follow-up can additionally invoke `maybePrunePersistedRecords` from `AppStateManager#onActivityPaused`; the 24h throttle already coordinates across call sites so this is a safe additive change.
• Docs. Public documentation is updated in companion PR mparticle-by-rokt/docsite#3390.

Reference Issue (For employees only. Ignore if you are an outside contributor)

• Closes https://rokt.atlassian.net/browse/TRIAGE-608

[cursor]

PR Summary

Medium Risk
Introduces a new age-based deletion path for persisted messages/uploads/sessions (defaulting to 90 days), which could drop data on devices that remain offline longer than the retention window. Risk is mitigated by strict cutoff semantics, a 24-hour throttle, and added test coverage around boundary conditions.

Overview
Adds a new public option MParticleOptions.Builder#persistenceMaxAgeSeconds(int) (and getter) to cap how long the SDK keeps locally persisted events/batches/sessions; non-positive values are rejected with a warning.

Wires this value through ConfigManager into the upload cycle and introduces an age-based pruning sweep (UploadHandler.maybePrunePersistedRecords) that runs at most once per 24 hours and deletes records older than the configured window (default 90 days) via a new MParticleDBManager.deleteRecordsOlderThan transaction spanning messages, uploads, and sessions.

Adds instrumentation/unit tests covering builder validation, per-table delete semantics (strict < cutoff), and pruning behavior (default vs configured window, throttle, and retry-after-failure).

^{Reviewed by Cursor Bugbot for commit c588b67. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit c588b67. Configure here.}

[cursor]

Swallowed exceptions defeat retry-on-failure throttle logic

Medium Severity

deleteRecordsOlderThan catches all exceptions internally and returns normally, so exceptions never propagate to the caller maybePrunePersistedRecords. This means mLastPersistenceCleanupMillis = nowMillis always executes — even when the sweep fails — arming the 24-hour throttle and preventing the documented retry-on-next-cycle behavior. The unit test passes only because it mocks deleteRecordsOlderThan to throw directly from the mock, bypassing the internal try-catch.

Additional Locations (1)

• android-core/src/main/java/com/mparticle/internal/UploadHandler.java#L247-L266

 

^{Reviewed by Cursor Bugbot for commit c588b67. Configure here.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud