~launchpad-pqm/launchpad/devel

XMLRPC access to mailing list memberships

=========================================

Just like the creation and deactivation of mailing lists, membership changes

to mailing lists must be communicated to Mailman over XMLRPC.  Because the

bandwidth involved is not expected to be overwhelming, a simplified interface

was chosen.

The communication pattern is initiated by Mailman in all cases; in other

words, Mailman polls Launchpad to see if there is any work for Mailman to do.

    >>> # Note that this test is run multiple times, with the harness

    >>> # providing `mailinglist_api` and `commit` for impedance matching.

Requesting membership information

---------------------------------

Mailman requests membership information for specific list of teams.  Let's

create and populate some teams to demonstrate.

    # login() as an admin so that we can call join() on anyone

    # and change their mailing list auto-subscription settings.

    >>> login('foo.bar@canonical.com')

    >>> from lp.registry.tests.mailinglists_helper import new_team

    >>> team_one, list_one = new_team('team-one', with_list=True)

    >>> anne = factory.makePersonByName('Anne')

    >>> bart = factory.makePersonByName('Bart')

    >>> cris = factory.makePersonByName('Cris')

    >>> dirk = factory.makePersonByName('Dirk')

    >>> elle = factory.makePersonByName('Elle')

    >>> fred = factory.makePersonByName('Fred')

    >>> gwen = factory.makePersonByName('Gwen')

    >>> hank = factory.makePersonByName('Hank')

    >>> people = [anne, bart, cris, dirk, elle, fred, gwen, hank]

    >>> for person in people:

    ...     person.join(team_one)

    ...     list_one.subscribe(person)

    # The IMailingListSet APIs use the SLAVE_FLAVOR since they are read-only.

    # Commit the transaction so that the changes are visible there.

    >>> transaction.commit()

Asking for the membership information for team-one's list returns all the

above people.  We want to see all the email addresses for all the people

subscribed to the mailing list, along with their full name. We'll also print

the address's flags (which will currently always be zero), and the address's

delivery status.  A status of RECIPIENT means the address will receive

messages posted to the list.  A status of X means that delivery to this

address is suppressed.  The important point is that all addresses regardless

of status, will be able to post to the mailing list.

    >>> info = mailinglist_api.getMembershipInformation(('team-one',))

    >>> from lp.registry.tests.mailinglists_helper import print_info

    >>> print_info(info)

    team-one

        anne.person@example.com Anne Person             0 RECIPIENT

        aperson@example.org     Anne Person             0 X

        bart.person@example.com Bart Person             0 RECIPIENT

        bperson@example.org     Bart Person             0 X

        cperson@example.org     Cris Person             0 X

        cris.person@example.com Cris Person             0 RECIPIENT

        dirk.person@example.com Dirk Person             0 RECIPIENT

        dperson@example.org     Dirk Person             0 X

        elle.person@example.com Elle Person             0 RECIPIENT

        eperson@example.org     Elle Person             0 X

        fperson@example.org     Fred Person             0 X

        fred.person@example.com Fred Person             0 RECIPIENT

        gperson@example.org     Gwen Person             0 X

        gwen.person@example.com Gwen Person             0 RECIPIENT

        hank.person@example.com Hank Person             0 RECIPIENT

        hperson@example.org     Hank Person             0 X

        no-priv@canonical.com   No Privileges Person    0 X

We can also ask for the membership information for more than one mailing list

at a time.  Mix things up for the fun of it.

    >>> team_two, list_two = new_team('team-two', with_list=True)

    >>> fred.leave(team_one)

    >>> gwen.leave(team_one)

    >>> for person in people:

    ...     if person is bart:

    ...         continue

    ...     person.join(team_two)

    ...     list_two.subscribe(person)

    >>> transaction.commit()

    >>> info = mailinglist_api.getMembershipInformation(

    ...     ('team-one', 'team-two'))

    >>> print_info(info)

    team-one

        anne.person@example.com Anne Person             0 RECIPIENT

        aperson@example.org     Anne Person             0 X

        bart.person@example.com Bart Person             0 RECIPIENT

        bperson@example.org     Bart Person             0 X

        cperson@example.org     Cris Person             0 X

        cris.person@example.com Cris Person             0 RECIPIENT

        dirk.person@example.com Dirk Person             0 RECIPIENT

        dperson@example.org     Dirk Person             0 X

        elle.person@example.com Elle Person             0 RECIPIENT

        eperson@example.org     Elle Person             0 X

        hank.person@example.com Hank Person             0 RECIPIENT

        hperson@example.org     Hank Person             0 X

        no-priv@canonical.com   No Privileges Person    0 X

    team-two

        anne.person@example.com Anne Person             0 RECIPIENT

        aperson@example.org     Anne Person             0 X

        cperson@example.org     Cris Person             0 X

        cris.person@example.com Cris Person             0 RECIPIENT

        dirk.person@example.com Dirk Person             0 RECIPIENT

        dperson@example.org     Dirk Person             0 X

        elle.person@example.com Elle Person             0 RECIPIENT

        eperson@example.org     Elle Person             0 X

        fperson@example.org     Fred Person             0 X

        fred.person@example.com Fred Person             0 RECIPIENT

        gperson@example.org     Gwen Person             0 X

        gwen.person@example.com Gwen Person             0 RECIPIENT

        hank.person@example.com Hank Person             0 RECIPIENT

        hperson@example.org     Hank Person             0 X

        no-priv@canonical.com   No Privileges Person    0 X

Membership tests

----------------

Mailman may also occasionally ask whether a specific email address is

registered with Launchpad.  It does this as a simple line-of-defense against

spam.  Email from addresses not registered with Launchpad are summarily

discarded.

    >>> mailinglist_api.isRegisteredInLaunchpad('dirk.person@example.com')

    True

    >>> mailinglist_api.isRegisteredInLaunchpad('dperson@example.org')

    True

    >>> mailinglist_api.isRegisteredInLaunchpad('geddy.lee@canonical.com')

    False

Similarly, email addresses with an unvalidated status are not considered

registered either.

    >>> from lp.services.identity.interfaces.emailaddress import IEmailAddressSet

    >>> emailset = getUtility(IEmailAddressSet)

    >>> new_address = emailset.new('frederick@example.com', fred)

    >>> new_address.email, new_address.status.title

    (u'frederick@example.com', 'New Email Address')

    >>> sorted((email_address.email, email_address.status.title)

    ...        for email_address in emailset.getByPerson(fred))

    [(u'fperson@example.org', 'Validated Email Address'),

     (u'fred.person@example.com', 'Preferred Email Address'),

     (u'frederick@example.com', 'New Email Address')]

    >>> mailinglist_api.isRegisteredInLaunchpad('frederick@example.com')

    False

Standing tests

--------------

Mailman may also occasionally ask whether a specific email address is a

Launchpad member in good (or better) standing.  It does this when a non-member

of a mailing list tries to post to the mailing list.  By default, an address

not registered in Launchpad is not in good standing (even though the previous

membership test should always take precedence).

    >>> mailinglist_api.inGoodStanding('frederick@example.com')

    False

Since standing makes no sense for teams, an email address assigned to a team

is also not in good standing.

    >>> team_address = list(emailset.getByPerson(team_one))[0]

    >>> mailinglist_api.inGoodStanding(team_address.email)

    False

By default, Launchpad members have an unknown, and thus not good, standing.

    >>> anne.personal_standing

    <DBItem PersonalStanding.UNKNOWN...

    >>> mailinglist_api.inGoodStanding('anne.person@example.com')

    False

Anne is a bad person and the Launchpad administrator assigns her a poor

standing.

    >>> from lp.registry.interfaces.person import PersonalStanding

    >>> anne.personal_standing = PersonalStanding.POOR

    >>> transaction.commit()

    >>> mailinglist_api.inGoodStanding('anne.person@example.com')

    False

Anne makes amends and the Launchpad administrator improves her standing.

    >>> anne.personal_standing = PersonalStanding.GOOD

    >>> transaction.commit()

    >>> mailinglist_api.inGoodStanding('anne.person@example.com')

    True

It turns out that Anne is a wonderful person!  Her standing is really

excellent.

    >>> anne.personal_standing = PersonalStanding.EXCELLENT

    >>> transaction.commit()

    >>> mailinglist_api.inGoodStanding('anne.person@example.com')

    True

The archive address

-------------------

We archive messages by sending them to The Mail Archive

<http://www.mail-archive.com>.  They automatically determine which list a

message is posted to so all we need to do is include them in the recipients

list and the rest is taken care of.

    >>> from lp.services.config import config

    >>> config.mailman.archive_address

    'archive@mail-archive.dev'

Every public team should have this address as an enabled recipient.  There is

no real name for this member.

    >>> list_one.is_public

    True

    >>> list_two.is_public

    True

    >>> info = mailinglist_api.getMembershipInformation(

    ...     ('team-one', 'team-two'))

    >>> print_info(info, full=True)

    team-one

        anne.person@example.com   Anne Person           0 RECIPIENT

        aperson@example.org       Anne Person           0 X

        archive@mail-archive.dev  (n/a)                 0 RECIPIENT

        bart.person@example.com   Bart Person           0 RECIPIENT

        bperson@example.org       Bart Person           0 X

        cperson@example.org       Cris Person           0 X

        cris.person@example.com   Cris Person           0 RECIPIENT

        dirk.person@example.com   Dirk Person           0 RECIPIENT

        dperson@example.org       Dirk Person           0 X

        elle.person@example.com   Elle Person           0 RECIPIENT

        eperson@example.org       Elle Person           0 X

        hank.person@example.com   Hank Person           0 RECIPIENT

        hperson@example.org       Hank Person           0 X

        no-priv@canonical.com     No Privileges Person  0 X

    team-two

        anne.person@example.com   Anne Person           0 RECIPIENT

        aperson@example.org       Anne Person           0 X

        archive@mail-archive.dev  (n/a)                 0 RECIPIENT

        cperson@example.org       Cris Person           0 X

        cris.person@example.com   Cris Person           0 RECIPIENT

        dirk.person@example.com   Dirk Person           0 RECIPIENT

        dperson@example.org       Dirk Person           0 X

        elle.person@example.com   Elle Person           0 RECIPIENT

        eperson@example.org       Elle Person           0 X

        fperson@example.org       Fred Person           0 X

        fred.person@example.com   Fred Person           0 RECIPIENT

        gperson@example.org       Gwen Person           0 X

        gwen.person@example.com   Gwen Person           0 RECIPIENT

        hank.person@example.com   Hank Person           0 RECIPIENT

        hperson@example.org       Hank Person           0 X

        no-priv@canonical.com     No Privileges Person  0 X

However, in order to prevent this address from being used to forge spam onto

the lists, the archive address is hard-coded to not be registered in

Launchpad.

    >>> mailinglist_api.isRegisteredInLaunchpad(

    ...     config.mailman.archive_address)

    False

This is true even if by dumb luck the address actually gets registered in

Launchpad.

    >>> from lp.services.identity.interfaces.emailaddress import EmailAddressStatus

    >>> new_address = emailset.new(

    ...     config.mailman.archive_address, fred,

    ...     EmailAddressStatus.VALIDATED)

    >>> transaction.commit()

    >>> mailinglist_api.isRegisteredInLaunchpad(

    ...     config.mailman.archive_address)

    False

The Mail Archive is only used for public team mailing lists.  If the team

itself is private, so is its archive, and then messages are not sent to the

archiver email address.

    >>> from zope.component import queryAdapter

    >>> from lp.services.privacy.interfaces import IObjectPrivacy

    >>> from lp.registry.interfaces.person import PersonVisibility

    >>> team_three = new_team('team-three')

    >>> queryAdapter(team_three, IObjectPrivacy).is_private

    False

Teams with mailing lists cannot change visibility, so the team must be made

private before its mailing list is created.

    >>> team_three.visibility = PersonVisibility.PRIVATE

    >>> queryAdapter(team_three, IObjectPrivacy).is_private

    True

When Anne subscribes to the team-three mailing list, her validated addresses

are the only recipients in the list's membership information.  Because the

team is private, the special archive@mail-archive.dev address is not

included.

    >>> from lp.registry.tests.mailinglists_helper import (

    ...     new_list_for_team)

    >>> list_three = new_list_for_team(team_three)

    >>> list_three.is_public

    False

    >>> anne.join(team_three)

    >>> list_three.subscribe(anne)

    >>> transaction.commit()

    >>> info = mailinglist_api.getMembershipInformation(

    ...     ('team-one', 'team-two', 'team-three'))

    >>> print_info(info, full=True)

    team-one

        anne.person@example.com   Anne Person           0 RECIPIENT

        aperson@example.org       Anne Person           0 X

        archive@mail-archive.dev  (n/a)                 0 RECIPIENT

        bart.person@example.com   Bart Person           0 RECIPIENT

        bperson@example.org       Bart Person           0 X

        cperson@example.org       Cris Person           0 X

        cris.person@example.com   Cris Person           0 RECIPIENT

        dirk.person@example.com   Dirk Person           0 RECIPIENT

        dperson@example.org       Dirk Person           0 X

        elle.person@example.com   Elle Person           0 RECIPIENT

        eperson@example.org       Elle Person           0 X

        hank.person@example.com   Hank Person           0 RECIPIENT

        hperson@example.org       Hank Person           0 X

        no-priv@canonical.com     No Privileges Person  0 X

    team-three

        anne.person@example.com   Anne Person           0 RECIPIENT

        aperson@example.org       Anne Person           0 X

        no-priv@canonical.com     No Privileges Person  0 X

    team-two

        anne.person@example.com   Anne Person           0 RECIPIENT

        aperson@example.org       Anne Person           0 X

        archive@mail-archive.dev  (n/a)                 0 RECIPIENT

        cperson@example.org       Cris Person           0 X

        cris.person@example.com   Cris Person           0 RECIPIENT

        dirk.person@example.com   Dirk Person           0 RECIPIENT

        dperson@example.org       Dirk Person           0 X

        elle.person@example.com   Elle Person           0 RECIPIENT

        eperson@example.org       Elle Person           0 X

        fperson@example.org       Fred Person           0 X

        fred.person@example.com   Fred Person           0 RECIPIENT

        gperson@example.org       Gwen Person           0 X

        gwen.person@example.com   Gwen Person           0 RECIPIENT

        hank.person@example.com   Hank Person           0 RECIPIENT

        hperson@example.org       Hank Person           0 X

        no-priv@canonical.com     No Privileges Person  0 X

Error cases

-----------

If Mailman requests the membership information for a team that doesn't exist,

the team name will have a value of None in the resulting dictionary.

    >>> mailinglist_api.getMembershipInformation(('no-such-team',))

    {'no-such-team': None}