[tor-dev] Google Summer of Code Proposal - PathSupport counterpart for Stem

Ravi Chandra Padmala neenaoffline at gmail.com
Mon Apr 2 06:10:35 UTC 2012

> I want to apply to the Tor Project/EFF for Google's Summer of Code
> program this summer. I would like to spend the summer building the
> PathSupport counter part for Stem. I have submitted a work in progress
> proposal at http://www.google-melange.com/gsoc/proposal/review/google/gsoc2012/neena/1

I'm sending the contents of my proposal here (with minor
modifications), since not everyone has access to that page. Not
everyone can comment on it even if I make it public, so, I would
prefer it if people with access to that page also commented here.

What project would you like to work on?

I would like to work on the PathSupport counterpart for Stem.

Apart from simply writing code, I want to focus on creating a well
designed API (during the community bonding period) and on writing
comprehensive documentation (very important for a library).

During the community bonding period, I will spend my time preparing a
proper API and interacting with the maintainers of projects which use
TorCtl and getting their feedback. Their feedback will ensure that the
API will be usable. I also will communicate with my mentor about my
progress and hopefully, will have an intuitive, easy to use API design
ready before the coding period starts.

As suggested, I will be coding iteratively, writing documentation and
tests as I write each class/function/module of the project.
Implementation implies writing the code, tests and the documentation.

Rough API Draft

Introducing a new submodule - stem.path

This submodule will contain all PathSupport specific code.


    An amalgamation of the PathSupport.PathBuilder and the
PathSupport.ConsensusTracker classes. Justification:
PathSupport.ConsensusTracker can be merged because
TorCtl.PathSupport.ConsensusTracker isn't being used anywhere but as a
super class of TorCtl.PathSupport.PathBuilder. Among pytorctl, arm,
torbel and torflow the only other mention of ConsensusTracker is
TorCtl.SQLSupport.ConsensusTrackerListener which is used by Torflow
for storing stats and SQLSUPPORT.
    TorCtl.PathSupport.PathBuilder uses a
TorCtl.PathSupport.SelectionManager. A helper class for handling
(router) configuration updates. I will merge a part of this into
stem.path.PathController too, in particular, the configuration update
handling code. I will look into moving the NodeGenerator handling
functionality and the circuit generation functionality of
TorCtl.PathSupport.SelectionManager into stem.path.PathGenerator.
    In the process of merging these three classes together, if
stem.path.PathController grows too large or becomes unwieldy, I will
make helper classes as necessary.
    Is a direct subclass of stem.control.BaseController
    A major change would be to make PathController fully thread-safe
instead of an event/queue system. Stem's BaseController class prefers
locking and we will use the same approach.
    Handles tracking the NEWCONSENSUS and NEWDESC events just like
    Write integration tests that check circuit construction and the
like, where possible.
    Write unit tests to ensure all the individual methods of the class
are working as expected.

The following classes will be renamed

    TorCtl.PathSupport.CircuitHandler -> stem.path.CircuitController
        CircuitHandler gives the impression that the class 'handles' one Circuit
        CircuitManager is more appropriate since they 'control'
(multiple) Circuit building, and it is also what people should expect
since it is a subclass of stem.control.BaseController

    TorCtl.PathSupport.StreamHandler -> stem.path.StreamController
        StreamHandler gives the impression that the class 'handles' one Stream
        StreamController is more appropriate since they 'control'
Stream-Circuit attachment, and it is also what people should expect
since it is a subclass of stem.control.BaseController.
        Torflow (OPAddon) has PingHandler which is a subclass of this.
Check how it is subclassing StreamHandler and if this can be made
easier to use.This will be done during the community bonding period.

    TorCtl.PathSelector -> stem.path.PathGenerator
        Maintain naming consistency with NodeGenerator
        Merge parts of TorCtl.PathSupport.SelectionManager into this.
In particular, the NodeGenerator handling code.


    Both of these Restriction classes have one restriction checking
function, r_is_ok and path_is_ok respectively. These will be renamed
to 'check'.

Implement the various NodeRestrictions and PathRestrictions available
in TorCtl.PathSupport

There's a TODO comment in PathSupport.py (also in torflow/TODO) which
mentions other NodeRestrictions and PathRestrictions. If time permits,
implement these Restrictions too.


Mid term evaluation:

The following will be implemented as deliverables for the mid term evaluation

    Required base classes, such as the stem.path.Circuit class and the
stem.path.Stream class.
    NodeRestrictions and CircuitRestrictions currently available in
    NodeGenerators and PathGenerators.
    stem.path.PathController (This might be split into 2 or more
classes, if the merge doesn't seem like the right thing to do)

Final evaluation:

The following will be implemented as deliverables for the final term evaluation


The following will be ported to use Stem:


Note: Torflow is our main 'testbed' for testing the new API, since it
the only major codebase that uses PathSupport. Depending on how this
goes, I might refactor or make changes to the stem.path submodule.

Optional Deliverables:

In case I finish my deliverables with time to spare, I'll spend it
doing the following tasks

    Implementing the extra Restrictions mentioned in the TODO
    Porting Arm to use Stem
    Porting TorBEL to use Stem

Note: Neither TorBEL, nor Arm use PathSupport


April 23rd - May 20th Community bonding period

I will spend this time designing the final API for Stem's
TorCtl.PathSupport equivalent. I will be communicating with people in
the Tor community who have used TorCtl and TorCtl.PathSupport and
getting their feedback, thus ensuring that we have a nice API design
ready by the beginning of the coding period.

There are some unimplemented parts of the general controller class
that are required for the implementation of PathSupport, such as the
Router class. Atagar is currently working on this. I will help with
implementing these so that they will be ready before the coding period

May 20th - July 9th Coding Period (Pre-mid term evaluation)

The pre-mid term coding period  I will be implement the deliverables
for the mid term evaluation as follows:

Week 1 -

    Implement required base classes, such as the stem.path.Circuit
class and the stem.path.Stream class.

Week 2 -

    Implement NodeRestrictions and CircuitRestrictions currently
available in TorCtl.PathSupport.

Week 3 -

    Implement NodeGenerators and PathGenerators.

Week 4-7 -

    Implement stem.path.PathController.This might be split into 2 or
more classes, if the merge doesn't seem like the right thing to do.
This is a major chunk of the project and will take a significant
amount of time and might consume a part of week 8.

Note: The individual blocks that PathController is composed of make up
about 50% of the existing PathSupport.py code. I will also be writing
tests and documentation. This is why I have allocated 3 weeks to this.

Week 8 -

    Leaving this week free as buffer time. I have optional
deliverables that will be worked on if I have extra time.

July 9th - August 13th (Post-mid term evaluation)

Week 9 -

    Implement stem.path.CircuitController and stem.path.StreamController

Week 10 -

    Port Torflow to use Stem. This will consume a part of week 11,
since Torflow depends on Stem and PathSupport a fair bit. The codebase
itself consists of a variety of scripts and utilities and is
relatively large (compared to something like TorBEL).

Week 11 -

    More buffer time. Depending on the status of my work, I will spend
this time doing  the following things (In order of importance):
        Finishing stuff
        Write the additional Restrictions
        Begin porting Arm and TorBEL to Stem

August 13th - August 20th (Post-soft pencils down deadline)

Week 12 -

    The gsoc page suggests taking a week to scrub code, write tests,
improve documentation, etc. Since this is a library, documentation
takes priority. So, assuming the code is complete and assuming it has
sufficient test coverage I will spend this week writing and improving
the documentation. This will involve writing examples and
comprehensive documentation.

Point us to a code sample: something good and clean to demonstrate
that you know what you're doing, ideally from an existing project.

I have written a few patches for some Tor Project projects. #1667,
#5032. Two to Stem, which have been committed to the repository #5199
and #5472.

Why do you want to work with The Tor Project / EFF in particular?

I began reading stuff about The Tor Project about 2 months ago after a
friend suggest that I contribute to it. Now, I love the internet, and
it is responsible for a large part who I am. The Tor Project and the
EFF work to defend the things that make the internet what it is, i.e.
(among other things) free speech.

I can relate with this goal very easily.

Tell us about your experiences in free software development
environments. We especially want to hear examples of how you have
collaborated with others rather than just working on a project by

Though I have been using Free software for a long time (I switched to
Linux about 7 years ago), I haven't made any significant contributions
to free software, apart from a few bugs reports and minor patches.
However, I am familiar with version control software, bug trackers
etc. I have used them while submitting the patches mentioned earlier.

Will you be working full-time on the project for the summer, or will
you have other commitments too (a second job, classes, etc)? If you
won't be available full-time, please explain, and list timing if you
know them for other major deadlines (e.g. exams). Having other
activities isn't a deal-breaker, but we don't want to be surprised.

I have exams until the 29th of April, so I will be missing a few days
of the community bonding period, though, I hope to show up on the IRC
channels even then, albeit sporadically. I also might have to write an
exam either in july or august. Though, that depends on me flunking. It
won't cost me more than 2 days, and I will work extra during the
weekends to make up for it.

Will your project need more work and/or maintenance after the summer
ends? What are the chances you will stick around and help out with
that and other related projects?

Stem, like all libraries implementing an API for a moving target
requires maintenance. I will co-maintain Stem in the future. By the
time I'm done with the SoC program, I would've also gained familiarity
with other related projects such as Torflow, TorBEL and Arm. I'll be
in a position where I can help out with those if there is a need.

Though, personally, I am interested in getting involved in Tor
development, and the re-implementation of Thandy (if/when it happens),
and that is what I'll do unless any other project requires more

What is your ideal approach to keeping everybody informed of your
progress, problems, and questions over the course of the project? Said
another way, how much of a "manager" will you need your mentor to be?

IRC is my preferred mode of communication, and I will be using it to
ask questions and for help with my problems. If I'm unable to get the
answer I want on the IRC, I will ask them on the mailing list.

I will keep people informed about my progress by sending (probably
monthly, or as often as required) reports the mailing list.

What school are you attending? What year are you, and what's your
major/degree/focus? If you're part of a research group, which one?

I'm an undergraduate student majoring in computer science studying at
GITAM University  I'm currently working on my final year project which
involves computer network modelling.

How can we contact you to ask you further questions? Google doesn't
share your contact details with us automatically, so you should
include that in your application. In addition, what's your IRC
nickname? Interacting with us on IRC will help us get to know you, and
help you get to know our community.

I'm available via email at neenaoffline at gmail.com. I'm also subscribed
to many of the tor-* mailing lists, including tor-dev and tor-talk. My
nickname on OFTC is 'neena'. My email account also doubles up as my
Jabber account, though, I prefer IRC.

Are you applying to other projects for GSoC and, if so, what would be
your preference if you're accepted to both? Having a stated preference
helps with the deduplication process and will not impact if we accept
your application or not.

I am not applying to any other projects for GSoC.


More information about the tor-dev mailing list