ruby-net-nntp 0.2.2 → 1.0.0

data/lib/net/nntp/response.rb

@@ -0,0 +1,731 @@
+module Net
+  class NNTP
+
+    class GenericError < StandardError; end
+    class ProtocolError < RuntimeError; end
+    # Simple header class to parse headers received from LIST OVERVIEW.FMT
+    #
+    # See Net::NNTP::ListInformationFollows
+    class FormatHeader
+      attr_reader :name, :full
+      def initialize(line)
+        if match = line.match(/^(\S+):(full)?/m)
+          @name = match[1].downcase
+          @full = ('full' == match[2])
+        elsif match = line.match(/^:(\S+)$/m)
+          @name = match[1].downcase
+          @full = false
+        end
+      end
+    end
+
+    # Prepares the basic functionality for responses that have a body (directly following the status line).
+    #
+    # Every class that includes this can use strings or objects responding to +readline+ to retrieve the body.
+    module BodyBaseResponse 
+      # Sets the body attribute. 
+      #
+      # The parameter +body+ can be a string or an object responding to +readline+. Reading will be halted at a line
+      # with a single dot followed by <CRLF> or <LF>, or when an EOFError occurs. The result will be stored in the
+      # internal attribute @raw. Subsequently, parse_body will be called.
+      def body=(body)
+        if body.respond_to? :readline
+          begin
+            @raw = ''
+            loop do
+              line = body.readline
+              @raw << line
+              break if line =~/\A\.\r?\n\z/m
+            end
+          rescue EOFError => e
+          end
+        else
+          @raw = body
+        end
+        parse_body
+      end
+      # Returns the body attribute.
+      #
+      # If a block is given, the results will be sent to body= before returning the attribute.
+      def body
+        self.body = yield if block_given?
+        @body
+      end
+      # Is called from body= and should be used to set the @body attribute transforming the contents of the @raw
+      # attribute. 
+      def parse_body
+        @body = @raw.dup
+      end
+    end
+    
+    # Base response class. Parent of all responses. DO NOT instantiate directly unless you're ready to handle the nitty
+    # gritty yourself.
+    #
+    # Class Tree:
+    # * Net::NNTP::Response
+    #   * InformationResponse
+    #     * HelpResponse
+    #     * CapabilityList
+    #     * DateResponse
+    #   * OKResponse
+    #     * PostingAllowed
+    #     * PostingProhibited
+    #     * ConnectionClosing
+    #     * GroupSelected
+    #     * ListInformationFollows
+    #     * ArticleResponse
+    #     * HeaderResponse
+    #     * BodyResponse
+    #     * ArticleSelected
+    #     * OverviewInformation
+    #     * HdrResponse
+    #     * NewnewsResponse
+    #     * NewgroupsResponse
+    #     * TransferOK
+    #     * ArticleReceived
+    #     * AuthenticationAccepted
+    class Response
+      attr_reader :code, :message
+      # * Parameter +code+ is the code returned from the server, should be a string representing the first three bytes
+      #   (digits).
+      # * Parameter +message+ is the message following the code on the status line without the separating whitespace.
+      # * Parameter +generic+ gives the subclasses the opportunity to denote if the response is a generic response
+      #   according to the RFC, and therefor valid following any request, or if the response is a response that MUST
+      #   follow a certain request. See Request for validating responses.
+      # * Parameter +multiline+ gives the subclasses the opportunity to denote if the response is a multiline response
+      #   according to RFC, and if a body is to be expected.
+      def initialize(request, code, message, generic=false, multiline=false)
+        @code = code
+        @message = message
+        @generic=generic
+        @multiline = multiline
+        @request = request
+      end
+
+      # Returns the value of the *generic* attribute, set by the generic parameter to new.
+      def generic?
+        @generic
+      end
+
+      # Returns the value of the *multiline* attribute, set by the multiline parameter to new.
+      def multiline?
+        @multiline
+      end
+
+      # Returns *true* if the response is a multiline response and has a body set.
+      def has_body?
+        multiline? && body
+      end
+
+      # Returns the body in subclasses; returns nil in Response.
+      def body
+        nil
+      end
+
+      def ==(other)
+        if other.is_a? Response
+          self.class == other.class && self.code == other.code && self.message == other.message && self.multiline? == other.multiline? && self.generic? == other.generic? && self.body == other.body
+        else 
+          return false
+        end
+      end
+
+      def needs_article?
+        false
+      end
+
+      def force_close?
+        false
+      end
+    end
+    
+    # Categorizes the responses starting with a code of 1xx as information responses.
+    #
+    # All InformationResponse subclasses do have a body, so BodyBaseResponse is included here.
+    #
+    # == Subclasses
+    # * HelpResponse
+    # * CapabilityList
+    # * DateResponse
+    class InformationResponse < Response
+      include BodyBaseResponse
+    end
+
+    # Code: 100
+    #
+    # Response to a Help request.
+    class HelpResponse < InformationResponse
+      attr_reader :raw
+      def initialize(request, code, message)
+        super request, code, message, false, true
+      end
+    end
+
+    # Code: 101
+    #
+    # Response to a Capabilities request.
+    #
+    class CapabilityList < InformationResponse
+      attr_reader :raw
+
+      def initialize(request, code, message)
+        @capabilities = {}
+        super request, code, message, false, true
+      end
+
+      # Returns the capabilities as a hash. Key is the first word (capability) downcased, value either a single string
+      # or a array of strings, or the value 'true'.
+      #
+      def capabilities
+        @capabilities.dup
+      end
+      def parse_body # :nodoc: internal use only
+        @raw.split(/\n/).each do |line|
+          break if line == '.'
+          key, *value = line.split(/\s+/)
+          value = (value.size <= 1 ? value[0]: value) 
+          @capabilities[key.downcase]= value || true
+        end unless @raw.nil?
+      end
+    end
+
+    # Code: 111
+    #
+    # DATE response. 
+    class DateResponse < InformationResponse
+      # Returns the date given as message from server.
+      def date 
+        DateTime.parse(@message)
+      end
+    end
+    
+    # Categorizes responses starting with a code of 2xx as OKResponses
+    # Codes: 2xx
+    #
+    # DO NOT instantiate, use the following
+    #
+    # == Subclasses
+    # * PostingAllowed
+    # * PostingProhibited
+    # * ConnectionClosing
+    # * GroupSelected
+    # * ListInformationFollows
+    # * ArticleResponse
+    # * HeaderResponse
+    # * BodyResponse
+    # * ArticleSelected
+    # * OverviewInformation
+    # * HdrResponse
+    # * NewnewsResponse
+    # * NewgroupsResponse
+    # * TransferOK
+    # * ArticleReceived
+    # * AuthenticationAccepted
+    class OKResponse < Response
+    end
+
+    # Code: 200
+    # Posting allowed response. See NNTP#connect, Modereader.
+    class PostingAllowed < OKResponse
+    end
+
+    # Code: 201
+    # Posting prohibited response. See NNTP#connect, Modereader, Post.
+    class PostingProhibited < OKResponse
+    end
+
+    # Code: 205
+    # Connection closing response. See NNTP#quit.
+    class ConnectionClosing < OKResponse
+      def force_close?
+        true
+      end
+    end
+
+    # Code: 211
+    #
+    # GroupSelected response. 
+    #
+    # See Group, Listgroup.
+    class GroupSelected < OKResponse
+      attr_reader :group, :list
+      attr_reader :raw
+      include BodyBaseResponse
+      def initialize(request, code, message)
+        @group = OpenStruct.new
+        tokens = message.split
+        raise ProtocolError, "Malformed group message: #{message}" unless tokens.size >= 4
+        @group.number, @group.low, @group.high, @group.name = tokens[0].to_i, tokens[1].to_i, tokens[2].to_i, tokens[3]
+        @body = nil
+        super request, code, message, false, Listgroup === request
+      end
+      def parse_body
+        @body=@raw
+        @list = @raw.gsub(/\r?\n\.\r?\n/, '').split(/\r?\n/)
+      end
+
+    end
+
+    class GroupListResponse < OKResponse
+      include BodyBaseResponse
+      attr_reader :list, :raw
+
+      def initialize(request, code, message)
+        @list = []
+        super request, code, message, false, true
+      end
+
+    end
+
+    # Code: 215
+    class ListInformationFollows < GroupListResponse
+      def parse_body
+        case @request.keyword
+        when nil, 'ACTIVE'
+          @raw.split(/\r?\n/).each do |line|
+            break if line == '.'
+            name, low, high, status = line.split(/\s+/)
+            @list << OpenStruct.new(:name => name, :low => low.to_i, :high => high.to_i, :status => status.strip)
+          end unless @raw.nil?
+        when 'ACTIVE.TIMES'
+          @raw.split(/\r?\n/).each do |line|
+            break if line == '.'
+            name, epoch, creator = line.split(/\s+/)
+            @list << OpenStruct.new(:name => name, :epoch => epoch, :creator => creator)
+          end unless @raw.nil?
+        when 'DISTRIB.PATS'
+          @raw.split(/\r?\n/).each do |line|
+            break if line == '.'
+            priority, pattern, distribution = line.split(/:/)
+            @list << OpenStruct.new(:priority => priority.to_i, :pattern => pattern, :distribution => distribution)
+          end unless @raw.nil?
+        when 'HEADERS'
+          @list = @raw.gsub(/\r?\n\.\r?\n/, '').split(/\r?\n/) unless @raw.nil?
+        when 'NEWSGROUPS'
+          @raw.split(/\r?\n/).each do |line|
+            break if line == '.'
+            if match = line.match(/\A(\S+)\s+(.*)\z/)
+              name, desc = match.captures
+              @list << OpenStruct.new(:name => name, :desc => desc)
+            else
+              raise ProtocolError,'List format mismatch'
+            end
+          end unless @raw.nil?
+        when 'OVERVIEW.FMT'
+          @raw.split(/\r?\n/).each do |line|
+            break if line == '.'
+            @list << FormatHeader.new(line)
+          end unless @raw.nil?
+        end
+      end
+
+    end
+
+    class ArticleBaseResponse < OKResponse
+      attr_reader :number, :message_id, :raw
+      def initialize(request, code, message, generic=false, multiline=true)
+        number, id = message.split(/\s+/)
+        @number = number.to_i
+        @message_id = id
+        super request, code, message, generic, multiline
+      end
+    end
+
+    # Code: 220
+    class ArticleResponse < ArticleBaseResponse
+      include BodyBaseResponse
+      def parse_body
+        unless @article
+          r = @raw.dup
+          r.gsub!(/^\./,"")
+          @article = TMail::Mail.parse(r) 
+        end
+      end
+      def article
+        @article.dup 
+      end
+      def [](header)
+        @article[header].to_s
+      end
+    end
+
+    # Code: 221
+    #
+    # CAVEAT::  according to RFC 2980, an XHDR request will trigger a 221 response, but with a TOTALLY different format.
+    #           THANKS, IDIOTS (fucking on a heap of barbed wire ...)
+    class HeaderResponse < ArticleBaseResponse
+      include BodyBaseResponse
+      attr_reader :list
+      def parse_body
+        unless @article 
+          if Xhdr === @request
+            @xhdr = true
+            @list = {}
+            @raw.split(/\r?\n/).each do |line|
+              number, value = line.split(/\t/)
+              @list[number.to_i] = value
+            end
+          elsif Head === @request
+            @xhdr = false
+            begin
+              @article = TMail::Mail.new 
+              @article.__send__(:parse_header, StringIO.new(@raw))
+            rescue TMail::SyntaxError
+            end
+          end
+        end
+      end
+
+      def [](header)
+        return @article[header].to_s if @article
+        nil
+      end
+      def header
+        return @article.header if @article
+        nil
+      end
+
+    end
+
+
+    # Code: 222
+    class BodyResponse < ArticleBaseResponse
+      include BodyBaseResponse
+    end
+
+    # Code: 223
+    class ArticleSelected < ArticleBaseResponse
+      def initialize(request, code, message)
+        super request, code, message, false, false
+      end
+    end
+
+    # Code: 224
+    class OverviewInformation < ArticleBaseResponse
+      include BodyBaseResponse
+      attr_reader :subject, :from, :date, :references, :bytes, :lines, :optional_headers
+      def parse_body
+        raw = @raw.gsub(/\r\n\.\r\n/, '')
+        number, subject, from, date, message_id, references, bytes, lines, *rest =
+          raw.strip.split(/\t/)
+        @number = number.to_i
+        @subject = subject
+        @from = from
+        @date = DateTime.parse(date)
+        @message_id = message_id
+        @references = references.split(/\s/)
+        @bytes = bytes.to_i
+        @lines = lines.to_i
+        @optional_headers = {}
+        if rest 
+          rest.each do |line|
+            header, value = line.split(/:\s+/)
+            optional_headers[header.downcase] = value
+          end
+        end
+      end
+    end
+
+    # Code : 225
+    class HdrResponse < ArticleBaseResponse
+      include BodyBaseResponse
+      attr_reader :list
+      def parse_body
+        @list = {}
+        @raw.split(/\r?\n/).each do |line|
+          number, value = line.split(/\t/)
+          @list[number.to_i] = value
+        end
+      end
+    end
+
+    # Code: 230
+    class NewnewsResponse < ArticleBaseResponse
+      include BodyBaseResponse
+      attr_reader :list
+      def parse_body
+        @list = @raw.split(/\r?\n/)
+      end
+    end
+
+    # Code: 231
+    class NewgroupsResponse < GroupListResponse
+      def parse_body
+        @raw.split(/\r?\n/).each do |line|
+          break if line == '.'
+          name, low, high, status = line.split(/\s+/)
+          @list << OpenStruct.new(:name => name, :low => low.to_i, :high => high.to_i, :status => status.strip)
+        end unless @raw.nil?
+      end
+
+    end
+
+    # Code: 235
+    class TransferOK < OKResponse
+    end
+
+    # Code: 240
+    class ArticleReceived < OKResponse
+    end
+
+    # Code: 281
+    class AuthenticationAccepted < OKResponse
+    end
+
+    class ContinueResponse < Response
+    end
+
+    # Code: 335
+    class TransferArticle < ContinueResponse
+      def needs_article?
+        true
+      end
+    end
+
+    # Code: 340
+    class PostArticle < ContinueResponse
+      def needs_article?
+        true
+      end
+    end
+
+    # Code: 381
+    class PasswordRequired < ContinueResponse
+    end
+
+    
+    # Codes: 4xx
+    # == Subclasses:
+    # * TemporarilyUnavailable        (400)
+    # * InternalFault                 (403)
+    # * GroupUnknown                  (411)
+    # * NoGroupSelected               (412)
+    # * InvalidArticle                (420)
+    # * NoNextArticle                 (421)
+    # * NoPreviousArticle             (422)
+    # * InvalidNumberOrRange          (423)
+    # * NoSuchMessageid               (430)
+    # * ArticleNotWanted              (435)
+    # * TransferNotPossible           (436)
+    # * TransferRejected              (437)
+    # * PostingNotPermitted           (440)
+    # * PostingFailed                 (441)
+    # * AuthenticationRequired        (480)
+    # * AuthenticationFailed          (481)
+    # * AuthenticationOutOfSequence   (482)
+    # * PrivacyRequired               (483)
+    class RetryResponse < Response
+    end
+
+    # Code: 400
+    class TemporarilyUnavailable < RetryResponse
+      def initialize(request, code, message)
+        super request, code, message, true
+      end
+    end
+
+    # Code: 403
+    class InternalFault < RetryResponse
+      def initialize(request, code, message)
+        super request, code, message, true
+      end
+    end
+
+    # Code: 411
+    class GroupUnknown < RetryResponse
+    end
+
+    # Code: 412
+    class NoGroupSelected < RetryResponse
+    end
+
+    # Code: 420
+    class InvalidArticle < RetryResponse
+    end
+
+    # Code: 421
+    class NoPreviousArticle < RetryResponse
+    end
+
+    # Code: 422
+    class NoNextArticle < RetryResponse
+    end
+
+    # Code: 423
+    class InvalidNumberOrRange < RetryResponse
+    end
+
+    # Code: 430
+    class NoSuchMessageid < RetryResponse
+    end
+
+    # Code: 435
+    class ArticleNotWanted < RetryResponse
+    end
+
+    # Code: 436
+    class TransferNotPossible < RetryResponse
+    end
+
+    # Code: 437
+    class TransferRejected < RetryResponse
+    end
+
+    # Code: 440
+    class PostingNotPermitted < RetryResponse
+    end
+
+    # Code: 441
+    class PostingFailed < RetryResponse
+    end
+
+    # Code: 480
+    class AuthenticationRequired < RetryResponse
+      def initialize(request, code, message)
+        super request, code, message, true
+      end
+    end
+
+    # Code: 481
+    class AuthenticationFailed < RetryResponse
+    end
+
+    # Code: 482
+    class AuthenticationOutOfSequence < RetryResponse
+    end
+
+    # Code: 483
+    class PrivacyRequired < RetryResponse
+      def initialize(request, code, message)
+        super request, code, message, true
+      end
+    end
+
+    # Codes: 5xx
+    # == Subclasses:
+    # * NotImplemented
+    # * SyntaxError
+    # * PermanentlyUnavailable
+    # * FeatureNotProvided
+    # * EncodingError
+    class FailResponse < Response
+    end
+
+    # Code: 500
+    class NotImplemented < FailResponse
+      def initialize(request, code, message)
+        super request, code, message, true
+      end
+    end
+
+    # Code: 501
+    class SyntaxError < FailResponse
+      def initialize(request, code, message)
+        super request, code, message, true
+      end
+    end
+
+    # Code: 502
+    class PermanentlyUnavailable < FailResponse
+      def initialize(request, code, message)
+        super request, code, message, true
+      end
+    end
+
+    # Code: 503
+    class FeatureNotProvided < FailResponse
+      def initialize(request, code, message)
+        super request, code, message, true
+      end
+    end
+
+    # Code: 500
+    class EncodingError < FailResponse
+      def initialize(request, code, message)
+        super request, code, message, true
+      end
+    end
+
+    class UnknownResponse < Response
+    end
+    RESPONSES = {
+        '100' => HelpResponse,
+        '101' => CapabilityList,
+        '111' => DateResponse,
+
+        '200' => PostingAllowed,
+        '201' => PostingProhibited,
+        '205' => ConnectionClosing,
+        '211' => GroupSelected,
+        '215' => ListInformationFollows,
+        '220' => ArticleResponse,
+        '221' => HeaderResponse,
+        '222' => BodyResponse,
+        '223' => ArticleSelected,
+        '224' => OverviewInformation,
+        '225' => HdrResponse,
+        '230' => NewnewsResponse,
+        '231' => NewgroupsResponse,
+        '235' => TransferOK,
+        '240' => ArticleReceived,
+        '281' => AuthenticationAccepted,
+
+        '335' => TransferArticle,
+        '340' => PostArticle,
+        '381' => PasswordRequired,
+
+        '400' => TemporarilyUnavailable,
+        '403' => InternalFault,
+        '411' => GroupUnknown,
+        '412' => NoGroupSelected,
+        '420' => InvalidArticle,
+        '421' => NoNextArticle,
+        '422' => NoPreviousArticle,
+        '423' => InvalidNumberOrRange,
+        '430' => NoSuchMessageid,
+        '435' => ArticleNotWanted,
+        '436' => TransferNotPossible,
+        '437' => TransferRejected,
+        '440' => PostingNotPermitted,
+        '441' => PostingFailed,
+        '480' => AuthenticationRequired,
+        '481' => AuthenticationFailed,
+        '482' => AuthenticationOutOfSequence,
+        '483' => PrivacyRequired,
+
+        '500' => NotImplemented,
+        '501' => SyntaxError,
+        '502' => PermanentlyUnavailable,
+        '503' => FeatureNotProvided,
+        '504' => EncodingError
+    }
+    CLASSES = { 
+      '1' => InformationResponse, 
+      '2' => OKResponse,
+      '3' => ContinueResponse,
+      '4' => RetryResponse,
+      '5' => FailResponse
+    }
+
+    class Response
+      attr_accessor :request
+      class << self
+        def create(request, statusline)
+          match = statusline.strip.match(/\A(\d{3})\s?(.*)\z/) or raise ProtocolError, "Unknown Response"
+          Net::NNTP.logger.debug("Response#create: request = #{request}")
+          klass = class_from_code(match[1])
+          Net::NNTP.logger.debug("Response#create: class = #{klass}")
+          this = klass.new(request, *match.captures)
+        end
+        def class_from_code(code)
+          Net::NNTP::RESPONSES[code]  or
+          Net::NNTP::CLASSES[code[0,1]] or
+          Net::NNTP::UnknownResponse
+        end
+
+      end
+    end
+
+  end
+  
+end