UpdateInfoService

open fun dump(fd: FileDescriptor?, writer: PrintWriter?, args: Array<String>?): Unit

Dumps the state of the service for debugging (e.g. adb shell dumpsys activity service).

This implementation provides a snapshot of the internal state, including:

• Active Request Count: To detect stuck threads or high concurrency.

• Global Last Check Time: The timestamp of the last successful service-wide sync (Service Health).

• Throttling Status: Whether the rate limiter is currently blocking network requests.

• Cached Updates: A complete list of stored updates with detailed metadata (Component, SPL, Provider, Published Date, Last Checked Time).

final fun onBind(intent: Intent?): IBinder?

Called by the system when a client binds to the service.

This method verifies that the Intent action matches the expected contract (ACTION_BIND). If the action is missing or incorrect, the binding is rejected to ensure the service is not exposed unintentionally.

Upon successful verification, this method returns a factory Binder (IUpdateInfoService) that allows the client to establish a secure, authenticated session.

final fun onUnbind(intent: Intent?): Boolean

Called by the system when all clients have disconnected from the service's factory interface.

This method is marked final to enforce the library's lifecycle contract. It returns false, which forces the Android system to call onBind for any future connections. This simplifies the service's lifecycle management by ensuring we never need to handle the android.app.Service.onRebind edge case.

Lifecycle Note: Individual client session disconnections and telemetry are tracked when the client calls IUpdateInfoSession.close (which triggers onClientDisconnected), not within this system-level callback.

protected abstract suspend fun fetchUpdates(): List<UpdateInfo>

Performs the actual network request to fetch fresh updates from the backend.

Template Method: This method is implemented by the host application (e.g., the System Updater) and invoked by the UpdateInfoService base class on a background thread. The base class handles concurrency, caching, and rate-limiting.

Preconditions: This method is only called if shouldFetchUpdates returns true and shouldThrottle returns false (the rate limiter allows the request).

Error Handling: If this method throws an exception (e.g., due to a network timeout or server error), the base class will catch it, invoke onFetchFailed for telemetry logging, and gracefully return the currently cached data to the client.

protected open fun getCallerUid(): Int

Retrieves the UID of the calling process.

The default implementation delegates to android.os.Binder.getCallingUid. Host implementations using a proxy or broker architecture should override this to return the logical client UID instead of the broker's UID, ensuring correct attribution.

protected open fun onClientConnected(packageName: String, callerUid: Int): Unit

Called when a client successfully establishes a session with the update provider.

This method is invoked when a client calls IUpdateInfoService.openSession and passes the identity validation checks.

Usage: Override this method to log connection metrics (e.g., "Session Started") or track adoption trends based on the client package name.

Client Identity & Security: The packageName provided to this hook is strictly validated against the Kernel-verified callerUid by the Android system. This guarantees that the identity is authentic and cannot be spoofed.

Package Visibility: The host application must have package visibility (e.g., via the QUERY_ALL_PACKAGES permission) to verify the client's package name. If the host cannot verify the package name, the connection will be rejected with a SecurityException before this hook is ever called.

protected open fun onClientDisconnected(packageName: String, callerUid: Int): Unit

Called when a client explicitly closes its session or its process terminates unexpectedly.

This method is invoked when the client calls IUpdateInfoSession.close or when the Android system detects that the process hosting the client has died (via android.os.IBinder.DeathRecipient).

Usage: Override this method to log session ends (e.g., "Session Ended") to calculate session duration when paired with onClientConnected. You can also use this to perform per-client resource cleanup.

protected open fun onFetchFailed(e: Exception): Unit

Callback for handling exceptions that occur during the update check process.

Template Method: The UpdateInfoService base class executes the update check logic and catches all unhandled exceptions to prevent the service from crashing. When an exception is caught, the base class gracefully falls back to returning the currently cached data to the client, and invokes this method.

This method will be triggered if an exception occurs during any step of the lifecycle, including:

• Determining cache freshness (e.g., inside shouldFetchUpdates).

• Evaluating rate limits (e.g., inside shouldThrottle).

• Fetching data from the backend (e.g., inside fetchUpdates).

• Persisting the fetched results or metadata to local storage.

The default implementation logs the error to Logcat. Hosts can override this method to report failures to their own telemetry or crash reporting systems.

protected open fun onRequestCompleted(telemetry: UpdateCheckTelemetry): Unit

Called when a request completes. Override this to log telemetry.

This hook is called for every request to listAvailableUpdates, regardless of whether it succeeded, failed, was throttled, or was served from the cache.

Usage: Use this hook to log granular performance metrics (latency histograms) and resource usage.

Attribution: The telemetry object contains the UpdateCheckTelemetry.callerUid, which is the Kernel-verified UID of the calling process. This is the authoritative source for attributing load (CPU/Network/Lock Contention) to specific client applications.

protected open fun shouldFetchUpdates(): Boolean

Determines if the local cache is stale and a refresh should be attempted.

The default implementation returns true if the data is older than 1 hour. Hosts can override this to implement custom caching policies (e.g., 4 hours, 24 hours).

protected open fun shouldThrottle(): Boolean

Checks if the update check operation should be throttled.

Default Behavior: The default implementation delegates to an internal rate limiter backed by SharedPreferences. This enforces a standard minimum interval (e.g., 1 hour) between network requests to protect backend infrastructure. The rate limiting state persists across application restarts.

Host Customization: Hosts can override this method to inject custom rate-limiting logic, such as blocking background checks when the device is on a metered network or has low battery.

Graceful Degradation: If this method returns true, the base class skips calling fetchUpdates and gracefully returns the currently cached data to the client. Because the client receives the cached state along with its original lastCheckTimeMillis, the client is not expected to manage complex backoff or retry loops.