
Extrainfo Descriptor
********************

Parsing for Tor extra-info descriptors. These are published by relays
whenever their server descriptor is published and have a similar
format. However, unlike server descriptors these don't contain
information that Tor clients require to function and as such aren't
fetched by default.

Defined in section 2.2 of the dir-spec, extra-info descriptors contain
interesting but non-vital information such as usage statistics. Tor
clients cannot request these documents for bridges.

Extra-info descriptors are available from a few sources...

* If you have 'DownloadExtraInfo 1' in your torrc...

   * control port via 'GETINFO extra-info/digest/*' queries

   * the 'cached-extrainfo' file in tor's data directory

* Archived descriptors provided by CollecTor
  (https://collector.torproject.org/).

* Directory authorities and mirrors via their DirPort.

**Module Overview:**

   ExtraInfoDescriptor - Tor extra-info descriptor.
     |- RelayExtraInfoDescriptor - Extra-info descriptor for a relay.
     |- BridgeExtraInfoDescriptor - Extra-info descriptor for a bridge.
     |
     +- digest - calculates the upper-case hex digest value for our content

stem.descriptor.extrainfo_descriptor.DirResponse(enum)

   Enumeration for known statuses for ExtraInfoDescriptor's
   dir_*_responses.

   +---------------------+--------------------------------------------------------+
   | DirResponse         | Description                                            |
   +=====================+========================================================+
   | **OK**              | network status requests that were answered             |
   +---------------------+--------------------------------------------------------+
   | **NOT_ENOUGH_SIGS** | network status wasn't signed by enough authorities     |
   +---------------------+--------------------------------------------------------+
   | **UNAVAILABLE**     | requested network status was unavailable               |
   +---------------------+--------------------------------------------------------+
   | **NOT_FOUND**       | requested network status was not found                 |
   +---------------------+--------------------------------------------------------+
   | **NOT_MODIFIED**    | network status unmodified since If-Modified-Since time |
   +---------------------+--------------------------------------------------------+
   | **BUSY**            | directory was busy                                     |
   +---------------------+--------------------------------------------------------+

stem.descriptor.extrainfo_descriptor.DirStat(enum)

   Enumeration for known stats for ExtraInfoDescriptor's
   dir_*_direct_dl and dir_*_tunneled_dl.

   +-----------------------+---------------------------------------------------------------+
   | DirStat               | Description                                                   |
   +=======================+===============================================================+
   | **COMPLETE**          | requests that completed successfully                          |
   +-----------------------+---------------------------------------------------------------+
   | **TIMEOUT**           | requests that didn't complete within a ten minute timeout     |
   +-----------------------+---------------------------------------------------------------+
   | **RUNNING**           | requests still in process when measurement's taken            |
   +-----------------------+---------------------------------------------------------------+
   | **MIN**               | smallest rate at which a descriptor was downloaded in B/s     |
   +-----------------------+---------------------------------------------------------------+
   | **MAX**               | largest rate at which a descriptor was downloaded in B/s      |
   +-----------------------+---------------------------------------------------------------+
   | **D1-4** and **D6-9** | rate of the slowest x/10 download rates in B/s                |
   +-----------------------+---------------------------------------------------------------+
   | **Q1** and **Q3**     | rate of the slowest and fastest quarter download rates in B/s |
   +-----------------------+---------------------------------------------------------------+
   | **MD**                | median download rate in B/s                                   |
   +-----------------------+---------------------------------------------------------------+

class class stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor(raw_contents, validate=False)

   Bases: "stem.descriptor.Descriptor"

   Extra-info descriptor document.

   Variables:
      * **nickname** (*str*) -- ***** relay's nickname

      * **fingerprint** (*str*) -- ***** identity key fingerprint

      * **published** (*datetime*) -- ***** time in UTC when this
        descriptor was made

      * **geoip_db_digest** (*str*) -- sha1 of the geoIP database file
        for IPv4 addresses

      * **geoip6_db_digest** (*str*) -- sha1 of the geoIP database
        file for IPv6 addresses

      * **transport** (*dict*) -- ***** mapping of transport methods
        to their (address, port, args) tuple, these usually appear on
        bridges in which case all of those are **None**

   **Bi-directional connection usage:**

   Variables:
      * **conn_bi_direct_end** (*datetime*) -- end of the sampling
        interval

      * **conn_bi_direct_interval** (*int*) -- seconds per interval

      * **conn_bi_direct_below** (*int*) -- connections that
        read/wrote less than 20 KiB

      * **conn_bi_direct_read** (*int*) -- connections that read at
        least 10x more than wrote

      * **conn_bi_direct_write** (*int*) -- connections that wrote at
        least 10x more than read

      * **conn_bi_direct_both** (*int*) -- remaining connections

   **Bytes read/written for relayed traffic:**

   Variables:
      * **read_history_end** (*datetime*) -- end of the sampling
        interval

      * **read_history_interval** (*int*) -- seconds per interval

      * **read_history_values** (*list*) -- bytes read during each
        interval

      * **write_history_end** (*datetime*) -- end of the sampling
        interval

      * **write_history_interval** (*int*) -- seconds per interval

      * **write_history_values** (*list*) -- bytes written during each
        interval

   **Cell relaying statistics:**

   Variables:
      * **cell_stats_end** (*datetime*) -- end of the period when
        stats were gathered

      * **cell_stats_interval** (*int*) -- length in seconds of the
        interval

      * **cell_processed_cells** (*list*) -- measurement of processed
        cells per circuit

      * **cell_queued_cells** (*list*) -- measurement of queued cells
        per circuit

      * **cell_time_in_queue** (*list*) -- mean enqueued time in
        milliseconds for cells

      * **cell_circuits_per_decile** (*int*) -- mean number of
        circuits in a decile

   **Directory Mirror Attributes:**

   Variables:
      * **dir_stats_end** (*datetime*) -- end of the period when stats
        were gathered

      * **dir_stats_interval** (*int*) -- length in seconds of the
        interval

      * **dir_v2_ips** (*dict*) -- mapping of locales to rounded count
        of requester ips

      * **dir_v3_ips** (*dict*) -- mapping of locales to rounded count
        of requester ips

      * **dir_v2_share** (*float*) -- percent of total directory
        traffic it expects to serve

      * **dir_v3_share** (*float*) -- percent of total directory
        traffic it expects to serve

      * **dir_v2_requests** (*dict*) -- mapping of locales to rounded
        count of requests

      * **dir_v3_requests** (*dict*) -- mapping of locales to rounded
        count of requests

      * **dir_v2_responses** (*dict*) -- mapping of "DirResponse" to
        their rounded count

      * **dir_v3_responses** (*dict*) -- mapping of "DirResponse" to
        their rounded count

      * **dir_v2_responses_unknown** (*dict*) -- mapping of
        unrecognized statuses to their count

      * **dir_v3_responses_unknown** (*dict*) -- mapping of
        unrecognized statuses to their count

      * **dir_v2_direct_dl** (*dict*) -- mapping of "DirStat" to
        measurement over DirPort

      * **dir_v3_direct_dl** (*dict*) -- mapping of "DirStat" to
        measurement over DirPort

      * **dir_v2_direct_dl_unknown** (*dict*) -- mapping of
        unrecognized stats to their measurement

      * **dir_v3_direct_dl_unknown** (*dict*) -- mapping of
        unrecognized stats to their measurement

      * **dir_v2_tunneled_dl** (*dict*) -- mapping of "DirStat" to
        measurement over ORPort

      * **dir_v3_tunneled_dl** (*dict*) -- mapping of "DirStat" to
        measurement over ORPort

      * **dir_v2_tunneled_dl_unknown** (*dict*) -- mapping of
        unrecognized stats to their measurement

      * **dir_v3_tunneled_dl_unknown** (*dict*) -- mapping of
        unrecognized stats to their measurement

   **Bytes read/written for directory mirroring:**

   Variables:
      * **dir_read_history_end** (*datetime*) -- end of the sampling
        interval

      * **dir_read_history_interval** (*int*) -- seconds per interval

      * **dir_read_history_values** (*list*) -- bytes read during each
        interval

      * **dir_write_history_end** (*datetime*) -- end of the sampling
        interval

      * **dir_write_history_interval** (*int*) -- seconds per interval

      * **dir_write_history_values** (*list*) -- bytes read during
        each interval

   **Guard Attributes:**

   Variables:
      * **entry_stats_end** (*datetime*) -- end of the period when
        stats were gathered

      * **entry_stats_interval** (*int*) -- length in seconds of the
        interval

      * **entry_ips** (*dict*) -- mapping of locales to rounded count
        of unique user ips

   **Exit Attributes:**

   Variables:
      * **exit_stats_end** (*datetime*) -- end of the period when
        stats were gathered

      * **exit_stats_interval** (*int*) -- length in seconds of the
        interval

      * **exit_kibibytes_written** (*dict*) -- traffic per port (keys
        are ints or 'other')

      * **exit_kibibytes_read** (*dict*) -- traffic per port (keys are
        ints or 'other')

      * **exit_streams_opened** (*dict*) -- streams per port (keys are
        ints or 'other')

   **Hidden Service Attributes:**

   Variables:
      * **hs_stats_end** (*datetime*) -- end of the sampling interval

      * **hs_rend_cells** (*int*) -- rounded count of the RENDEZVOUS1
        cells seen

      * **hs_rend_cells_attr** (*int*) -- ***** attributes provided
        for the hs_rend_cells

      * **hs_dir_onions_seen** (*int*) -- rounded count of the
        identities seen

      * **hs_dir_onions_seen_attr** (*int*) -- ***** attributes
        provided for the hs_dir_onions_seen

   **Bridge Attributes:**

   Variables:
      * **bridge_stats_end** (*datetime*) -- end of the period when
        stats were gathered

      * **bridge_stats_interval** (*int*) -- length in seconds of the
        interval

      * **bridge_ips** (*dict*) -- mapping of locales to rounded count
        of unique user ips

      * **geoip_start_time** (*datetime*) -- replaced by
        bridge_stats_end (deprecated)

      * **geoip_client_origins** (*dict*) -- replaced by bridge_ips
        (deprecated)

      * **ip_versions** (*dict*) -- mapping of ip protocols to a
        rounded count for the number of users

      * **ip_versions** -- mapping of ip transports to a count for the
        number of users

   ***** attribute is either required when we're parsed with
   validation or has a default value, others are left as **None** if
   undefined

   Changed in version 1.4.0: Added the hs_stats_end, hs_rend_cells,
   hs_rend_cells_attr, hs_dir_onions_seen, and hs_dir_onions_seen_attr
   attributes.

   digest()

      Provides the upper-case hex encoded sha1 of our content. This
      value is part of the server descriptor entry for this relay.

      Returns:
         **str** with the upper-case hex digest value for this server
         descriptor

class class stem.descriptor.extrainfo_descriptor.RelayExtraInfoDescriptor(raw_contents, validate=False)

   Bases: "stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor"

   Relay extra-info descriptor, constructed from data such as that
   provided by 'GETINFO extra-info/digest/*', cached descriptors, and
   metrics (specification).

   Variables:
      **signature** (*str*) -- ***** signature for this extrainfo
      descriptor

   ***** attribute is required when we're parsed with validation

   digest(*args, **kwds)

class class stem.descriptor.extrainfo_descriptor.BridgeExtraInfoDescriptor(raw_contents, validate=False)

   Bases: "stem.descriptor.extrainfo_descriptor.ExtraInfoDescriptor"

   Bridge extra-info descriptor (bridge descriptor specification)

   digest()
