[or-cvs] r11761: Add a bunch of function documentation; clean up a little cod (in tor/trunk: . doc src/common src/or)
nickm at seul.org
nickm at seul.org
Thu Oct 4 16:21:58 UTC 2007
Author: nickm
Date: 2007-10-04 12:21:58 -0400 (Thu, 04 Oct 2007)
New Revision: 11761
Modified:
tor/trunk/
tor/trunk/doc/TODO
tor/trunk/src/common/aes.c
tor/trunk/src/common/util.c
tor/trunk/src/or/circuitbuild.c
tor/trunk/src/or/control.c
tor/trunk/src/or/directory.c
tor/trunk/src/or/dirserv.c
tor/trunk/src/or/dirvote.c
tor/trunk/src/or/main.c
tor/trunk/src/or/ntmain.c
tor/trunk/src/or/or.h
tor/trunk/src/or/rephist.c
tor/trunk/src/or/router.c
tor/trunk/src/or/routerlist.c
tor/trunk/src/or/routerparse.c
Log:
r15530 at catbus: nickm | 2007-10-04 12:16:27 -0400
Add a bunch of function documentation; clean up a little code; fix some XXXXs; tag the nonsensical EXTRAINFO_PURPOSE_GENERAL as nonsesnse; note another bit of "do not cache special routers" code to nuke.
Property changes on: tor/trunk
___________________________________________________________________
svk:merge ticket from /tor/trunk [r15530] on 8246c3cf-6607-4228-993b-4d95d33730f1
Modified: tor/trunk/doc/TODO
===================================================================
--- tor/trunk/doc/TODO 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/doc/TODO 2007-10-04 16:21:58 UTC (rev 11761)
@@ -52,18 +52,19 @@
. 101: Voting on the Tor Directory System (plus 103)
. Finalize proposal
* Describe schedule in copious detail.
- - Get authorities voting
+ . Get authorities voting
o Code to manage key certificates
o Download as needed.
o Code to download
- . Code to retry download.
+ D Code to retry download.
o Code to generate consensus from a list of votes
o Detect whether votes are really all for the same period.
o Push/pull documents as appropriate.
o Pull votes and signatures if we don't get them.
- - Cache votes and signatures on disk?
+ o Cache votes and signatures on disk?
o Code to keep consensus docs in limbo if they don't have
have enough signatures.
+ D Save votes on disk.
o Have clients know which authorities are v3 authorities, and what
their keys are.
- While we're at it, let v3 authorities have fqdns lines.
Modified: tor/trunk/src/common/aes.c
===================================================================
--- tor/trunk/src/common/aes.c 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/common/aes.c 2007-10-04 16:21:58 UTC (rev 11761)
@@ -311,7 +311,8 @@
}
}
-/** DOCDOC */
+/** Reset the 128-bit counter of <b>cipher</b> to the 16-bit big-endian value
+ * in <b>iv</b>. */
void
aes_set_iv(aes_cnt_cipher_t *cipher, const char *iv)
{
Modified: tor/trunk/src/common/util.c
===================================================================
--- tor/trunk/src/common/util.c 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/common/util.c 2007-10-04 16:21:58 UTC (rev 11761)
@@ -1516,16 +1516,32 @@
return write_bytes_to_file(fname, str, strlen(str), bin);
}
-/** DOCDOC */
+/** Represents a file that we're writing to, with support for atomic commit:
+ * we can write into a a temporary file, and either remove the file on
+ * failure, or replace the original file on success. */
struct open_file_t {
- char *tempname;
- char *filename;
- int rename_on_close;
- int fd;
- FILE *stdio_file;
+ char *tempname; /**< Name of the temporary file. */
+ char *filename; /**< Name of the original file. */
+ int rename_on_close; /**< Are we using the temporary file or not? */
+ int fd; /**< fd for the open file. */
+ FILE *stdio_file; /**< stdio wrapper for <b>fd</b>. */
};
-/** DOCDOC */
+/** Try to start writing to the file in <b>fname</b>, passing the flags
+ * <b>open_flags</b> to the open() syscall, creating the file (if needed) with
+ * access value <b>mode</b>. If the O_APPEND flag is set, we append to the
+ * original file. Otherwise, we open a new a temporary file in the same
+ * directory, and either replace the original or remove the temprorary file
+ * when we're done.
+ *
+ * Return the fd for the newly opened file, and store working data in
+ * *<b>data_out</b>. The caller should not close the fd manually:
+ * instead, call finish_writing_to_file() or abort_writing_to_file().
+ * Returns -1 on failure.
+ *
+ * NOTE: When not appending, the flags O_CREAT and O_TRUNC are treated
+ * as true and the flag O_EXCL is treated as false.
+ */
int
start_writing_to_file(const char *fname, int open_flags, int mode,
open_file_t **data_out)
@@ -1551,6 +1567,9 @@
log(LOG_WARN, LD_GENERAL, "Failed to generate filename");
goto err;
}
+ /* We always replace an existing temporary file if there is one. */
+ open_flags |= O_CREAT|O_TRUNC;
+ open_flags &= ~O_EXCL;
new_file->rename_on_close = 1;
}
@@ -1572,7 +1591,9 @@
return -1;
}
-/** DOCDOC */
+/** Given <b>file_data</b> from start_writing_to_file(), return a stdio FILE*
+ * that can be used to write to the same file. The caller should not mix
+ * stdio calls with non-stdio calls. */
FILE *
fdopen_file(open_file_t *file_data)
{
@@ -1587,7 +1608,8 @@
return file_data->stdio_file;
}
-/** DOCDOC */
+/** Combines start_writing_to_file with fdopen_file(): arguments are as
+ * for start_writing_to_file, but */
FILE *
start_writing_to_stdio_file(const char *fname, int open_flags, int mode,
open_file_t **data_out)
@@ -1600,7 +1622,10 @@
return res;
}
-/** DOCDOC */
+/** Helper function: close and free the underlying file and memory in
+ * <b>file_data</b>. If we were writing into a temporary file, then delete
+ * that file (if abort_write is true) or replaces the target file with
+ * the temporary file (if abort_write is false). */
static int
finish_writing_to_file_impl(open_file_t *file_data, int abort_write)
{
@@ -1641,14 +1666,17 @@
return r;
}
-/** DOCDOC */
+/** Finish writing to <b>file_data</b>: close the file handle, free memory as
+ * needed, and if using a temporary file, replace the original file with
+ * the temporary file. */
int
finish_writing_to_file(open_file_t *file_data)
{
return finish_writing_to_file_impl(file_data, 0);
}
-/** DOCDOC */
+/** Finish writing to <b>file_data</b>: close the file handle, free memory as
+ * needed, and if using a temporary file, delete it. */
int
abort_writing_to_file(open_file_t *file_data)
{
Modified: tor/trunk/src/or/circuitbuild.c
===================================================================
--- tor/trunk/src/or/circuitbuild.c 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/or/circuitbuild.c 2007-10-04 16:21:58 UTC (rev 11761)
@@ -2103,7 +2103,9 @@
tor_free(e);
}
-/** DOCDOC */
+/** Remove any entry guard which was selected by an unknown version of Tor,
+ * or which was selected by a version of Tor that's known to select
+ * entry guards badly. */
static int
remove_obsolete_entry_guards(void)
{
@@ -2512,7 +2514,7 @@
return r;
}
-/** DOCDOC */
+/** Helper: Return the start of the month containing <b>time</b>. */
static time_t
start_of_month(time_t now)
{
Modified: tor/trunk/src/or/control.c
===================================================================
--- tor/trunk/src/or/control.c 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/or/control.c 2007-10-04 16:21:58 UTC (rev 11761)
@@ -1249,7 +1249,15 @@
return 0;
}
-/** DOCDOC */
+/** Awful hack: return a newly allocated string based on a routerinfo and
+ * (possibly) an extrainfo, sticking the read-history and write-history from
+ * <b>ei</b> into the resulting string. The thing you get back won't
+ * necessarily have a valid signature.
+ *
+ * New code should never use this; it's for backward compatibiliy.
+ *
+ * NOTE: <b>ri_body</b> is as returned by signed_descriptor_get_body: it might
+ * not be NUL-terminated. */
static char *
munge_extrainfo_into_routerinfo(const char *ri_body, signed_descriptor_t *ri,
signed_descriptor_t *ei)
@@ -2355,7 +2363,8 @@
return 0;
}
-/** DOCDOC */
+/** Called when we get a RESOLVE command: start trying to resolve
+ * the listed addresses. */
static int
handle_control_resolve(control_connection_t *conn, uint32_t len,
const char *body)
@@ -2390,7 +2399,7 @@
return 0;
}
-/** DOCDOC */
+/** Called when we get a PROTOCOLINFO command: send back a reply. */
static int
handle_control_protocolinfo(control_connection_t *conn, uint32_t len,
const char *body)
@@ -3554,7 +3563,8 @@
return 0;
}
-/** DOCDOC */
+/** Helper: Return a newly allocated string containing a path to the
+ * file where we store our authentication cookie. */
static char *
get_cookie_file(void)
{
Modified: tor/trunk/src/or/directory.c
===================================================================
--- tor/trunk/src/or/directory.c 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/or/directory.c 2007-10-04 16:21:58 UTC (rev 11761)
@@ -1066,7 +1066,12 @@
}
}
-/** DOCDOC */
+/** Called when we've just fetched a bunch of router descriptors in
+ * <b>body</b>. The list <b>which</b>, if present, holds digests for
+ * descriptors we requested: descriptor digests if <b>descriptor_digests</b>
+ * is true, or identity digests otherwise. Parse the descriptors, validate
+ * them, and annotate them as having purpose <b>purpose</b> and as having been
+ * downloaded from <b>source</b>. */
static void
load_downloaded_routers(const char *body, smartlist_t *which,
int descriptor_digests,
@@ -1077,6 +1082,7 @@
char time_buf[ISO_TIME_LEN+1];
int general = router_purpose == ROUTER_PURPOSE_GENERAL;
format_iso_time(time_buf, time(NULL));
+ tor_assert(source);
if (tor_snprintf(buf, sizeof(buf),
"@downloaded-at %s\n"
Modified: tor/trunk/src/or/dirserv.c
===================================================================
--- tor/trunk/src/or/dirserv.c 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/or/dirserv.c 2007-10-04 16:21:58 UTC (rev 11761)
@@ -1694,10 +1694,11 @@
/** Helper: write the router-status information in <b>rs</b> into <b>buf</b>,
* which has at least <b>buf_len</b> free characters. Do NUL-termination.
- * Use the same format as in network-status documents. If <b>platform</b> is
+ * Use the same format as in network-status documents. If <b>version</b> is
* non-NULL, add a "v" line for the platform. Return 0 on success, -1 on
- * failure.
- * DOCDOC new arguments */
+ * failure. If <b>first_line_only<b> is true, don't include any flags
+ * or version line.
+ */
int
routerstatus_format_entry(char *buf, size_t buf_len,
routerstatus_t *rs, const char *version,
@@ -1918,6 +1919,7 @@
/** Return a new networkstatus_vote_t* containing our current opinion. (For v3
* authorities */
+/* XXXX020 possibly rename and relocate to dirvote.c? */
static networkstatus_vote_t *
generate_networkstatus_vote_obj(crypto_pk_env_t *private_key,
authority_cert_t *cert)
@@ -2238,7 +2240,8 @@
return status;
}
-/** DOCDOC */
+/** Replace the value of <b>the_v3_networkstatus_vote</b> with a
+ * new vote, and return that value. Returns NULL on failure. */
/* XXXX020 possibly rename and relocate to dirvote.c? */
cached_dir_t *
generate_v3_networkstatus(void)
Modified: tor/trunk/src/or/dirvote.c
===================================================================
--- tor/trunk/src/or/dirvote.c 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/or/dirvote.c 2007-10-04 16:21:58 UTC (rev 11761)
@@ -1048,25 +1048,26 @@
static struct {
/** When do we generate and distribute our vote for this interval? */
time_t voting_starts;
- /** DOCDOC */
+ /** When do we send an HTTP request for any votes that we haven't
+ * been posted yet?*/
time_t fetch_missing_votes;
/** When do we give up on getting more votes and generate a consensus? */
time_t voting_ends;
- /** DOCDOC */
+ /** When do we send an HTTP request for any signatures we're expecting to
+ * see on the consensus? */
time_t fetch_missing_signatures;
/** When do we publish the consensus? */
time_t interval_starts;
-
/** When do we discard old votes and pending detached signatures? */
time_t discard_old_votes;
/* True iff we have generated and distributed our vote. */
int have_voted;
- /* DOCDOC */
+ /* True iff we've requested missing votes. */
int have_fetched_missing_votes;
/* True iff we have built a consensus and sent the signatures around. */
int have_built_consensus;
- /* DOCDOC */
+ /* True iff we've fetched missing signatures. */
int have_fetched_missing_signatures;
/* True iff we have published our consensus. */
int have_published_consensus;
@@ -1220,7 +1221,9 @@
log_notice(LD_DIR, "Vote posted.");
}
-/** DOCDOC */
+/** Send an HTTP request to every other v3 authority, for the votes of every
+ * authority for which we haven't received a vote yet in this period. (V3
+ * authority only) */
static void
dirvote_fetch_missing_votes(void)
{
@@ -1254,7 +1257,8 @@
smartlist_free(missing_fps);
}
-/** DOCDOC */
+/** Send a request to every other authority for its detached signatures,
+ * unless we have signatures from all other v3 authorities already. */
static void
dirvote_fetch_missing_signatures(void)
{
@@ -1722,10 +1726,14 @@
return pending_consensus_signatures;
}
-/** Return the vote for the authority with the v3 authority identity key
- * digest <b>id</b>. If <b>id</b> is NULL, return our own vote. May return
- * NULL if we have no vote for the authority in question.
- * DOCDOC args */
+/** Return a given vote specified by <b>fp</b>. If <b>by_id</b>, return the
+ * vote for the authority with the v3 authority identity key digest <b>fp</b>;
+ * if <b>by_id</b> is false, return the vote whose digest is <b>fp</b>. If
+ * <b>fp</b> is NULL, return our own vote. If <b>include_previous</b> is
+ * false, do not consider any votes for a consensus that's already been built.
+ * If <b>include_pending</b> is false, do not consider any votes for the
+ * consensus that's in progress. May return NULL if we have no vote for the
+ * authority in question. */
const cached_dir_t *
dirvote_get_vote(const char *fp, int by_id, int include_previous,
int include_pending)
Modified: tor/trunk/src/or/main.c
===================================================================
--- tor/trunk/src/or/main.c 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/or/main.c 2007-10-04 16:21:58 UTC (rev 11761)
@@ -908,7 +908,9 @@
dirserv_test_reachability(now, 0);
}
- /** 1d. DOCDOC */
+ /** 1d. Periodically, we discount older stability information so that new
+ * stability info counts more, and save the stability information to disk as
+ * appropriate. */
if (time_to_downrate_stability < now)
time_to_downrate_stability = rep_hist_downrate_old_runs(now);
if (authdir_mode_tests_reachability(options)) {
@@ -923,7 +925,8 @@
}
}
- /* 1e. DOCDOC */
+ /* 1e. Periodicaly, if we're a v3 authority, we check whether our cert is
+ * close to expiring and warn the admin if it is. */
if (time_to_check_v3_certificate < now) {
v3_authority_check_key_expiry();
time_to_check_v3_certificate = now + CHECK_V3_CERTIFICATE_INTERVAL;
Modified: tor/trunk/src/or/ntmain.c
===================================================================
--- tor/trunk/src/or/ntmain.c 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/or/ntmain.c 2007-10-04 16:21:58 UTC (rev 11761)
@@ -194,7 +194,7 @@
return 0;
}
-/** DOCDOC */
+/** Set the dwCurrentState field for our service to <b>state</b>. */
void
nt_service_set_state(DWORD state)
{
Modified: tor/trunk/src/or/or.h
===================================================================
--- tor/trunk/src/or/or.h 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/or/or.h 2007-10-04 16:21:58 UTC (rev 11761)
@@ -1167,7 +1167,8 @@
#define ROUTER_PURPOSE_CONTROLLER 1
/** Tor should use this router only for bridge positions in circuits. */
#define ROUTER_PURPOSE_BRIDGE 2
-/** DOCDOC */
+/** Tor should not use this router; it was marked in cached-descriptors with
+ * a purpose we didn't recognize. */
#define ROUTER_PURPOSE_UNKNOWN 255
uint8_t purpose; /** What positions in a circuit is this router good for? */
@@ -1187,8 +1188,11 @@
int routerlist_index;
} routerinfo_t;
-/** DOCDOC */
-#define EXTRAINFO_PURPOSE_GENERAL -1
+/** DOCDOC
+ * XXXX020 remove this; purpose should have the same value for router
+ * and extrainfo.
+ */
+#define EXTRAINFO_PURPOSE_GENERAL 0
/** Information needed to keep and cache a signed extra-info document. */
typedef struct extrainfo_t {
@@ -1312,58 +1316,81 @@
* sorted by identity_digest. */
} networkstatus_t;
-/** DOCDOC */
+/** The claim about a single router, make in a vote. */
typedef struct vote_routerstatus_t {
- routerstatus_t status;
- uint64_t flags;
- char *version;
+ routerstatus_t status; /**< Underlying 'status' object for this router.
+ * Flags are redundant. */
+ uint64_t flags; /**< Bit-field for all recognized flags; index into
+ * networkstatus_vote_t.known_flags. */
+ char *version; /**< The version that the authority says this router is
+ * running. */
} vote_routerstatus_t;
-/* DOCDOC */
+/* Information about a single voter in a vote or a consensus. */
typedef struct networkstatus_voter_info_t {
- char *nickname;
- char identity_digest[DIGEST_LEN];
- char *address;
- uint32_t addr;
- uint16_t dir_port;
- uint16_t or_port;
- char *contact;
- char vote_digest[DIGEST_LEN];
+ char *nickname; /**< Nickname of this voter */
+ char identity_digest[DIGEST_LEN]; /**< Digest of this voter's identity key */
+ char *address; /**< Address of this voter, in string format. */
+ uint32_t addr; /**< Address of this voter, in IPv4, in host order. */
+ uint16_t dir_port; /**< Directory port of this voter */
+ uint16_t or_port; /**< OR port of this voter */
+ char *contact; /**< Contact information for this voter. */
+ char vote_digest[DIGEST_LEN]; /**< Digest of this voter's vote, as signed. */
+
+ /* DOCDOC */
char signing_key_digest[DIGEST_LEN]; /* This part is _not_ signed. */
-
char *signature;
int signature_len;
unsigned int bad_signature : 1;
unsigned int good_signature : 1;
} networkstatus_voter_info_t;
-/*XXXX020 rename to networkstatus_t once it works. */
-/** DOCDOC is vote or consensus. */
+/** A common structure to hold a v2 network status vote, or a v2 network
+ * status consensus. */
+/* XXXX020 rename to networkstatus_t once it replaces networkstatus_t in
+ * functionality. */
typedef struct networkstatus_vote_t {
- int is_vote;
- time_t published; /* vote only. */
- time_t valid_after;
- time_t fresh_until;
- time_t valid_until;
+ int is_vote; /**< True if this is a vote; false if it is a consensus. */
+ time_t published; /**< Vote only: Tiem when vote was written. */
+ time_t valid_after; /**< Time after which this vote or consensus applies. */
+ time_t fresh_until; /**< Time before which this is the most recent vote or
+ * consensus. */
+ time_t valid_until; /**< Time after which this vote or consensus should not
+ * be used. */
+
+ /** How long does this vote/consensus claim that authorities take to
+ * distribute their votes to one another? */
int vote_seconds;
+ /** How long does this vote/consensus claim that authorites take to
+ * distribute their consensus signatures to one another? */
int dist_seconds;
+ /** Comma-separated list of recommended client software, or NULL if this
+ * voter has no opinion. */
char *client_versions;
char *server_versions;
+ /** List of flags that this vote/consensus applies to routers. If a flag is
+ * not listed here, the voter has no opinion on what its value should be. */
smartlist_t *known_flags;
- smartlist_t *voters; /* list of networkstatus_voter_info_t */
+ /** List of networkstatus_voter_info_t. For a vote, only one element
+ * is included. For a consensus, one element is included for every voter
+ * whose vote contributed to the consensus. */
+ smartlist_t *voters;
- struct authority_cert_t *cert; /* vote only. */
+ struct authority_cert_t *cert; /**< Vote only: the voter's certificate. */
+ /** Digest of this document, as signed. */
char networkstatus_digest[DIGEST_LEN];
- smartlist_t *routerstatus_list; /* holds vote_routerstatus_t if is_vote,
- * otherwise just routerstatus_t. */
+ /** List of router statuses, sorted by identity digest. For a vote,
+ * the elements are vote_routerstatus_t; for a consensus, the elements
+ * are routerstatus_t. */
+ smartlist_t *routerstatus_list;
} networkstatus_vote_t;
-/* XXXX020 merge with networkstatus_vote_t ?? */
-/** DOCDOC */
+/** A set of signatures for a networkstatus consensus. All fields are as for
+ * networkstatus_vote_t. */
typedef struct ns_detached_signatures_t {
time_t valid_after;
time_t fresh_until;
@@ -1372,21 +1399,29 @@
smartlist_t *signatures; /* list of networkstatus_voter_info_t */
} ns_detached_signatures_t;
+/** Allowable types of desc_store_t. */
typedef enum store_type_t {
- ROUTER_STORE,
- ANNOTATED_ROUTER_STORE,
- EXTRAINFO_STORE
+ ROUTER_STORE = 0,
+ EXTRAINFO_STORE = 1
} store_type_t;
-/** DOCDOC */
+/** A 'store' is a set of descriptors saved on disk, with accompanying
+ * journal, mmaped as needed, rebuilt as needed. */
typedef struct desc_store_t {
+ /** Filename (within DataDir) for the store. We append .tmp to this
+ * filename for a temporary file when rebuilding the store, and .new to this
+ * filename for the journal. */
const char *fname_base;
+ /** Alternative (obsolete) value for fname_base: if the file named by
+ * fname_base isn't present, we read from here instead, but we never write
+ * here. */
const char *fname_alt_base;
+ /** Human-readable description of what this store contains. */
const char *description;
- tor_mmap_t *mmap;
+ tor_mmap_t *mmap; /**< A mmap for the main file in the store. */
- store_type_t type;
+ store_type_t type; /**< What's stored in this store? */
/** The size of the router log, in bytes. */
size_t journal_len;
@@ -1416,11 +1451,11 @@
/** List of signed_descriptor_t for older router descriptors we're
* caching. */
smartlist_t *old_routers;
- /** DOCDOC Mmaped file holding server descriptors. If present, any router
- * whose cache_info.saved_location == SAVED_IN_CACHE is stored in this file
+ /** Store holding server descriptors. If present, any router whose
+ * cache_info.saved_location == SAVED_IN_CACHE is stored in this file
* starting at cache_info.saved_offset */
desc_store_t desc_store;
- /** Mmaped file holding extra-info documents. */
+ /** Store holding extra-info documents. */
desc_store_t extrainfo_store;
} routerlist_t;
@@ -2870,7 +2905,7 @@
void authority_cert_free(authority_cert_t *cert);
authority_cert_t *authority_cert_dup(authority_cert_t *cert);
-/** DOCDOC */
+/** Describes the schedule by which votes should be generated. */
typedef struct vote_timing_t {
int vote_interval;
int n_intervals_valid;
Modified: tor/trunk/src/or/rephist.c
===================================================================
--- tor/trunk/src/or/rephist.c 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/or/rephist.c 2007-10-04 16:21:58 UTC (rev 11761)
@@ -384,7 +384,8 @@
return total / total_weights;
}
-/** DOCDOC */
+/** Helper: Return the weighted percent-of-time-online of the router with
+ * history <b>hist</b>. */
static double
get_weighted_fractional_uptime(or_history_t *hist, time_t when)
{
@@ -413,7 +414,8 @@
return get_stability(hist, when);
}
-/** DOCDOC */
+/** Return an estimated percent-of-time-online for the router whose identity
+ * digest is <b>id</b>. Return 0 if the router is unknown. */
double
rep_hist_get_weighted_fractional_uptime(const char *id, time_t when)
{
Modified: tor/trunk/src/or/router.c
===================================================================
--- tor/trunk/src/or/router.c 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/or/router.c 2007-10-04 16:21:58 UTC (rev 11761)
@@ -319,7 +319,8 @@
authority_cert_free(parsed);
}
-/* DOCDOC */
+/** If we're a v3 authority, check whether we have a certificatge that's
+ * likely to expire soon. Warn if we do, but not too often. */
void
v3_authority_check_key_expiry(void)
{
@@ -791,7 +792,8 @@
{
return authdir_mode(options) && options->V3AuthoritativeDir != 0;
}
-/** DOCDOC */
+/** Return true if we belive ourselves to be any kind of non-bridge
+ * authoritative directory */
int
authdir_mode_any_nonbridge(or_options_t *options)
{
@@ -1773,7 +1775,9 @@
}
}
-/** DOCDOC */
+/** Given a router purpose, convert it to a string. Don't call this on
+ * ROUTER_PURPOSE_UNKNOWN: The whole point of that value is that we don't
+ * know its string representation. */
const char *
router_purpose_to_string(uint8_t p)
{
@@ -1788,7 +1792,7 @@
return NULL;
}
-/** DOCDOC */
+/** Given a string, convert it to a router purpose. */
uint8_t
router_purpose_from_string(const char *s)
{
Modified: tor/trunk/src/or/routerlist.c
===================================================================
--- tor/trunk/src/or/routerlist.c 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/or/routerlist.c 2007-10-04 16:21:58 UTC (rev 11761)
@@ -179,7 +179,7 @@
return 0;
}
-/**DOCDOC */
+/** Read the cached v3 consensus networkstatus from the disk. */
int
router_reload_consensus_networkstatus(void)
{
@@ -363,7 +363,9 @@
trusted_dirs_flush_certs_to_disk();
}
-/** DOCDOC */
+/** Return the newest v3 authority certificate whose v3 authority identity key
+ * has digest <b>id_digest</b>. Return NULL if no such authority is known,
+ * or it has no certificate. */
authority_cert_t *
authority_cert_get_newest_by_id(const char *id_digest)
{
@@ -379,7 +381,9 @@
return best;
}
-/** DOCDOC */
+/** Return the newest v3 authority certificate whose directory signing key has
+ * giest <sk_digest</b>. Return NULL if no such certificate is known.
+ */
authority_cert_t *
authority_cert_get_by_sk_digest(const char *sk_digest)
{
@@ -416,7 +420,12 @@
return NULL;
}
-/** DOCDOC */
+/** Try to download any v3 authority certificates that we may be missing. If
+ * <b>status</b> is provided, try to get all the ones that were used to sign
+ * <b>status</b>. Additionally, try to have a non-expired certificate for
+ * every V3 authority in trusted_dir_servers. Don't fetch certificates we
+ * already have.
+ **/
void
authority_certs_fetch_missing(networkstatus_vote_t *status)
{
@@ -526,6 +535,7 @@
const char *body = signed_descriptor_get_body_impl(desc,1);
size_t len = desc->signed_descriptor_len + desc->annotations_len;
+ /* XXXX020 remove this; we can now cache things with weird purposes. */
if (purpose != ROUTER_PURPOSE_GENERAL &&
purpose != EXTRAINFO_PURPOSE_GENERAL) {
/* we shouldn't cache it. be happy and return. */
@@ -1983,7 +1993,14 @@
/** Return a pointer to the signed textual representation of a descriptor.
* The returned string is not guaranteed to be NUL-terminated: the string's
- * length will be in desc-\>signed_descriptor_len. */
+ * length will be in desc-\>signed_descriptor_len.
+ *
+ * If with_annotations is set, the returned string will include the annotations
+ * (if any) preceding the descriptor. This will increase the length of the
+ * string by desc-\>annotations_len.
+ *
+ * The caller must not free the string returned.
+ */
static const char *
signed_descriptor_get_body_impl(signed_descriptor_t *desc,
int with_annotations)
@@ -2020,7 +2037,12 @@
return r;
}
-/** DOCDOC */
+/** Return a pointer to the signed textual representation of a descriptor.
+ * The returned string is not guaranteed to be NUL-terminated: the string's
+ * length will be in desc-\>signed_descriptor_len.
+ *
+ * The caller must not free the string returned.
+ */
const char *
signed_descriptor_get_body(signed_descriptor_t *desc)
{
@@ -4110,7 +4132,11 @@
return NULL;
}
-/** DOCDOC */
+/** Try to replace the current cached v3 networkstatus with the one in
+ * <b>consensus</b>. If we don't have enough certificates to validate it,
+ * store it in consensus_waiting_for_certs and launch a certificate fetch.
+ *
+ * Return 0 on success, -1 on failure. */
int
networkstatus_set_current_consensus(const char *consensus, int from_cache,
int was_waiting_for_certs)
@@ -4146,9 +4172,12 @@
options->DataDirectory);
write_str_to_file(filename, consensus, 0);
}
- /* XXXX020 trigger the certificate download. */
+ /* XXXX this test isn't quite right; see below. */
+ if (!connection_get_by_type_purpose(CONN_TYPE_DIR,
+ DIR_PURPOSE_FETCH_CERTIFICATE))
+ authority_certs_fetch_missing(c);
}
- return -1;
+ return -1; /* XXXX020 shoul*/
} else {
if (!was_waiting_for_certs)
log_warn(LD_DIR, "Not enough good signatures on networkstatus "
@@ -4158,6 +4187,14 @@
}
}
+ /* Are we missing any certificates at all? */
+ /* XXXX The test for 'are we downloading' should be 'are we downloading
+ * these certificates', and it should get pushed into
+ * authority_certs_fetch_missing. */
+ if (r != 1 && !connection_get_by_type_purpose(CONN_TYPE_DIR,
+ DIR_PURPOSE_FETCH_CERTIFICATE))
+ authority_certs_fetch_missing(c);
+
if (current_consensus)
networkstatus_vote_free(current_consensus);
Modified: tor/trunk/src/or/routerparse.c
===================================================================
--- tor/trunk/src/or/routerparse.c 2007-10-04 16:21:52 UTC (rev 11760)
+++ tor/trunk/src/or/routerparse.c 2007-10-04 16:21:58 UTC (rev 11761)
@@ -143,7 +143,7 @@
/** One or more of AT_START/AT_END to limit where the item may appear in a
* document. */
int pos;
- /** DOCDOC */
+ /** True iff this token is an annotation. */
int is_annotation;
} token_rule_t;
@@ -855,7 +855,11 @@
return 0;
}
-/** DOCDOC */
+/** Helper: move *<b>s_ptr</b> ahead to the next router, the next extra-info,
+ * or to the first of the annotations proceeding the next router or
+ * extra-info---whichever comes first. Set <b>is_extrainfo_out</b> to true if
+ * we found an extrainfo, or false if found a router. Do not scan beyond
+ * <b>eos</b>. Return -1 if we found nothing; 0 if we found something. */
static int
find_start_of_next_router_or_extrainfo(const char **s_ptr,
const char *eos,
@@ -1005,7 +1009,14 @@
* returns NULL. If <b>cache_copy</b> is true, duplicate the contents of
* s through end into the signed_descriptor_body of the resulting
* routerinfo_t.
- * DOCDOC annotations
+ *
+ * If <b>allow_annotations</b>, it's okay to encounter annotations in <b>s</b>
+ * before the router; if it's false, reject the router if it's annotated. If
+ * <b>prepend_annotations</b> is set, it should contain some annotations:
+ * append them to the front of the router before parsing it, and keep them
+ * around when caching the router.
+ *
+ * Only one of allow_annotations and prepend_annotations may be set.
*/
routerinfo_t *
router_parse_entry_from_string(const char *s, const char *end,
@@ -1531,7 +1542,11 @@
/** Given a string at *<b>s</b>, containing a routerstatus object, and an
* empty smartlist at <b>tokens</b>, parse and return the first router status
* object in the string, and advance *<b>s</b> to just after the end of the
- * router status. Return NULL and advance *<b>s</b> on error. */
+ * router status. Return NULL and advance *<b>s</b> on error.
+ *
+ * If <b>vote</b> and <b>vote_rs</b> are provided, don't allocate a fresh
+ * routerstatus but use <b>vote_rs</b> instead
+ **/
static routerstatus_t *
routerstatus_parse_entry_from_string(const char **s, smartlist_t *tokens,
networkstatus_vote_t *vote,
More information about the tor-commits
mailing list