UpdateInfoService

public void dump(FileDescriptor fd, PrintWriter writer, String[] args)

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).

public final IBinder onBind(Intent intent)

Called by the system when a client binds to the particular interface defined by the intent.

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.

Lifecycle Note: Because the client library attaches unique data (the package name) to the intent, this method is called for every new client session, allowing the onClientConnected hook to reliably track individual connections.

public final boolean onUnbind(Intent intent)

Called by the system when all clients have disconnected from the particular interface defined by the intent.

This method is marked final to enforce the library's lifecycle contract. It performs two critical actions:

1. Triggers the onClientDisconnected hook, allowing the host to log the end of the session.

2. Returns false, which forces the Android system to call onBind (and thus onClientConnected) for all future connections. This simplifies telemetry by ensuring a consistent "Connect -> Disconnect" cycle without needing to handle the onRebind edge case.

protected abstract @NonNull List<@NonNull UpdateInfo> fetchUpdates()

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

Implementations of this method should:

• Block until the network request completes.

• Return the list of updates found.

• Throw an exception if the network request fails (this will be caught and logged).

Note: This method is only called if shouldFetchUpdates returns true and the rate limiter allows the request.

protected int getCallerUid()

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 void onClientConnected(@NonNull Intent intent)

Called when a client binds to the particular interface defined by the intent.

This method is invoked during onBind after the Intent action has been verified.

Usage: Override this method to log connection metrics (e.g., "Session Started") or track adoption trends.

Client Identity: The intent passed to this method typically contains the client's package name in the data URI (e.g., package:com.example.client). This allows you to identify which app is starting a session. Note that this value is self-reported by the client library and is useful for aggregate trends but less secure than the UpdateCheckTelemetry.callerUid captured in onRequestCompleted.

Lifecycle: Because the client library attaches unique data to the bind Intent, this method is called for every new client session, enabling accurate session counting.

protected void onClientDisconnected(Intent intent)

Called when all clients have disconnected from the particular interface defined by the intent.

This method is invoked during onUnbind.

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 void onFetchFailed(@NonNull Exception e)

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

This method is invoked if any step of the update logic fails, including:

• Determining cache freshness (shouldFetchUpdates).

• Recording rate-limit attempts.

• Fetching data from the backend (fetchUpdates).

• Persisting the results to local storage.

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

protected void onRequestCompleted(@NonNull UpdateCheckTelemetry telemetry)

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 boolean shouldFetchUpdates()

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 boolean shouldThrottle()

Checks if the operation should be throttled based on the rate limiter.

The default implementation delegates to an internal rate limiter that enforces a cooling-off period (e.g., one check per hour). Hosts can override this to inject custom rate limiting logic (e.g., battery checks).