libfalcon-engine1 0.9.6.9-git20120606-2.1+b1 / usr / lib / falcon / net / imap.fal

/*
    FALCON - IMAP client module

    FILE: imap.fal

    Interface for IMAP remote services
    -------------------------------------------------------------------
    Author: Stanislas Marquis
    Begin: Sun, 21 Nov 2010 19:38:39 +0100

    See http://tools.ietf.org/html/rfc3501
    -------------------------------------------------------------------
    (C) Copyright 2010: the FALCON developers (see list in AUTHORS file)

    See LICENSE file for licensing details.
*/

import from socket
import from regex
export

class IMAPError( code, desc, extra ) from Error( code, desc, extra )
end

/*# IMAP states. */
enum IMAPState
   logout         = -2,
   nostate        = -1, // initial state
   connected      = 0,
   authenticated  = 1,
   selected       = 2
end

/*#
   @brief IMAP class.
   @param server Server address.
   @optparam port Port number (default 143).
   @optparam timeout Socket timeout in milliseconds (default 1000).
   @optparam useSsl Wether to use SSL encrypted socket (default false).
   @optparam sslVer SSL version to use (default TLSv1).
 */
class IMAP( server, port, timeout, useSsl, sslVer )

   /*# Server address. */
   server = server
   /*# Port number. */
   port = port ? toString( port ) : "143"
   /*# Timeout (in milliseconds) waiting for server contact. */
   timeout = timeout ? timeout : 1000
   /*# Wether to use ssl. Change it before connection. */
   useSsl = useSsl ? useSsl : false
   /*# Ssl version to use, default TLSv1. */
   sslVersion = sslVer ? sslVer : socket.TLSv1
   /*# Function used to show communication between client and server. */
   trace = {=>}
   /*# Current state (see @a IMAPState). */
   state = IMAPState.nostate
   /*# Current selected mailbox. */
   selected = nil

   _sock = nil
   _n = 0

   // save multiple lines, if we receive them.
   oldReply = ""

   re_num = regex.Regex( "\\* ([0-9]+) (.*)$" )
   re_ok = regex.Regex( "\\* OK ?(\\[(.*)\\])? ?(.*)$" )
   re_flags = regex.Regex( "\\* FLAGS (.*)$" )

   /*#
      @brief Connect to IMAP server.
      @raise IMAPError Unable to connect.
    */
   function connect()
      sock = socket.TCPSocket()
      sock.setTimeout( self.timeout )
      sock.connect( self.server, self.port )
      if not sock.isConnected()
         raise IMAPError( 10001, "Can't connect to required server", self.server.toString() + ":" + self.port )
      end
      sock.setTimeout( 0 )
      self._sock = sock
      // get the OK or PREAUTH message
      reply = self._recvLine()
      if reply[0:9] == "* PREAUTH"
         self.state = IMAPState.authenticated
      elif reply[0:4] != "* OK"
         raise IMAPError( 10002, "Remote server not ready", reply.trim() )
      else
         self.state = IMAPState.connected
      end
      // ssl ?
      if self.useSsl
         self.startTLS()
         self._sock.sslConfig( false, self.sslVersion )
         self._sock.sslConnect()
      end
   end

   /*#
      @brief Login procedure.
      @param user username.
      @param pasw password.
      @raise IMAPError Login failure.

      Connection attempt will be performed if not already done.
    */
   function login( user, pasw )
      // connect if not done
      if self._sock == nil
         self.connect()
      end
      if self.state >= IMAPState.authenticated: return
      tag = self._tag()
      out = @ "$(tag) LOGIN $(user) $(pasw)"
      self._send( out )
      self._getTagResponse( "LOGIN", tag )
      // error is thrown by getTagResponse in case of failure.
      self.state = IMAPState.authenticated
   end

   /*#
      @brief Logout procedure.
      @raise IMAPError Logout failure.
    */
   function logout()
      if self.state < IMAPState.connected: return
      tag = self._tag()
      out = @ "$(tag) LOGOUT"
      self._send( out )
      reply = self._recvLine()
      if not reply.startsWith( "* BYE" )
         raise IMAPError( 10010, "Logout failed", reply.trim() )
      end
      self.state = IMAPState.logout
      self.selected = nil
      self._n = 0 // reset internal counter
   end

   /*#
      @brief Start TLS procedure.
    */
   function startTLS()
      tag = self._tag()
      out = @ "$(tag) STARTTLS"
      self._send( out )
      self._getTagResponse( "STARTTLS", tag )
   end

   /*#
      @brief Select a mailbox.
      @optparam mailbox The mailbox to select (default INBOX).
      @optparam readonly (boolean) Default false.
      @raise IMAPError Select failure.
    */
   function sel( mailbox, readonly )
      if mailbox == nil: mailbox = "INBOX"
      cmd = readonly ? "EXAMINE" : "SELECT"
      tag = self._tag()
      out = @ "$(tag) $(cmd) $(mailbox)"
      self._send( out )
      reply = self._getTagResponse( cmd, tag )
      // error is thrown by getTagResponse in case of failure.
      reply = self.parseReply( reply )
      self.selected = mailbox
      self.state = IMAPState.selected
      return reply
   end

   /*#
      @brief Close selected mailbox.
      @raise IMAPError Close failure.
    */
   function close()
      if not self.selected: return
      tag = self._tag()
      out = @ "$(tag) CLOSE"
      self._send( out )
      self._getTagResponse( "CLOSE", tag )
      // error is thrown by getTagResponse in case of failure.
      self.selected = nil
      self.state = IMAPState.authenticated
   end

   /*#
      @brief Expunge a mailbox.
      @raise IMAPError Expunge failure.
    */
   function expunge()
      if not self.selected: return
      tag = self._tag()
      out = @ "$(tag) EXPUNGE"
      self._send( out )
      self._getTagResponse( "EXPUNGE", tag )
      // error is thrown by getTagResponse in case of failure.
   end

   /*#
      @brief Create a mailbox.
      @param mailbox The mailbox to create.
      @raise IMAPError Create failure.
    */
   function create( mailbox )
      tag = self._tag()
      out = @ "$(tag) CREATE $(mailbox)"
      self._send( out )
      self._getTagResponse( "CREATE", tag )
   end

   /*#
      @brief Rename a mailbox.
      @param oldbox The actual mailbox to rename.
      @param newbox The desired mailbox name.
      @raise IMAPError Rename failure.
    */
   function rename( oldbox, newbox )
      tag = self._tag()
      out = @ "$(tag) RENAME $(oldbox) $(newbox)"
      self._send( out )
      self._getTagResponse( "RENAME", tag )
      // error is thrown by getTagResponse in case of failure.
   end

   /*#
      @brief Delete a mailbox.
      @param mailbox The mailbox to delete.
      @raise IMAPError Delete failure.
    */
   function delete( mailbox )
      tag = self._tag()
      out = @ "$(tag) DELETE $(mailbox)"
      self._send( out )
      self._getTagResponse( "DELETE", tag )
      // error is thrown by getTagResponse in case of failure.
   end

   /*#
      @brief Subscribe to a mailbox.
      @param mailbox The mailbox to subscribe to.
      @raise IMAPError Subscribe failure.
    */
   function subscribe( mailbox )
      tag = self._tag()
      out = @ "$(tag) SUBSCRIBE $(mailbox)"
      self._send( out )
      self._getTagResponse( "SUBSCRIBE", tag )
      // error is thrown by getTagResponse in case of failure.
   end

   /*#
      @brief Unsubscribe to a mailbox.
      @param mailbox The mailbox to unsubscribe to.
      @raise IMAPError Unsubscribe failure.
    */
   function unsubscribe( mailbox )
      tag = self._tag()
      out = @ "$(tag) UNSUBSCRIBE $(mailbox)"
      self._send( out )
      self._getTagResponse( "UNSUBSCRIBE", tag )
      // error is thrown by getTagResponse in case of failure.
   end

   /*#
      @brief List mailboxes.
      @optparam dir Reference directory (default "").
      @optparam pattern Search pattern (default "").
      @return A list of mailboxes information.
      @raise IMAPError List failure.
    */
   function lst( dir, pattern )
      if not dir: dir = '""'
      if not pattern: pattern = '""'
      tag = self._tag()
      out = @ "$(tag) LIST $(dir) $(pattern)"
      self._send( out )
      reply = self._getTagResponse( "LIST", tag )
      // error is thrown by getTagResponse in case of failure.
      lines = reply.split( "\r\n" )
      if lines.len() == 0: return []
      ret = arrayBuffer( lines.len() )
      i = 0
      for line in lines
         ret[i++] = [].comp( line.split(" ")[2:], { v => v[1:-1] } )
      end
      return ret
   end

   /*#
      @brief List subscribed mailboxes.
      @optparam dir Reference directory (default "").
      @optparam pattern Search pattern (default "").
      @return A list of subscribed mailboxes names.
      @raise IMAPError Lsub failure.
    */
   function lsub( dir, pattern )
      if not dir: dir = '""'
      if not pattern: pattern = '""'
      tag = self._tag()
      out = @ "$(tag) LSUB $(dir) $(pattern)"
      self._send( out )
      reply = self._getTagResponse( "LSUB", tag )
      lines = reply.split( "\r\n" )
      return [].comp( lines[0].split(" ")[2:] )
   end

   /*#
      @brief Search for messages.
      @optparam criterion Search criteria (default ALL).
      @optparam charset Optional charset specification.
      @return A list of message ids matching the criteria.
      @raise IMAPError Search failure.
    */
   function search( criterion, charset )
      tag = self._tag()
      if not criterion: criterion = "ALL"
      charset = charset ? " CHARSET " + charset : ""
      out = @ "$(tag) SEARCH$(charset) $(criterion)"
      self._send( out )
      data = self._getTagResponse( "SEARCH", tag )
      ids = data.split(" ")
      // skip * SELECT in return
      if ids.len() <= 2: return []
      return ids[2:]
   end

   /*#
      @brief Fetch data associated with a message.
      @param msg_set Message id or a sequence of message ids.
      @optparam msg_parts message data item names or macro (default FAST).
      @return the raw data.
      @raise IMAPError Fetch failure.
      @see http://tools.ietf.org/html/rfc3501#section-6.4.5

      That is a raw, 'low-level' function returning the untreated answer got
      from the server. More appropriate functions are the IMAP.get* functions.
    */
   function fetch( msg_set, msg_parts )
      tag = self._tag()
      msg_set = toString( msg_set )
      if not msg_parts: msg_parts = "FAST"
      out = @ "$(tag) FETCH $(msg_set) $(msg_parts)"
      self._send( out )

      // in fetch, the first line may contain a total size of the incoming data,
      // if the incoming data is not internally generated by the fetch command

      // In this case, the fetch reply starts with * and has {size} bytes that
      // must be read.

      reply = []
      while fetchStatus = self._recvLine()
         reply += fetchStatus
         // A long reply?
         posStart = fetchStatus.find( "{" )
         posEnd = fetchStatus.find( "}", posStart )
         if posStart >= 0 and posEnd >= posStart
            // in this case, read all what's next
            size = int( fetchStatus[posStart+1:posEnd] )
            reply += self._recvAll( size )
         end

         // are we done?
         if fetchStatus.startsWith( tag )
            // fetchStatus starts with tag, but it's ok or fail?
            if not fetchStatus.startsWith( tag + " OK" )
               raise IMAPError( 10010, "FETCH failed", fetchStatus )
            end
            break
         end
      end

      return "".merge(reply)
   end

   /*#
      @brief Get a whole message.
      @param msg_id The message id.
      @return The whole message.
      @raise IMAPError Fetch failed.
    */
   function getBody( msg_id )
      raw = self.fetch( msg_id, "BODY[]" )
      apos = raw.find( "\r\n" ) + 2
      zpos = raw.rfind( ")" )
      return raw[apos:zpos]
   end

   /*#
      @brief Get a section of a message.
      @param msg_id The message id.
      @param section The desired section.
      @raise IMAPError Fetch failed.

      Examples:
      @code
         imap.getBodySection( 1, 'HEADER' ) # get header
         imap.getBodySection( 3, '1.HEADER' ) # get header of first part
         imap.getBodySection( 5, 3 ) # get third part...
      @endcode
    */
   function getBodySection( msg_id, section )
      raw = self.fetch( msg_id, "BODY[" + toString( section ) + "]" )
      apos = raw.find("\r\n") + 2
      zpos = raw.rfind(")")
      return raw[apos:zpos]
   end

   /*#
      @brief Get the flags associated with a message.
      @param msg_id The message id.
      @return A list of flags.
      @raise IMAPError Fetch failed.
    */
   function getFlags( msg_id )
      raw = self.fetch( msg_id, "FLAGS" )
      lines = raw.split( "\r\n" )
      apos = lines[0].find("(FLAGS ") + 7
      zpos = lines[0].rfind(")")
      return lines[0][apos:zpos].split(" ")
   end

   /*#
      @brief Get the RFC822 size of a message.
      @param msg_id The message id.
      @return The message size.
      @raise IMAPError Fetch failed.
    */
   function getSize( msg_id )
      raw = self.fetch( msg_id, "RFC822.SIZE" )
      lines = raw.split( "\r\n" )
      apos = lines[0].rfind(" ") + 1
      zpos = lines[0].rfind(")")
      return int( lines[0][apos:zpos] )
   end

   /*#
      @brief Get the hierarchy delimiter.
      @optparam ref The reference (default "").
      @return The character used as hierarchy delimiter.
    */
   function getHierarchyDelimiter( ref )
      res = self.lst( ref, "" )
      return res[0][1]
   end

   function _tag()
      n = self._n++
      return @ "A$(n:5p0r)"
   end

   function _lastTag()
      n = self._n - 1
      return @ "A$(n:5p0r)"
   end

   function _send( cmd )
      self.trace( "--> " + cmd )
      if self._sock.writeAvailable( self.timeout/1000.0 )
         self._sock.send( cmd + "\r\n" )
      else
         raise IMAPError( 10001, "Socket write timeout (" + self.timeout.toString() + ")" )
      end
   end

   function _recvAll( totalsz )
      // if we have already more than enough buffer...
      if self.oldReply.len() >= totalsz
         if self.oldReply.len() == totalsz
            reply = self.oldReply
            self.oldReply = ""
         else
            reply = self.oldReply[:totalsz]
            self.oldReply = self.oldReply[totalsz:]
         end
         self.trace( "<--("+reply.len()+") " + reply.trim() )
         return reply
      end

      // read each block separately
      reply = strBuffer( totalsz + 1024 )
      buf = strBuffer( 1501 )

      recCount = self.oldReply.len()
      oldsz = recCount // for trace
      restsz = totalsz - oldsz // for trace

      if recCount
         reply = self.oldReply + reply
         self.oldReply = ""
      end

      excess = ""

      while 1
         // timeout? -- the remote server hung.
         if not self._sock.readAvailable( self.timeout/1000.0 )
            // Indicate a network problem, and how much data we got in the meanwhile
            raise socket.NetError( 10020, "Timeout in waiting for full size reply.",
               "(" + reply.len() + "/" + totalsz + ")" )
         end

         // receive more data.
         recCount += self._sock.recv( buf, 1500 )
         reply += buf

         // see if we have the tag response entirely with OK.
         if recCount > totalsz
            excess = reply[totalsz:]
            if excess.endsWith( "\r\n" ) and excess.startsWith( ")\r\n"+self._lastTag()+" OK " )
               break
            end
         end
      end

      // put excess in internal buffer.
      self.oldReply = excess
      reply = reply[:totalsz]

      self.trace( "<--["+oldsz+"+"+restsz+"] " + reply.trim() )
      return reply
   end


   function parseReply( reply )
      res = [=>]
      lines = reply.split( "\r\n" )
      for line in lines
         self.parseLine( line, res )
      end
      return bless(res)
   end


   function parseLine( line, res )
      // it's a numeric field?
      if (fields = self.re_num.grab( line ))
         res[strLower( fields[2] )] = int( fields[1] )
      elif (fields = self.re_ok.grab( line ))
         // do we have a value to be parsed in an OK response?
         if fields[2]
            field = strSplit( fields[2], " " )
            res[field[0]] = field.len() > 1 ? self.parseValue( field[1] ) : ""
         end
      elif (fields = self.re_flags.grab( line ))
         res["flags"] = self.parseValue( fields[1] )
      end

      // for now, ignore other kinds of responses
   end


   function parseValue( value )
      // check for special values.
      if value.len() > 0
         firstChar = value[0]
         // lists?
         if firstChar == '(' and value[-1] == ')'
            // empty array?
            if value == "()": return nil
            // otherwise, just split
            return value[1:-1].split(' ')
         // numbers?
         elif firstChar >= "0" and value <= "9"
            return int( value )
         end
      end
      // nope, just values.
      return value
   end


   function _recvLine( maxsz )
      static
         buf = strBuffer( 1024 )
      end

      if maxsz == nil: maxsz = 1024
      reply = self.oldReply + strBuffer( maxsz )

      while (pos = reply.find( "\r\n" )) < 0 and reply.len() < maxsz

         // timeout? -- the remote server hung.
         if not self._sock.readAvailable( self.timeout/1000.0 )
            raise socket.NetError( 10021, "Timeout in reading next line from reply." )
         end

         // receive more data.
         self._sock.recv( buf )
         reply += buf
      end
      // send the first line and save the rest for later.
      self.oldReply = reply[pos+2:]
      reply = reply[0:pos+2]  // include \r\n in this reply
      self.trace( "<-- " + reply.trim() )
      return reply
   end

   function _getTagResponse( command, tag )
      data = ""
      while line = self._recvLine()
         // last line?
         if line.startsWith( tag )
            if not line.startsWith( tag + " OK" )
               raise IMAPError( 10010,
                     @"$(command) failed after receiving " + data.len() + " bytes",
                     line.trim() )
            end
            // we're done.
            break
         end

         data += line
      end

      // remove trailing space.
      return data.trim()
   end

end // class IMAP

/* vim: set et ai sw=3 ts=3 sts=3: */