New controller event "clients_seen" to report a geoip-based summary

of which countries we've seen clients from recently. Now controllers
like Vidalia can show bridge operators that they're actually making
a difference.


svn:r17796

ChangeLog

@@ -1,5 +1,11 @@
-Changes in version 0.2.1.10-alpha - 2009-??-??
-  o Minor bugfixes
+Changes in version 0.2.1.10-alpha - 2009-01-??
+  o Minor features:
+    - New controller event "clients_seen" to report a geoip-based summary
+      of which countries we've seen clients from recently. Now controllers
+      like Vidalia can show bridge operators that they're actually making
+      a difference.
+
+  o Minor bugfixes:
     - Make get_interface_address() function work properly again; stop
       guessing the wrong parts of our address as our address.
 

doc/TODO.external

@@ -138,8 +138,8 @@ E   - Vidalia improvements
       - Figure out a plan for presenting other Tor status warning events.
       - Move Polipo into the main Vidalia -dev bundle.
       - Vidalia displays by-country user summary for bridge operators
-R       * Tor sends a status event or something so Vidalia knows what
-          to display
+        o Tor sends a status event or something so Vidalia knows what
+          to display: "clients_seen"
 
 M   - Network scanning and network health
       - Implement some initial automated scans.

doc/spec/control-spec.txt

@@ -1284,8 +1284,7 @@ $Id$
        {Controllers may want to warn the user if this event occurs; further
        action is generally not possible.}
 
-     COSENSUS_ARRIVED
-
+     CONSENSUS_ARRIVED
         Tor has received and validated a new consensus networkstatus.
         (This event can be delayed a little while after the consensus
         is received, if Tor needs to fetch certificates.)
@@ -1566,6 +1565,28 @@ $Id$
   These events apply only to streams entering Tor (such as on a SOCKSPort,
   TransPort, or so on).  They are not generated for exiting streams.
 
+4.1.14. Per-country client stats
+
+  The syntax is:
+     "650" SP "CLIENTS_SEEN" SP TimeStarted SP CountrySummary CRLF
+
+  We just generated a new summary of which countries we've seen clients
+  from recently. The controller could display this for the user, e.g.
+  in their "relay" configuration window, to give them a sense that they
+  are actually being useful.
+
+  Currently only bridge relays will receive this event, but once we figure
+  out how to sufficiently aggregate and sanitize the client counts on
+  main relays, we might start sending these events in other cases too.
+
+  TimeStarted is a quoted string indicating when the reported summary
+  counts from (in GMT).
+
+  The CountrySummary keyword has as its argument a comma-separated
+  set of "countrycode=count" pairs. For example,
+  650-CLIENTS_SEEN TimeStarted="Thu Dec 25 23:50:43 EST 2008"
+  650 CountrySummary=us=16,de=8,uk=8
+
 5. Implementation notes
 
 5.1. Authentication

src/or/control.c

@@ -44,7 +44,8 @@ const char control_c_id[] =
 #define EVENT_STATUS_GENERAL   0x0012
 #define EVENT_GUARD            0x0013
 #define EVENT_STREAM_BANDWIDTH_USED   0x0014
-#define _EVENT_MAX             0x0014
+#define EVENT_CLIENTS_SEEN     0x0015
+#define _EVENT_MAX             0x0015
 /* If _EVENT_MAX ever hits 0x0020, we need to make the mask wider. */
 
 /** Bitfield: The bit 1&lt;&lt;e is set if <b>any</b> open control
@@ -125,7 +126,7 @@ static void send_control_event(uint16_t event, event_format_t which,
                                const char *format, ...)
   CHECK_PRINTF(3,4);
 static void send_control_event_extended(uint16_t event, event_format_t which,
-                                         const char *format, ...)
+                                        const char *format, ...)
   CHECK_PRINTF(3,4);
 static int handle_control_setconf(control_connection_t *conn, uint32_t len,
                                   char *body);
@@ -596,7 +597,7 @@ send_control_event_string(uint16_t event, event_format_t which,
  * ending \\r\\n\\0). */
 static void
 send_control_event_impl(uint16_t event, event_format_t which, int extended,
-                         const char *format, va_list ap)
+                        const char *format, va_list ap)
 {
   /* This is just a little longer than the longest allowed log message */
 #define SEND_CONTROL1_EVENT_BUFFERSIZE 10064
@@ -638,7 +639,7 @@ send_control_event_impl(uint16_t event, event_format_t which, int extended,
  * ending \\n\\r\\0. */
 static void
 send_control_event(uint16_t event, event_format_t which,
-                    const char *format, ...)
+                   const char *format, ...)
 {
   va_list ap;
   va_start(ap, format);
@@ -658,7 +659,7 @@ send_control_event(uint16_t event, event_format_t which,
  * ending \\n\\r\\0. */
 static void
 send_control_event_extended(uint16_t event, event_format_t which,
-                             const char *format, ...)
+                            const char *format, ...)
 {
   va_list ap;
   va_start(ap, format);
@@ -3299,10 +3300,10 @@ control_event_stream_bandwidth_used(void)
           continue;
 
         send_control_event(EVENT_STREAM_BANDWIDTH_USED, ALL_NAMES,
-                            "650 STREAM_BW "U64_FORMAT" %lu %lu\r\n",
-                            U64_PRINTF_ARG(edge_conn->_base.global_identifier),
-                            (unsigned long)edge_conn->n_read,
-                            (unsigned long)edge_conn->n_written);
+                           "650 STREAM_BW "U64_FORMAT" %lu %lu\r\n",
+                           U64_PRINTF_ARG(edge_conn->_base.global_identifier),
+                           (unsigned long)edge_conn->n_read,
+                           (unsigned long)edge_conn->n_written);
 
         edge_conn->n_written = edge_conn->n_read = 0;
     }
@@ -3319,9 +3320,9 @@ control_event_bandwidth_used(uint32_t n_read, uint32_t n_written)
 {
   if (EVENT_IS_INTERESTING(EVENT_BANDWIDTH_USED)) {
     send_control_event(EVENT_BANDWIDTH_USED, ALL_NAMES,
-                        "650 BW %lu %lu\r\n",
-                        (unsigned long)n_read,
-                        (unsigned long)n_written);
+                       "650 BW %lu %lu\r\n",
+                       (unsigned long)n_read,
+                       (unsigned long)n_written);
   }
 
   return 0;
@@ -3695,11 +3696,11 @@ control_event_guard(const char *nickname, const char *digest,
       tor_snprintf(buf, sizeof(buf), "$%s~%s", hbuf, nickname);
     }
     send_control_event(EVENT_GUARD, LONG_NAMES,
-                        "650 GUARD ENTRY %s %s\r\n", buf, status);
+                       "650 GUARD ENTRY %s %s\r\n", buf, status);
   }
   if (EVENT_IS_INTERESTING1S(EVENT_GUARD)) {
     send_control_event(EVENT_GUARD, SHORT_NAMES,
-                        "650 GUARD ENTRY $%s %s\r\n", hbuf, status);
+                       "650 GUARD ENTRY $%s %s\r\n", hbuf, status);
   }
   return 0;
 }
@@ -3947,3 +3948,14 @@ control_event_bootstrap_problem(const char *warn, int reason)
   control_event_client_status(LOG_WARN, "%s", buf);
 }
 
+/** We just generated a new summary of which countries we've seen clients
+ * from recently. Send a copy to the controller in case it wants to
+ * display it for the user. */
+void
+control_event_clients_seen(const char *timestarted, const char *countries)
+{
+  send_control_event(EVENT_CLIENTS_SEEN, 0,
+    "650 CLIENTS_SEEN Timestarted=\"%s\" CountrySummary=%s\r\n",
+    timestarted, countries);
+}
+

src/or/or.h

@@ -3265,6 +3265,9 @@ typedef enum {
 void control_event_bootstrap(bootstrap_status_t status, int progress);
 void control_event_bootstrap_problem(const char *warn, int reason);
 
+void control_event_clients_seen(const char *timestarted,
+                                const char *countries);
+
 #ifdef CONTROL_PRIVATE
 /* Used only by control.c and test.c */
 size_t write_escaped_data(const char *data, size_t len, char **out);

src/or/router.c

@@ -1878,6 +1878,7 @@ extrainfo_dump_to_string(char *s, size_t maxlen, extrainfo_t *extrainfo,
                             "geoip-start-time %s\n"
                             "geoip-client-origins %s\n",
                             geoip_start, geoip_summary);
+      control_event_clients_seen(geoip_start, geoip_summary);
       tor_free(geoip_summary);
       if (result<0)
         return -1;