bridgedb.Bucket

This module is responsible for everything concerning file bucket bridge distribution. File bucket bridge distribution means that unallocated bridges are allocated to a certain pseudo-distributor and later written to a file.

For example, the following is a dict of pseudo-distributors (also called ‘bucket identifiers’) with numbers of bridges assigned to them:

FILE_BUCKETS = { “name1”: 10, “name2”: 15, “foobar”: 3 }

This configuration for buckets would result in 3 files being created for bridge distribution: name1-2010-07-17.brdgs, name2-2010-07-17.brdgs and foobar-2010-07-17.brdgs. The first file would contain 10 bridges from BridgeDB’s ‘unallocated’ pool. The second file would contain 15 bridges from the same pool and the third one similarly 3 bridges. These files can then be handed out to trusted parties via mail or fed to other distribution mechanisms such as twitter.

Note that in BridgeDB slang, the _distributor_ would still be ‘unallocated’, even though in the database, there would now by ‘name1’, ‘name2’ or ‘foobar’ instead of ‘unallocated’. This is why they are called pseudo-distributors.

class BucketData(name, needed)

Bases: object

Configures a bridge bucket with the number of bridges which should be allocated, the name of the bucket, and other similar data.

Parameters:

• name (str) – The name of this bucket (from the config file). This will be prefixed by the PSEUDO_DISTRIBUTOR_PREFIX.
• needed (str or int) – The number of bridges needed for this bucket (also from the config file).
• allocated (int) – Number of bridges already allocated for this bucket.

class BucketManager(cfg)

Bases: object

BucketManager reads a number of file bucket identifiers from the config.

They’re expected to be in the following format:

FILE_BUCKETS = { "name1": 10, "name2": 15, "foobar": 3 }

This syntax means that certain buckets (“name1”, “name2” and so on) are given a number of bridges (10, 15 and so on). Names can be anything. The name will later be the prefix of the file that is written with the assigned number of bridges in it. Instead of a number, a wildcard item (“*”) is allowed, too. This means that the corresponsing bucket file will get the maximum number of possible bridges (as many as are left in the unallocated bucket).

The files will be written in ip:port format, one bridge per line.

The way this works internally is as follows:

First of all, the assignBridgesToBuckets() routine runs through the database of bridges and looks up the ‘distributor’ field of each bridge. Unallocated bridges are sent to a pool for later assignement. Already allocated bridges for file bucket distribution are sorted and checked. They’re checked for whether their bucket identifier still exists in the current config and also whether the number of assigned bridges is still valid. If either the bucket identifier is not existing anymore or too many bridges are currently assigned to it, bridges will go to the unassigned pool.

In the second step, after bridges are sorted and the unassigned pool is ready, the assignBridgesToBuckets() routine assigns one bridge from the unassigned pool to a known bucket identifier at a time until it either runs out of bridges in the unallocated pool or the number of needed bridges for that bucket is reached.

When all bridges are assigned in this way, they can then be dumped into files by calling the dumpBridges() routine.

Variables:

• cfg – The central configuration instance.
• bucketList (list) – A list of BucketData instances, holding all configured (and thus requested) buckets with their respective numbers.
• unallocatedList (list) – Holds all bridges from the ‘unallocated’ pool.
• unallocated_available (bool) – Is at least one unallocated bridge available?
• distributor_prefix (str) – The ‘distributor’ field in the database will hold the name of our pseudo-distributor, prefixed by this string. By default, this uses PSEUDO_DISTRIBUTOR_PREFIX.
• db – The bridge database instance.

Create a BucketManager.

Parameters:cfg (bridgedb.persistent.Conf) – The central configuration instance.

addToUnallocatedList(hex_key)

Add a bridge by hex_key into the unallocated pool.

getBucketByIdent(bucketIdent)

If we know this bucket identifier, then return the corresponding BucketData object.

assignUnallocatedBridge(bucket)

Assign an unallocated bridge to a certain bucket.

assignBridgesToBuckets()

Read file bucket identifiers from the configuration, sort them, and write necessary changes to the database.

dumpBridgesToFile(filename, bridges)

Dump a list of given bridges into filename.

dumpBridges()

Dump all known file distributors to files, sorted by distributor.