-----------------------
Lab #04 for CST8165 due November 15, 2006 (* DUE DATE UPDATED YET AGAIN *)
-----------------------
-Ian! D. Allen - idallen@idallen.ca

| I was very late in finishing marking for Lab 3; so, as I announced
| in the lab yesterday, I'm extending the due date to make feedback
| corrections for Lab 4 to November 15.

Remember - knowing how to find out an answer is more important than
memorizing the answer.  Learn to fish!  RTFM!  (Read The Fine Manual)

Global weight: 5% of your total mark this term.
Due date: At the start of your lab period on Wednesday November 15.

Interim submissions: Wednesday October 18 and 25, November 1
  You will submit whatever progress you have made on this assignment
  before midnight on Wednesday October 18, October 25, and November 1.
  (That is three interim submissions.)

The on-line deliverables for this exercise are to be submitted on-line in
the Linux Lab T127 using the "cstsubmit" method described in the exercise
description, below.  No paper; no email; no FTP.

Late-submission date: I will accept without penalty exercises that are
submitted late but before 10h00 (10am) Thursday November 16, 2006.
After that late-submission date, the exercise is worth zero marks.

Interim work must be submitted by midnight on October 18, 25, and Nov 1.

Exercises submitted by the *due date* will be marked on-line and your
marks will be sent to you by email after the late-submission date.

Code submitted without your added useful comments (no matter what its
source) will not be marked.

Exercise Synopsis:

    Code a "raw" SMTP client that sends a text message.
    Document it as you write it.
    Test it.

Where to work:
    Submissions must run cleanly in the T127 Linux Lab, though you are
    free to develop and work on them anywhere you like.

    If you develop elsewhere, make sure the code works on the Linux Lab
    machines as well; that's where I test it!

    Code submitted without your added useful comments (no matter what
    its source) will not be marked.

Resources
---------

    On most systems (except the Linux Lab) "man Net::Telnet" gives you
    a man page on using the Net::Telnet Perl module.  I've placed the
    missing man page in the notes under perl_net_telnet.txt

    Built-in Perl functions are explained in "man perlfunc".  In the man
    page pager ("less"), you can search the man page for a function,
    e.g. in "man perlfunc" try typing:   /^ *join

    Suggested module to use for Perl:

       "man Net::Telnet" (may not work in Linux Lab)
       http://teaching.idallen.com/cst8165/06f/notes/perl_net_telnet.txt
       http://search.cpan.org/search?module=Net::Telnet

    Documentation on the SMTP protocol is in RFC 2821:

       RFC:  http://tools.ietf.org/html/rfc2821
       RFC:  http://www.faqs.org/rfcs/rfc2821.html
       RFC:  ftp://ftp.rfc-editor.org/in-notes/rfc2821.txt
       Sample SMTP session: week05notes.txt
       Sample SMTP session: http://helpdesk.islandnet.com/pep/smtp.php

    Suggested template from which to start coding:

       A working template smtpclient_v1.pl is available in the course notes.
       Remove all the "Perl:" comments and related code from this example.

Code Quality and Portability
----------------------------

A.  You must include useful comment blocks ahead of the code you write or
    modify.  Code submitted without your added useful comments will not
    be marked.

B.  Marks are awarded for readability and elegance, not just correctness.  
    If your code can't be read, you're useless in a team project.

Coding the client
-----------------

1)  This perl client must be named "smtpclient.pl".   Spelling counts.

2)  A template smtpclient_v1.pl is available in the course notes.
    Remove all the "Perl:" comments and related code from this example.

3)  The perl client must handle the following command line arguments: 

       -to email
       -from email
       -smtpserver hostname 
       -port portnum

    The Perl script will be run as follows (all arguments are mandatory
    and must appear in exactly this order; spelling counts):

       $ ./smtpclient.pl  -to user@domain.com  -from sender@domain.com \
          -smtpserver mail.domain.com  -port 25

    It is imperative that it runs exactly as described above (command line
    options etc) as I am using a script to test this.  Spelling counts.
    
4)  The client will connect to the given SMTP server on the given port
    and send a text message (read from STDIN) to the given address.

5)  Email userid syntax should be gently validated as best you can.
    (Must contain exactly one '@'; must have a '.' somewhere after the
    '@', no blanks, unprintables, or non-ASCII characters in the domain,
    etc.)  The allowed domain characters are given in the RFC Section
    4.1.2.  Do try to catch obvious errors; don't go overboard on this!

6)  Also gently validate the syntax of the smtp server argument.
    Make sure the port argument is alphanumeric (no funny chars).
    (Consider making the port all lower-case, since upper-case names
    may not match /etc/services names.)

7)  After each client command line sent to the SMTP server, your
    client must verify that the command was accepted by the server.
    Check the SMTP response code.  RFC 2821 Section 4.3.2 lists the
    possible responses to each client message.  (Note that there are
    also three codes that may be returned after *any* SMTP command, in
    "unusual circumstances".)

    On a temporary or permanent error, print the SMTP response line
    and exit the program with an appropriate exit value chosen from
    the numbers in <sysexits.h>, e.g. exit($EX_USAGE) if the SMTP
    error indicates bad syntax.  (You will need to define $EX_USAGE.)
    Match the error code to the type of SMTP error.  All temporary errors
    (and only temporary errors) should return $EX_TEMPFAIL.

8)  If the SMTP server limits the size of messages, extract and save
    this limit for later use.

9)  The message text to send will come from standard input.  (You may
    use shell input redirection, or type it at the keyboard.)
    A sample Perl program that reads standard input is in the notes.

10) You do not have to verify the semantic content of the message read
    from standard input.  Your program will accept anything and pass it
    to the SMTP server.  You must follow (1) the period escaping rules
    given in RFC Section 4.5.2, (2) the length limits given for text
    lines in section 4.5.3.1, and (3) any message maximum SIZE limit
    given in response to EHLO.
    
    If you detect a line too long for the SMTP limit, print a good error
    message to the user; but, let the line pass.  When you detect that you
    cannot send another line of data to the SMTP server because you have
    reached the overall message size limit, print a good error message
    to the user and discard the rest of the message that is oversize.
    Send the partial message.

11) If you find yourself duplicating code, re-factor your source and
    create a function to handle the duplicate code in one place.

    Code submitted without your added useful comments (no matter what
    its source) will not be marked.

Test Plan
---------

12) The object of a Test Plan is to prove to the reader that your code
    works under all possible combinations of inputs (or at least as many
    as you can reasonably test).

    Develop a written Test Plan "README.txt" for your client and do it.
    Partial test plans are work partial marks.

13) To test SMTP responses, you can "fake" a whole set of responses from
    an SMTP server by putting the lines you want the fake server to send
    in a text file and using "nc" as the server:

       $ nc -v -l localhost 55555 <file       # Red Hat systems
       $ nc -v -l -p 55555 localhost <file    # Debian systems

    If you start the above fake SMTP server and then connect your SMTP
    client to port 55555, it will read lines from the given file used as
    input to "nc", allowing you to test your client against a variety of
    SMTP server responses.  (You can also just type the lines in by hand.)

    You will find an automated test script with a few tests already
    programmed in the notes as "testplanscript2.txt" and sample output
    from running the test script in notes file "test_out2.txt".

14) Create a README.txt file containing a summary description of your
    test plan and its results.

    Record the output of applying your Test Plan in file "test_out.txt".
    (Either redirect the output of your test script "test_plan.sh"; or,
    run a "script" session and submit it with your files for marking.)
    (Using a shell script to run your tests will make this much easier.)

Bonus
-----
    1. Allow arguments to appear in any order, not the fixed order given.
    2. Use a default port of 25 if one is not given.
    3. Use a default SMTP host of "localhost" if one is not given.
    4. Use a default "from" of the current userid running the script
       ( use $ENV{USER} ) with domain "@algonquincollege.com" added.
       (Remember to escape the '@' inside of Perl strings.)

Submission and Marking Scheme
-----------------------------

Submission Standards (see earlier labs for details):

1.  At the top of each and every submitted file, as comments, create an
    Exterior Assignment Submission label.  This label identifies the
    file; it is not a substitute for proper documentation in the file.
    Your file will still need comments and function headers.

2.  For material you copy from other sources, credit the author and source.
    If the comments in the source you copy are not sufficient, you must
    fix and add to them, just as if you wrote the code yourself.

3.  Submit all your source files for marking as Exercise 04 using a
    *single* cstsubmit command line (always submit all files together):

      $ ~alleni/bin/cstsubmit 04 smtpclient.pl \
          README.txt test_out.txt test_plan.sh

    Submit all the files necessary to test and run your SMTP client.
    Do not submit object files or binary files.

    Note: Nothing in your code or test structure can include absolute
    pathnames (except to well-known system files); in particular, you
    must not reference your own home directory.

To be marked, the files named above must have the exact names given.
Code submitted without your added useful comments (no matter what its
source) will not be marked.

If you aren't sure if you've submitted all the necessary files for your
project, change to a new empty directory and use cstsubmit to fetch your
submission back, expand it, and run your test script.  It should work.

Marking Scheme
--------------

Internal documentation: 33%
 - see note file programming_style.txt
 - are the comments you add useful in understanding what the code does?
 - no "useless comments" - see programming_style.txt
 - comments are in block form, not excessively interleaved with code
 - sparing use of end-of-line comments

Programming correctness, robustness, and style: 33%
 - "be liberal in what you accept"
 - do the error messages appear on stderr and contain full information,
   including the name of the program issuing them?
   - never say "too many" - print the limit
   - never say "not enough" - tell exactly what was expected
   - no user input, short of child pornography, should be mislabelled "illegal" 
 - is this code easy to read and understand?
   - neat, organized, well-spaced
   - is the indentation consistent (Unix tabs are every 8 - "man expand")
 - is this code easy to change and maintain?
   - no "magic numbers" - document your constants and offsets
   - no duplicate code (uses functions for common actions, repeated code)
 - all input presumed hostile and handled safely
 - all return codes checked
 - "less code is better code"

Test Plan README.txt, test_plan.sh, and output in test_out.txt : 34%
 - The SMTP RFC 2821 sets down the rules for your client behaviour
 - Number the sections in README.txt; refer to them in your testing
 - Your testing must refer to the numbered sections in your README.txt file.
 - Document what should happen for every possible type of good and bad input.
   - What errors are possible (RFC); how are they handled?
   - Test command line argument parsing and error messages.
   - Test error response handling on errors from SMTP server.
 - Submit your testing output file test_out.txt
   - either use the test_plan.sh automated testing script or do manual
     testing using the "script" command

All files submitted must be named correctly and have assignment headers.