RulesRegistry for declarative APIs.

chrome/browser/extensions/api/declarative/rules_registry.h

Index: chrome/browser/extensions/api/declarative/rules_registry.h
diff --git a/chrome/browser/extensions/api/declarative/rules_registry.h b/chrome/browser/extensions/api/declarative/rules_registry.h
new file mode 100644
index 0000000000000000000000000000000000000000..0bd99370e8539824c6861ad5dd87be381c072087
--- /dev/null
+++ b/chrome/browser/extensions/api/declarative/rules_registry.h
@@ -0,0 +1,69 @@
+// Copyright (c) 2012 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef CHROME_BROWSER_EXTENSIONS_API_DECLARATIVE_RULES_REGISTRY_H__
+#define CHROME_BROWSER_EXTENSIONS_API_DECLARATIVE_RULES_REGISTRY_H__
+#pragma once
+
+#include <string>
+#include <vector>
+
+#include "base/values.h"
+
+namespace extensions {
+
+// Interface for rule registries.
+class RulesRegistry {
+ public:
+  virtual ~RulesRegistry() {}
+
+  // Registers |rules|, owned by |extension_id| to this RulesRegistry.
+  // If a concrete RuleRegistry does not support some of the rules,
+  // it may ignore them.
+  //
+  // |rules| is a list of Rule instances following the definition of the
+  // declarative extension APIs. It is guaranteed that each rule in |rules| has
+  // a unique name within the scope of |extension_id| that has not been
+  // registered before, unless it has been removed again.
+  // The ownership of rules remains with the caller.
+  //
+  // Returns true if the function is successful. Otherwise, an error message
+  // can be written into |error|.
+  //
+  // IMPORTANT: This function is atomic. Either all rules that are deemed
+  // relevant are added or none.
+  virtual bool AddRules(const std::string& extension_id,
+                        const std::vector<DictionaryValue*>& rules,
+                        std::string* error) = 0;
+
+  // Unregisters all rules listed in |rule_identifiers| and owned by
+  // |extension_id| from this RulesRegistry. If |rule_identifiers| is empty, all
+  // rules of this extension will be unregistered.
+  // Some or all IDs in |rule_identifiers| may not affect this RulesRegistry.
+  //
+  // Returns true if the function is successful. Otherwise, an error message
+  // can be written into |error|.
+  //
+  // IMPORTANT: This function is atomic. Either all rules that are deemed
+  // relevant are removed or none.
+  virtual bool RemoveRules(const std::string& extension_id,
+                           const std::vector<std::string>& rule_identifiers,
+                           std::string* error) = 0;

[not at google - send to devlin, 2012/02/07 03:25:10]

I think it's possible/simpler to return a std::string error (rather than as an
out-parameter) and having (return value).empty() imply success.

[battre, 2012/02/07 18:45:33]

We need to change the interface to be asynchronous anyway (the webrequest API
implementation needs to live on the IO thread and even implementations that live
on the UI thread might require some preprocessing that should not happen on the
UI thread). I will do that change in a separate CL.

[not at google - send to devlin, 2012/02/07 23:54:57]

Do you mean the FILE thread?  IO thread is for IPCs.

Either way, the threading issue isn't going to be solved by making this API
asynchronous; I think it will end up with the threading stuff a concern of
either the API bindings, or another class that wraps this interface (see how the
storage API works). So the interface probably won't need to be changed.

Unless you're strongly opposed to this method returning the error directly, I
think that would be simpler and preferable.

[battre, 2012/02/08 12:49:54]

The network stack lives on the IO thread. For the declarative webrequest API we
will want to handle events in the NetworkDelegate or
ExtensionWebRequestEventRouter. Both live on the IO thread.

Of course we don't want to block the IO thread indefinitely either. We'll need
to figure out a strategy. Maybe we will use the WorkerPool.

Either way, for this to work we need to to move from the SyncExtensionFunctions
in declarative_api.h to AsyncExtensionFunctions. We can then figure out the best
way to handle the RulesRegistries. I can see the following protocol:

- AddRulesFunction is called from extension on UI thread
- Preprocessing is done on SequencedWorkerPool thread
- Internal representation of webrequest rules is replaced on IO thread with the
one that was generated in the previous preporcessing thread
- AddRulesFunction confirms success on UI thread

I can see that the Preprocessing could remain synchronous, trigger an
asynchronous update to the IO thread and confirm success before the update on
the IO thread has been executed.
Let's see.
Ok, I have changed the signatures to return a std::string.

Done.

[not at google - send to devlin, 2012/02/08 22:31:18]

Cool, sounds good.

+
+  // Returns all rules listed in |rule_identifiers| and owned by |extension_id|
+  // registered in this RuleRegistry. If |rule_identifiers| is empty, all rules
+  // of |extension_id| are returned.
+  // The returned rules are stored in |out|. Ownership is passed to the caller.
+  virtual void GetRules(const std::string& extension_id,
+                        const std::vector<std::string>& rule_identifiers,
+                        std::vector<DictionaryValue*>* out) = 0;

[not at google - send to devlin, 2012/02/07 23:54:57]

Should GetRules have the ability to report errors?

[battre, 2012/02/08 12:49:54]

Done.

+
+  // Called to notify the RulesRegistry that an extension has been unloaded
+  // and all rules of this extension need to be removed.
+  virtual void OnExtensionUnloaded(const std::string& extension_id) = 0;
+};
+
+}  // namespace extensions
+
+#endif  // CHROME_BROWSER_EXTENSIONS_API_DECLARATIVE_RULES_REGISTRY_H__