1 // Copyright 2014 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.
5 // This class contains common functionality for search-based autocomplete
6 // providers. Search provider and zero suggest provider both use it for common
9 #ifndef CHROME_BROWSER_AUTOCOMPLETE_BASE_SEARCH_PROVIDER_H_
10 #define CHROME_BROWSER_AUTOCOMPLETE_BASE_SEARCH_PROVIDER_H_
17 #include "base/memory/scoped_vector.h"
18 #include "base/strings/string16.h"
19 #include "chrome/browser/autocomplete/autocomplete_input.h"
20 #include "chrome/browser/autocomplete/autocomplete_match.h"
21 #include "chrome/browser/autocomplete/autocomplete_provider.h"
22 #include "net/url_request/url_fetcher_delegate.h"
24 class AutocompleteProviderListener;
27 class SuggestionDeletionHandler;
35 // Base functionality for receiving suggestions from a search engine.
36 // This class is abstract and should only be used as a base for other
37 // autocomplete providers utilizing its functionality.
38 class BaseSearchProvider : public AutocompleteProvider,
39 public net::URLFetcherDelegate {
41 // ID used in creating URLFetcher for default provider's suggest results.
42 static const int kDefaultProviderURLFetcherID;
44 // ID used in creating URLFetcher for keyword provider's suggest results.
45 static const int kKeywordProviderURLFetcherID;
47 // ID used in creating URLFetcher for deleting suggestion results.
48 static const int kDeletionURLFetcherID;
50 BaseSearchProvider(AutocompleteProviderListener* listener,
52 AutocompleteProvider::Type type);
54 // Returns whether |match| is flagged as a query that should be prefetched.
55 static bool ShouldPrefetch(const AutocompleteMatch& match);
57 // Returns a simpler AutocompleteMatch suitable for persistence like in
59 // NOTE: Use with care. Most likely you want the other CreateSearchSuggestion
60 // with protected access.
61 static AutocompleteMatch CreateSearchSuggestion(
62 const base::string16& suggestion,
63 AutocompleteMatchType::Type type,
64 bool from_keyword_provider,
65 const TemplateURL* template_url);
67 // AutocompleteProvider:
68 virtual void Stop(bool clear_cached_results) OVERRIDE;
69 virtual void DeleteMatch(const AutocompleteMatch& match) OVERRIDE;
70 virtual void AddProviderInfo(ProvidersInfo* provider_info) const OVERRIDE;
72 bool field_trial_triggered_in_session() const {
73 return field_trial_triggered_in_session_;
77 // The following keys are used to record additional information on matches.
79 // We annotate our AutocompleteMatches with whether their relevance scores
80 // were server-provided using this key in the |additional_info| field.
81 static const char kRelevanceFromServerKey[];
83 // Indicates whether the server said a match should be prefetched.
84 static const char kShouldPrefetchKey[];
86 // Used to store metadata from the server response, which is needed for
88 static const char kSuggestMetadataKey[];
90 // Used to store a deletion request url for server-provided suggestions.
91 static const char kDeletionUrlKey[];
93 // These are the values for the above keys.
94 static const char kTrue[];
95 static const char kFalse[];
97 virtual ~BaseSearchProvider();
99 // The Result classes are intermediate representations of AutocompleteMatches,
100 // simply containing relevance-ranked search and navigation suggestions.
101 // They may be cached to provide some synchronous matches while requests for
102 // new suggestions from updated input are in flight.
103 // TODO(msw) Extend these classes to generate their corresponding matches and
104 // other requisite data, in order to consolidate and simplify the
105 // highly fragmented SearchProvider logic for each Result type.
108 Result(bool from_keyword_provider,
110 bool relevance_from_server);
113 bool from_keyword_provider() const { return from_keyword_provider_; }
115 const base::string16& match_contents() const { return match_contents_; }
116 const ACMatchClassifications& match_contents_class() const {
117 return match_contents_class_;
120 int relevance() const { return relevance_; }
121 void set_relevance(int relevance) { relevance_ = relevance; }
123 bool relevance_from_server() const { return relevance_from_server_; }
124 void set_relevance_from_server(bool relevance_from_server) {
125 relevance_from_server_ = relevance_from_server;
128 // Returns if this result is inlineable against the current input |input|.
129 // Non-inlineable results are stale.
130 virtual bool IsInlineable(const base::string16& input) const = 0;
132 // Returns the default relevance value for this result (which may
133 // be left over from a previous omnibox input) given the current
134 // input and whether the current input caused a keyword provider
136 virtual int CalculateRelevance(const AutocompleteInput& input,
137 bool keyword_provider_requested) const = 0;
140 // The contents to be displayed and its style info.
141 base::string16 match_contents_;
142 ACMatchClassifications match_contents_class_;
144 // True if the result came from the keyword provider.
145 bool from_keyword_provider_;
147 // The relevance score.
151 // Whether this result's relevance score was fully or partly calculated
152 // based on server information, and thus is assumed to be more accurate.
153 // This is ultimately used in
154 // SearchProvider::ConvertResultsToAutocompleteMatches(), see comments
156 bool relevance_from_server_;
159 class SuggestResult : public Result {
161 SuggestResult(const base::string16& suggestion,
162 AutocompleteMatchType::Type type,
163 const base::string16& match_contents,
164 const base::string16& match_contents_prefix,
165 const base::string16& annotation,
166 const std::string& suggest_query_params,
167 const std::string& deletion_url,
168 bool from_keyword_provider,
170 bool relevance_from_server,
171 bool should_prefetch,
172 const base::string16& input_text);
173 virtual ~SuggestResult();
175 const base::string16& suggestion() const { return suggestion_; }
176 AutocompleteMatchType::Type type() const { return type_; }
177 const base::string16& match_contents_prefix() const {
178 return match_contents_prefix_;
180 const base::string16& annotation() const { return annotation_; }
181 const std::string& suggest_query_params() const {
182 return suggest_query_params_;
184 const std::string& deletion_url() const { return deletion_url_; }
185 bool should_prefetch() const { return should_prefetch_; }
187 // Fills in |match_contents_class_| to reflect how |match_contents_| should
188 // be displayed and bolded against the current |input_text|. If
189 // |allow_bolding_all| is false and |match_contents_class_| would have all
190 // of |match_contents_| bolded, do nothing.
191 void ClassifyMatchContents(const bool allow_bolding_all,
192 const base::string16& input_text);
195 virtual bool IsInlineable(const base::string16& input) const OVERRIDE;
196 virtual int CalculateRelevance(
197 const AutocompleteInput& input,
198 bool keyword_provider_requested) const OVERRIDE;
201 // The search terms to be used for this suggestion.
202 base::string16 suggestion_;
204 AutocompleteMatchType::Type type_;
206 // The contents to be displayed as prefix of match contents.
207 // Used for postfix suggestions to display a leading ellipsis (or some
208 // equivalent character) to indicate omitted text.
209 // Only used to pass this information to about:omnibox's "Additional Info".
210 base::string16 match_contents_prefix_;
212 // Optional annotation for the |match_contents_| for disambiguation.
213 // This may be displayed in the autocomplete match contents, but is defined
214 // separately to facilitate different formatting.
215 base::string16 annotation_;
217 // Optional additional parameters to be added to the search URL.
218 std::string suggest_query_params_;
220 // Optional deletion URL provided with suggestions. Fetching this URL
221 // should result in some reasonable deletion behaviour on the server,
222 // e.g. deleting this term out of a user's server-side search history.
223 std::string deletion_url_;
225 // Should this result be prefetched?
226 bool should_prefetch_;
229 class NavigationResult : public Result {
231 // |provider| is necessary to use StringForURLDisplay() in order to
232 // compute |formatted_url_|.
233 NavigationResult(const AutocompleteProvider& provider,
235 const base::string16& description,
236 bool from_keyword_provider,
238 bool relevance_from_server,
239 const base::string16& input_text,
240 const std::string& languages);
241 virtual ~NavigationResult();
243 const GURL& url() const { return url_; }
244 const base::string16& description() const { return description_; }
245 const base::string16& formatted_url() const { return formatted_url_; }
247 // Fills in |match_contents_| and |match_contents_class_| to reflect how
248 // the URL should be displayed and bolded against the current |input_text|
249 // and user |languages|. If |allow_bolding_nothing| is false and
250 // |match_contents_class_| would result in an entirely unbolded
251 // |match_contents_|, do nothing.
252 void CalculateAndClassifyMatchContents(const bool allow_bolding_nothing,
253 const base::string16& input_text,
254 const std::string& languages);
257 virtual bool IsInlineable(const base::string16& input) const OVERRIDE;
258 virtual int CalculateRelevance(
259 const AutocompleteInput& input,
260 bool keyword_provider_requested) const OVERRIDE;
263 // The suggested url for navigation.
266 // The properly formatted ("fixed up") URL string with equivalent meaning
267 // to the one in |url_|.
268 base::string16 formatted_url_;
270 // The suggested navigational result description; generally the site name.
271 base::string16 description_;
274 typedef std::vector<SuggestResult> SuggestResults;
275 typedef std::vector<NavigationResult> NavigationResults;
276 typedef std::pair<base::string16, std::string> MatchKey;
277 typedef std::map<MatchKey, AutocompleteMatch> MatchMap;
278 typedef ScopedVector<SuggestionDeletionHandler> SuggestionDeletionHandlers;
280 // A simple structure bundling most of the information (including
281 // both SuggestResults and NavigationResults) returned by a call to
282 // the suggest server.
284 // This has to be declared after the typedefs since it relies on some of them.
289 // Clears |suggest_results| and |navigation_results| and resets
290 // |verbatim_relevance| to -1 (implies unset).
293 // Returns whether any of the results (including verbatim) have
294 // server-provided scores.
295 bool HasServerProvidedScores() const;
297 // Query suggestions sorted by relevance score.
298 SuggestResults suggest_results;
300 // Navigational suggestions sorted by relevance score.
301 NavigationResults navigation_results;
303 // The server supplied verbatim relevance scores. Negative values
304 // indicate that there is no suggested score; a value of 0
305 // suppresses the verbatim result.
306 int verbatim_relevance;
308 // The JSON metadata associated with this server response.
309 std::string metadata;
312 DISALLOW_COPY_AND_ASSIGN(Results);
315 // Returns an AutocompleteMatch with the given |autocomplete_provider|
316 // for the search |suggestion|, which represents a search via |template_url|.
317 // If |template_url| is NULL, returns a match with an invalid destination URL.
319 // |input| is the original user input. Text in the input is used to highlight
320 // portions of the match contents to distinguish locally-typed text from
323 // |input| is also necessary for various other details, like whether we should
324 // allow inline autocompletion and what the transition type should be.
325 // |accepted_suggestion| and |omnibox_start_margin| are used to generate
326 // Assisted Query Stats.
327 // |append_extra_query_params| should be set if |template_url| is the default
328 // search engine, so the destination URL will contain any
329 // command-line-specified query params.
330 static AutocompleteMatch CreateSearchSuggestion(
331 AutocompleteProvider* autocomplete_provider,
332 const AutocompleteInput& input,
333 const SuggestResult& suggestion,
334 const TemplateURL* template_url,
335 int accepted_suggestion,
336 int omnibox_start_margin,
337 bool append_extra_query_params);
339 // Parses JSON response received from the provider, stripping XSSI
340 // protection if needed. Returns the parsed data if successful, NULL
342 static scoped_ptr<base::Value> DeserializeJsonData(std::string json_data);
344 // Returns whether the requirements for requesting zero suggest results
345 // are met. The requirements are
346 // * The user is enrolled in a zero suggest experiment.
347 // * The user is not on the NTP.
348 // * The suggest request is sent over HTTPS. This avoids leaking the current
349 // page URL or personal data in unencrypted network traffic.
350 // * The user has suggest enabled in their settings and is not in incognito
351 // mode. (Incognito disables suggest entirely.)
352 // * The user's suggest provider is Google. We might want to allow other
353 // providers to see this data someday, but for now this has only been
354 // implemented for Google.
355 static bool ZeroSuggestEnabled(
356 const GURL& suggest_url,
357 const TemplateURL* template_url,
358 AutocompleteInput::PageClassification page_classification,
361 // Returns whether we can send the URL of the current page in any suggest
362 // requests. Doing this requires that all the following hold:
363 // * ZeroSuggestEnabled() is true, so we meet the requirements above.
364 // * The current URL is HTTP, or HTTPS with the same domain as the suggest
365 // server. Non-HTTP[S] URLs (e.g. FTP/file URLs) may contain sensitive
366 // information. HTTPS URLs may also contain sensitive information, but if
367 // they're on the same domain as the suggest server, then the relevant
368 // entity could have already seen/logged this data.
369 // * The user is OK in principle with sending URLs of current pages to their
370 // provider. Today, there is no explicit setting that controls this, but if
371 // the user has tab sync enabled and tab sync is unencrypted, then they're
372 // already sending this data to Google for sync purposes. Thus we use this
373 // setting as a proxy for "it's OK to send such data". In the future,
374 // especially if we want to support suggest providers other than Google, we
375 // may change this to be a standalone setting or part of some explicit
377 static bool CanSendURL(
378 const GURL& current_page_url,
379 const GURL& suggest_url,
380 const TemplateURL* template_url,
381 AutocompleteInput::PageClassification page_classification,
384 // net::URLFetcherDelegate:
385 virtual void OnURLFetchComplete(const net::URLFetcher* source) OVERRIDE;
387 // Creates an AutocompleteMatch from |result| to search for the query in
388 // |result|. Adds the created match to |map|; if such a match
389 // already exists, whichever one has lower relevance is eliminated.
390 // |metadata| and |accepted_suggestion| are used for generating an
391 // AutocompleteMatch.
392 // |mark_as_deletable| indicates whether the match should be marked deletable.
393 // NOTE: Any result containing a deletion URL is always marked deletable.
394 void AddMatchToMap(const SuggestResult& result,
395 const std::string& metadata,
396 int accepted_suggestion,
397 bool mark_as_deletable,
400 // Parses results from the suggest server and updates the appropriate suggest
401 // and navigation result lists in |results|. |is_keyword_result| indicates
402 // whether the response was received from the keyword provider.
403 // Returns whether the appropriate result list members were updated.
404 bool ParseSuggestResults(const base::Value& root_val,
405 bool is_keyword_result,
408 // Called at the end of ParseSuggestResults to rank the |results|.
409 virtual void SortResults(bool is_keyword,
410 const base::ListValue* relevances,
413 // Returns the TemplateURL corresponding to the keyword or default
414 // provider based on the value of |is_keyword|.
415 virtual const TemplateURL* GetTemplateURL(bool is_keyword) const = 0;
417 // Returns the AutocompleteInput for keyword provider or default provider
418 // based on the value of |is_keyword|.
419 virtual const AutocompleteInput GetInput(bool is_keyword) const = 0;
421 // Returns a pointer to a Results object, which will hold suggest results.
422 virtual Results* GetResultsToFill(bool is_keyword) = 0;
424 // Returns whether the destination URL corresponding to the given |result|
425 // should contain command-line-specified query params.
426 virtual bool ShouldAppendExtraParams(const SuggestResult& result) const = 0;
428 // Stops the suggest query.
429 // NOTE: This does not update |done_|. Callers must do so.
430 virtual void StopSuggest() = 0;
432 // Clears the current results.
433 virtual void ClearAllResults() = 0;
435 // Returns the relevance to use if it was not explicitly set by the server.
436 virtual int GetDefaultResultRelevance() const = 0;
438 // Records in UMA whether the deletion request resulted in success.
439 virtual void RecordDeletionResult(bool success) = 0;
441 // Records UMA statistics about a suggest server response.
442 virtual void LogFetchComplete(bool succeeded, bool is_keyword) = 0;
444 // Returns whether the |fetcher| is for the keyword provider.
445 virtual bool IsKeywordFetcher(const net::URLFetcher* fetcher) const = 0;
447 // Updates |matches_| from the latest results; applies calculated relevances
448 // if suggested relevances cause undesriable behavior. Updates |done_|.
449 virtual void UpdateMatches() = 0;
451 // Whether a field trial, if any, has triggered in the most recent
452 // autocomplete query. This field is set to true only if the suggestion
453 // provider has completed and the response contained
454 // '"google:fieldtrialtriggered":true'.
455 bool field_trial_triggered_;
457 // Same as above except that it is maintained across the current Omnibox
459 bool field_trial_triggered_in_session_;
461 // The number of suggest results that haven't yet arrived. If it's greater
462 // than 0, it indicates that one of the URLFetchers is still running.
463 int suggest_results_pending_;
466 friend class SearchProviderTest;
467 FRIEND_TEST_ALL_PREFIXES(SearchProviderTest, TestDeleteMatch);
469 // Removes the deleted |match| from the list of |matches_|.
470 void DeleteMatchFromMatches(const AutocompleteMatch& match);
472 // This gets called when we have requested a suggestion deletion from the
473 // server to handle the results of the deletion. It will be called after the
474 // deletion request completes.
475 void OnDeletionComplete(bool success,
476 SuggestionDeletionHandler* handler);
478 // Each deletion handler in this vector corresponds to an outstanding request
479 // that a server delete a personalized suggestion. Making this a ScopedVector
480 // causes us to auto-cancel all such requests on shutdown.
481 SuggestionDeletionHandlers deletion_handlers_;
483 DISALLOW_COPY_AND_ASSIGN(BaseSearchProvider);
486 #endif // CHROME_BROWSER_AUTOCOMPLETE_BASE_SEARCH_PROVIDER_H_