src/extensions/browser/event_router.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef EXTENSIONS_BROWSER_EVENT_ROUTER_H_
   6 #define EXTENSIONS_BROWSER_EVENT_ROUTER_H_
   7
   8 #include <map>
   9 #include <set>
  10 #include <string>
  11 #include <utility>
  12
  13 #include "base/callback.h"
  14 #include "base/compiler_specific.h"
  15 #include "base/containers/hash_tables.h"
  16 #include "base/memory/linked_ptr.h"
  17 #include "base/memory/ref_counted.h"
  18 #include "base/scoped_observer.h"
  19 #include "base/values.h"
  20 #include "content/public/browser/notification_observer.h"
  21 #include "content/public/browser/notification_registrar.h"
  22 #include "extensions/browser/event_listener_map.h"
  23 #include "extensions/browser/extension_registry_observer.h"
  24 #include "extensions/common/event_filtering_info.h"
  25 #include "ipc/ipc_sender.h"
  26
  27 class GURL;
  28 class PrefService;
  29
  30 namespace content {
  31 class BrowserContext;
  32 class RenderProcessHost;
  33 }
  34
  35 namespace extensions {
  36 class ActivityLog;
  37 class Extension;
  38 class ExtensionHost;
  39 class ExtensionPrefs;
  40 class ExtensionRegistry;
  41
  42 struct Event;
  43 struct EventDispatchInfo;
  44 struct EventListenerInfo;
  45
  46 class EventRouter : public content::NotificationObserver,
  47                     public ExtensionRegistryObserver,
  48                     public EventListenerMap::Delegate {
  49  public:
  50   // These constants convey the state of our knowledge of whether we're in
  51   // a user-caused gesture as part of DispatchEvent.
  52   enum UserGestureState {
  53     USER_GESTURE_UNKNOWN = 0,
  54     USER_GESTURE_ENABLED = 1,
  55     USER_GESTURE_NOT_ENABLED = 2,
  56   };
  57
  58   // The pref key for the list of event names for which an extension has
  59   // registered from its lazy background page.
  60   static const char kRegisteredEvents[];
  61
  62   // Observers register interest in events with a particular name and are
  63   // notified when a listener is added or removed. Observers are matched by
  64   // the base name of the event (e.g. adding an event listener for event name
  65   // "foo.onBar/123" will trigger observers registered for "foo.onBar").
  66   class Observer {
  67    public:
  68     // Called when a listener is added.
  69     virtual void OnListenerAdded(const EventListenerInfo& details) {}
  70     // Called when a listener is removed.
  71     virtual void OnListenerRemoved(const EventListenerInfo& details) {}
  72   };
  73
  74   // Gets the EventRouter for |browser_context|.
  75   // Shorthand for ExtensionSystem::Get(browser_context)->event_router(); it's
  76   // a very common operation.
  77   static EventRouter* Get(content::BrowserContext* browser_context);
  78
  79   // Converts event names like "foo.onBar/123" into "foo.onBar". Event names
  80   // without a "/" are returned unchanged.
  81   static std::string GetBaseEventName(const std::string& full_event_name);
  82
  83   // Sends an event via ipc_sender to the given extension. Can be called on any
  84   // thread.
  85   static void DispatchEvent(IPC::Sender* ipc_sender,
  86                             void* browser_context_id,
  87                             const std::string& extension_id,
  88                             const std::string& event_name,
  89                             scoped_ptr<base::ListValue> event_args,
  90                             UserGestureState user_gesture,
  91                             const EventFilteringInfo& info);
  92
  93   // An EventRouter is shared between |browser_context| and its associated
  94   // incognito context. |extension_prefs| may be NULL in tests.
  95   EventRouter(content::BrowserContext* browser_context,
  96               ExtensionPrefs* extension_prefs);
  97   ~EventRouter() override;
  98
  99   // Add or remove an extension as an event listener for |event_name|.
 100   //
 101   // Note that multiple extensions can share a process due to process
 102   // collapsing. Also, a single extension can have 2 processes if it is a split
 103   // mode extension.
 104   void AddEventListener(const std::string& event_name,
 105                         content::RenderProcessHost* process,
 106                         const std::string& extension_id);
 107   void RemoveEventListener(const std::string& event_name,
 108                            content::RenderProcessHost* process,
 109                            const std::string& extension_id);
 110
 111   // Add or remove a URL as an event listener for |event_name|.
 112   void AddEventListenerForURL(const std::string& event_name,
 113                               content::RenderProcessHost* process,
 114                               const GURL& listener_url);
 115   void RemoveEventListenerForURL(const std::string& event_name,
 116                                  content::RenderProcessHost* process,
 117                                  const GURL& listener_url);
 118
 119   EventListenerMap& listeners() { return listeners_; }
 120
 121   // Registers an observer to be notified when an event listener for
 122   // |event_name| is added or removed. There can currently be only one observer
 123   // for each distinct |event_name|.
 124   void RegisterObserver(Observer* observer,
 125                         const std::string& event_name);
 126
 127   // Unregisters an observer from all events.
 128   void UnregisterObserver(Observer* observer);
 129
 130   // Add or remove the extension as having a lazy background page that listens
 131   // to the event. The difference from the above methods is that these will be
 132   // remembered even after the process goes away. We use this list to decide
 133   // which extension pages to load when dispatching an event.
 134   void AddLazyEventListener(const std::string& event_name,
 135                             const std::string& extension_id);
 136   void RemoveLazyEventListener(const std::string& event_name,
 137                                const std::string& extension_id);
 138
 139   // If |add_lazy_listener| is true also add the lazy version of this listener.
 140   void AddFilteredEventListener(const std::string& event_name,
 141                                 content::RenderProcessHost* process,
 142                                 const std::string& extension_id,
 143                                 const base::DictionaryValue& filter,
 144                                 bool add_lazy_listener);
 145
 146   // If |remove_lazy_listener| is true also remove the lazy version of this
 147   // listener.
 148   void RemoveFilteredEventListener(const std::string& event_name,
 149                                    content::RenderProcessHost* process,
 150                                    const std::string& extension_id,
 151                                    const base::DictionaryValue& filter,
 152                                    bool remove_lazy_listener);
 153
 154   // Returns true if there is at least one listener for the given event.
 155   bool HasEventListener(const std::string& event_name);
 156
 157   // Returns true if the extension is listening to the given event.
 158   bool ExtensionHasEventListener(const std::string& extension_id,
 159                                  const std::string& event_name);
 160
 161   // Return or set the list of events for which the given extension has
 162   // registered.
 163   std::set<std::string> GetRegisteredEvents(const std::string& extension_id);
 164   void SetRegisteredEvents(const std::string& extension_id,
 165                            const std::set<std::string>& events);
 166
 167   // Broadcasts an event to every listener registered for that event.
 168   virtual void BroadcastEvent(scoped_ptr<Event> event);
 169
 170   // Dispatches an event to the given extension.
 171   virtual void DispatchEventToExtension(const std::string& extension_id,
 172                                         scoped_ptr<Event> event);
 173
 174   // Dispatches |event| to the given extension as if the extension has a lazy
 175   // listener for it. NOTE: This should be used rarely, for dispatching events
 176   // to extensions that haven't had a chance to add their own listeners yet, eg:
 177   // newly installed extensions.
 178   void DispatchEventWithLazyListener(const std::string& extension_id,
 179                                      scoped_ptr<Event> event);
 180
 181   // Record the Event Ack from the renderer. (One less event in-flight.)
 182   void OnEventAck(content::BrowserContext* context,
 183                   const std::string& extension_id);
 184
 185  private:
 186   friend class EventRouterTest;
 187
 188   // The extension and process that contains the event listener for a given
 189   // event.
 190   struct ListenerProcess;
 191
 192   // A map between an event name and a set of extensions that are listening
 193   // to that event.
 194   typedef std::map<std::string, std::set<ListenerProcess> > ListenerMap;
 195
 196   // An identifier for an event dispatch that is used to prevent double dispatch
 197   // due to race conditions between the direct and lazy dispatch paths.
 198   typedef std::pair<const content::BrowserContext*, std::string>
 199       EventDispatchIdentifier;
 200
 201   // TODO(gdk): Document this.
 202   static void DispatchExtensionMessage(
 203       IPC::Sender* ipc_sender,
 204       void* browser_context_id,
 205       const std::string& extension_id,
 206       const std::string& event_name,
 207       base::ListValue* event_args,
 208       UserGestureState user_gesture,
 209       const extensions::EventFilteringInfo& info);
 210
 211   void Observe(int type,
 212                const content::NotificationSource& source,
 213                const content::NotificationDetails& details) override;
 214   // ExtensionRegistryObserver implementation.
 215   void OnExtensionLoaded(content::BrowserContext* browser_context,
 216                          const Extension* extension) override;
 217   void OnExtensionUnloaded(content::BrowserContext* browser_context,
 218                            const Extension* extension,
 219                            UnloadedExtensionInfo::Reason reason) override;
 220
 221   // Returns true if the given listener map contains a event listeners for
 222   // the given event. If |extension_id| is non-empty, we also check that that
 223   // extension is one of the listeners.
 224   bool HasEventListenerImpl(const ListenerMap& listeners,
 225                             const std::string& extension_id,
 226                             const std::string& event_name);
 227
 228   // Shared by DispatchEvent*. If |restrict_to_extension_id| is empty, the
 229   // event is broadcast.
 230   // An event that just came off the pending list may not be delayed again.
 231   void DispatchEventImpl(const std::string& restrict_to_extension_id,
 232                          const linked_ptr<Event>& event);
 233
 234   // Ensures that all lazy background pages that are interested in the given
 235   // event are loaded, and queues the event if the page is not ready yet.
 236   // Inserts an EventDispatchIdentifier into |already_dispatched| for each lazy
 237   // event dispatch that is queued.
 238   void DispatchLazyEvent(const std::string& extension_id,
 239                          const linked_ptr<Event>& event,
 240                          std::set<EventDispatchIdentifier>* already_dispatched);
 241
 242   // Dispatches the event to the specified extension or URL running in
 243   // |process|.
 244   void DispatchEventToProcess(const std::string& extension_id,
 245                               const GURL& listener_url,
 246                               content::RenderProcessHost* process,
 247                               const linked_ptr<Event>& event);
 248
 249   // Returns false when the event is scoped to a context and the listening
 250   // extension does not have access to events from that context. Also fills
 251   // |event_args| with the proper arguments to send, which may differ if
 252   // the event crosses the incognito boundary.
 253   bool CanDispatchEventToBrowserContext(content::BrowserContext* context,
 254                                         const Extension* extension,
 255                                         const linked_ptr<Event>& event);
 256
 257   // Possibly loads given extension's background page in preparation to
 258   // dispatch an event.  Returns true if the event was queued for subsequent
 259   // dispatch, false otherwise.
 260   bool MaybeLoadLazyBackgroundPageToDispatchEvent(
 261       content::BrowserContext* context,
 262       const Extension* extension,
 263       const linked_ptr<Event>& event);
 264
 265   // Adds a filter to an event.
 266   void AddFilterToEvent(const std::string& event_name,
 267                         const std::string& extension_id,
 268                         const base::DictionaryValue* filter);
 269
 270   // Removes a filter from an event.
 271   void RemoveFilterFromEvent(const std::string& event_name,
 272                              const std::string& extension_id,
 273                              const base::DictionaryValue* filter);
 274
 275   // Returns the dictionary of event filters that the given extension has
 276   // registered.
 277   const base::DictionaryValue* GetFilteredEvents(
 278       const std::string& extension_id);
 279
 280   // Track of the number of dispatched events that have not yet sent an
 281   // ACK from the renderer.
 282   void IncrementInFlightEvents(content::BrowserContext* context,
 283                                const Extension* extension);
 284
 285   // static
 286   static void IncrementInFlightEventsOnUI(
 287       void* browser_context_id,
 288       const std::string& extension_id);
 289
 290   void DispatchPendingEvent(const linked_ptr<Event>& event,
 291                             ExtensionHost* host);
 292
 293   // Implementation of EventListenerMap::Delegate.
 294   void OnListenerAdded(const EventListener* listener) override;
 295   void OnListenerRemoved(const EventListener* listener) override;
 296
 297   content::BrowserContext* browser_context_;
 298
 299   // The ExtensionPrefs associated with |browser_context_|. May be NULL in
 300   // tests.
 301   ExtensionPrefs* extension_prefs_;
 302
 303   content::NotificationRegistrar registrar_;
 304
 305   ScopedObserver<ExtensionRegistry, ExtensionRegistryObserver>
 306       extension_registry_observer_;
 307
 308   EventListenerMap listeners_;
 309
 310   // Map from base event name to observer.
 311   typedef base::hash_map<std::string, Observer*> ObserverMap;
 312   ObserverMap observers_;
 313
 314   DISALLOW_COPY_AND_ASSIGN(EventRouter);
 315 };
 316
 317 struct Event {
 318   typedef base::Callback<void(content::BrowserContext*,
 319                               const Extension*,
 320                               base::ListValue*)> WillDispatchCallback;
 321
 322   // The event to dispatch.
 323   std::string event_name;
 324
 325   // Arguments to send to the event listener.
 326   scoped_ptr<base::ListValue> event_args;
 327
 328   // If non-NULL, then the event will not be sent to other BrowserContexts
 329   // unless the extension has permission (e.g. incognito tab update -> normal
 330   // tab only works if extension is allowed incognito access).
 331   content::BrowserContext* restrict_to_browser_context;
 332
 333   // If not empty, the event is only sent to extensions with host permissions
 334   // for this url.
 335   GURL event_url;
 336
 337   // Whether a user gesture triggered the event.
 338   EventRouter::UserGestureState user_gesture;
 339
 340   // Extra information used to filter which events are sent to the listener.
 341   EventFilteringInfo filter_info;
 342
 343   // If specified, this is called before dispatching an event to each
 344   // extension. The third argument is a mutable reference to event_args,
 345   // allowing the caller to provide different arguments depending on the
 346   // extension and profile. This is guaranteed to be called synchronously with
 347   // DispatchEvent, so callers don't need to worry about lifetime.
 348   //
 349   // NOTE: the Extension argument to this may be NULL because it's possible for
 350   // this event to be dispatched to non-extension processes, like WebUI.
 351   WillDispatchCallback will_dispatch_callback;
 352
 353   Event(const std::string& event_name,
 354         scoped_ptr<base::ListValue> event_args);
 355
 356   Event(const std::string& event_name,
 357         scoped_ptr<base::ListValue> event_args,
 358         content::BrowserContext* restrict_to_browser_context);
 359
 360   Event(const std::string& event_name,
 361         scoped_ptr<base::ListValue> event_args,
 362         content::BrowserContext* restrict_to_browser_context,
 363         const GURL& event_url,
 364         EventRouter::UserGestureState user_gesture,
 365         const EventFilteringInfo& info);
 366
 367   ~Event();
 368
 369   // Makes a deep copy of this instance. Ownership is transferred to the
 370   // caller.
 371   Event* DeepCopy();
 372 };
 373
 374 struct EventListenerInfo {
 375   EventListenerInfo(const std::string& event_name,
 376                     const std::string& extension_id,
 377                     const GURL& listener_url,
 378                     content::BrowserContext* browser_context);
 379   // The event name including any sub-event, e.g. "runtime.onStartup" or
 380   // "webRequest.onCompleted/123".
 381   const std::string event_name;
 382
 383   const std::string extension_id;
 384   const GURL listener_url;
 385   content::BrowserContext* browser_context;
 386 };
 387
 388 }  // namespace extensions
 389
 390 #endif  // EXTENSIONS_BROWSER_EVENT_ROUTER_H_