Readme

• Free Your Email is an perl OO "event driven" daemon. It periodically checks all your "clients" (mail, weather, etc...) for new email and delivers them via a POP3 daemon. It also includes an SMTP daemon to send mail back out those same services.
  Note: the most common "events" are socket reads, socket writes, and timeouts.
• For our purposes, daemons are modules that listen for incoming connections. Currently there are three daemons: POP3, SMTP, and HTTP. And clients are information "gatherers" and "providers". Currently there are three clients: GroupWise, Yahoo!Mail, and Yahoo!Weather. Hopefully there are many more clients to come, but I suspect that the number of useful daemons has been reached.
• It does not contain linear code. E.g. wait for POP3 login, download emails, report emails back to POP3 client, process various POP3 commands, and logout POP3 user. This is for two reasons:
  • I want emails available for an email checker (xfaces, xbiff, etc...)
  • I do not want to tie up the daemon for long periods of time
  To achieve the second goal, no one service is read or written to more than three times in a row. That way Free Your Email can serve all clients/daemons in a "responsive" manner. Once all services have a chance to read and write, any left over "ready" connections are given another slice.
• Because retrieved emails are not guaranteed to be read via the POP3 deamon, Free Your Email must be very stable, robust, and able to recover from any state it encounters (socket failures, disconnects, etc...). And in the case of a fatal error or shutdown, any unread/unsaved data must be persisted to the next instance (most likely via "dead.letter"). For the same reason, emails are not deleted from the host. GroupWise already offers an expire feature and so this is not a problem. Yahoo!Mail, however, does not offer an expire feature. Thus, the Yahoo!Mail has an expire feature in the works (it is fully "fleshed-out", I just need the guts to turn it on).
• To achive a "stable" rating, I would like to see all perl 'die' commands properly handled and removed. Right now there are several left so that I can detect "real life" error situations and correct/handle them. If a fatal condition is detected, it might be nice to at least try and mark any unread emails as unread on the server (depends on internet connection status); but realistically "dead.letter" is the primary option.
• I have been using this code base for a while and it works for me ... but further testing/feedback is required. I have had one session up for five or six days, which includes spanning a weekend. Free Your Email has a "black out" period (usually nights and weekends) where I don't want it checking emails (because I primarily run it at work). And it has always recovered from expired logins via re-login nicely. But I need a lot more data and testers before I would even consider labeling it even slightly stable.
• Free Your Email does not download attachments. I decided this early on because it would mean many more "clicks" on URLs and would make for extra regular expressions. Also, I may or may not have a decent GNU/Linux viewer for the attachments. As it is, if I care to view attachments (the presence of which is noted in the email) I switch to either a browser client or my WIN32 GroupWise client. In the future, attachments may become available via a parameter to each email client.
• Free Your Email does not send GroupWise email via a GroupWise gateway. This is because GroupWise uses some strange "DOMAIN.PO.USER" addressing (even though its address book displays a "USER.PO.DOMAIN" address ... ugghhhh). My company has several "PO"s and several standards applied to "USER"s. So many combinations are possible and an extra "translation" would be necessary. I wouldn't fathom tackling this and it would have definitely been a nightmare to support/release. Even if the address could be translated, my gateway does not provide for delivery of outside email. Instead, sticking with the HTML interface seemed easy/natural and works very well. Note: if you want to tackle this and your solution is "elegant", go ahead! But your time maybe better spent on adding attachment support to the web client.
• Free Your Email does not have any hardcodes URLs or pathnames. This is because any of the email webservers may change their underlying CGI structure without any notice to its users. Instead I prefer to use regular expressions to "read" the page in much the same way as a real person would. This should keep us running despite minor changes. Of course, any major UI overhaul would likely break our ability to "read" the website and halt downloads and/or sends to it (this is covered in the TODO list).
• Each client is dynamically loaded, so if a particular client is not used, then it is never loaded. This keeps the memory footprint to a minimum and (if the client perl module is deleted) the disk usage to a minimum. I.e. if a user doesn't want it they can delete it. If they want it back, install/download it again; it's as easy as that.
• Why perl? Because it is platform independent, widely available, the language of choice for most of the internet, works with the widest range of browsers, and is an excellent text/HTML parser.
• Why not other similar SF projects? Most of them were tied to just one email service (e.g. Hotmail, Yahoo!Mail, etc...). Were tied to just email, no weather, stock quotes, or other information sources. Provided only POP3 or only SMTP services, but not both. Where written in Java, which doesn't work with all browsers; or C++, which makes it harder for users to install and slows development (aka. not RAD enough).
• Did you copy these other projects? As most SF projects are GPL, I could have; but I did not. I had too much of a code base to copy their source and they would not have fit Free Your Email's design. Besides that, it would have taken more time to digest, extract, and recode other project's expressions than it would have to create the proper regular expressions to extract the correct URLs needed to retrieve/send emails. Thus, Free Your Email is 100% new and lives (or dies) on its own.
• Do you accept donations? Not right now. I just hope this gets used and people like it. It would have to become stable and widely used before I would ever consider accepting a dime. It WILL always be free, it WILL always be open for improvements, it WILL always be open source (OSI and GPL included). It will NEVER be commercial or "payware".
• Can GroupWise or Yahoo! sue you/block you? I am no lawyer, so your answer is "?". There are a lot of similar projects and I would guess they would have to open a "class action" suit against me (Free Your Email) and all similar projects. As for blocking, yes. GroupWise or Yahoo! is free to change/modify/eliminate any of their services and served HTML. But I intend to collect all regular expressions and put them in one place to make updates easy. I may even supply a link that would automatically download the "latest and greatest" set of expressions (see the TODO list).
• Email usernames and email passwords are stored for each user in a ~username/.appauth file. E.g.

  • 
    GROUPWISE_ID='joe'
    GROUPWISE_PASSWORD='joe-is-cool'
    
    YAHOO_ID='shmoe'
    YAHOO_PASSWORD='joe-is-not-cool'
    
    ## OR:
    
    YAHOO_ACCT1_ID='jane'
    YAHOO_ACCT1_PASSWORD='jane-has-2-yahoo-accounts'
    
    YAHOO_ACCT2_ID='plain'
    YAHOO_ACCT2_PASSWORD='jane-isnt-cool-either'
    
    ## And maybe (see TODO) for authentication:
    
    POP3_ID='janes-pop3-name'
    POP3_PASSWORD='wall-flower'
    		

    Where: ACCT1 and ACCT2 can be anything unique to tell the accounts apart. ACCT1 could have been JANE and ACCT2 could have been PLAIN.
    Note: this file format was chosen because it can also be "sourced" into and used via scripts (sh, bash, ksh, etc...). That makes it reusable which is a good thing.
  • Note: POP3 uses localuser and /etc/passwd for authentication (not a good idea). Using the user's ~localuser/.appauth would steer clear of "clear texting" a login password. But there are bigger fish to fry right now and POP3 only listens to 'localhost' right now so "clear texting" is not on the BIG radar scope. Possibly do this:

    
    POP3_ID='joe'
    POP3_PASSWORD='joes-mozilla-email-client-password'
    
    ## Or:
    
    POP3_ID='joe'
    POP3_PASSWORD='crypt("joes-mozilla-email-client-password")'
    			

    Where: crypt("joes-mozilla-email-client-password") is replaced with what "crypt(3)" provides. This would at least keep freeyouremail from ever having to know the user's REAL password.
• 'perl' standards :
  • String variables are prefixed with "str". E.g. my $strUsername;.
  • Numeric variables are prefixed with "n". E.g. my $nCnt;.
  • Array variables are prefixed with "a". E.g. my @aEmailList;.
  • Associative array variables (aka. hashes) are prefixed with "aa". E.g. my %aaServerOptions;.
  • Variable references add "ref" to the prefix. E.g. my $arefEmailList; and my $aarefServerOptions;.
  • Use the word "FIXME" in comments where additional work is needed. E.g.
    
    • ## FIXME: 'die' when this happens ... but clean up before release.
  • In comments, put single quotes (') around perl builtin and project funtions and keywords. E.g.
    
    • ## I am going to 'flock' this file handle to keep it "safe" from updates.
    • ## Check if 'isOkToCheckWeather' to see if enough time has elapsed.
  • No one operation can last for more than one second.
    
    • I.e. don't go into a 'sleep' loop waiting for an event. Better, set a status (e.g. '$nWritePhase' or '$nReadPhase') and return.
    • Errata: 'flock'ing files is a good thing and can possibly take more than a second. However, don't leave a file locked (e.g. dead.letter) and return. If two different clients try and 'flock' dead.letter and leave it 'flock'ed, it might cause a deadlock situation.
• If you would like to contribute to the project, a good place to start is to grep for FIXME, NOTE, and 'die' ... and then start fixing.
• As a CVS user, I don't know why SF.NET decided to go with a totally seperate documentation engine. If you would like to submit HTML homepage changes, feel FREE! Just update the HTML and check it in just like any other project file. I will "consider" it and move it to the freeyouremail SF.NET website. Just MAKE SURE that it still works with W3.ORG validators (or else the link below is false advertising). If you don't, your documentation will likely be deleted.