bridgedb.Bridges

This module has low-level functionality for parsing bridges and arranging them into hashrings for distributors.

class BridgeRingParameters(needPorts=[], needFlags=[])

Bases: object

Store validated settings on minimum number of Bridges with certain attributes which should be included in any generated subring of a hashring.

Variables:

• needPorts (list) – List of two-tuples of desired port numbers and their respective minimums.
• needFlags (list) – List of two-tuples of desired flags assigned to a Bridge by the Bridge DirAuth.

Control the creation of subrings by including a minimum number of bridges which possess certain attributes.

Parameters:

• needPorts (iterable) – An iterable of two-tuples. Each two tuple should contain (port, minimum), where port is an integer specifying a port number, and minimum is another integer specifying the minimum number of Bridges running on that port to include in any new subring.
• needFlags (iterable) – An iterable of two-tuples. Each two tuple should contain (flag, minimum), where flag is a string specifying an OR flag_, and minimum is an integer for the minimum number of Bridges which have acquired that flag to include in any new subring.

Raises:

An TypeError if an invalid port number, a minimum less than one, or an “unsupported” flag is given. “Stable” appears to be the only currently “supported” flag.

class BridgeRing(key, answerParameters=None)

Bases: object

Arranges bridges into a hashring based on an hmac function.

Create a new BridgeRing, using key as its hmac key.

Parameters:

• key (bytes) – The HMAC key, generated with getKey().
• answerParameters (BridgeRingParameters) – DOCDOC

Variables:

• bridges (dict) – A dictionary which maps HMAC keys to :class:`~bridgedb.bridges.Bridge`s.
• bridgesByID (dict) – A dictionary which maps raw hash digests of bridge ID keys to :class:`~bridgedb.bridges.Bridge`s.
• hmac – An HMAC function, which uses the key parameter to generate new HMACs for storing, inserting, and retrieving :class:`~bridgedb.bridges.Bridge`s within mappings.
• isSorted (bool) – True if sortedKeys is currently sorted.
• sortedKeys (list) – A sorted list of all of the HMACs.
• name (str) – A string which identifies this hashring, used mostly for differentiating this hashring in log messages, but it is also used for naming subrings. If this hashring is a subring, the name will include whatever distinguishing parameters differentiate that particular subring (i.e. '(port-443 subring)' or '(Stable subring)')
• subrings –

  A list of other ``BridgeRing``s, each of which contains bridges of a particular type. For example, a subring might contain only ``Bridge``s which have been given the “Stable” flag, or it might contain only IPv6 bridges. Each item in this list should be a 4-tuple:

  (type, value, count, ring)
  

  where:

  • type is a string which describes what kind of parameter is used to determine if a Bridge belongs in that subring, i.e. 'port' or 'flag'.
  • value is a specific value pertaining to the type, e.g. type='port'; value=443.
  • count is an integer for the current total number of bridges in the subring.
  • ring is a BridgeRing; it is the subhashring which contains count number of Bridge`s of a certain ``type`.

setName(name)

Tag a unique name to this hashring for identification.

Parameters:name (string) – The name for this hashring.

clear()

Remove all bridges and mappings from this hashring and subrings.

insert(bridge)

Add a bridge to this hashring.

The bridge’s position in the hashring is dependent upon the HMAC of the raw hash digest of the bridge’s ID key. The function used to generate the HMAC, :ivar:`BridgeRing.hmac`, is unique to each individual hashring.

If the (presumably same) bridge is already at that determined position in this hashring, replace the old one.

Parameters:bridge (Bridge) – The bridge to insert into this hashring.

_sort()

Helper: put the keys in sorted order.

_getBridgeKeysAt(pos, N=1)

Bisect a list of bridges at a specified position, pos, and retrieve bridges from that point onwards, wrapping around the hashring if necessary.

If the number of bridges requested, N, is larger that the size of this hashring, return the entire ring. Otherwise:

1. Sort this bridges in this hashring, if it is currently unsorted.

2. Bisect the sorted bridges. If the bridge at the desired position, pos, already exists within this hashring, the the bisection result is the bridge at position pos. Otherwise, the bisection result is the first position after pos which has a bridge assigned to it.

3. Try to obtain N bridges, starting at (and including) the bridge in the requested position, pos.

   1. If there aren’t N bridges after pos, wrap back around to the beginning of the hashring and obtain bridges until we have N bridges.

4. Check that the number of bridges obtained is indeed N, then return them.

Parameters:

• pos (bytes) – The position to jump to. Any bridges returned will start at this position in the hashring, if there is a bridge assigned to that position. Otherwise, indexing will start at the first position after this one which has a bridge assigned to it.
• N (int) – The number of bridges to return.

Return type:

list

Returns:

A list of :class:`~bridgedb.Bridges.Bridge`s.

getBridges(pos, N=1)

Return N bridges appearing in this hashring after a position.

Parameters:

• pos (bytes) – The position to jump to. Any bridges returned will start at this position in the hashring, if there is a bridge assigned to that position. Otherwise, indexing will start at the first position after this one which has a bridge assigned to it.
• N (int) – The number of bridges to return.

Return type:

list

Returns:

A list of :class:`~bridgedb.bridges.Bridge`s.

getBridgeByID(fp)

Return the bridge whose identity digest is fp, or None if no such bridge exists.

dumpAssignments(f, description='')

class FixedBridgeSplitter(key, rings)

Bases: object

Splits bridges up based on an HMAC and assigns them to one of several subhashrings with equal probability.

insert(bridge)

clear()

Clear all bridges from every ring in rings.

dumpAssignments(filename, description='')

Write all bridges assigned to this hashring to filename.

Parameters:description (string) – If given, include a description next to the index number of the ring from FilteredBridgeSplitter.rings the following bridges were assigned to. For example, if the description is "IPv6 obfs2 bridges" the line would read: "IPv6 obfs2 bridges ring=3".

class UnallocatedHolder

Bases: object

A pseudo-bridgeholder that ignores its bridges and leaves them unassigned.

insert(bridge)

clear()

dumpAssignments(f, description='')

class BridgeSplitter(key)

Bases: object

Splits incoming bridges up based on an HMAC, and assigns them to sub-bridgeholders with different probabilities. Bridge ←→ BridgeSplitter associations are recorded in a store.

addRing(ring, ringname, p=1)

Add a new subring.

Parameters:

• ring – The subring to add.
• ringname (str) – This is used to record which bridges have been assigned where in the store.
• p (int) – The relative proportion of bridges to assign to this bridgeholder.

addPseudoRing(ringname)

Add a pseudo ring to the list of pseudo rings.

addTracker(t)

Adds a statistics tracker that gets told about every bridge we see.

clear()

insert(bridge)

dumpAssignments(f, description='')

class FilteredBridgeSplitter(key, max_cached_rings=3)

Bases: object

Places bridges into subrings based upon sets of filters.

The set of subrings and conditions used to assign Bridge`s should be passed to :meth:`~FilteredBridgeSplitter.addRing.

Create a hashring which filters bridges into sub hashrings.

Parameters:

• key (DOCDOC) – An HMAC key.
• max_cached_rings (int) – XXX max_cached_rings appears to not be used anywhere.

Variables:

• filterRings –

  A dictionary of subrings which has the form {ringname: (filterFn, subring)}, where:

  • ringname is a unique string identifying the subring.
  • filterFn is a callable which filters Bridges in some manner, i.e. by whether they are IPv4 or IPv6, etc.
  • subring is any of the horribly-implemented, I-guess-it-passes-for-some-sort-of-hashring classes in this module.

• hmac – DOCDOC
• bridges – DOCDOC
• distributorName – The name of this splitter’s distributor. See setDistributorName().

clear()

insert(bridge)

Insert a bridge into all appropriate sub-hashrings.

For all sub-hashrings, the bridge will only be added iff it passes the filter functions for that sub-hashring.

Parameters:bridge (Bridge) – The bridge to add.

extractFilterNames(ringname)

Get the names of the filters applied to a particular sub hashring.

Parameters:ringname (str) – A unique name identifying a sub hashring. Return type:list Returns:A sorted list of strings, all the function names of the filters applied to the sub hashring named ringname.

addRing(subring, ringname, filterFn, populate_from=None)

Add a subring to this hashring.

Parameters:

• subring – The subring to add.
• ringname (str) – A unique name for identifying the new subring.
• filterFn – A function whose input is a Bridge, and returns True/False based on some filtration criteria.
• populate_from (iterable or None) – A group of :class:`Bridge`s. If given, the newly added subring will be populated with these bridges.

Return type:

bool

Returns:

False if there was a problem adding the subring, True otherwise.

dumpAssignments(f, description='')