The Tor Browser: comparison toolkit/components/url-classifier/content/moz/debug.js

comparison: toolkit/components/url-classifier/content/moz/debug.js

toolkit/components/url-classifier/content/moz/debug.js

branch: TOR_BUG_9701
changeset 14: 925c144e1f1f

equal deleted inserted replaced

--1:000000000000
+:fbea82fffbbe
+# 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/.
+#ifdef DEBUG
+// Generic logging/debugging functionality that:
+//
+// (*) when disabled compiles to no-ops at worst (for calls to the service)
+//     and to nothing at best (calls to G_Debug() and similar are compiled
+//     away when you use a jscompiler that strips dead code)
+//
+// (*) has dynamically configurable/creatable debugging "zones" enabling
+//     selective logging
+//
+// (*) hides its plumbing so that all calls in different zones are uniform,
+//     so you can drop files using this library into other apps that use it
+//     without any configuration
+//
+// (*) can be controlled programmatically or via preferences.  The
+//     preferences that control the service and its zones are under
+//     the preference branch "safebrowsing-debug-service."
+//
+// (*) outputs function call traces when the "loggifier" zone is enabled
+//
+// (*) can write output to logfiles so that you can get a call trace
+//     from someone who is having a problem
+//
+// Example:
+//
+// var G_GDEBUG = true                           // Enable this module
+// var G_debugService = new G_DebugService();    // in global context
+//
+// // You can use it with arbitrary primitive first arguement
+// G_Debug("myzone", "Yo yo yo");   // outputs: [myzone] Yo yo yo\n
+//
+// // But it's nice to use it with an object; it will probe for the zone name
+// function Obj() {
+//   this.debugZone = "someobj";
+// }
+// Obj.prototype.foo = function() {
+//   G_Debug(this, "foo called");
+// }
+// (new Obj).foo();                        // outputs: [someobj] foo called\n
+//
+// G_debugService.loggifier.loggify(Obj.prototype);  // enable call tracing
+//
+// // En/disable specific zones programmatically (you can also use preferences)
+// G_debugService.enableZone("somezone");
+// G_debugService.disableZone("someotherzone");
+// G_debugService.enableAllZones();
+//
+// // We also have asserts and errors:
+// G_Error(this, "Some error occurred");                    // will throw
+// G_Assert(this, (x > 3), "x not greater than three!");    // will throw
+//
+// See classes below for more methods.
+//
+// TODO add code to set prefs when not found to the default value of a tristate
+// TODO add error level support
+// TODO add ability to turn off console output
+//
+// -------> TO START DEBUGGING: set G_GDEBUG to true
+// These are the functions code will typically call. Everything is
+// wrapped in if's so we can compile it away when G_GDEBUG is false.
+if (typeof G_GDEBUG == "undefined") {
+throw new Error("G_GDEBUG constant must be set before loading debug.js");
+}
+/**
+* Write out a debugging message.
+*
+* @param who The thingy to convert into a zone name corresponding to the
+*            zone to which this message belongs
+* @param msg Message to output
+*/
+function G_Debug(who, msg) {
+if (G_GDEBUG) {
+G_GetDebugZone(who).debug(msg);
+}
+}
+/**
+* Debugs loudly
+*/
+function G_DebugL(who, msg) {
+if (G_GDEBUG) {
+var zone = G_GetDebugZone(who);
+if (zone.zoneIsEnabled()) {
+G_debugService.dump(
+"\n************************************************************\n");
+G_Debug(who, msg);
+G_debugService.dump(
+"************************************************************\n\n");
+}
+}
+}
+/**
+* Write out a call tracing message
+*
+* @param who The thingy to convert into a zone name corresponding to the
+*            zone to which this message belongs
+* @param msg Message to output
+*/
+function G_TraceCall(who, msg) {
+if (G_GDEBUG) {
+if (G_debugService.callTracingEnabled()) {
+G_debugService.dump(msg + "\n");
+}
+}
+}
+/**
+* Write out an error (and throw)
+*
+* @param who The thingy to convert into a zone name corresponding to the
+*            zone to which this message belongs
+* @param msg Message to output
+*/
+function G_Error(who, msg) {
+if (G_GDEBUG) {
+G_GetDebugZone(who).error(msg);
+}
+}
+/**
+* Assert something as true and signal an error if it's not
+*
+* @param who The thingy to convert into a zone name corresponding to the
+*            zone to which this message belongs
+* @param condition Boolean condition to test
+* @param msg Message to output
+*/
+function G_Assert(who, condition, msg) {
+if (G_GDEBUG) {
+G_GetDebugZone(who).assert(condition, msg);
+}
+}
+/**
+* Helper function that takes input and returns the DebugZone
+* corresponding to it.
+*
+* @param who Arbitrary input that will be converted into a zone name. Most
+*            likely an object that has .debugZone property, or a string.
+* @returns The DebugZone object corresponding to the input
+*/
+function G_GetDebugZone(who) {
+if (G_GDEBUG) {
+var zone = "?";
+if (who && who.debugZone) {
+zone = who.debugZone;
+} else if (typeof who == "string") {
+zone = who;
+}
+return G_debugService.getZone(zone);
+}
+}
+// Classes that implement the functionality.
+/**
+* A debug "zone" is a string derived from arbitrary types (but
+* typically derived from another string or an object). All debugging
+* messages using a particular zone can be enabled or disabled
+* independent of other zones. This enables you to turn on/off logging
+* of particular objects or modules. This object implements a single
+* zone and the methods required to use it.
+*
+* @constructor
+* @param service Reference to the DebugService object we use for
+*                registration
+* @param prefix String indicating the unique prefix we should use
+*               when creating preferences to control this zone
+* @param zone String indicating the name of the zone
+*/
+function G_DebugZone(service, prefix, zone) {
+if (G_GDEBUG) {
+this.debugService_ = service;
+this.prefix_ = prefix;
+this.zone_ = zone;
+this.zoneEnabledPrefName_ = prefix + ".zone." + this.zone_;
+this.settings_ = new G_DebugSettings();
+}
+}
+/**
+* @returns Boolean indicating if this zone is enabled
+*/
+G_DebugZone.prototype.zoneIsEnabled = function() {
+if (G_GDEBUG) {
+var explicit = this.settings_.getSetting(this.zoneEnabledPrefName_, null);
+if (explicit !== null) {
+return explicit;
+} else {
+return this.debugService_.allZonesEnabled();
+}
+}
+}
+/**
+* Enable this logging zone
+*/
+G_DebugZone.prototype.enableZone = function() {
+if (G_GDEBUG) {
+this.settings_.setDefault(this.zoneEnabledPrefName_, true);
+}
+}
+/**
+* Disable this logging zone
+*/
+G_DebugZone.prototype.disableZone = function() {
+if (G_GDEBUG) {
+this.settings_.setDefault(this.zoneEnabledPrefName_, false);
+}
+}
+/**
+* Write a debugging message to this zone
+*
+* @param msg String of message to write
+*/
+G_DebugZone.prototype.debug = function(msg) {
+if (G_GDEBUG) {
+if (this.zoneIsEnabled()) {
+this.debugService_.dump("[" + this.zone_ + "] " + msg + "\n");
+}
+}
+}
+/**
+* Write an error to this zone and throw
+*
+* @param msg String of error to write
+*/
+G_DebugZone.prototype.error = function(msg) {
+if (G_GDEBUG) {
+this.debugService_.dump("[" + this.zone_ + "] " + msg + "\n");
+throw new Error(msg);
+debugger;
+}
+}
+/**
+* Assert something as true and error if it is not
+*
+* @param condition Boolean condition to test
+* @param msg String of message to write if is false
+*/
+G_DebugZone.prototype.assert = function(condition, msg) {
+if (G_GDEBUG) {
+if (condition !== true) {
+G_Error(this.zone_, "ASSERT FAILED: " + msg);
+}
+}
+}
+/**
+* The debug service handles auto-registration of zones, namespacing
+* the zones preferences, and various global settings such as whether
+* all zones are enabled.
+*
+* @constructor
+* @param opt_prefix Optional string indicating the unique prefix we should
+*                   use when creating preferences
+*/
+function G_DebugService(opt_prefix) {
+if (G_GDEBUG) {
+this.prefix_ = opt_prefix ? opt_prefix : "safebrowsing-debug-service";
+this.consoleEnabledPrefName_ = this.prefix_ + ".alsologtoconsole";
+this.allZonesEnabledPrefName_ = this.prefix_ + ".enableallzones";
+this.callTracingEnabledPrefName_ = this.prefix_ + ".trace-function-calls";
+this.logFileEnabledPrefName_ = this.prefix_ + ".logfileenabled";
+this.logFileErrorLevelPrefName_ = this.prefix_ + ".logfile-errorlevel";
+this.zones_ = {};
+this.loggifier = new G_Loggifier();
+this.settings_ = new G_DebugSettings();
+}
+}
+// Error levels for reporting console messages to the log.
+G_DebugService.ERROR_LEVEL_INFO = "INFO";
+G_DebugService.ERROR_LEVEL_WARNING = "WARNING";
+G_DebugService.ERROR_LEVEL_EXCEPTION = "EXCEPTION";
+/**
+* @returns Boolean indicating if we should send messages to the jsconsole
+*/
+G_DebugService.prototype.alsoDumpToConsole = function() {
+if (G_GDEBUG) {
+return this.settings_.getSetting(this.consoleEnabledPrefName_, false);
+}
+}
+/**
+* @returns whether to log output to a file as well as the console.
+*/
+G_DebugService.prototype.logFileIsEnabled = function() {
+if (G_GDEBUG) {
+return this.settings_.getSetting(this.logFileEnabledPrefName_, false);
+}
+}
+/**
+* Turns on file logging. dump() output will also go to the file specified by
+* setLogFile()
+*/
+G_DebugService.prototype.enableLogFile = function() {
+if (G_GDEBUG) {
+this.settings_.setDefault(this.logFileEnabledPrefName_, true);
+}
+}
+/**
+* Turns off file logging
+*/
+G_DebugService.prototype.disableLogFile = function() {
+if (G_GDEBUG) {
+this.settings_.setDefault(this.logFileEnabledPrefName_, false);
+}
+}
+/**
+* @returns an nsIFile instance pointing to the current log file location
+*/
+G_DebugService.prototype.getLogFile = function() {
+if (G_GDEBUG) {
+return this.logFile_;
+}
+}
+/**
+* Sets a new log file location
+*/
+G_DebugService.prototype.setLogFile = function(file) {
+if (G_GDEBUG) {
+this.logFile_ = file;
+}
+}
+/**
+* Enables sending messages to the jsconsole
+*/
+G_DebugService.prototype.enableDumpToConsole = function() {
+if (G_GDEBUG) {
+this.settings_.setDefault(this.consoleEnabledPrefName_, true);
+}
+}
+/**
+* Disables sending messages to the jsconsole
+*/
+G_DebugService.prototype.disableDumpToConsole = function() {
+if (G_GDEBUG) {
+this.settings_.setDefault(this.consoleEnabledPrefName_, false);
+}
+}
+/**
+* @param zone Name of the zone to get
+* @returns The DebugZone object corresopnding to input. If not such
+*          zone exists, a new one is created and returned
+*/
+G_DebugService.prototype.getZone = function(zone) {
+if (G_GDEBUG) {
+if (!this.zones_[zone])
+this.zones_[zone] = new G_DebugZone(this, this.prefix_, zone);
+return this.zones_[zone];
+}
+}
+/**
+* @param zone Zone to enable debugging for
+*/
+G_DebugService.prototype.enableZone = function(zone) {
+if (G_GDEBUG) {
+var toEnable = this.getZone(zone);
+toEnable.enableZone();
+}
+}
+/**
+* @param zone Zone to disable debugging for
+*/
+G_DebugService.prototype.disableZone = function(zone) {
+if (G_GDEBUG) {
+var toDisable = this.getZone(zone);
+toDisable.disableZone();
+}
+}
+/**
+* @returns Boolean indicating whether debugging is enabled for all zones
+*/
+G_DebugService.prototype.allZonesEnabled = function() {
+if (G_GDEBUG) {
+return this.settings_.getSetting(this.allZonesEnabledPrefName_, false);
+}
+}
+/**
+* Enables all debugging zones
+*/
+G_DebugService.prototype.enableAllZones = function() {
+if (G_GDEBUG) {
+this.settings_.setDefault(this.allZonesEnabledPrefName_, true);
+}
+}
+/**
+* Disables all debugging zones
+*/
+G_DebugService.prototype.disableAllZones = function() {
+if (G_GDEBUG) {
+this.settings_.setDefault(this.allZonesEnabledPrefName_, false);
+}
+}
+/**
+* @returns Boolean indicating whether call tracing is enabled
+*/
+G_DebugService.prototype.callTracingEnabled = function() {
+if (G_GDEBUG) {
+return this.settings_.getSetting(this.callTracingEnabledPrefName_, false);
+}
+}
+/**
+* Enables call tracing
+*/
+G_DebugService.prototype.enableCallTracing = function() {
+if (G_GDEBUG) {
+this.settings_.setDefault(this.callTracingEnabledPrefName_, true);
+}
+}
+/**
+* Disables call tracing
+*/
+G_DebugService.prototype.disableCallTracing = function() {
+if (G_GDEBUG) {
+this.settings_.setDefault(this.callTracingEnabledPrefName_, false);
+}
+}
+/**
+* Gets the minimum error that will be reported to the log.
+*/
+G_DebugService.prototype.getLogFileErrorLevel = function() {
+if (G_GDEBUG) {
+var level = this.settings_.getSetting(this.logFileErrorLevelPrefName_,
+G_DebugService.ERROR_LEVEL_EXCEPTION);
+return level.toUpperCase();
+}
+}
+/**
+* Sets the minimum error level that will be reported to the log.
+*/
+G_DebugService.prototype.setLogFileErrorLevel = function(level) {
+if (G_GDEBUG) {
+// normalize case just to make it slightly easier to not screw up.
+level = level.toUpperCase();
+if (level != G_DebugService.ERROR_LEVEL_INFO &&
+level != G_DebugService.ERROR_LEVEL_WARNING &&
+level != G_DebugService.ERROR_LEVEL_EXCEPTION) {
+throw new Error("Invalid error level specified: {" + level + "}");
+}
+this.settings_.setDefault(this.logFileErrorLevelPrefName_, level);
+}
+}
+/**
+* Internal dump() method
+*
+* @param msg String of message to dump
+*/
+G_DebugService.prototype.dump = function(msg) {
+if (G_GDEBUG) {
+dump(msg);
+if (this.alsoDumpToConsole()) {
+try {
+var console = Components.classes['@mozilla.org/consoleservice;1']
+.getService(Components.interfaces.nsIConsoleService);
+console.logStringMessage(msg);
+} catch(e) {
+dump("G_DebugZone ERROR: COULD NOT DUMP TO CONSOLE\n");
+}
+}
+this.maybeDumpToFile(msg);
+}
+}
+/**
+* Writes the specified message to the log file, if file logging is enabled.
+*/
+G_DebugService.prototype.maybeDumpToFile = function(msg) {
+if (this.logFileIsEnabled() && this.logFile_) {
+/* try to get the correct line end character for this platform */
+if (!this._LINE_END_CHAR)
+this._LINE_END_CHAR =
+Cc["@mozilla.org/xre/app-info;1"].getService(Ci.nsIXULRuntime)
+.OS == "WINNT" ? "\r\n" : "\n";
+if (this._LINE_END_CHAR != "\n")
+msg = msg.replace(/\n/g, this._LINE_END_CHAR);
+try {
+var stream = Cc["@mozilla.org/network/file-output-stream;1"]
+.createInstance(Ci.nsIFileOutputStream);
+stream.init(this.logFile_,
+0x02 | 0x08 | 0x10 /* PR_WRONLY | PR_CREATE_FILE | PR_APPEND */
+-1 /* default perms */, 0 /* no special behavior */);
+stream.write(msg, msg.length);
+} finally {
+stream.close();
+}
+}
+}
+/**
+* Implements nsIConsoleListener.observe(). Gets called when an error message
+* gets reported to the console and sends it to the log file as well.
+*/
+G_DebugService.prototype.observe = function(consoleMessage) {
+if (G_GDEBUG) {
+var errorLevel = this.getLogFileErrorLevel();
+// consoleMessage can be either nsIScriptError or nsIConsoleMessage. The
+// latter does not have things like line number, etc. So we special case
+// it first.
+if (!(consoleMessage instanceof Ci.nsIScriptError)) {
+// Only report these messages if the error level is INFO.
+if (errorLevel == G_DebugService.ERROR_LEVEL_INFO) {
+this.maybeDumpToFile(G_DebugService.ERROR_LEVEL_INFO + ": " +
+consoleMessage.message + "\n");
+}
+return;
+}
+// We make a local copy of these fields because writing to it doesn't seem
+// to work.
+var flags = consoleMessage.flags;
+var sourceName = consoleMessage.sourceName;
+var lineNumber = consoleMessage.lineNumber;
+// Sometimes, a scripterror instance won't have any flags set. We
+// default to exception.
+if (!flags) {
+flags = Ci.nsIScriptError.exceptionFlag;
+}
+// Default the filename and line number if they aren't set.
+if (!sourceName) {
+sourceName = "<unknown>";
+}
+if (!lineNumber) {
+lineNumber = "<unknown>";
+}
+// Report the error in the log file.
+if (flags & Ci.nsIScriptError.warningFlag) {
+// Only report warnings if the error level is warning or better.
+if (errorLevel == G_DebugService.ERROR_LEVEL_WARNING ||
+errorLevel == G_DebugService.ERROR_LEVEL_INFO) {
+this.reportScriptError_(consoleMessage.message,
+sourceName,
+lineNumber,
+G_DebugService.ERROR_LEVEL_WARNING);
+}
+} else if (flags & Ci.nsIScriptError.exceptionFlag) {
+// Always report exceptions.
+this.reportScriptError_(consoleMessage.message,
+sourceName,
+lineNumber,
+G_DebugService.ERROR_LEVEL_EXCEPTION);
+}
+}
+}
+/**
+* Private helper to report an nsIScriptError instance to the log/console.
+*/
+G_DebugService.prototype.reportScriptError_ = function(message, sourceName,
+lineNumber, label) {
+message = "\n------------------------------------------------------------\n" +
+label + ": " + message +
+"\nlocation: " + sourceName + ", " + "line: " + lineNumber +
+"\n------------------------------------------------------------\n\n";
+dump(message);
+this.maybeDumpToFile(message);
+}
+/**
+* A class that instruments methods so they output a call trace,
+* including the values of their actual parameters and return value.
+* This code is mostly stolen from Aaron Boodman's original
+* implementation in clobber utils.
+*
+* Note that this class uses the "loggifier" debug zone, so you'll see
+* a complete call trace when that zone is enabled.
+*
+* @constructor
+*/
+function G_Loggifier() {
+if (G_GDEBUG) {
+// Careful not to loggify ourselves!
+this.mark_(this);
+}
+}
+/**
+* Marks an object as having been loggified. Loggification is not
+* idempotent :)
+*
+* @param obj Object to be marked
+*/
+G_Loggifier.prototype.mark_ = function(obj) {
+if (G_GDEBUG) {
+obj.__loggified_ = true;
+}
+}
+/**
+* @param obj Object to be examined
+* @returns Boolean indicating if the object has been loggified
+*/
+G_Loggifier.prototype.isLoggified = function(obj) {
+if (G_GDEBUG) {
+return !!obj.__loggified_;
+}
+}
+/**
+* Attempt to extract the class name from the constructor definition.
+* Assumes the object was created using new.
+*
+* @param constructor String containing the definition of a constructor,
+*                    for example what you'd get by examining obj.constructor
+* @returns Name of the constructor/object if it could be found, else "???"
+*/
+G_Loggifier.prototype.getFunctionName_ = function(constructor) {
+if (G_GDEBUG) {
+return constructor.name || "???";
+}
+}
+/**
+* Wraps all the methods in an object so that call traces are
+* automatically outputted.
+*
+* @param obj Object to loggify. SHOULD BE THE PROTOTYPE OF A USER-DEFINED
+*            object. You can get into trouble if you attempt to
+*            loggify something that isn't, for example the Window.
+*
+* Any additional parameters are considered method names which should not be
+* loggified.
+*
+* Usage:
+* G_debugService.loggifier.loggify(MyClass.prototype,
+*                                  "firstMethodNotToLog",
+*                                  "secondMethodNotToLog",
+*                                  ... etc ...);
+*/
+G_Loggifier.prototype.loggify = function(obj) {
+if (G_GDEBUG) {
+if (!G_debugService.callTracingEnabled()) {
+return;
+}
+if (typeof window != "undefined" && obj == window ||
+this.isLoggified(obj))   // Don't go berserk!
+return;
+var zone = G_GetDebugZone(obj);
+if (!zone || !zone.zoneIsEnabled()) {
+return;
+}
+this.mark_(obj);
+// Helper function returns an instrumented version of
+// objName.meth, with "this" bound properly. (BTW, because we're
+// in a conditional here, functions will only be defined as
+// they're encountered during execution, so declare this helper
+// before using it.)
+function wrap(meth, objName, methName) {
+return function() {
+// First output the call along with actual parameters
+var args = new Array(arguments.length);
+var argsString = "";
+for (var i = 0; i < args.length; i++) {
+args[i] = arguments[i];
+argsString += (i == 0 ? "" : ", ");
+if (typeof args[i] == "function") {
+argsString += "[function]";
+} else {
+argsString += args[i];
+}
+}
+G_TraceCall(this, "> " + objName + "." + methName + "(" +
+argsString + ")");
+// Then run the function, capturing the return value and throws
+try {
+var retVal = meth.apply(this, arguments);
+var reportedRetVal = retVal;
+if (typeof reportedRetVal == "undefined")
+reportedRetVal = "void";
+else if (reportedRetVal === "")
+reportedRetVal = "\"\" (empty string)";
+} catch (e) {
+if (e && !e.__logged) {
+G_TraceCall(this, "Error: " + e.message + ". " +
+e.fileName + ": " + e.lineNumber);
+try {
+e.__logged = true;
+} catch (e2) {
+// Sometimes we can't add the __logged flag because it's an
+// XPC wrapper
+throw e;
+}
+}
+throw e;      // Re-throw!
+}
+// And spit it out already
+G_TraceCall(
+this,
+"< " + objName + "." + methName + ": " + reportedRetVal);
+return retVal;
+};
+};
+var ignoreLookup = {};
+if (arguments.length > 1) {
+for (var i = 1; i < arguments.length; i++) {
+ignoreLookup[arguments[i]] = true;
+}
+}
+// Wrap each method of obj
+for (var p in obj) {
+// Work around bug in Firefox. In ffox typeof RegExp is "function",
+// so make sure this really is a function. Bug as of FFox 1.5b2.
+if (typeof obj[p] == "function" && obj[p].call && !ignoreLookup[p]) {
+var objName = this.getFunctionName_(obj.constructor);
+obj[p] = wrap(obj[p], objName, p);
+}
+}
+}
+}
+/**
+* Simple abstraction around debug settings. The thing with debug settings is
+* that we want to be able to specify a default in the application's startup,
+* but have that default be overridable by the user via their prefs.
+*
+* To generalize this, we package up a dictionary of defaults with the
+* preferences tree. If a setting isn't in the preferences tree, then we grab it
+* from the defaults.
+*/
+function G_DebugSettings() {
+this.defaults_ = {};
+this.prefs_ = new G_Preferences();
+}
+/**
+* Returns the value of a settings, optionally defaulting to a given value if it
+* doesn't exist. If no default is specified, the default is |undefined|.
+*/
+G_DebugSettings.prototype.getSetting = function(name, opt_default) {
+var override = this.prefs_.getPref(name, null);
+if (override !== null) {
+return override;
+} else if (typeof this.defaults_[name] != "undefined") {
+return this.defaults_[name];
+} else {
+return opt_default;
+}
+}
+/**
+* Sets the default value for a setting. If the user doesn't override it with a
+* preference, this is the value which will be returned by getSetting().
+*/
+G_DebugSettings.prototype.setDefault = function(name, val) {
+this.defaults_[name] = val;
+}
+var G_debugService = new G_DebugService(); // Instantiate us!
+if (G_GDEBUG) {
+G_debugService.enableAllZones();
+}
+#else
+// Stubs for the debugging aids scattered through this component.
+// They will be expanded if you compile yourself a debug build.
+function G_Debug(who, msg) { }
+function G_Assert(who, condition, msg) { }
+function G_Error(who, msg) { }
+var G_debugService = { __noSuchMethod__: function() { } };
+#endif