Terminology
- InstanceID: An identifier for “a specific app installed on a specific device”. The term comes from GMSCore on Android. Here, an “app” is a client of invalidations, such as Sync, Drive, or Policy. It's just a mostly random string of 8 bytes, created by Chrome.
- Registration: As in “registering with FCM”; means making an InstanceID known to the FCM server. The result of registering is an InstanceID token (note that this is different from an InstanceID).
- Topic: A “namespace” or “channel” of messages that clients can subscribe to. For Sync, they correspond to data types. A topic can be either private (i.e. GAIA-keyed) or public. For private topics, a unique ID derived from the user's GAIA ID is appended to the topic name to make it unique (though this is an implementation detail which is hidden from clients).
- Subscription: As in “subscribing to a topic”, i.e. telling the server that this client (identified by InstanceID token) is interested in a given topic.
- ProjectID (aka SenderID): An ID from the Google Cloud Platform console that identifies a client of invalidations (such as Sync, Drive, or Policy). E.g. for Sync its value is kInvalidationGCMSenderId. Note that (as opposed to InstanceID) this is constant across all users and Chrome instances.
Classes
InvalidationHandler
An InvalidationHandler is a client (receiver) of Invalidations. Every feature that wants to receive Invalidations needs to implement an InvalidationHandler and register it with InvalidationService (see below). InvalidationHandler has the following methods (the list is not exhaustive):
- OnIncomingInvalidation is called from InvalidationService to notify about incoming Invalidation messages.
- GetOwnerName must return a unique name for this InvalidationHandler.
InvalidationService
InvalidationService is the main entry point for clients of the Invalidations system. This is where an InvalidationHandler registers/unregisters itself, and where it registers the Topics it is interested in. When a message arrives, InvalidationService calls OnIncomingInvalidation for the receiving InvalidationHandler.
InvalidationService provides the following methods (the list is not exhaustive):
- RegisterInvalidationHandler allows an InvalidationHandler to register itself as a observer for Invalidations. InvalidationService will only dispatch messages to registered handlers.
- UpdateInterestedTopics allows InvalidationHandler to change the set of Topics it is interested in.
- UnregisterInvalidationHandler lets an InvalidationHandler unregister itself again, after which it stops receiving Invalidations.
An InvalidationService instance is usually tied to a profile (via ProfileInvalidationProviderFactory), but on ChromeOS there is also a device-scoped instance, managed by AffiliatedInvalidationServiceProvider (used for device policies, which must apply even before any user is signed in).
FCMInvalidationService
FCMInvalidationService is the only real (non-test) implementation of InvalidationService, using FCM+Fandango as its publish/subscribe service. It delegates most of the work to InvalidatorRegistrarWithMemory and FCMInvalidationListener.
InvalidatorRegistrarWithMemory
InvalidatorRegistrarWithMemory maintains the mapping between Topics and InvalidationHandlers. When a message arrives via FCMInvalidationListener, InvalidatorRegistrarWithMemory dispatches that message (invalidation) to the appropriate InvalidationHandler.
InvalidatorRegistrarWithMemory also persists the set of Topics per handler, to avoid redundant re-subscriptions after every Chrome restart.
FCMInvalidationListener
FCMInvalidationListener gets the list of interesting Topics from FCMInvalidationService. It passes the Topics to PerUserTopicSubscriptionManager (see below) for subscription/unsubscription, receives Invalidation messages from FCMNetworkHandler, and passes Invalidations for the interesting Topics back to FCMInvalidationService.
PerUserTopicSubscriptionManager
PerUserTopicSubscriptionManager manages subscriptions to Topics, sending subscription or unsubscriptions requests to the server as necessary. It persists the set of subscribed Topics in prefs to avoid redundant re-subscriptions after Chrome restarts.
FCMNetworkHandler
FCMNetworkHandler is responsible for communication via GCM channel. It provides the following functionality:
- Retrieves the InstanceID token required for the subscription. When this token is received, it is passed to PerUserTopicSubscriptionManager which subscribes to Topics with the given token.
- Receives messages from GCM driver and passes them up to FCMInvalidationListener, where they are converted to Invalidations.