feat: Add max persistence age override option [TRIAGE-608]

[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 automatic deletion of persisted events/uploads/sessions based on age (defaulting to 90 days) and runs it during the upload cycle, which can affect data retention if cutoff calculations or SQL predicates are wrong. Scoped to local SQLite cleanup with added tests and a 24-hour throttle to limit impact.

Overview
Adds a new public option MParticleOptions.Builder#persistenceMaxAgeSeconds(int) (with getter) to cap how long events, uploads, and sessions may remain persisted locally; non-positive values are rejected and fall back to the default.

Wires the value through ConfigManager and introduces an age-based retention sweep invoked at the start of UploadHandler#upload(), throttled to run at most once per 24 hours and defaulting to a 90-day window when unset.

Implements a transactional DB prune path via MParticleDBManager#deleteRecordsOlderThan(...), backed by new delete*OlderThan helpers in MessageService, UploadService, and SessionService using strict < cutoff semantics, with new unit/instrumentation tests covering builder validation, cutoff boundaries, throttle behavior, and failure retry.

^{Reviewed by Cursor Bugbot for commit efe31bb. Bugbot is set up for automated code reviews on this repo. 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

[mparticle-automation]

🎉 This PR is included in version 5.79.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀