xasin-telegram 0.2.3 → 0.3.0

data/lib/xasin/telegram/HTTPCore.rb

@@ -1,64 +1,116 @@
 
 require 'net/http'
 require 'json'
+require 'shellwords'
 
 module Xasin
 module Telegram
+	# This class handles the direct connection to the Telegram API
+	# All it does is handle a receive loop with the fitting update IDs, as well
+	# as a rescue'd "perform post" message.
 	class HTTPCore
 		def initialize(apikey)
 			@apikey = apikey;
 
 			@lastUpdateID = 0;
-			Thread.new do
+			# Start the receive loop. Shouldn't crash, but if it does we
+			# want to know.
+			@receiveThread = Thread.new do
 				receive_loop();
-			end.abort_on_exception = true
+			end
+			@receiveThread.abort_on_exception = true
 
+			# Receptors are class instances that will receive updates
+			# from the HTTP update connection
 			@receptors = Array.new();
 		end
 
-		def perform_post(method, data = nil)
-			callAddress = URI "https://api.telegram.org/bot#{@apikey}/#{method}"
-
-			begin
-				if data
-					outData = Hash.new();
-					data.each do |key, val|
-						if(val.is_a? Hash or val.is_a? Array)
-							outData[key] = val.to_json
-						else
-							outData[key] = val;
-						end
-					end
+		private def _double_json_data(data)
+			return {} unless data
 
-					response = Net::HTTP.post_form(callAddress, outData);
+			out_data = {}
+			# JSON-Ify nested Hashes and Arrays to a String before the main
+			# POST request is performed. Needed by Telegram, it seems.
+			data.each do |key, val|
+				if(val.is_a? Hash or val.is_a? Array)
+					out_data[key] = val.to_json
 				else
-					response = Net::HTTP.get callAddress
+					out_data[key] = val;
 				end
+			end
+
+			out_data
+		end
+
+		private def _raw_post(addr, data)
+			d_str = Shellwords.escape(data.to_json)
+
+			response = `curl -s -X POST -H "Content-Type: application/json" -d #{d_str} "#{addr}"`
 
-				response = JSON.parse(response.body, symbolize_names: true);
+			JSON.parse(response, symbolize_names: true)
+		end
+		# Perform a POST request.
+		# @param method [String]  The Telegram bot API method that should be called
+		# @param data [nil, Hash] The data to be sent with the command.
+		#   Caution, any nested Hashes and Arrays will be converted to JSON
+		#   BEFORE the Hash itself is also JSON-ified. Telegram apparently
+		#   needs this to work.
+		def perform_post(method, data = nil)
+			call_address = "https://api.telegram.org/bot#{@apikey}/#{method}"
+
+			# Rescue-construct to prevent a HTTP error from
+			# crashing our system.
+			timeoutLen = data[:timeout] if data.is_a? Hash
+			timeoutLen ||= 4;
+			retryCount = 0;
+			begin
+				Timeout.timeout(timeoutLen) do
+					return _raw_post(call_address, _double_json_data(data));
+				end
 			rescue
+				retryCount += 1;
+				return {} if retryCount >= 3;
+
 				sleep 0.5;
 				retry
 			end
+		end
 
-			return response;
+		def feed_receptors(data)
+			# Hand it out to the receptors
+			@receptors.each do |r|
+				begin
+					r.handle_packet(data);
+				rescue => e
+					warn "Error in repector: #{e}"
+					warn e.backtrace.join("\n");
+				end
+			end
 		end
 
+		# Handle receiving of the data from Telegram API
+		# This is done via the "getUpdates" HTTP Request, with a timeout
+		# of 20s
+		# Update-ID offset is handled automagically by the system, so you needn't
+		# worry about it.
 		def receive_loop()
 			loop do
 				begin
+					# Perform the update request
 					packet = perform_post("getUpdates", {timeout: 20, offset: @lastUpdateID + 1})
 
 					next unless packet[:ok];
+					# Check if there even was a message sent by Telegram
+					# Due to the 20s timeout, a zero-length reply can happen
 					next if packet[:result].length == 0;
 
+					# Handle each result individually.
 					packet[:result].each do |data|
 						hUpdateID = data[:update_id].to_i
+						# Calculate the maximum Update ID (for the offset "getUpdates" parameter)
 						@lastUpdateID = [hUpdateID, @lastUpdateID].max
 
-						@receptors.each do |r|
-							r.handle_packet(data);
-						end
+						feed_receptors data
 					end
 				rescue
 					sleep 1
@@ -67,6 +119,7 @@ module Telegram
 			end
 		end
 
+		# TODO check if the class supports handle_packet
 		def attach_receptor(receptorClass)
 			@receptors << receptorClass;
 		end

data/lib/xasin/telegram/Handler.rb

@@ -0,0 +1,301 @@
+
+require_relative 'HTTPCore.rb'
+require_relative 'Message.rb'
+require_relative 'User.rb'
+
+module Xasin
+	module Telegram
+		# Dummy class to provide sensible defaults for most things.
+		# Only really matters for priority, so that we can sort
+		# after that.
+		#
+		# @todo Test if the sorting is the right way around
+		class OnTelegramEvent
+			attr_accessor :priority
+
+			def initialize()
+				@priority = 0
+			end
+
+			def nomp_message(message) end
+
+			def <=>(other)
+				self.priority <=> other.priority
+			end
+		end
+
+		# Main handler class, provides interfaces.
+		# It gives the user a way to send messages, set callbacks
+		# and retrieve chats with detailed data.
+		# More in-depth functions for messages are provided in the
+		# message class itself.
+		class Handler
+			# Returns the {HTTPCore} used to communicate with
+			# Telegram.
+			attr_reader :core
+
+			# List of permissions.
+			# Set this to a Hash containing arrays to
+			# included permissions, i.e. the following:
+			# {
+			#   "admin" => ["default", "advanced"]
+			# }
+			#
+			# A user with "admin" would now also have "default" and "advanced"
+			# permissions for command execution.
+			#
+			# @note The :sudo permission will always overwrite everything, use
+			#   only for developer access!
+			attr_accessor :permissions_list
+
+			def self.from_options(options)
+				out_handler = Handler.new(options['Key']);
+
+				if perms = options['Permissions']
+					raise ArgumentError, 'Permission list must be a hash!' unless perms.is_a? Hash
+					out_handler.permissions_list = perms
+				end
+
+				if u_list = options['Users']
+					raise ArgumentError, 'Userlist must be a hash!' unless u_list.is_a? Hash
+
+					u_list.each do |key, extra_opts|
+						u = out_handler[key];
+
+						unless u
+							warn "User #{key} could not be found."
+							next
+						end
+
+						if u_perms = extra_opts['Permissions']
+							u.add_permissions u_perms
+						end
+					end
+				end
+
+				out_handler
+			end
+
+			# initialize a new Handler.
+			#
+			# @param [String, HTTPCore] http_core The core to use, either
+			#   a String representing the API Key, or an initialized Telegram Core
+			def initialize(http_core)
+				@core = if(http_core.is_a? Telegram::HTTPCore)
+						http_core;
+					elsif http_core.is_a? String
+						Telegram::HTTPCore.new(http_core);
+					else
+						raise ArgumentError, "Could not make a valid HTTPCore from string!"
+					end
+
+				@core.attach_receptor(self);
+
+				@chats = {}
+
+				@on_telegram_event = []
+
+				@permissions_list = {}
+			end
+
+			private def handle_message(message)
+				message = Message.new(self, message);
+
+				return unless message.valid
+
+				(@on_telegram_event + message.chat&.on_telegram_event).sort.each do |evt|
+					evt.nomp_message message
+
+					break if message.handled
+				end
+			end
+
+			# Handle an incoming callback query (inline keyboard button press)
+			# as received from the HTTP Core
+			private def handle_callback_query(cbq)
+				# Generate a fake message to feed into the message
+				# handling system ;)
+
+				fake_msg = {
+					from: cbq[:from],
+					text: cbq[:data],
+					chat: cbq[:message][:chat],
+					message_id: cbq[:message][:message_id]
+				}
+
+				handle_message fake_msg
+
+				# Send out a callback query reply (i.e. Telegram now knows we saw it)
+				@core.perform_post("answerCallbackQuery", {callback_query_id: cbq[:id]})
+			end
+
+			# Internal function, called from the Telegram Core.
+			# This is meant to be fed a Hash representing one update object
+			# from Telegram's /getUpdate function
+			def handle_packet(packet)
+				if m = packet[:message]
+					handle_message m
+				end
+
+				if cbq = packet[:callback_query]
+					handle_callback_query cbq
+				end
+			end
+
+			# Return a {Chat} object directly constructed from the
+			# passed Hash.
+			#
+			# Pass a Hash here to either fetch a chat with matching ID, or
+			# else constuct a new chat from the provided data. Can be used
+			# for getting a chat from a Message object, or adding a chat from
+			# stored chat configs.
+			def chat_from_object(object)
+				chat_id = object[:id];
+
+				if c = @chats[chat_id]
+					return c
+				end
+
+				c = nil;
+				if object[:username]
+					c = User.new(self, object);
+				else
+					c = Chat.new(self, object);
+				end
+
+				@chats[chat_id] = c;
+
+				c
+			end
+
+			# Try to find a chat with matching string ID.
+			# Useful when trying to find a chat by username, or a channel.
+			def chat_from_string(str)
+				@chats.each do |_, chat|
+					if chat.str_id == str
+						return chat
+					end
+				end
+
+				nil
+			end
+
+			# Return the {Chat} with given ID.
+			# This will either return a known chat with the wanted ID, or else
+			# will call getChat to fetch details on the wanted chat and
+			# construct a new {Chat} object. May also return nil if the wanted
+			# chat does not exist!
+			def chat_from_id(num)
+				if c = @chats[num]
+					return c
+				end
+
+				chat_obj = @core.perform_post('getChat', { chat_id: num });
+
+				return nil unless chat_obj[:ok]
+
+				chat_from_object chat_obj[:result]
+			end
+
+			# Convenience function to get a chat by any means.
+			# Pass a Number (interpreted as Chat ID), String (username)
+			# or Hash into here to try and fetch a Chat based on the parameter.
+			# Chat ID is preferred as it will let the system fetch the Chat from
+			# Telegram's API.
+			def get_chat(object)
+				if object.is_a? Chat
+					object
+				elsif object.is_a? Hash
+					chat_from_object object;
+				elsif object.is_a? Numeric
+					chat_from_id object
+				elsif object.is_a? String
+					if object =~ /^@/
+						chat_from_id object
+					else
+						chat_from_string object
+					end
+				end
+			end
+			alias [] get_chat
+
+			# Send a message to a given chat.
+			# The following options are supported when sending:
+			#
+			# - silent: true/false, whether to enable or disable notification
+			# - reply_to: {Message}/nil, try to reply to the given message ID.
+			# - inline_keyboard: Hash or Array of Hashes, to set the inline keyboard
+			#    with fitting commands.
+			#
+			# @note When a Inline Keyboard is used, the button presses are
+			#   internally interpreted as messages. This way, they can feed into
+			#   the /command syntax.
+			def send_message(chat, text, **options)
+				raise ArgumentError, "Text needs to be a string" unless text.is_a? String
+
+				if text.length > 900
+					text = text[0..900] + "..."
+				end
+
+				out_data = {
+					chat_id: get_chat(chat).chat_id,
+					parse_mode: 'HTML',
+					text: text
+				}
+
+				if r = options[:reply_to]
+					out_data[:reply_to_message_id] = r.to_i
+				end
+
+				if options[:silent]
+					out_data[:disable_notification] = true;
+				end
+
+				if layout = options[:inline_keyboard]
+					out_data[:reply_markup] = KeyboardLayout.new(layout).ilk_reply_markup
+				end
+
+				reply = @core.perform_post('sendMessage', out_data);
+
+				Message.new(self, reply[:result]);
+			end
+
+			# Add a new callback on any generic message.
+			# The provided block will be called with the Message as parameter
+			# when something arrives. May additionally specify a RegExp to match
+			# against, in which case the match is a second parameter to the
+			# block.
+			def on_message(regexp = nil, &block)
+				raise ArgumentError, 'Block must be given!' unless block_given?
+
+				out_evt = OnMessage.new({ block: block, regexp: regexp });
+				@on_telegram_event << out_evt
+
+				out_evt
+			end
+
+			# Add a new callback on any /command message.
+			# The provided block will be called whenever the fitting /command
+			# is called. Additionally, by setting a list of priorities
+			# (options[:priorities] = []), only certain users may be allowed
+			# to execute a command.
+			#
+			# The block will be passed the message as argument.
+			def on_command(command, **options, &block)
+				raise ArgumentError, 'Block must be given!' unless block_given?
+
+				options[:block] = block
+				options[:command] = command
+
+				out_evt = OnCommand.new(options);
+				@on_telegram_event << out_evt
+
+				out_evt
+			end
+		end
+	end
+end
+
+require_relative 'OnMessage.rb'
+require_relative 'OnCommand.rb'
+require_relative 'KeyboardLayout.rb'

data/lib/xasin/telegram/KeyboardLayout.rb

@@ -0,0 +1,67 @@
+
+module Xasin
+	module Telegram
+		class KeyboardLayout
+			def initialize(start_config = nil)
+				@rows = Array.new()
+
+				if start_config.is_a? Hash
+					start_config = [start_config]
+				end
+
+				if start_config.is_a? Array
+					start_config.each_index do |i|
+						j = 0
+						start_config[i].each do |k, v|
+							set_button(k, v, r: i, c: j)
+							j += 1
+						end
+					end
+				end
+			end
+
+			def [](i)
+				@rows[i]
+			end
+
+			def set_button(name, command = nil, c: 0, r: 0)
+				command ||= name
+
+				@rows[r] ||= [];
+				out_button = {text: name}
+				if command =~ /^(http|tg)/
+					out_button[:url] = command
+				else
+					out_button[:callback_data] = command
+				end
+
+				@rows[r][c] = out_button
+			end
+
+			def ilk_reply_markup()
+				return { inline_keyboard: to_ilk_layout }
+			end
+
+			def to_ilk_layout()
+				out_data = [];
+
+				@rows.each do |row|
+					next if row.nil?
+					next if row.empty?
+
+					formatted_row = []
+
+					row.each do |button|
+						next if button.nil?
+
+						formatted_row << button
+					end
+
+					out_data << formatted_row unless formatted_row.empty?
+				end
+
+				out_data
+			end
+		end
+	end
+end