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 automated deletion of persisted messages/uploads/sessions (defaulting to 90 days) during the upload cycle, which could impact data retention and database behavior if the cutoff logic or scheduling is incorrect.

Overview
Adds a new public MParticleOptions.Builder#persistenceMaxAgeSeconds(int) option (validated as >0) and threads it through ConfigManager so runtime code can read the configured retention window.

Updates the upload pipeline to run a throttled (24h) age-based sweep before uploads, deleting persisted messages/uploads/sessions older than the configured max age (or a new 90-day default), via a new transactional MParticleDBManager.deleteRecordsOlderThan() and new per-table delete helpers.

Adds unit/instrumentation tests covering option validation, the new delete-by-cutoff semantics (strict <), and UploadHandler.maybePrunePersistedRecords() default/configured behavior plus retry/throttle behavior.

^{Reviewed by Cursor Bugbot for commit efe31bb. 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.}

[thomson-t]

Shouldn't we check for the upper bound? Something like

if (builder.persistenceMaxAgeSeconds <= 0) {
    Logger.warning("Persistence Max Age must be a positive number, disregarding value.");
} else if (builder.persistenceMaxAgeSeconds > MAX_PERSISTENCE_MAX_AGE_SECONDS) {
    Logger.warning("Persistence Max Age is too high");
    this.mPersistenceMaxAgeSeconds = MAX_PERSISTENCE_MAX_AGE_SECONDS;
} else {
    this.mPersistenceMaxAgeSeconds = builder.persistenceMaxAgeSeconds;
}

or not set it at all of not in the range?

[junias-rokt]

Hey good callout! This is intentional as the main aim for these changes was to have feature parity with the other SDKs. Changing this would diverge from the other ones. This also matches all the other validators in the file and large values basically just disable the sweep.

[thomson-t]

ok, fair enough

[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