diff options
| -rw-r--r-- | DESIGN.md | 238 | ||||
| -rw-r--r-- | README.md | 26 | ||||
| -rw-r--r-- | src/leap/mx/alias_resolver.py | 348 | ||||
| -rw-r--r-- | src/leap/mx/couchdb.py | 59 |
4 files changed, 533 insertions, 138 deletions
diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..2d9fe82 --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,238 @@ +# design # + +## overview # +---------------------- +This page pertains to the incoming mail exchange servers of the provider. + +General overview of how incoming email will work: + + 1. Incoming message is received by provider's MX servers. + 2. The MTA (postfix in our case) does a ton of checks on the message before we + even check to see if the recipient is valid (this comes from experience + running the riseup mail infrastructure, where the vast majority of messages + can be rejected early in the SMTP reception and thus save a ton of processing + time on the server). + 3. Postfix then queries the database to check if the recipient is valid, if + they are over quota, if their account is enabled, and to resolve any aliases + for the account. + 4. The message is then delivered to an on-disk message spool. + 5. A daemon watches for new files in this spool. Each message is encrypted to + the user's public key, and stored in the user's incoming message queue (stored + in couchdb), and removed from disk. + 6. When the user next logs in with their client, the user's message queue is + emptied by the client. + 7. Each message is decrypted by the client, and then stored in the user's + "inbox" as an unread message. + 8. This local inbox uses soledad for storage + 9. Soledad, in the background, will then re-encrypt this email (now a soledad + document), and sync to the cloud. + +## postfix pipeline ## +--------------------------- +incoming mx servers will run postfix, configured in a particular way: + + 1. postscreen: before accepting an incoming message, checks RBLs, checks RFC + validity, checks for spam pipelining. + (pass) proceed to next step. + (fail) return SMTP error, which bounces email. + 2. more SMTP checks: valid hostnames, etc. + (pass) accepted, proceed to next step. + (fail) return SMTP error, which bounces email. + 3. check_recipient_access -- look up each recipient and ensure they are + allowed to receive messages. + (pass) empty result, proceed to next step. + (fail) return SMTP error code and error comment, bounce message. + 4. milter processessing (spamassassin & clamav) + (pass) continue + (fail) bounce message, flag as spam, or silently kill. + 5. virtual_alias_maps -- map user defined aliases and forwards + (local address) continue if new address is for this mx + (remote address) continue. normally, postfix would relay to the remote domain, but we don't want that. + 6. deliver message to spool + (write) save the message to disk on the mx. + 7. postfix's job is done, mail_receiver picks up email from spool directory + +Questions: + + * what is the best way to have postfix write a message to a spool directory? + There is a built-in facility for saving to a maildir, so we could just + specify a common maildir for everyone. alternately, we could pipe to a + simple command that was responsible for safely saving the file to disk. a + third possibility would be to have a local long running daemon that spoke + lmtp that postfix forward the message on to for delivery. + * if virtual_alias_maps comes after check_recipient_access, then a user with + aliases set but who is over quota will not be able to forward email. i think + this is fine. + * if we are going to support forwarding, we should ensure that the message + gets encrypted before getting forwarded. so, postfix should not do any + forwarding. instead, this should be the job of mail_receiver. + +Considerations: + + 1. high load should fill queue, not crash pipeline: It is important that the + pipeline be able to handle massive bursts of email, as often happens with + email. This means map lookups need to be very fast, and when there is a high + load of email postfix should not be waiting on the mail receiver but must be + able to pass the message off quickly and have the slower mail receiver churn + through the backlog as best it can. + 2. don't lose messages: It is important to not lose any messages when there is + a problem. So, generally, a copy of an email should always exist in some spool + somewhere, and that copy should not be deleted until there is confirmation + that the next stage has succeeded. + +## alias_resolver ## +------------------------------ +The alias_resolver will be a daemon running on MX servers that handles lookups +in the user database of email aliases, forwards, quota, and account status. + +Communication with: + + 1. postfix:: alias_resolver will be bound to localhost and speak postfix's + very simple [tcp map protocol -> http://www.postfix.org/tcp_table.5.html]. + + 2. couchdb:: alias_resolver will make couchdb queries to a local http load + balancer that connects to a couchdb/bigcouch + cluster. [directly accessing the couch->https://we.riseup.net/leap+platform/querying-the-couchdb] + might help getting started. + +### Discussion: ### + + 1. we want the lookups to be fast. using views in couchdb, these should be + very fast. when using bigcouch, we can make it faster by specifying a read + quorum of 1 (instead of the default 2). this will make it so that only a + single couchdb needs to be queried to find the result. i don't know if this + would cause problems, but aliases don't change very often. + +alias_resolver will be responsible for two map lookups in postfix: + +#### check_recipient #### +------------------------- +postfix config: + +@check_recipient_access tcp:localhost:1000@ + +postfix will send "get username@domain.org" and alias_resolver should return an +empty result ("200 \n", i think) if postfix should deliver email to the +user. otherwise, it should return an error. here is example response, verbatim, +that can be used to bounce over quota users: + +``` +200 DEFER_IF_PERMIT Sorry, your message cannot be delivered because the +recipient's mailbox is full. If you can contact them another way, you may wish +to tell them of this problem. +``` + +"DEFER_IF_PERMIT" will let the other MX know that this error is temporary and +that they should try again soon. Typically, an MX will try repeatedly, at +longer and longer intervals, for four days before giving up. + +#### virtual alias map #### +--------------------------- +postfix config: + +@virtual_alias_map tcp:localhost:1001@ + +postfix will send "get alias-address@domain.org" and alias_resolver should +return "200 id_123456\n", where 123456 is the unique id of the user that has +alias-address@domain.org. + +couchdb should have a view that will let us query on an (alias) address and +return the user id. + +note: if the result of the alias map (e.g. id_123456) does not have a domain +suffix, i think postfix will use the 'default transport'. if we want it to use +the virtual transport instead, we should append the domain (eg +id_123456@example.org). see +http://www.postfix.org/ADDRESS_REWRITING_README.html#resolve + + +### Current status: ### +The current implementation of alias_resolver is in +leap-mx/src/leap/mx/alias_resolver.py. + +The class ```alias_resolver.StatusCodes``` deals with creating SMTP-like +response messages for Postfix, speaking Postfix's TCP Map protocol (from item +#1). + +As for Discussion item #1: + +It might be possible to use +[python-memcached](https://pypi.python.org/pypi/python-memcached/) as an +interface to a [memcached](http://memcached.org/) instance to speed up database +lookups, by keeping an in memory mapping of recent request/response +pairs. Also, Twisted now (I think as of 12.0.0) ships with a protocol for +handling Memcached servers, this is in ```twisted.protocols.memcache```. This +should be prioritised for later, if it is decided that querying the CouchDB is +too expensive or time-consuming. + +Thus far, to speed up alias lookup, an in-memory mapping of alias<->resolution +pairs is created by ```alias_resolver.AliasResolverFactory()```, which can be +optionally seeded with a dictionary of ```{ 'alias': 'resolution' }``` pairs +by doing: +~~~~~~ +>>> from leap.mx import alias_resolver +>>> aliasResolverFactory = alias_resolver.AliasResolverFactory( +... addr='1.2.3.4', port=4242, data={'isis': 'isis@leap.se', +... 'drebs': 'drebs@leap.se'}) +>>> aliasResolver = aliasResolverFactory.buildProtocol() +>>> aliasResolver.check_recipient_access('isis') +200 OK Others might say 'HELLA AWESOME'...but we're not convinced. +~~~~~~ + +TODO: + 1. The AliasResolverFactory needs to be connected to the CouchDB. The + classmethod in which this should occur is ```AliasResolverFactory.get()```. + + 2. I am not sure where to get the user's UUID from (Soledad?). Wherever we get + it from, it will need to be returned in + ```AliasResolver.virtual_alias_map()```, and if we want Postfix to hear about + it, then that response will need to be fed into ```AliasResolver.sendCode```. + + 3. Other than those two things, I think everything is done. The only potential + other thing I can think of is that the codes in + ```alias_resolver.StatusCodes``` might need to be urlencoded for Postfix to + accept them, but this is like two lines of code from urllib. + + + +## mail_receiver ## + +the mail_receiver is a daemon that runs on incoming MX servers and is +responsible for encrypting incoming email to the user's public key and saving +the email to an incoming queue database for that user. + +communicates with: + + * message spool directory:: mail_reciever sits and waits for new email to be + written to the spool directory (maybe using this + https://github.com/seb-m/pyinotify, i think it is better than FAM). when a + new file is dumped into the spool, mail_receiver reads the file, encrypts + the entire thing using the public key of the recipient, and saves to + couchdb. + * couchdb get:: mail_receiver does a query on user id to get back user's + public openpgp key. read quorum of 1 is probably ok. + * couchdb put:: mail_receiver communicates with couchdb for storing encrypted + email for each user (eventually, mail_receiver will communicate with a local + http proxy, that communicates with a bigcouch cluster, but the api is + identical) + +discussion: + * i am not sure if postfix adds a header to indicate to whom a message was + actually delivered. if not, this is a problem, because then how do we know + what db to put it in or what public key to use? this is perhaps a good + reason to not let postfix handle writing the message to disk, but instead + pipe it to another command (because postfix sets env variables for stuff + like recipient). + + * should the incoming message queue be a separate database or should it be + just documents in the user's main database with special flags? + + * whenever possible, we should refer to the user by a fixed id, not their + username, because we want to support the ability to change usernames. so, + for example, database names should not be based on usernames. + +### Current Status: ### +None of this is done, although having it be a separate daemon sound weird. + +You would probably want to use ```twisted.mail.mail.FileMonitoringService``` to +watch the mailbox (is the mailbox virtual or a maildir or mbox or?) @@ -1,22 +1,22 @@ leap_mx ======= **Note:** Currently in development. Feel free to test, and please [report - bugs](mailto:isis@leap.se). + bugs on our tracker](https://we.riseup.net/leap/mx) or [by email](mailto:isis@leap.se). An asynchronous, transparently-encrypting remailer for the LEAP platform, using BigCouch/CouchDB and PGP/GnuPG, written in Twisted Python. ## [install](#install) ## -========================= -[tl;dr](#tl;dr) ### [virtualenv](#virtualenv) ### ================================= +Impatient? Don't like virtualenvs? [tl;dr](#tl;dr) + Virtualenv is somewhat equivalent to fakeroot for python packages, and -- due to being packaged with copies of pip and python -- can be used to bootstrap its own install process, allowing pip and python to be used with sudo. -#### [installing without sudo] #### +#### installing without sudo #### To install without using sudo, a bootstrap script to handle the setup process is provided. It does the following: @@ -38,7 +38,7 @@ $ ./bootstrap $ workon leap_mx ~~~ -#### [installing in a regular virtualenv] ### +#### installing in a regular virtualenv ### To install python, virtualenv, and get started, do: ~~~ @@ -62,8 +62,20 @@ Although, **it is advised** to install inside a python virtualenv. ## [running](#running) ## ========================= -To get running, clone this repo, and (assuming you've already set up your virtualenv and obtained all the requirements) do: +To get running, clone this repo, and (assuming you've already set up your +virtualenv and obtained all the requirements) do: ~~~ $ ./start_mx.py --help -~~~
\ No newline at end of file +~~~ + +## [hacking](#hacking) ## +========================= +Please see the HACKING and DESIGN docs. + +Our bugtracker is [here](https://leap.se/code/projects/eip_server/issue/new). + +Please use that for bug reports and feature requests instead of github's +tracker. We're using github for code commenting and review between +collaborators. + diff --git a/src/leap/mx/alias_resolver.py b/src/leap/mx/alias_resolver.py index e079b80..f71c4d8 100644 --- a/src/leap/mx/alias_resolver.py +++ b/src/leap/mx/alias_resolver.py @@ -5,22 +5,15 @@ alias_resolver.py ================= Classes for resolving postfix aliases. -@authors: Isis Agora Lovecruft -@version: 0.0.1-beta -@license: see included LICENSE file -@copyright: copyright 2013 Isis Agora Lovecruft +:authors: Isis Agora Lovecruft +:version: 0.0.1-beta +:license: see included LICENSE file +:copyright: (c) 2013 Isis Agora Lovecruft TODO: o Look into using twisted.protocols.postfix.policies classes for controlling concurrent connections and throttling resource consumption. - - o alias.ProcessAlias() - -## have uuid -> get gpg keyid - -alias.ProcessAlias('/path/to/mail_reciever', *args) - ''' import os @@ -34,73 +27,145 @@ except ImportError: print "This software requires Twisted. Please see the README file" print "for instructions on getting required dependencies." +from leap.mx import couchdb from leap.mx.util import net, log, config, exceptions def createUUID(alias): - """ - Creates Universal Unique ID by taking the SHA-1 HASH of an email alias: + """Creates Universal Unique ID by taking the SHA1 HASH of an email alias: + + >>> uuid.uuid5(uuid.NAMESPACE_URL, "isis@leap.se") + UUID('7194878e-4aea-563f-85a4-4f58519f3c4f') - >>> uuid.uuid5(uuid.NAMESPACE_URL, "isis@leap.se") - UUID('7194878e-4aea-563f-85a4-4f58519f3c4f') + TODO: Is there a commonly accepted way to check that an email address + is valid? - @param alias: An email address alias. - @returns: A :class:`uuid.UUID` containing attributes specifying the UUID. + :param str alias: An email address alias. + :returns: A :class:`uuid.UUID` containing attributes specifying the UUID. """ return uuid.uuid5(uuid.NAMESPACE_URL, str(alias)) + +class DatabaseNotConnected(Exception): + """Raised when not currently connected to a database.""" + class StatusCodes(object): - """ - The Postfix manual states: + """The Postfix manual states: + + The request completion status is one of OK, RETRY, NOKEY (lookup failed + because the key was not found), BAD (malformed request) or DENY (the + table is not approved for proxy read or update access). + + In brief, Postfix will send ``get SPACE key NEWLINE``, or + ``put SPACE key NEWLINE`` where ``key`` is an alias or email address. + It expects non-printable ascii characters to be url-encoded, i.e. a + get-request would look like: + + ``get%20isis@leap.se%0A`` + + and in response, Postfix expects an SMTP-like status code and a string + describing the nature of or reason for the response, no longer than + 4096 "characters" (which, due to UTF-8 ubiquity, we'll err on the safe + side and assume that means 4096 bytes.) + + From the Postfix manual on its TCP map protocol + (http://www.postfix.org/tcp_table.5.html): + + 500 SPACE text NEWLINE + In case of a lookup request, the requested data + does not exist. In case of an update request, the + request was rejected. The text describes the + nature of the problem. + + 400 SPACE text NEWLINE + This indicates an error condition. The text + describes the nature of the problem. The client + should retry the request later. - The request completion status is one of OK, RETRY, NOKEY (lookup - failed because the key was not found), BAD (malformed request) or DENY - (the table is not approved for proxy read or update access). + 200 SPACE text NEWLINE + The request was successful. In the case of a lookup + request, the text contains an encoded version of + the requested data. Other SMTP codes: http://www.greenend.org.uk/rjk/tech/smtpreplies.html + + >>> statcodes = StatusCodes() + >>> if <query local user database for email address>: + >>> response_message = statcodes(200) + >>> aliasresolver.tellMTA() """ + OK = "OK Others might say 'HELLA AWESOME'...but we're not convinced." RETRY = "RETRY Server is busy plotting revolution; requests might take a while." BAD = "BAD bad Leroy Brown, baddest man in the whole...er. Malformed request." NOKEY = "NOKEY Couldn't find your keys, sorry. Did you check in the sofa?" DEFER = "DEFER_IF_LOCAL xxx fill me in" DENY = "DENY no gurlz aloud in teh tree house." - FAIL = "FAIL xxx fill me in" - - fakeSMTPCodes = { '250': OK, - '300': RETRY, - '500': BAD, - '550': NOKEY, - '552': DEFER, - '553': DENY, - '554': FAIL, } + FAIL = "FAIL this belongs on the failblog" + + SMTPCodes = { '200': OK, + '400': RETRY, + '500': BAD, + '550': NOKEY, + '552': DEFER, + '553': DENY, + '554': FAIL, } + + SMTPStrings = { 'OK' 200, + 'RETRY': 400, + 'BAD': 500, + 'NOKEY': 550, + 'DEFER': 552, + 'DENY': 553, + 'FAIL': 554, } def __init__(self, status_code=None): - """xxx fill me in""" + """Construct an SMTP status code generator. + + :type status_code: str or int + :param status_code: (optional) see :func:`StatusCode.get`. + """ if status_code: self.get(status_code) def get(self, status_code=None) - """xxx fill me in""" + """Takes an SMTP-like status code and returns an SMTP-like message. + + :type status_code: str or int + :param status_code: The string or integer for the response we want + to give back to the MTA, after looking up an + email address in the local user database. + Can be one of: + * ``OK`` or ``200`` + * ``RETRY`` or ``400`` + * ``BAD`` or ``500`` + * ``NOKEY`` or ``550`` + * ``DEFER`` or ``552`` + * ``DENY`` or ``553`` + * ``FAIL`` or ``554`` + """ if status_code: if isinstance(status_code, str): - return status_code, getattr(self, status_code.upper(), None) + if status_code.upper() in self.SMTPStrings.keys(): + return self.SMTPStrings[status_code], getattr( + self, status_code.upper(), '') + else: + return 500, self.FAIL elif isinstance(status_code, int): - for k, v in self.fake_smtp_codes.items(): - ## we want to return None if it's 550 - if k == str(status_code) and k != '550': + for k, v in self.SMTPCodes.items(): + ## we want to return None if it's 500 + if k == str(status_code) and k != '500': return status_code, v log.debug("%s" % self.NOKEY) return None, '' class AliasResolver(postfix.PostfixTCPMapServer): - """ - Resolve postfix aliases, similarly to using "$ postmap -q <alias>". + """Resolve postfix aliases, similarly to using "$ postmap -q <alias>". This class starts a simple LineReceiver server which listens for a string - specifying an alias to look up, :param:`key`, and which will be used to - query the local Postfix server. You can test it with: + specifying an alias ``key`` to look up, which will be used to query the + local user database. You can test it with: $ ./alias_resolver.py & $ /usr/bin/postmap -q <key> tcp:localhost:1347 @@ -109,15 +174,36 @@ class AliasResolver(postfix.PostfixTCPMapServer): http://www.postfix.org/proxymap.8.html https://www.iana.org/assignments/smtp-enhanced-status-codes/ """ + + virtual_transport = '@example.com' + use_virtual_transport = False + def __init__(self, *args, **kwargs): - """Create a server which listens for Postfix aliases to resolve.""" + """Create a server which listens for Postfix aliases to resolve. + + :param int timeout: Number of seconds to wait for a response. + :param str delimiter: The delimiter to use for the EOL on responses. + (Default: '\n') + """ super(postfix.PostfixTCPMapServer, self).__init__(*args, **kwargs) self.status_codes = StatusCodes() def sendCode(self, code, message=None): - """Send an SMTP-like code with a message.""" - if not message: - message = self.status_codes.get(code) + """Send an SMTP-like code with a message. + + :type code: str or int + :param code: The status code to send, see + ``alias_resolver.StatusCodes``. + """ + try: + assert isinstance(code, int), "status code must be type int" + except AssertionError as ae: + log.err(ae.message) + self.sendLine('500 internal server error: %s' % ae.message) + + msg = self.status_codes.get(code) + if message is not None and isinstance(message, str): + msg += (" " + message) self.sendLine('%3.3d %s' % (code, message or '')) def do_get(self, key): @@ -132,7 +218,11 @@ class AliasResolver(postfix.PostfixTCPMapServer): @defer.inlineCallbacks def do_put(self, keyAndValue): - """Add a key and value to the database, provided it does not exist.""" + """Add a key and value to the database, provided it does not exist. + + :param str keyAndValue: An alias and email address, separated by a + space, i.e. ``"isis isis@leap.se"``. + """ if keyAndValue is None: self.sendCode(500) log.warn("Command 'put' takes two parameters.") @@ -153,20 +243,26 @@ class AliasResolver(postfix.PostfixTCPMapServer): @defer.inlineCallbacks def do_delete(self, key): - """ - Delete an alias from the mapping database. + """Delete an alias from the CouchDB. - xxx not sure if this is a good idea... + xxx I'm not sure if implementing this would be a good idea... + + :param str key: An email address to delete from the CouchDB. """ raise NotImplemented def check_recipient_access(self, key): - """Make a query to resolve an alias.""" - self.do_get(self, key) + """Make a query to the CouchDB to resolve an alias. - def virtual_alias_map(self, key): + If the ``key`` is an email address which the CouchDB has information + for that account, we should respond to Postfix with an '200%20\n". + + :param str key: An email address to look up in the CouchDB. """ - Get the Universal Unique ID for the alias address. If + return self.do_get(key) + + def virtual_alias_map(self, key): + """Get the Universal Unique ID for the alias address. If virtual_transport is True, then suffix the UUID with a domain. xxx I don't think we actually need couchdb for this, the UUID is an @@ -175,62 +271,83 @@ class AliasResolver(postfix.PostfixTCPMapServer): querying a database, I would presume), it seems silly to do this. Instead, we should query CouchDB with the UUID to get the GPG keyid. + + xxx Or are we supposed to query Soledad for this? + + :param str key: An email address to look up in the CouchDB. + :returns: The UUID of the user. """ ## xxx need email address parser - client_id = createUUID(key) + userid = createUUID(key) - if self.virtual_transport: - return client.get_urn() + '@example.com' - else: - return client.get_urn() - - def _cbGot(self, value): - """Callback for self.get()""" - if value is None: - self.sendCode(550) + if self.use_virtual_transport \ + and isinstance(self.virtual_transport, str): + return userid.get_urn() + self.virtual_transport else: - self.sendCode(250, quote(value)) - - def _cbNot(self, fail): - """Errback for self.get()""" - self.sendCode(554, fail.getErrorMessage()) - - def _cbPut(self, value): - """xxx fill me in""" - pass - - def _cbPout(self, fail): - """xxx fill me in""" - pass + return userid.get_urn() class AliasResolverFactory(postfix.PostfixTCPMapDeferringDictServerFactory): - """ - A Factory for creating :class:`AliasResolver` servers, which handles inputs - and outputs, and keeps an in-memory mapping of Postfix aliases in the form - of a dictionary. - - xxx fill me in + """A Factory for creating :class:`AliasResolver` servers, which handles + inputs and outputs, and keeps an in-memory mapping of Postfix aliases in + the form of a dictionary. + + >>> from leap.mx import alias_resolver + >>> aliasResolverFactory = alias_resolver.AliasResolver( + ... data={'isis': 'isis@leap.se', + ... 'drebs': 'drebs@leap.se', + ... 'elijah': 'elijah@leap.se',}) + >>> aliasResolver = aliasResolverFactory.buildProtocol() + >>> aliasResolver.check_recipient_access('isis') """ protocol = AliasResolver - - def __init__(self, addr='127.0.0.1', port=4242, timeout=120, data=None): - """ - Create a Factory which returns :class:`AliasResolver` servers. - - @param addr: A string giving the IP address of this server. - Default: '127.0.0.1' - @param port: An integer that specifies the port number to listen - on. Default: 4242 - @param timeout: An integer specifying the number of seconds to wait - until we should time out. Default: 120 - @param data: A dict to use to initialise or update the alias mapping. + database = couchdb.ConnectedCouchDB + + def __init__(self, addr='127.0.0.1', port=4242, timeout=120, + data=None, virtual_transport=None, use_virtual_transport=False, + couch_host=None, couch_port=None, couch_dbname='users', + couch_username=None, couch_password=None): + """Create a Factory which returns :class:`AliasResolver` servers. + + :param str addr: A string giving the IP address of this server, for + talking to postfix. Default: '127.0.0.1' + :param int port: An integer that specifies the port number that this + server should listen and respond on, for talking to + Postfix. on. Default: 4242 + :param int timeout: An integer specifying the number of seconds to wait + until we should time out. Default: 120 + :param dict data: A dict to use to initialise or update the alias + mapping. + :param str virtual_transport: The domain portion of an email address + to suffix the UUID responses of + ``AliasResolver.virtual_alias_map`` with. + :param bool use_virtual_transport: If True, suffix UUIDs with the + ``virtual_transport`` string. + + :param str couch_host: The IP address of the CouchDB server to query. + :param int couch_port: The port of the CouchDB server to query. + :param str couch_dbname: The database in the CouchDB to bind to. + :param str couch_username: The username for authenticating to the + CouchDB. + :param str couch_password: The password for authentication. """ super(postfix.PostfixTCPMapDeferringDictServerFactory, self).__init__(data=data) self.timeout = timeout + self.virtual_transport = virtual_transport + self.use_virtual_transport = use_virtual_transport self.noisy = True if config.advanced.noisy else False + if couch_port is None: + couch_port = 5984 + if couch_dbname is None: + couch_dbname = 'users' + self.database_connected = False + if couch_host is not None: + self.couch = self.connectDatabase(couch_host, couch_port, + couch_dbname, couch_username, + couch_password) + try: assert isinstance(port, int), "Port number must be an integer" assert isinstance(timeout, int), "Timeout must be an integer" @@ -249,25 +366,44 @@ class AliasResolverFactory(postfix.PostfixTCPMapDeferringDictServerFactory): % (addr, port)) def buildProtocol(self): - """ - Create an instance of the :class:`AliasResolver` server. - """ + """Create an instance of the :class:`AliasResolver` server.""" proto = self.protocol() proto.timeout = self.timeout + proto.virtual_transport = self.virtual_transport + proto.use_virtual_transport = self.use_virtual_transport proto.factory = self return proto - def get(self, *args, **kwargs): - """ - xxx connect me to the couchdb - """ - pass + def _cb_connectDatabase(self): + self.database_connected = True - def put(self, *args, **kwargs): - """ - xxx connect me to the couchdb + def connectDatabase(self, couch_host, couch_port=None, couch_dbname=None, + couch_username=None, couch_password=None): + """Connect to the CouchDB instance.""" + if not self.database_connected: + d = self.database(couch_host, couch_port, dbName=couch_dbname, + username=couch_username, password=couch_password) + d.addCallback(self._cb_connectDatabase) + d.addErrback(log.err) + return d + else: + return self.couch ## xxx are we sure we only want one connection? + + def get(self, key, **kwargs): + """Query the CouchDB for a user's info. + + :param str key: The alias to look up. Should be either an email address + or a username. (xxx do we want to also support lookups + by UUID?) """ - pass + if self.database_connected: + return self.couch.queryByEmailOrAlias(key) + else: + raise DatabaseNotConnected("Must be connected to a database.") + + def put(self, key, **kwargs): + """Add an alias to the CouchDB database.""" + raise NotImplemented if __name__ == "__main__": diff --git a/src/leap/mx/couchdb.py b/src/leap/mx/couchdb.py index b5d4127..04cfc4d 100644 --- a/src/leap/mx/couchdb.py +++ b/src/leap/mx/couchdb.py @@ -26,44 +26,49 @@ from leap.mx.util import log class ConnectedCouchDB(client.CouchDB): - """ - Connect to a CouchDB instance. + """Connect to a CouchDB instance. - ## xxx will we need to open CouchDB documents and views? - ## yes, these are in a _design document + CouchDB document for testing is '_design', and the view is simply + a preconfigured set of mapped responses. """ - def __init__(self, host, port, dbName=None, username=None, + def __init__(self, host, port=5984, dbName=None, username=None, password=None, *args, **kwargs): """ Connect to a CouchDB instance. - @param host: A hostname string for the CouchDB server. - @param port: The port of the CouchDB server, as an integer. - @param dbName: (optional) The default database to connect to. - @param username: (optional) The username for authorization. - @param password: (optional) The password for authorization. - @returns: A :class:`twisted.internet.defer.Deferred` representing the + :param str host: A hostname string for the CouchDB server. + :param int port: The port of the CouchDB server. + :param str dbName: (optional) The default database to bind queries to. + :param str username: (optional) The username for authorization. + :param str password: (optional) The password for authorization. + :returns: A :class:`twisted.internet.defer.Deferred` representing the the client connection to the CouchDB instance. """ - super(client.CouchDB, self).__init__(host, port, + super(client.CouchDB, self).__init__(host, + port=port, dbName=dbName, username=username, password=password, *args, **kwargs) - if dbName: - self.bindToDB(dbName) - else: + if dbName is None: databases = self.listDB() log.msg("Available databases: %s" % databases) + def createDB(self, dbName): + """Overrides ``paisley.client.CouchDB.createDB``.""" + pass + + def deleteDB(self, dbName): + """Overrides ``paisley.client.CouchDB.deleteDB``.""" + pass + def queryByEmailOrAlias(self, alias, dbDoc="User", view="by_email_or_alias"): - """ - Check to see if a particular email or alias exists. + """Check to see if a particular email or alias exists. - @param alias: A string representing the email or alias to check. - @param dbDoc: The CouchDB document to open. - @param view: The view of the CouchDB document to use. + :param str alias: A string representing the email or alias to check. + :param str dbDoc: The CouchDB document to open. + :param str view: The view of the CouchDB document to use. """ assert isinstance(alias, str), "Email or alias queries must be string" @@ -84,8 +89,10 @@ class ConnectedCouchDB(client.CouchDB): return d def query(self, uri): - """ - Query a CouchDB instance that we are connected to. + """Query a CouchDB instance that we are connected to. + + :param str uri: A particular URI in the CouchDB, i.e. + "/users/_design/User/_view/by_email_or_alias". """ try: self.checkURI(uri) ## xxx write checkURI() @@ -102,12 +109,14 @@ class ConnectedCouchDB(client.CouchDB): @defer.inlineCallbacks def listUsersAndEmails(self, limit=1000, reverse=False): - """ - List all users and email addresses, up to the given limit. + """List all users and email addresses, up to the given limit. + + :param int limit: The number of results to limit the response to. + :param bool reverse: Start at the end of the database mapping. """ query = "/users/_design/User/_view/by_email_or_alias/?reduce=false" answer = yield self.query(query, limit=limit, reverse=reverse) - + if answer: parsed = yield self.parseResult(answer) if parsed: |