1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
|
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
#include "nsISupports.idl"
%{C++
#include "Entries.h"
#include "LookupCache.h"
class nsUrlClassifierLookupResult;
%}
[ptr] native ResultArray(nsTArray<mozilla::safebrowsing::LookupResult>);
[ptr] native CacheCompletionArray(nsTArray<mozilla::safebrowsing::CacheResult>);
[ptr] native PrefixArray(mozilla::safebrowsing::PrefixArray);
interface nsIUrlClassifierHashCompleter;
interface nsIPrincipal;
// Interface for JS function callbacks
[scriptable, function, uuid(4ca27b6b-a674-4b3d-ab30-d21e2da2dffb)]
interface nsIUrlClassifierCallback : nsISupports {
void handleEvent(in ACString value);
};
/**
* The nsIUrlClassifierUpdateObserver interface is implemented by
* clients streaming updates to the url-classifier (usually
* nsUrlClassifierStreamUpdater.
*/
[scriptable, uuid(9fa11561-5816-4e1b-bcc9-b629ca05cce6)]
interface nsIUrlClassifierUpdateObserver : nsISupports {
/**
* The update requested a new URL whose contents should be downloaded
* and sent to the classifier as a new stream.
*
* @param url The url that was requested.
* @param table The table name that this URL's contents will be associated
* with. This should be passed back to beginStream().
*/
void updateUrlRequested(in ACString url,
in ACString table);
/**
* A stream update has completed.
*
* @param status The state of the update process.
* @param delay The amount of time the updater should wait to fetch the
* next URL in ms.
*/
void streamFinished(in nsresult status, in unsigned long delay);
/* The update has encountered an error and should be cancelled */
void updateError(in nsresult error);
/**
* The update has completed successfully.
*
* @param requestedTimeout The number of seconds that the caller should
* wait before trying to update again.
**/
void updateSuccess(in unsigned long requestedTimeout);
};
/**
* This is a proxy class that is instantiated and called from the JS thread.
* It provides async methods for querying and updating the database. As the
* methods complete, they call the callback function.
*/
[scriptable, uuid(7a258022-6765-11e5-b379-b37b1f2354be)]
interface nsIUrlClassifierDBService : nsISupports
{
/**
* Looks up a URI in the specified tables.
*
* @param principal: The principal containing the URI to search.
* @param c: The callback will be called with a comma-separated list
* of tables to which the key belongs.
*/
void lookup(in nsIPrincipal principal,
in ACString tables,
in nsIUrlClassifierCallback c);
/**
* Lists the tables along with their meta info in the following format:
*
* tablename;[metadata]\n
* tablename2;[metadata]\n
*
* For v2 tables, the metadata is the chunks info such as
*
* goog-phish-shavar;a:10,14,30-40s:56,67
* goog-unwanted-shavar;a:1-3,5
*
* For v4 tables, base64 encoded state is currently the only info in the
* metadata (can be extended whenever necessary). For exmaple,
*
* goog-phish-proto;Cg0IARAGGAEiAzAwMTABEKqTARoCGAjT1gDD:oCGAjT1gDD\n
* goog-malware-proto;Cg0IAhAGGAEiAzAwMTABENCQARoCGAjx5Yty:BENCQARoCGAj\n
*
* Note that the metadata is colon-separated.
*
*/
void getTables(in nsIUrlClassifierCallback c);
/**
* Set the nsIUrlClassifierCompleter object for a given table. This
* object will be used to request complete versions of partial
* hashes.
*/
void setHashCompleter(in ACString tableName,
in nsIUrlClassifierHashCompleter completer);
/**
* Set the last update time for the given table. We use this to
* remember freshness past restarts. Time is in milliseconds since epoch.
*/
void setLastUpdateTime(in ACString tableName,
in unsigned long long lastUpdateTime);
/**
* Forget the results that were used in the last DB update.
*/
void clearLastResults();
////////////////////////////////////////////////////////////////////////////
// Incremental update methods.
//
// An update to the database has the following steps:
//
// 1) The update process is started with beginUpdate(). The client
// passes an nsIUrlClassifierUpdateObserver object which will be
// notified as the update is processed by the dbservice.
// 2) The client sends an initial update stream to the dbservice,
// using beginStream/updateStream/finishStream.
// 3) While reading this initial update stream, the dbservice may
// request additional streams from the client as requested by the
// update stream.
// 4) For each additional update stream, the client feeds the
// contents to the dbservice using beginStream/updateStream/endStream.
// 5) Once all streams have been processed, the client calls
// finishUpdate. When the dbservice has finished processing
// all streams, it will notify the observer that the update process
// is complete.
/**
* Begin an update process. Will throw NS_ERROR_NOT_AVAILABLE if there
* is already an update in progress.
*
* @param updater The update observer tied to this update.
* @param tables A comma-separated list of tables included in this update.
*/
void beginUpdate(in nsIUrlClassifierUpdateObserver updater,
in ACString tables);
/**
* Begin a stream update. This should be called once per url being
* fetched.
*
* @param table The table the contents of this stream will be associated
* with, or empty for the initial stream.
*/
void beginStream(in ACString table);
/**
* Update the table incrementally.
*/
void updateStream(in ACString updateChunk);
// It would be nice to have an updateFromStream method to round out the
// interface, but it's tricky because of XPCOM proxies.
/**
* Finish an individual stream update. Must be called for every
* beginStream() call, before the next beginStream() or finishUpdate().
*
* The update observer's streamFinished will be called once the
* stream has been processed.
*/
void finishStream();
/**
* Finish an incremental update. This will attempt to commit any
* pending changes and resets the update interface.
*
* The update observer's updateSucceeded or updateError methods
* will be called when the update has been processed.
*/
void finishUpdate();
/**
* Cancel an incremental update. This rolls back any pending changes.
* and resets the update interface.
*
* The update observer's updateError method will be called when the
* update has been rolled back.
*/
void cancelUpdate();
/**
* Reset the url-classifier database. This call will delete the existing
* database, emptying all tables. Mostly intended for use in unit tests.
*/
void resetDatabase();
/**
* Reload he url-classifier database. This will empty all cache for
* completions from gethash, and reload it from database. Mostly intended
* for use in tests.
*/
void reloadDatabase();
};
/**
* This is an internal helper interface for communication between the
* main thread and the dbservice worker thread. It is called for each
* lookup to provide a set of possible results, which the main thread
* may need to expand using an nsIUrlClassifierCompleter.
*/
[uuid(b903dc8f-dff1-42fe-894b-36e7a59bb801)]
interface nsIUrlClassifierLookupCallback : nsISupports
{
/**
* The lookup process is complete.
*
* @param results
* If this parameter is null, there were no results found.
* If not, it contains an array of nsUrlClassifierEntry objects
* with possible matches. The callee is responsible for freeing
* this array.
*/
void lookupComplete(in ResultArray results);
};
|
