ruby-net-nntp 0.2.2 → 1.0.0

data/lib/net/nntp.rb

@@ -1,407 +1,341 @@
-# = Net::NNTP class
+# = Net::NNTP library
 # Author:: Anton Bangratz
-require 'socket'
-require 'thread'
-require 'timeout' # :nodoc:
-require 'net/nntp/group'
-require 'net/nntp/article'
-require 'net/nntp/version.rb'
+#
 require 'rubygems'
-require 'log4r' 
-
-
-
-module Net      
+require 'timeout'
+require 'tmail'
+require 'log4r'
+require 'date'
+require 'ostruct'
+require 'net/nntp/version'
+require 'net/nntp/request.rb'
+require 'net/nntp/response.rb'
+
+# Namespace
+module Net
+  # Base class for connecting to an NNTP server and handling requests and responses.
   class NNTP
-    include Timeout # :nodoc:
-
-    # Statuses of one-line responses
-    ONELINE_STATUSES = %w( 111 200 201 205 223 235 240 281 335 340 381 400 401 403 411 412 420 421 422 423 430 435 436 437 440 441 480 483 500 501 502 503 504 ).freeze
-
-    # Statuses of multiline responses
-    MULTILINE_STATUSES = %w( 100 101 215 220 221 222 224 225 230 231 ).freeze
-
-    # Error to indicate that NNTP Command failed gracefully
-    class CommandFailedError < StandardError
-    end
-    # Error to indicate that a Protocol Error occured during NNTP command execution
-    class ProtocolError < StandardError
-    end
 
+    attr_accessor :host, :port, :timeout
+    attr_reader :last_response, :current_group, :current_article
 
-    attr_reader :socket, :grouplist, :overview_format 
-    attr_accessor :response_timeout
 
+    # Setter for a Log4r style logger.
     def self.logger=(logger)
       @@logger = logger
     end
 
+    # Accessor for the Log4r style logger.
     def self.logger
       @@logger
     end
 
-    def logger
-      @@logger
-    end
+    # Shortcut for Net::NNTP.logger.debug(message)
     def debug(message)
-      @@logger.debug(message)
-    end
-
-    # initializes NNTP class with host, port and timeout values
-      def initialize(host, port = 119, response_timeout = 10)
-      @host = host
-      @port = port
-      @response_timeout = response_timeout
-      @socket_class = TCPSocket
-      @group = nil
-      @@logger ||= Log4r::Logger['net::nntp'] || Log4r::Logger.new('net::nntp')
+      Net::NNTP.logger.debug(message)
     end
 
-    # Actually connects to NNTP host and port given in new()
-    def connect
-      @socket = @socket_class.new(@host, @port)
-      @welcome = read_response()
-      debug "Welcome: #{@welcome[0]} "
-      @welcome
-    end
-
-    # Checks if socket is still valid and connected
-    def connected?
-      @socket && !@socket.closed?
+    # Initializes an NNTP instance.
+    #
+    # Takes an option hash as argument. Keys being processed are :host, :port and :timeout
+    def initialize(args={})
+      @host = args[:host] || default_host()
+      @port = args[:port] || default_port()
+      @timeout = args[:timeout] || default_timeout()
+      @current_request = nil
+      if block_given?
+        begin
+          yield self
+        ensure
+          close
+        end
+      end
     end
 
-    # Sends QUIT command to server and closes the connection (unless force_close is set to false). Returns response.
-    def quit(force_close=true)
-      send_cmd "QUIT"
-      response = read_response
-      close if force_close
-      response
+    # Sets up the connection to a TCPSocket, using #host and #port accessors.
+    #
+    # To use different server and port values, use the accessors.
+    #
+    # Reads and returns the response (should be a PostingOK or PostingProhibited response, or a generic response).
+    #
+    # == Usage Example
+    #
+    #   nntp = Net::NNTP.new
+    #   nntp.server = 'my.server.example.com'
+    #   nntp.port = 22119
+    #   if nntp.connect
+    #     # ... do stuff ...
+    #   end
+    def connect 
+      @socket = TCPSocket.new(host(), port());
+      @connected = true
+      @current_request = nil
+      @last_response = read_response()
+    end
+
+    def reconnect
+      close unless @socket.closed?
+      connect
+      authenticate *@credentials if @credentials
+      process @current_group.request if @current_group
+      process @current_article.request if @current_article
     end
 
-
-    # Closes connection. If not reconnected, subsequent calls of commands raise exceptions
     def close
-      debug 'closing connection per request'
-      @socket.close unless socket.closed?
+      @socket.close unless @socket.closed?
     end
 
-    def has_xover?
-      !help.select {|i| i =~ /\bxover\b/i}.empty?
+    # Returns true if #connect was successful and the socket is connected.
+    def connected?
+      @socket && !@socket.closed? && @connected
+    end
+
+    def read_response
+      begin
+        debug "reading from socket: #{@socket}"
+        line=nil
+        Timeout::timeout(@timeout) {
+          line = @socket.readline
+        }
+        debug("line from socket: #{line}")
+        response = Response.create(@current_request, line)
+        response
+      rescue EOFError
+      ensure
+        @current_request = nil
+      end
     end
+    private :read_response
 
-    def has_over?
-      !help.select {|i| i =~ /\bover\b/i}.empty?
-    end
-    # Uses authinfo commands to authenticate. Timeout for first command is set to 10 seconds. 
+    # Processes a request.
     #
-    # Returns true on success, false on failure.
-    def authenticate(user, pass)
-      cmd = "authinfo user #{user}"
-      debug "Authenticating: Sending #{cmd}"
-      send_cmd cmd
-      response_array = read_response()
-      response = response_array[0]
-      debug "Authenticating: Response #{response}"
-      if response[0..2] == '381' then
-        cmd = "authinfo pass #{pass}"
-        debug "Authenticating: Sending #{cmd}"
-        send_cmd cmd
-        response_array = read_response()
-        response = response_array[0]
-        debug "Authenticating: Response #{response}"
+    # +request+ must be a Net::NNTP::Request subclass. Certain requests (Authinfo and requests that require a two-stage
+    # response/request cycle will try to process these two stages gracefully. For multiline responses, the body will be
+    # processed, too.
+    #
+    # Net::NNTP::GroupSelected responses will be recorded in *current_group*, Net::NNTP::ArticleSelected responses in
+    # *current_article*.
+    #
+    # Returns the last response.
+    def process(request)
+      if connected?
+        @current_request = request
+        debug("Sending #{request.command}")
+        @socket.write(request.command)
+        @last_response = read_response()
+        if @last_response.needs_article?
+          debug "Sending article: #{request.dotstuff}"
+          request.dotstuff.split(/\r?\n/).each do |line|
+            line << "\r\n"
+            @socket.write line
+          end
+          @socket.write ".\r\n"
+          @last_response = read_response()
+        end
+        if (@last_response.multiline?)
+          debug "Response is multiline"
+          @last_response.body = @socket
+        end
+        @socket.close if @last_response.force_close?
+        @last_response
+        if (GroupSelected === @last_response)
+          @current_group = @last_response
+        elsif (ArticleSelected === @last_response)
+          @current_article = @last_response
+        else 
+          @last_response
+        end
       end
-      return response && response[0..2] == '281'
     end
 
-    # Issues 'GROUP' command to NNTP Server and creates new active group from returning data.
+    # Proxy for authentication request/response cycles. 
     #
-    # Throws CommandFailedError
+    # See Net::NNTP::Authinfo for parameters.
     #
-    def group(group)
-      send_cmd "group #{group}"
-      response = read_response(true)
-      responsecode, cnt, first, last, name = response[0].split
-      if responsecode == '211'
-        @group = Group.new(name)
-        @group.article_info = [cnt, first, last]
-        @group
+    # Returns +true+ if the authentication has been accepted.
+    def authenticate(user, pass)
+      @credentials = [user, pass]
+      auth_request = Authinfo.new('user', user)
+      if PasswordRequired === process(auth_request)
+        auth_request = Authinfo.new('pass', pass)
+        AuthenticationAccepted === process(auth_request)
       else
-        raise CommandFailedError, response[0]
+        false
       end
     end
 
-    # Issues 'HELP' command to NNTP Server, and returns raw response.
-    def help
-      send_cmd("help")
-      read_response()
+    # Proxy for Net::NNTP::Article requests and processing.
+    #
+    # See Net::NNTP::Article for parameters
+    #
+    # Returns the response.
+    def article(opts=nil)
+      request = Article.new(opts)
+      process(request)
     end
 
-    # Issues 'XHDR' command to NNTP Server, and returns raw response. Checks if group has been selected, selects group
-    # otherwise.
+    # Proxy for Net::NNTP::Body requests and processing.
     #
-    # TODO:: Implement XHDR header <message-id>
-    def xhdr(header, groupname=nil, rest=nil)
-      raise CommandFailedError, 'No group selected' unless @group || groupname
-      if @group.nil?
-        group(groupname) 
-      elsif groupname.nil?
-      else
-        @group.name != groupname
-        group(groupname)
-      end
-      cmd = "xhdr #{header}"
-      suffix = numbers_or_id(rest)
-      send_cmd([cmd, suffix].join(' '))
-      read_response()
+    # See Net::NNTP::Body for parameters
+    #
+    # Returns the response.
+    def body(opts)
+      request = Body.new(opts)
+      process(request)
     end
 
-    # Issues 'XOVER' command to NNTP Server, and returns raw response. Checks if group has been selected, selects group
-    # otherwise. If no group is selected nor given, raises error. 
-    # Parameter 'rest' can be in the form of :from => number, :to => number or :messageid => 'messageid',
-    # if not set, a 'next' command is issued to the server prior to the xover command
+    # Proxy for Net::NNTP::Head requests and processing.
     #
-    def xover(groupname=nil, rest=nil)
-      raise CommandFailedError, 'No group selected' unless @group || groupname
-      if @group.nil?
-        group(groupname) 
-      elsif groupname.nil?
-      else
-        @group.name != groupname
-        group(groupname)
-      end
-      debug "Selected Group: #{@group.name}"
-      self.next unless rest
-      prefix = "xover"
-      suffix = numbers_or_id(rest)
-      cmd = [prefix, suffix].join ' ' 
-      send_cmd(cmd)
-      response = nil
-      timeout(@response_timeout) do
-        response = read_response()
-      end
-      response
+    # See Net::NNTP::Head for parameters
+    #
+    # Returns the response.
+    def head(opts)
+      request = Head.new(opts)
+      process(request)
     end
 
-    def newnews(groups='*', date=nil, time=nil, gmt=true)
-      gmt_str = gmt ? '"GMT"' : "" 
-      debug groups
-      debug date
-      debug time
-      debug gmt_str
-      cmd = 'newnews %s %s %s %s' % [groups, date, time, gmt_str]
-      debug "Sending #{cmd}"
-      send_cmd(cmd)
-      response = nil
-      response = read_response
-      response
+    # Proxy for Net::NNTP::Help requests and processing.
+    #
+    # Returns the response.
+    def help
+      process Help.new
     end
 
-    # Issues 'LISTGROUP' command to NNTP Server, and returns raw response. Checks if group has been selected, selects group
-    # otherwise.
+    # Proxy for Net::NNTP::Last requests and processing.
     #
-    def listgroup(groupname=nil)
-      raise CommandFailedError, 'No group selected' unless @group || groupname
-      if @group.nil?
-        group(groupname) 
-      elsif @group.name != groupname
-        group(groupname)
-      end
-      debug "Selected Group: #{@group.name}"
-      send_cmd('listgroup')
-      read_response()
+    # Returns the response.
+    def last
+      process Last.new
     end
 
-    # Issues 'LIST' command to NNTP Server. Depending on server capabilities and given keyword, can either set overview
-    # format (if called with 'overview.fmt') or create a grouplist (see Attributes)
-    #
-    # Throws CommandFailedError
-
-    def list(keyword=nil, pattern=nil)
-      cmd = ['list', keyword, pattern].join ' '
-      send_cmd(cmd)
-      list = read_response()
-      responsecode = list[0][0..2]
-      case responsecode 
-      when '215'
-        case keyword
-        when /overview.fmt/
-          @overview_format_raw = list
-          @overview_format = Net::NNTP.parse_overview_format list
-        else
-          create_grouplist(list)
-          list
-        end
-
-      when '501', '503', '500'
-        raise CommandFailedError, list
-      end
+    # Proxy for Net::NNTP::Next requests and processing.
+    #
+    def next
+      process Next.new
     end
 
-    # prepares overview format as read from server, used by Net::NNTP::Article and list()
-    def self.parse_overview_format(format)
-      overview_format = %w{number}
-      lines = format
-      lines.each do |line|
-        next if line[0] == ?2 || line[0] == ?. || line == 'full'
-        ident = line.scan(/\w/).join.downcase
-        unless ident[0..3] == 'xref'
-          overview_format << ident 
-        else
-          overview_format << 'xref'
-        end
-      end
-      overview_format
+    # Proxy for Net::NNTP::Group requests and processing.
+    #
+    # See Net::NNTP::Group for parameters
+    #
+    # Returns the response.
+    def group(name)
+      process Group.new(name)
     end
 
-    # TODO: complete implementation
-    def stat
+    # Proxy for Net::NNTP::List requests and processing.
+    #
+    # See Net::NNTP::List for parameters
+    #
+    # Returns the response.
+    def list(keyword=nil, rest={})
+      process List.new(keyword, rest)
     end
 
-    # Issues 'HEAD' command to NNTP server, returning raw response
-    #
-    # Throws CommandFailedError
-    def head(args=nil)
-      suffix = numbers_or_id(args)
-      cmd = 'head'
-      cmd = ['head', suffix].join " " if suffix
-      send_cmd(cmd)
-      response = read_response()
-      case response[0][0..2]
-      when '221'
-        return response
-      else
-        raise CommandFailedError, response
-      end
+    # Proxy for Net::NNTP::Listgroup request and processing
+    #
+    # See Net::NNTP::Listgroup for parameters
+    #
+    # Returns the response.
+    def listgroup(groupname=nil, range={})
+      process Listgroup.new(groupname, range)
     end
 
-    # Issues 'BODY' command to NNTP server, returning raw response as array of lines.
-    # options:: messageid|id
-    #
-    # Throws CommandFailedError
-    def body(args=nil)
-      suffix = args
-      cmd = 'body'
-      cmd = ['body', suffix].join " " if suffix
-      send_cmd(cmd)
-      response = read_response()
-      case response[0][0..2]
-      when '222'
-        return response
-      else
-        raise CommandFailedError, response
-      end
+    # Proxy for Net::NNTP::Quit requests and processing.
+    #
+    def quit
+      process Quit.new
     end
 
-    # Issues 'ARTICLE' command to NNTP server, returning raw response.
-    # options:: messageid|id
-    #
-    # Throws CommandFailedError
-    def article(args=nil)
-      suffix = args
-      cmd = 'article'
-      cmd = ['article', suffix].join " " if suffix
-      send_cmd(cmd)
-      response = read_response()
-      case response[0][0..2]
-      when '220'
-        return response
-      else
-        raise CommandFailedError, response
-      end
+    # Proxy for Net::NNTP::Stat requests and processing.
+    #
+    # See Net::NNTP::Stat for parameters
+    #
+    # Returns the response.
+    def stat(opts=nil)
+      request = Stat.new(opts)
+      process(request)
     end
 
-    def last_or_next(cmd)
-      raise ProtocolError, "No group selected" unless @group
-      send_cmd(cmd)
-      response = read_response()[0]
-      code = response[0..2]
-      article = @group.articles.create
-      case code
-      when '223'
-        code, id, msgid, what = response.split
-        article.number = id
-        article.messageid = msgid
-      else
-        raise CommandFailedError, response
-      end
-      response
+    # Proxy for Net::NNTP::Hdr requests and processing.
+    #
+    # See Net::NNTP::Hdr for parameters
+    #
+    # Returns the response.
+    def hdr(field, opts)
+      request = Hdr.new(field, opts)
+      process(request)
     end
 
-    # Issues the LAST command to the NNTP server, returning the raw response
-    def last
-      last_or_next("last")
+    # Proxy for Net::NNTP::Xhdr requests and processing.
+    #
+    # See Net::NNTP::Xhdr for parameters
+    #
+    # Returns the response.
+    def xhdr(field, opts)
+      request = Xhdr.new(field, opts)
+      process(request)
     end
 
-    # Issues the NEXT command to the NNTP server, returning the raw response
-    def next
-      last_or_next("next")
+
+    # Proxy for Net::NNTP::Over requests and processing.
+    #
+    # See Net::NNTP::Over for parameters
+    #
+    # Returns the response.
+    def over(range=nil)
+      request = Over.new(range)
+      process(request)
     end
 
-    def create_grouplist(response)
-      @grouplist = {}
-      response.each_with_index do |line, idx|
-        next if idx == 0
-        break if line =~ /^\.$/
-          groupinfo = line.split 
-        group = Group.new groupinfo.shift
-        group.article_info = groupinfo
-        @grouplist[group.name] = group
-      end
-      @grouplist
+    # Proxy for Net::NNTP::Xover requests and processing.
+    #
+    # See Net::NNTP::Xover for parameters
+    #
+    # Returns the response.
+    def xover(range=nil)
+      request = Xover.new(range)
+      process(request)
     end
 
-    def send_cmd(cmd)
-      debug "Sending: '#{cmd}'"
-      @socket.write(cmd+"\r\n")
+
+    # Proxy for Net::NNTP::Post requests and processing.
+    #
+    # See Net::NNTP::Post for parameters
+    #
+    # Returns the response.
+    def post(body)
+      request = Post.new
+      request.body = body
+      process(request)
     end
 
-    # Reads response from server socket. On multiline responses according to RFC, the response will be returned as an
-    # array of lines, else as an array including the response on one line. Parameter force_online can be used to
-    # override this behaviour and just read one line from the server.
-    def read_response(force_oneline=false)
-      response = ''
-      str = ''
-      ra = []
-      linecnt = 0
-      loop do
-        str = @socket.readline
-        #debug "  -> got line: '#{str}'"
-        str = str[1..-1] if str && str[0..1] == '..'
-        ra << str.chomp if str
-        break if force_oneline || (!str || str.chomp == "." || (linecnt == 0 && ONELINE_STATUSES.include?(str[0..2])) )
-        linecnt += 1
-      end
-      debug "Response: '#{ra.inspect}'"
-      ra
+
+    # Proxy for Net::NNTP::Ihave requests and processing.
+    #
+    # See Net::NNTP::Ihave for parameters
+    #
+    # Returns the response.
+    def ihave(id, body)
+      request = Ihave.new id
+      request.body = body
+      process(request)
+    end
+    private 
+    def default_host
+    'localhost'
     end
 
-    # Parses a hash in the format {:from => int, :to => int} or {:message_id => int}
-    # and returns a string. :to is optional, :from has precedence over :message_id if
-    # both are given
-    #
-    # Examples:
-    #   numbers_or_id(:from => 1, :to => 100) #=> returns '1-100'
-    #   numbers_or_id(:from => 1)             #=> returns '1-'
-    #   numbers_or_id(:message_id = '<abc>'   #=> returns '<abc>'
-    #   numbers_or_id(:from => 5, :message_id = '<abc>'   #=> returns 'f-'
-    def numbers_or_id(hash)
-      return nil unless hash
-      suffix = ''
-      from = hash[:from]
-      to = hash[:to]
-      msgid = hash[:message_id]
-      if from
-        suffix = "#{from}-"
-        suffix += "#{to}" if to
-      elsif msgid
-        suffix = "#{msgid}"
-      end
-      suffix
+    def default_port
+      119
     end
 
-    private :read_response, :numbers_or_id, :send_cmd, :last_or_next, :create_grouplist
+    def default_timeout
+      15
+    end
 
   end
 end
 
+
 # vim:sts=2:ts=2:sw=2:sta:et