eventmachine-eventmachine 0.12.3

data/lib/protocols/postgres.rb

@@ -0,0 +1,261 @@
+#
+# $Id$
+#
+# Author:: Francis Cianfrocca (gmail: blackhedd)
+# Homepage::  http://rubyeventmachine.com
+# Date:: 15 November 2006
+# 
+# See EventMachine and EventMachine::Connection for documentation and
+# usage examples.
+#
+#----------------------------------------------------------------------------
+#
+# Copyright (C) 2006-08 by Francis Cianfrocca. All Rights Reserved.
+# Gmail: blackhedd
+# 
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of either: 1) the GNU General Public License
+# as published by the Free Software Foundation; either version 2 of the
+# License, or (at your option) any later version; or 2) Ruby's License.
+# 
+# See the file COPYING for complete licensing information.
+#
+#---------------------------------------------------------------------------
+#
+# 
+# 
+
+
+=begin
+PROVISIONAL IMPLEMENTATION of an evented Postgres client.
+This implements version 3 of the Postgres wire protocol, which will work
+with any Postgres version from roughly 7.4 onward.
+
+Until this code is judged ready for prime time, you have to access it by
+explicitly requiring protocols/postgres.
+
+Objective: we want to access Postgres databases without requiring threads.
+Until now this has been a problem because the Postgres client implementations 
+have all made use of blocking I/O calls, which is incompatible with a
+thread-free evented model.
+
+But rather than re-implement the Postgres Wire3 protocol, we're taking advantage
+of the existing postgres-pr library, which was originally written by Michael
+Neumann but (at this writing) appears to be no longer maintained. Still, it's
+in basically a production-ready state, and the wire protocol isn't that complicated
+anyway.
+
+We need to monkeypatch StringIO because it lacks the #readbytes method needed
+by postgres-pr.
+
+We're tucking in a bunch of require statements that may not be present in garden-variety
+EM installations. Until we find a good way to only require these if a program
+requires postgres, this file will need to be required explicitly.
+
+The StringIO monkeypatch is lifted verbatim from the standard library readbytes.rb,
+which adds method #readbytes directly to class IO. But StringIO is not a subclass of IO.
+
+We cloned the handling of postgres messages from lib/postgres-pr/connection.rb
+in the postgres-pr library, and modified it for event-handling.
+
+TODO: The password handling in dispatch_conn_message is totally incomplete.
+
+
+We return Deferrables from the user-level operations surfaced by this interface.
+Experimentally, we're using the pattern of always returning a boolean value as the
+first argument of a deferrable callback to indicate success or failure. This is
+instead of the traditional pattern of calling Deferrable#succeed or #fail, and
+requiring the user to define both a callback and an errback function.
+
+Sample code:
+require 'eventmachine'
+require 'protocols/postgres' # provisionally needed
+
+EM.run {
+	db = EM.connect_unix_domain( "/tmp/.s.PGSQL.5432", EM::P::Postgres3 )
+	db.connect( dbname, username, psw ).callback do |status|
+		if status
+			db.query( "select * from some_table" ).callback do |status, result, errors|
+				if status
+					result.rows.each do |row|
+						p row
+					end
+				end
+			end
+		end
+	end
+}
+
+
+
+=end
+
+
+require 'readbytes'
+require 'postgres-pr/message'
+require 'postgres-pr/connection'
+require 'stringio'
+
+include PostgresPR
+
+class StringIO
+  # Reads exactly +n+ bytes.
+  #
+  # If the data read is nil an EOFError is raised.
+  #
+  # If the data read is too short a TruncatedDataError is raised and the read
+  # data is obtainable via its #data method.
+  def readbytes(n)
+    str = read(n)
+    if str == nil
+      raise EOFError, "End of file reached"
+    end
+    if str.size < n
+      raise TruncatedDataError.new("data truncated", str) 
+    end
+    str
+  end
+end
+
+
+module EventMachine; module Protocols; class Postgres3 < EventMachine::Connection
+
+
+	def initialize
+		@data = ""
+		@params = {}
+	end
+
+	def connect db, user, psw=nil
+		d = EM::DefaultDeferrable.new
+		d.timeout 15
+
+		if @pending_query || @pending_conn
+			d.succeed false, "Operation already in progress"
+		else
+			@pending_conn = d
+			prms = {"user"=>user, "database"=>db}
+			@user = user
+			if psw
+				@password = psw
+				#prms["password"] = psw
+			end
+			send_data PostgresPR::StartupMessage.new( 3 << 16, prms ).dump
+		end
+
+		d
+	end
+
+	def query sql
+		d = EM::DefaultDeferrable.new
+		d.timeout 15
+
+		if @pending_query || @pending_conn
+			d.succeed false, "Operation already in progress"
+		else
+			@r = PostgresPR::Connection::Result.new
+			@e = []
+			@pending_query = d
+			send_data PostgresPR::Query.dump(sql)
+		end
+
+		d
+	end
+
+
+	def receive_data data
+		@data << data
+		while @data.length >= 5
+			pktlen = @data[1...5].unpack("N").first
+			if @data.length >= (1 + pktlen)
+				pkt = @data.slice!(0...(1+pktlen))
+				m = StringIO.open( pkt, "r" ) {|io| PostgresPR::Message.read( io ) }
+				if @pending_conn
+					dispatch_conn_message m
+				elsif @pending_query
+					dispatch_query_message m
+				else
+					raise "Unexpected message from database"
+				end
+			else
+				break # very important, break out of the while
+			end
+		end
+	end
+
+
+	def unbind
+		if o = (@pending_query || @pending_conn)
+			o.succeed false, "lost connection"
+		end
+	end
+
+	# Cloned and modified from the postgres-pr.
+	def dispatch_conn_message msg
+		case msg
+		when AuthentificationClearTextPassword
+			raise ArgumentError, "no password specified" if @password.nil?
+			send_data PasswordMessage.new(@password).dump
+
+		when AuthentificationCryptPassword
+			raise ArgumentError, "no password specified" if @password.nil?
+			send_data PasswordMessage.new(@password.crypt(msg.salt)).dump
+
+		when AuthentificationMD5Password
+			raise ArgumentError, "no password specified" if @password.nil?
+			require 'digest/md5'
+
+			m = Digest::MD5.hexdigest(@password + @user) 
+			m = Digest::MD5.hexdigest(m + msg.salt)
+			m = 'md5' + m
+			send_data PasswordMessage.new(m).dump
+
+		when AuthentificationKerberosV4, AuthentificationKerberosV5, AuthentificationSCMCredential
+			raise "unsupported authentification"
+
+		when AuthentificationOk
+		when ErrorResponse
+			raise msg.field_values.join("\t")
+		when NoticeResponse
+			@notice_processor.call(msg) if @notice_processor
+		when ParameterStatus
+			@params[msg.key] = msg.value
+		when BackendKeyData
+			# TODO
+			#p msg
+		when ReadyForQuery
+			# TODO: use transaction status
+			pc,@pending_conn = @pending_conn,nil
+			pc.succeed true
+		else
+			raise "unhandled message type"
+		end
+	end
+
+	# Cloned and modified from the postgres-pr.
+	def dispatch_query_message msg
+		case msg
+		when DataRow
+			@r.rows << msg.columns
+		when CommandComplete
+			@r.cmd_tag = msg.cmd_tag
+		when ReadyForQuery
+			pq,@pending_query = @pending_query,nil
+			pq.succeed true, @r, @e
+		when RowDescription
+			@r.fields = msg.fields
+		when CopyInResponse
+		when CopyOutResponse
+		when EmptyQueryResponse
+		when ErrorResponse
+			# TODO
+			@e << msg
+		when NoticeResponse
+			@notice_processor.call(msg) if @notice_processor
+		else
+			# TODO
+		end
+	end
+
+end; end; end
+

data/lib/protocols/saslauth.rb

@@ -0,0 +1,179 @@
+# $Id$
+#
+# Author:: Francis Cianfrocca (gmail: blackhedd)
+# Homepage::  http://rubyeventmachine.com
+# Date:: 15 November 2006
+# 
+# See EventMachine and EventMachine::Connection for documentation and
+# usage examples.
+#
+#----------------------------------------------------------------------------
+#
+# Copyright (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
+# Gmail: blackhedd
+# 
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of either: 1) the GNU General Public License
+# as published by the Free Software Foundation; either version 2 of the
+# License, or (at your option) any later version; or 2) Ruby's License.
+# 
+# See the file COPYING for complete licensing information.
+#
+#---------------------------------------------------------------------------
+#
+# 
+# 
+
+
+
+module EventMachine
+	module Protocols
+
+		# Implements SASL authd.
+		# This is a very, very simple protocol that mimics the one used
+		# by saslauthd and pwcheck, two outboard daemons included in the
+		# standard SASL library distro.
+		# The only thing this is really suitable for is SASL PLAIN
+		# (user+password) authentication, but the SASL libs that are
+		# linked into standard servers (like imapd and sendmail) implement
+		# the other ones.
+		#
+		# SASL-auth is intended for reasonably fast operation inside a
+		# single machine, so it has no transport-security (although there
+		# have been multi-machine extensions incorporating transport-layer
+		# encryption).
+		#
+		# The standard saslauthd module generally runs privileged and does
+		# its work by referring to the system-account files.
+		#
+		# This feature was added to EventMachine to enable the development
+		# of custom authentication/authorization engines for standard servers.
+		#
+		# To use SASLauth, include it in a class that subclasses EM::Connection,
+		# and reimplement the validate method.
+		#
+		# The typical way to incorporate this module into an authentication
+		# daemon would be to set it as the handler for a UNIX-domain socket.
+		# The code might look like this:
+		#
+		#  EM.start_unix_domain_server( "/var/run/saslauthd/mux", MyHandler )
+		#  File.chmod( 0777, "/var/run/saslauthd/mux")
+		#
+		# The chmod is probably needed to ensure that unprivileged clients can
+		# access the UNIX-domain socket.
+		#
+		# It's also a very good idea to drop superuser privileges (if any), after
+		# the UNIX-domain socket has been opened.
+		#--
+		# Implementation details: assume the client can send us pipelined requests,
+		# and that the client will close the connection.
+		#
+		# The client sends us four values, each encoded as a two-byte length field in
+		# network order followed by the specified number of octets.
+		# The fields specify the username, password, service name (such as imap),
+		# and the "realm" name. We send back the barest minimum reply, a single
+		# field also encoded as a two-octet length in network order, followed by
+		# either "NO" or "OK" - simplicity itself.
+		#
+		# We enforce a maximum field size just as a sanity check.
+		# We do NOT automatically time out the connection.
+		#
+		# The code we use to parse out the values is ugly and probably slow.
+		# Improvements welcome.
+		#
+		module SASLauth
+
+			MaxFieldSize = 128*1024
+			def post_init
+				super
+				@sasl_data = ""
+				@sasl_values = []
+			end
+
+			def receive_data data
+				@sasl_data << data
+				while @sasl_data.length >= 2
+					len = (@sasl_data[0,2].unpack("n")).first
+					raise "SASL Max Field Length exceeded" if len > MaxFieldSize
+					if @sasl_data.length >= (len + 2)
+						@sasl_values << @sasl_data[2,len]
+						@sasl_data.slice!(0...(2+len))
+						if @sasl_values.length == 4
+							send_data( validate(*@sasl_values) ? "\0\002OK" : "\0\002NO" )
+							@sasl_values.clear
+						end
+					else
+						break
+					end
+				end
+			end
+
+			def validate username, psw, sysname, realm
+				p username
+				p psw
+				p sysname
+				p realm
+				true
+			end
+		end
+
+		# Implements the SASL authd client protocol.
+		# This is a very, very simple protocol that mimics the one used
+		# by saslauthd and pwcheck, two outboard daemons included in the
+		# standard SASL library distro.
+		# The only thing this is really suitable for is SASL PLAIN
+		# (user+password) authentication, but the SASL libs that are
+		# linked into standard servers (like imapd and sendmail) implement
+		# the other ones.
+		#
+		# You can use this module directly as a handler for EM Connections,
+		# or include it in a module or handler class of your own.
+		#
+		# First connect to a SASL server (it's probably a TCP server, or more
+		# likely a Unix-domain socket). Then call the #validate? method,
+		# passing at least a username and a password. #validate? returns
+		# a Deferrable which will either succeed or fail, depending
+		# on the status of the authentication operation.
+		#
+		module SASLauthclient
+			MaxFieldSize = 128*1024
+
+			def validate? username, psw, sysname=nil, realm=nil
+
+				str = [username, psw, sysname, realm].map {|m|
+					[(m || "").length, (m || "")]
+				}.flatten.pack( "nA*" * 4 )
+				send_data str
+
+				d = EM::DefaultDeferrable.new
+				@queries.unshift d
+				d
+			end
+
+			def post_init
+				@sasl_data = ""
+				@queries = []
+			end
+
+			def receive_data data
+				@sasl_data << data
+
+				while @sasl_data.length > 2
+					len = (@sasl_data[0,2].unpack("n")).first
+					raise "SASL Max Field Length exceeded" if len > MaxFieldSize
+					if @sasl_data.length >= (len + 2)
+						val = @sasl_data[2,len]
+						@sasl_data.slice!(0...(2+len))
+						q = @queries.pop
+						(val == "NO") ? q.fail : q.succeed
+					else
+						break
+					end
+				end
+			end
+		end
+
+	end
+end
+
+

data/lib/protocols/smtpclient.rb

@@ -0,0 +1,308 @@
+# $Id$
+#
+# Author:: Francis Cianfrocca (gmail: blackhedd)
+# Homepage::  http://rubyeventmachine.com
+# Date:: 16 July 2006
+# 
+# See EventMachine and EventMachine::Connection for documentation and
+# usage examples.
+#
+#----------------------------------------------------------------------------
+#
+# Copyright (C) 2006-07 by Francis Cianfrocca. All Rights Reserved.
+# Gmail: blackhedd
+# 
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of either: 1) the GNU General Public License
+# as published by the Free Software Foundation; either version 2 of the
+# License, or (at your option) any later version; or 2) Ruby's License.
+# 
+# See the file COPYING for complete licensing information.
+#
+#---------------------------------------------------------------------------
+#
+# 
+
+
+#require 'base64'
+require 'ostruct'
+
+module EventMachine
+module Protocols
+
+
+	class SmtpClient < Connection
+		include EventMachine::Deferrable
+		include EventMachine::Protocols::LineText2
+
+		# This is the external entry point.
+		#
+		# The argument is a hash containing these values:
+		# :host => a string containing the IP address or host name of the SMTP server to connect to.
+		# :port => optional, defaults to 25.
+		# :domain => required String. This is passed as the argument to the EHLO command.
+		# :starttls => optional. If it evaluates true, then the client will initiate STARTTLS with
+		#   the server, and abort the connection if the negotiation doesn't succeed.
+		#   TODO, need to be able to pass certificate parameters with this option.
+		# :auth => optional hash of auth parameters. If not given, then no auth will be attempted.
+		#   (In that case, the connection will be aborted if the server requires auth.)
+		#   Specify the hash value :type to determine the auth type, along with additional parameters
+		#   depending on the type.
+		#   Currently only :type => :plain is supported. Pass additional parameters :username (String),
+		#   and :password (either a String or a Proc that will be called at auth-time).
+		#   Example: :auth => {:type=>:plain, :username=>"mickey@disney.com", :password=>"mouse"}
+		# :from => required String. Specifies the sender of the message. Will be passed as the argument
+		#   to the MAIL FROM. Do NOT enclose the argument in angle-bracket (<>) characters.
+		#   The connection will abort if the server rejects the value.
+		# :to => required String or Array of Strings. The recipient(s) of the message. Do NOT enclose
+		#   any of the values in angle-brackets (<>) characters. It's NOT a fatal error if one or more
+		#   recipients are rejected by the server. (Of course, if ALL of them are, the server will most
+		#   likely trigger an error when we try to send data.) An array of codes containing the status
+		#   of each requested recipient is available after the call completes. TODO, we should define
+		#   an overridable stub that will be called on rejection of a recipient or a sender, giving
+		#   user code the chance to try again or abort the connection.
+		# :header => Required hash of values to be transmitted in the header of the message. The hash
+		#   keys are the names of the headers (do NOT append a trailing colon), and the values are strings
+		#   containing the header values. TODO, support Arrays of header values, which would cause us to
+		#   send that specific header line more than once.
+		#   Example: :header => {"Subject" => "Bogus", "CC" => "myboss@example.com"}
+		# :body => Optional string, defaults blank. This will be passed as the body of the email message.
+		#   TODO, this needs to be significantly beefed up. As currently written, this requires the caller
+		#   to properly format the input into CRLF-delimited lines of 7-bit characters in the standard
+		#   SMTP transmission format. We need to be able to automatically convert binary data, and add
+		#   correct line-breaks to text data. I think the :body parameter should remain as it is, and we
+		#   should add a :content parameter that contains autoconversions and/or conversion parameters.
+		#   Then we can check if either :body or :content is present and do the right thing.
+		# :verbose => Optional. If true, will cause a lot of information (including the server-side of the
+		#   conversation) to be dumped to $>.
+		#
+		def self.send args={}
+			args[:port] ||= 25
+			args[:body] ||= ""
+
+=begin
+			(I don't think it's possible for EM#connect to throw an exception under normal
+			circumstances, so this original code is stubbed out. A connect-failure will result
+			in the #unbind method being called without calling #connection_completed.)
+			begin
+				EventMachine.connect( args[:host], args[:port], self) {|c|
+					# According to the EM docs, we will get here AFTER post_init is called.
+					c.args = args
+					c.set_comm_inactivity_timeout 60
+				}
+			rescue
+				# We'll get here on a connect error. This code mimics the effect
+				# of a call to invoke_internal_error. Would be great to DRY this up.
+				# (Actually, it may be that we never get here, if EM#connect catches
+				# its errors internally.)
+				d = EM::DefaultDeferrable.new
+				d.set_deferred_status(:failed, {:error=>[:connect, 500, "unable to connect to server"]})
+				d
+			end
+=end
+			EventMachine.connect( args[:host], args[:port], self) {|c|
+				# According to the EM docs, we will get here AFTER post_init is called.
+				c.args = args
+				c.set_comm_inactivity_timeout 60
+			}
+
+		end
+
+		attr_writer :args
+
+		def post_init
+			@return_values = OpenStruct.new
+			@return_values.start_time = Time.now
+		end
+
+		def connection_completed
+			@responder = :receive_signon
+			@msg = []
+		end
+
+		# We can get here in a variety of ways, all of them being failures unless
+		# the @succeeded flag is set. If a protocol success was recorded, then don't
+		# set a deferred success because the caller will already have done it
+		# (no need to wait until the connection closes to invoke the callbacks).
+		#
+		def unbind
+			unless @succeeded
+				@return_values.elapsed_time = Time.now - @return_values.start_time
+				@return_values.responder = @responder
+				@return_values.code = @code
+				@return_values.message = @msg
+				set_deferred_status(:failed, @return_values)
+			end
+		end
+
+		def receive_line ln
+			$>.puts ln if @args[:verbose]
+			@range = ln[0...1].to_i
+			@code = ln[0...3].to_i
+			@msg << ln[4..-1]
+			unless ln[3...4] == '-'
+				$>.puts @responder if @args[:verbose]
+				send @responder
+				@msg.clear
+			end
+		end
+
+		# We encountered an error from the server and will close the connection.
+		# Use the error and message the server returned.
+		#
+		def invoke_error
+			@return_values.elapsed_time = Time.now - @return_values.start_time
+			@return_values.responder = @responder
+			@return_values.code = @code
+			@return_values.message = @msg
+			set_deferred_status :failed, @return_values
+			send_data "QUIT\r\n"
+			close_connection_after_writing
+		end
+
+		# We encountered an error on our side of the protocol and will close the connection.
+		# Use an extra-protocol error code (900) and use the message from the caller.
+		#
+		def invoke_internal_error msg = "???"
+			@return_values.elapsed_time = Time.now - @return_values.start_time
+			@return_values.responder = @responder
+			@return_values.code = 900
+			@return_values.message = msg
+			set_deferred_status :failed, @return_values
+			send_data "QUIT\r\n"
+			close_connection_after_writing
+		end
+
+		def receive_signon
+			return invoke_error unless @range == 2
+			send_data "EHLO #{@args[:domain]}\r\n"
+			@responder = :receive_ehlo_response
+		end
+
+		def receive_ehlo_response
+			return invoke_error unless @range == 2
+			@server_caps = @msg
+			invoke_starttls
+		end
+
+		def invoke_starttls
+			if @args[:starttls]
+				# It would be more sociable to first ask if @server_caps contains
+				# the string "STARTTLS" before we invoke it, but hey, life's too short.
+				send_data "STARTTLS\r\n"
+				@responder = :receive_starttls_response
+			else
+				invoke_auth
+			end
+		end
+		def receive_starttls_response
+			return invoke_error unless @range == 2
+			start_tls
+			invoke_auth
+		end
+
+
+
+		# Perform an authentication. If the caller didn't request one, then fall through
+		# to the mail-from state.
+		def invoke_auth
+			if @args[:auth]
+				if @args[:auth][:type] == :plain
+					psw = @args[:auth][:password]
+					if psw.respond_to?(:call)
+						psw = psw.call
+					end
+					#str = Base64::encode64("\0#{@args[:auth][:username]}\0#{psw}").chomp
+					str = ["\0#{@args[:auth][:username]}\0#{psw}"].pack("m").chomp
+					send_data "AUTH PLAIN #{str}\r\n"
+					@responder = :receive_auth_response
+				else
+					return invoke_internal_error("unsupported auth type")
+				end
+			else
+				invoke_mail_from
+			end
+		end
+		def receive_auth_response
+			return invoke_error unless @range == 2
+			invoke_mail_from
+		end
+
+		def invoke_mail_from
+			send_data "MAIL FROM: <#{@args[:from]}>\r\n"
+			@responder = :receive_mail_from_response
+		end
+		def receive_mail_from_response
+			return invoke_error unless @range == 2
+			invoke_rcpt_to
+		end
+
+		def invoke_rcpt_to
+			@rcpt_responses ||= []
+			l = @rcpt_responses.length
+			to = @args[:to].is_a?(Array) ? @args[:to] : [@args[:to].to_s]
+			if l < to.length
+				send_data "RCPT TO: <#{to[l]}>\r\n"
+				@responder = :receive_rcpt_to_response
+			else
+				e = @rcpt_responses.select {|rr| rr.last == 2}
+				if e and e.length > 0
+					invoke_data
+				else
+					invoke_error
+				end
+			end
+		end
+		def receive_rcpt_to_response
+			@rcpt_responses << [@code, @msg, @range]
+			invoke_rcpt_to
+		end
+
+		def invoke_data
+			send_data "DATA\r\n"
+			@responder = :receive_data_response
+		end
+		def receive_data_response
+			return invoke_error unless @range == 3
+
+			# The data to send can be given either in @args[:content] (an array or string of raw data
+			# which MUST be in correct SMTP body format, including a trailing dot line), or a header and
+			# body given in @args[:header] and @args[:body].
+			#
+			if @args[:content]
+				send_data @args[:content].to_s
+			else
+				# The header can be a hash or an array.
+				if @args[:header].is_a?(Hash)
+					(@args[:header] || {}).each {|k,v| send_data "#{k}: #{v}\r\n" }
+				else
+					send_data @args[:header].to_s
+				end
+				send_data "\r\n"
+
+				if @args[:body].is_a?(Array)
+					@args[:body].each {|e| send_data e}
+				else
+					send_data @args[:body].to_s
+				end
+
+				send_data "\r\n.\r\n"
+			end
+
+			@responder = :receive_message_response
+		end
+		def receive_message_response
+			return invoke_error unless @range == 2
+			send_data "QUIT\r\n"
+			close_connection_after_writing
+			@succeeded = true
+			@return_values.elapsed_time = Time.now - @return_values.start_time
+			@return_values.responder = @responder
+			@return_values.code = @code
+			@return_values.message = @msg
+			set_deferred_status :succeeded, @return_values
+		end
+	end
+end
+end
+