telegram-bot 0.13.1 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d72dfb00c1dab4bf5b80276354ff102737b537a02c1ba40656bb9ab6eb28288
-  data.tar.gz: ed15a4fa045c319c035ab4b5ec9b06169b4a7455004de59fbaeac7656de7c795
+  metadata.gz: a35f4302d428cf24b66fa6122bcb5852b8680b85259bd2dd070a6a8e9aff5b74
+  data.tar.gz: 53fa7c7a14b637cbcae403b87786e93c2b685fa2461cbef9edd9e68c869f9206
 SHA512:
-  metadata.gz: d2cd894d342bb01a901b2c24a243165b580adfd5bcbaef632d3d272693424b5b2f13b7236edcf32dcb897d123f68410c97e0c3235106e31f4de06ace5a712406
-  data.tar.gz: cb95a89bcf60e2993d6011203c7f6e4e56f725e2455cbe31e351f60fd72f9e2e40296da284c1147f36f4dcb5f9d004efa2f99aa8791563e3282e8ece64c29499
+  metadata.gz: 7d788d67fcc120b5f4ce0ac6299a3e6ab1015213b1a8710f1f7ea4311deca27381befae700ff708813f1c2d47dfbc9144c6cd901b5a39d8ca4843b405c7b2124
+  data.tar.gz: '09b511503e001cd6fe9a25072a384ac04b7c0de2a4e728894d3c4c10a5badcbb7872072fb9f3d10cf3c5cbae0edc14d7bb3ee70966ecaa01f09d6c8844edbf01'

data/CHANGELOG.md

@@ -1,3 +1,25 @@
+# Unreleased
+
+# 0.14.0
+
+- Make integration & controller specs consistent.
+  __Breaking changes__ for controller specs:
+    - Changed signature `dispatch(bot, update) => dispatch(update, bot)`.
+    - `update` helper is symbolized by default.
+    - `build_update(type, data)` is dropped in favor of `deep_stringify(type => data)`.
+- Provide support for integration testing of bots in poller mode and non-Rails apps.
+  __Breaking changes__:
+    - Requiring `telegram/bot/rspec/integration` is deprecated in favor of
+      `telegram/bot/rspec/integration/rails`.
+    - `:telegram_bot` rspec tag is replaced with `telegram_bot: :rails`.
+- __Breaking change__. Use bang-methods as actions for commands.
+  This prevents calling context contextual actions and payload specific actions with commands.
+  Translation helper strips `!` from action name for lazy translations.
+- __Breaking change__. Drop `.context_handler`, `.context_to_action!` methods.
+  Use pass action name directly to `#save_context`.
+  It's the same as `.context_to_action!` is enabled by default.
+- Class-level helper for lazy translations.
+
 # 0.13.1
 
 - Extracted typed response mappings to telegram-bot-types gem.

data/README.md

@@ -4,6 +4,8 @@
 [![Code Climate](https://codeclimate.com/github/telegram-bot-rb/telegram-bot/badges/gpa.svg)](https://codeclimate.com/github/telegram-bot-rb/telegram-bot)
 [![Build Status](https://travis-ci.org/telegram-bot-rb/telegram-bot.svg)](https://travis-ci.org/telegram-bot-rb/telegram-bot)
 
+__Breaking changes in v0.14!__ See [upgrading guide](https://github.com/telegram-bot-rb/telegram-bot/wiki/Upgrading-to-0.14).
+
 Tools for developing Telegram bots. Best used with Rails, but can be used in
 [standalone app](https://github.com/telegram-bot-rb/telegram-bot/wiki/Not-rails-application).
 Supposed to be used in webhook-mode in production, and poller-mode
@@ -154,14 +156,11 @@ class Telegram::WebhookController < Telegram::Bot::UpdatesController
   #   chosen_inline_result(result_id, query)
   #   callback_query(data)
 
-  # Define public methods to respond to commands.
+  # Define public methods ending with `!` to handle commands.
   # Command arguments will be parsed and passed to the method.
   # Be sure to use splat args and default values to not get errors when
   # someone passed more or less arguments in the message.
-  #
-  # For some commands like /message or /123 method names should start with
-  # `on_` to avoid conflicts.
-  def start(data = nil, *)
+  def start!(data = nil, *)
     # do_smth_with(data)
 
     # There are `chat` & `from` shortcut methods.
@@ -192,8 +191,9 @@ end
 #### Reply helpers
 
 There are helpers to respond for basic actions. They just set chat/message/query
-identifiers from update. See [`ReplyHelpers`](https://github.com/telegram-bot-rb/telegram-bot/blob/master/lib/telegram/bot/updates_controller/reply_helpers.rb) module for more information.
-Here are this methods signatures:
+identifiers from update. See
+[`ReplyHelpers`](https://github.com/telegram-bot-rb/telegram-bot/blob/master/lib/telegram/bot/updates_controller/reply_helpers.rb)
+module for more information. Here are this methods signatures:
 
 ```ruby
 def respond_with(type, params); end
@@ -256,11 +256,11 @@ class Telegram::WebhookController < Telegram::Bot::UpdatesController
   # You can override global config for this controller.
   self.session_store = :file_store
 
-  def write(text = nil, *)
+  def write!(text = nil, *)
     session[:text] = text
   end
 
-  def read(*)
+  def read!(*)
     respond_with :message, text: session[:text]
   end
 
@@ -283,35 +283,28 @@ it asks you for additional argument. There is `MessageContext` for this:
 class Telegram::WebhookController < Telegram::Bot::UpdatesController
   include Telegram::Bot::UpdatesController::MessageContext
 
-  def rename(*)
+  def rename!(*)
     # set context for the next message
-    save_context :rename
+    save_context :rename_from_message
     respond_with :message, text: 'What name do you like?'
   end
 
   # register context handlers to handle this context
-  context_handler :rename do |*words|
+  def rename_from_message(*words)
     update_name words[0]
     respond_with :message, text: 'Renamed!'
   end
 
-  # You can do it in other way:
-  def rename(name = nil, *)
+  # You can use same action name as context name:
+  def rename!(name = nil, *)
     if name
       update_name name
       respond_with :message, text: 'Renamed!'
     else
-      save_context :rename
+      save_context :rename!
       respond_with :message, text: 'What name do you like?'
     end
   end
-
-  # This will call #rename like if it is called with message '/rename %text%'
-  context_handler :rename
-
-  # If you have a lot of such methods you can call this method
-  # to use context value as action name for all contexts which miss handlers:
-  context_to_action!
 end
 ```
 
@@ -394,11 +387,11 @@ Telegram::Bot::UpdatesPoller.start(bot, controller_class)
 
 ### Testing
 
-There is `Telegram::Bot::ClientStub` class to stub client for tests.
-Instead of performing API requests it stores them in `requests` hash.
+There is a `Telegram::Bot::ClientStub` class to stub client for tests.
+Instead of performing API requests it stores them in a `requests` hash.
 
 To stub all possible clients use `Telegram::Bot::ClientStub.stub_all!` before
-initializing clients. Here is template for RSpec:
+initializing clients. Here is a template for RSpec:
 
 ```ruby
 # environments/test.rb
@@ -416,48 +409,83 @@ RSpec.configure do |config|
 end
 ```
 
-There are integration and controller contexts for RSpec and some built-in matchers:
+RSpec contexts and helpers are included automatically for groups and examples with matching
+tags. In RSpec < 3.4 it's required to use `include_context` explicitly.
+See [list of available helpers](https://github.com/telegram-bot-rb/telegram-bot/tree/master/lib/telegram/bot/rspec)
+for details.
+
+There are 3 types of integration tests:
+
+- `:rails` - for testing bot in webhooks-mode in Rails application.
+  It simulates webhook requests POSTing data to controller's endpoint.
+  It works on the top of requests specs, so `rspec-rails` gem is required.
+- `:rack` - For testing bot in webhooks-mode in non-Rails application.
+  It uses `rack-test` gem to POST requests to bot's endpoint.
+- `:poller` - Calls `.dispatch` directly on controller class.
+
+Pick the appropriate one, then require `telegram/bot/rspec/integration/#{type}`
+and mark spec group with tag `telegram_bot: type`. See configuration options
+for each type in
+[telegram/bot/rspec/integration/](https://github.com/telegram-bot-rb/telegram-bot/tree/master/lib/telegram/bot/rspec/integration).
+
+Here is an example test for a Rails app:
 
 ```ruby
 # spec/requests/telegram_webhooks_spec.rb
-require 'telegram/bot/rspec/integration'
+require 'telegram/bot/rspec/integration/rails'
+
+RSpec.describe TelegramWebhooksController, telegram_bot: :rails do
+  # for old RSpec:
+  # include_context 'telegram/bot/integration/rails'
+
+  # Main method is #dispatch(update). Some helpers are:
+  #   dispatch_message(text, options = {})
+  #   dispatch_command(cmd, *args)
 
-RSpec.describe TelegramWebhooksController, :telegram_bot do
-  # for old rspec add:
-  # include_context 'telegram/bot/integration'
+  # Available matchers can be found in Telegram::Bot::RSpec::ClientMatchers.
+  it 'shows usage of basic matchers'
+    # The most basic one is #make_telegram_request(bot, endpoint, params_matcher)
+    expect { dispatch_command(:start) }.
+      to make_telegram_request(bot, :sendMessage, hash_including(text: 'msg text'))
 
-  describe '#start' do
+    # There are some shortcuts for dispatching basic updates and testing responses.
+    expect { dispatch_message('Hi') }.to send_telegram_message(bot, /msg regexp/, some: :option)
+  end
+
+  describe '#start!' do
     subject { -> { dispatch_command :start } }
+    # Using built in matcher for `respond_to`:
     it { should respond_with_message 'Hi there!' }
   end
 
-  # There is context for callback queries with related matchers.
+  # There is context for callback queries with related matchers,
+  # use :callback_query tag to include it.
   describe '#hey_callback_query', :callback_query do
     let(:data) { "hey:#{name}" }
     let(:name) { 'Joe' }
     it { should answer_callback_query('Hey Joe') }
     it { should edit_current_message :text, text: 'Done' }
+  end
 end
+```
+
+There is a context for testing bot controller in the way similar to Rails controller tests.
+It's supposed to be a low-level alternative for integration tests. Among the differences is
+that controller tests use a single controller instance for all dispatches in specific exaple,
+session is stubbed (does not use configured store engine), and update is not serialized
+so it also supports mocks. This can be useful for unit testing, but should not be used as
+the default way to test the bot.
 
-# For controller specs use
+```ruby
 require 'telegram/bot/updates_controller/rspec_helpers'
 RSpec.describe TelegramWebhooksController, type: :telegram_bot_controller do
-  # for old rspec add:
+  # for old RSpec:
   # include_context 'telegram/bot/updates_controller'
-end
-
-# Matchers are available for custom specs:
-include Telegram::Bot::RSpec::ClientMatchers
 
-expect(&process_update).to send_telegram_message(bot, /msg regexp/, some: :option)
-expect(&process_update).
-  to make_telegram_request(bot, :sendMessage, hash_including(text: 'msg text'))
+  # Same helpers and matchers like dispatch_command, answer_callback_query are available here.
+end
 ```
 
-Place integration tests inside `spec/requests`
-when using RSpec's `infer_spec_type_from_file_location!`,
-or just add `type: :request` to `describe`.
-
 See sample app for more examples.
 
 ### Deployment

data/lib/telegram/bot.rb

@@ -14,10 +14,10 @@ module Telegram
 
     module_function
 
-    def deprecation_0_14
+    def deprecation_0_15
       @deprecation ||= begin
         require 'active_support/deprecation'
-        ActiveSupport::Deprecation.new('0.14', 'Telegram::Bot')
+        ActiveSupport::Deprecation.new('0.15', 'Telegram::Bot')
       end
     end
 

data/lib/telegram/bot/middleware.rb

@@ -1,8 +1,7 @@
 require 'active_support/concern'
 require 'active_support/core_ext/hash/indifferent_access'
 require 'active_support/json'
-require 'action_dispatch/http/mime_type'
-require 'action_dispatch/http/request'
+require 'action_dispatch'
 
 module Telegram
   module Bot

data/lib/telegram/bot/routes_helper.rb

@@ -24,33 +24,6 @@ module Telegram
         end
       end
 
-      #   # Create routes for all Telegram.bots to use same controller:
-      #   telegram_webhooks TelegramController
-      #
-      #   # Or pass custom bots usin any of supported config options:
-      #   telegram_webhooks TelegramController, [
-      #     bot,
-      #     {token: token, username: username},
-      #     other_bot_token,
-      #   ]
-      def telegram_webhooks(controllers, bots = nil, **options)
-        Bot.deprecation_0_14.deprecation_warning(:telegram_webhooks, <<-TXT.strip_heredoc)
-          It brings unnecessary complexity and encourages writeng less readable code.
-          Please use telegram_webhook method instead.
-          It's signature `telegram_webhook(controller, bot = :default, **options)`.
-          Multiple-bot environments now requires calling this method in a loop
-          or using statement for each bot.
-        TXT
-        unless controllers.is_a?(Hash)
-          bots = bots ? Array.wrap(bots) : Telegram.bots.values
-          controllers = Hash[bots.map { |x| [x, controllers] }]
-        end
-        controllers.each do |bot, controller|
-          controller, bot_options = controller if controller.is_a?(Array)
-          telegram_webhook(controller, bot, options.merge(bot_options || {}))
-        end
-      end
-
       # Define route which processes requests using given controller and bot.
       #
       #   telegram_webhook TelegramController, bot

data/lib/telegram/bot/rspec.rb

@@ -2,6 +2,15 @@ module Telegram
   module Bot
     module RSpec
       autoload :ClientMatchers, 'telegram/bot/rspec/client_matchers'
+
+      module_function
+
+      # Yelds a block if `include_context` is supported.
+      def with_include_context
+        ::RSpec.configure do |config|
+          yield(config) if config.respond_to?(:include_context)
+        end
+      end
     end
   end
 end

data/lib/telegram/bot/rspec/callback_query_helpers.rb

@@ -0,0 +1,39 @@
+require 'telegram/bot/rspec'
+require 'telegram/bot/rspec/message_helpers'
+
+# Shared helpers for testing callback query updates.
+RSpec.shared_context 'telegram/bot/callback_query' do
+  include_context 'telegram/bot/message_helpers'
+
+  subject { -> { dispatch callback_query: payload } }
+  let(:payload) { {id: callback_query_id, from: from, message: message, data: data} }
+  let(:callback_query_id) { 11 }
+  let(:message_id) { 22 }
+  let(:message) { {message_id: message_id, chat: chat, text: 'message text'} }
+  let(:data) { raise '`let(:data) { "callback query data here" }` is required' }
+
+  # Matcher to check that origin message got edited.
+  def edit_current_message(type, options = {})
+    description = 'edit current message'
+    options = options.merge(
+      message_id: message[:message_id],
+      chat_id: chat_id,
+    )
+    Telegram::Bot::RSpec::ClientMatchers::MakeTelegramRequest.new(
+      bot, :"editMessage#{type.to_s.camelize}", description: description
+    ).with(hash_including(options))
+  end
+
+  # Matcher to check that callback query is answered.
+  def answer_callback_query(text = Regexp.new(''), options = {})
+    description = "answer callback query with #{text.inspect}"
+    text = a_string_matching(text) if text.is_a?(Regexp)
+    options = options.merge(
+      callback_query_id: payload[:id],
+      text: text,
+    )
+    Telegram::Bot::RSpec::ClientMatchers::MakeTelegramRequest.new(
+      bot, :answerCallbackQuery, description: description
+    ).with(hash_including(options))
+  end
+end

data/lib/telegram/bot/rspec/integration.rb

@@ -1,85 +1,10 @@
-RSpec.shared_context 'telegram/bot/integration' do
-  let(:bot) { Telegram.bot }
-  let(:default_message_options) { {from: from, chat: chat} }
-  let(:from) { {id: from_id} }
-  let(:from_id) { 123 }
-  let(:chat) { {id: chat_id} }
-  let(:chat_id) { 456 }
-  let(:controller_path) do
-    route_name = Telegram::Bot::RoutesHelper.route_name_for_bot(bot)
-    Rails.application.routes.url_helpers.public_send("#{route_name}_path")
-  end
-  let(:request_headers) do
-    {
-      'ACCEPT' => 'application/json',
-      'Content-Type' => 'application/json',
-    }
-  end
-  let(:clear_session?) { described_class.respond_to?(:session_store) }
-  before { described_class.session_store.try!(:clear) if clear_session? }
-
-  include Telegram::Bot::RSpec::ClientMatchers
-
-  def dispatch(update)
-    if ActionPack::VERSION::MAJOR >= 5
-      post(controller_path, params: update.to_json, headers: request_headers)
-    else
-      post(controller_path, update.to_json, request_headers)
-    end
-  end
-
-  def dispatch_message(text, options = {})
-    dispatch message: default_message_options.merge(options).merge(text: text)
-  end
-
-  def dispatch_command(*args)
-    options = args.last.is_a?(Hash) ? args.pop : {}
-    dispatch_message("/#{args.join ' '}", options)
-  end
-
-  # Matcher to check response. Make sure to define `let(:chat_id)`.
-  def respond_with_message(expected = Regexp.new(''))
-    raise 'Define chat_id to use respond_with_message' unless defined?(chat_id)
-    send_telegram_message(bot, expected, chat_id: chat_id)
-  end
-end
-
-RSpec.shared_context 'telegram/bot/callback_query', callback_query: true do
-  include_context 'telegram/bot/integration'
-
-  subject { -> { dispatch callback_query: payload } }
-  let(:payload) { {id: 11, from: from, message: message, data: data} }
-  let(:message) { {message_id: 22, chat: chat, text: 'message text'} }
-
-  # Matcher to check that origin message got edited.
-  def edit_current_message(type, options = {})
-    description = 'edit current message'
-    options = options.merge(
-      message_id: message[:message_id],
-      chat_id: chat_id,
-    )
-    Telegram::Bot::RSpec::ClientMatchers::MakeTelegramRequest.new(
-      bot, :"editMessage#{type.to_s.camelize}", description: description
-    ).with(hash_including(options))
-  end
-
-  # Matcher to check that callback query is answered.
-  def answer_callback_query(text = Regexp.new(''), options = {})
-    description = "answer callback query with #{text.inspect}"
-    text = a_string_matching(text) if text.is_a?(Regexp)
-    options = options.merge(
-      callback_query_id: payload[:id],
-      text: text,
-    )
-    Telegram::Bot::RSpec::ClientMatchers::MakeTelegramRequest.new(
-      bot, :answerCallbackQuery, description: description
-    ).with(hash_including(options))
-  end
-end
-
-RSpec.configure do |config|
-  if config.respond_to?(:include_context)
-    config.include_context 'telegram/bot/integration', :telegram_bot
-    config.include_context 'telegram/bot/callback_query', :telegram_bot, :callback_query
-  end
+require 'telegram/bot'
+Telegram::Bot.deprecation_0_15.warn(
+  "`require 'telegram/bot/rspec/integration'` is deprecated in favor of " \
+  "`require 'telegram/bot/rspec/integration/rails'`"
+)
+require 'telegram/bot/rspec/integration/rails'
+
+Telegram::Bot::RSpec.with_include_context do |config|
+  config.include_context 'telegram/bot/integration/rails', telegram_bot: true
 end

data/lib/telegram/bot/rspec/integration/poller.rb

@@ -0,0 +1,14 @@
+require 'telegram/bot/rspec/integration/shared'
+
+RSpec.shared_context 'telegram/bot/integration/poller' do
+  include_context 'telegram/bot/integration/shared'
+  let(:controller_class) { described_class }
+
+  def dispatch(update)
+    controller_class.dispatch(bot, update.as_json)
+  end
+end
+
+Telegram::Bot::RSpec.with_include_context do |config|
+  config.include_context 'telegram/bot/integration/poller', telegram_bot: :poller
+end

data/lib/telegram/bot/rspec/integration/rack.rb

@@ -0,0 +1,24 @@
+require 'telegram/bot/rspec/integration/shared'
+require 'rack/test'
+
+RSpec.shared_context 'telegram/bot/integration/rack' do
+  include_context 'telegram/bot/integration/shared'
+  include Rack::Test::Methods
+
+  let(:request_path) { raise '`let(:request_path) { path to bot }` is required' }
+  let(:app) { raise '`let(:app) { your rack app here }` is required' }
+  let(:request_headers) do
+    {
+      'ACCEPT' => 'application/json',
+      'CONTENT_TYPE' => 'application/json',
+    }
+  end
+
+  def dispatch(update)
+    post request_path, update.to_json, request_headers
+  end
+end
+
+Telegram::Bot::RSpec.with_include_context do |config|
+  config.include_context 'telegram/bot/integration/rack', telegram_bot: :rack
+end

data/lib/telegram/bot/rspec/integration/rails.rb

@@ -0,0 +1,28 @@
+require 'telegram/bot/rspec/integration/shared'
+
+RSpec.shared_context 'telegram/bot/integration/rails', type: :request do
+  include_context 'telegram/bot/integration/shared'
+
+  let(:controller_path) do
+    route_name = Telegram::Bot::RoutesHelper.route_name_for_bot(bot)
+    Rails.application.routes.url_helpers.public_send("#{route_name}_path")
+  end
+  let(:request_headers) do
+    {
+      'Accept' => 'application/json',
+      'Content-Type' => 'application/json',
+    }
+  end
+
+  def dispatch(update)
+    if ActionPack::VERSION::MAJOR >= 5
+      post(controller_path, params: update.to_json, headers: request_headers)
+    else
+      post(controller_path, update.to_json, request_headers)
+    end
+  end
+end
+
+Telegram::Bot::RSpec.with_include_context do |config|
+  config.include_context 'telegram/bot/integration/rails', telegram_bot: :rails
+end

data/lib/telegram/bot/rspec/integration/shared.rb

@@ -0,0 +1,14 @@
+require 'active_support/json'
+require 'telegram/bot'
+require 'telegram/bot/rspec/message_helpers'
+require 'telegram/bot/rspec/callback_query_helpers'
+
+RSpec.shared_context 'telegram/bot/integration/shared' do
+  include Telegram::Bot::RSpec::ClientMatchers
+  include_context 'telegram/bot/message_helpers'
+  include_context 'telegram/bot/callback_query', :callback_query
+
+  let(:bot) { Telegram.bot }
+  let(:clear_session?) { described_class.respond_to?(:session_store) }
+  before { described_class.session_store.try!(:clear) if clear_session? }
+end

data/lib/telegram/bot/rspec/message_helpers.rb

@@ -0,0 +1,26 @@
+# Shared helpers for testing message updates.
+RSpec.shared_context 'telegram/bot/message_helpers' do
+  let(:default_message_options) { {from: from, chat: chat} }
+  let(:from) { {id: from_id} }
+  let(:from_id) { 123 }
+  let(:chat) { {id: chat_id} }
+  let(:chat_id) { 456 }
+
+  # Shortcut for dispatching messages with default params.
+  def dispatch_message(text, options = {})
+    dispatch message: default_message_options.merge(options).merge(text: text)
+  end
+
+  # Dispatch command message.
+  def dispatch_command(cmd, *args)
+    options = args.last.is_a?(Hash) ? args.pop : {}
+    args.unshift("/#{cmd}")
+    dispatch_message(args.join(' '), options)
+  end
+
+  # Matcher to check response. Make sure to define `let(:chat_id)`.
+  def respond_with_message(expected = Regexp.new(''))
+    raise 'Define chat_id to use respond_with_message' unless defined?(chat_id)
+    send_telegram_message(bot, expected, chat_id: chat_id)
+  end
+end

data/lib/telegram/bot/updates_controller.rb

@@ -1,4 +1,5 @@
 require 'abstract_controller'
+require 'active_support/core_ext/string/inflections'
 require 'active_support/callbacks'
 require 'active_support/version'
 
@@ -54,12 +55,14 @@ module Telegram
       abstract!
 
       %w[
-        instrumentation
-        log_subscriber
-        reply_helpers
-        rescue
-        session
-      ].each { |file| require "telegram/bot/updates_controller/#{file}" }
+        Commands
+        Instrumentation
+        LogSubscriber
+        ReplyHelpers
+        Rescue
+        Session
+        Translation
+      ].each { |name| require "telegram/bot/updates_controller/#{name.underscore}" }
 
       %w[
         CallbackQueryContext
@@ -78,9 +81,12 @@ module Telegram
                           skip_after_callbacks_if_terminated: true
       end
 
-      include AbstractController::Translation
+      include Commands
       include Rescue
       include ReplyHelpers
+      include Translation
+      # Add instrumentations hooks at the bottom, to ensure they instrument
+      # all the methods properly.
       include Instrumentation
 
       extend Session::ConfigMethods
@@ -96,8 +102,6 @@ module Telegram
         shipping_query
         pre_checkout_query
       ].freeze
-      CMD_REGEX = %r{\A/([a-z\d_]{,31})(@(\S+))?(\s|$)}i
-      CONFLICT_CMD_REGEX = Regexp.new("^(#{PAYLOAD_TYPES.join('|')}|\\d)")
 
       class << self
         # Initialize controller and process update.
@@ -105,27 +109,6 @@ module Telegram
           new(*args).dispatch
         end
 
-        # Overrid it to filter or transform commands.
-        # Default implementation is to convert to downcase and add `on_` prefix
-        # for conflicting commands.
-        def action_for_command(cmd)
-          cmd.downcase!
-          cmd.match(CONFLICT_CMD_REGEX) ? "on_#{cmd}" : cmd
-        end
-
-        # Fetches command from text message. All subsequent words are returned
-        # as arguments.
-        # If command has mention (eg. `/test@SomeBot`), it returns commands only
-        # for specified username. Set `username` to `true` to accept
-        # any commands.
-        def command_from_text(text, username = nil)
-          return unless text
-          match = text.match(CMD_REGEX)
-          return unless match
-          mention = match[3]
-          [match[1], text.split.drop(1)] if username == true || !mention || mention == username
-        end
-
         def payload_from_update(update)
           update && PAYLOAD_TYPES.find do |type|
             item = update[type]
@@ -134,8 +117,7 @@ module Telegram
         end
       end
 
-      attr_internal_reader :update, :bot, :payload, :payload_type, :is_command
-      alias_method :command?, :is_command
+      attr_internal_reader :update, :bot, :payload, :payload_type
       delegate :username, to: :bot, prefix: true, allow_nil: true
 
       # Second argument can be either update object with hash access & string
@@ -175,54 +157,64 @@ module Telegram
 
       # Processes current update.
       def dispatch
-        @_is_command, action, args = action_for_payload
+        action, args = action_for_payload
         process(action, *args)
       end
 
+      attr_internal_reader :action_options
+
+      # It provides support for passing array as action, where first vaule
+      # is action name and second is action metadata.
+      # This metadata is stored inside action_options
+      def process(action, *args)
+        action, options = action if action.is_a?(Array)
+        @_action_options = options || {}
+        super
+      end
+
+      # There are multiple ways how action name is calculated for update
+      # (see Commands, MessageContext, etc.). This method represents the
+      # way how action was calculated for current udpate.
+      #
+      # Some of possible values are `:payload, :command, :message_context`.
+      def action_type
+        action_options[:type] || :payload
+      end
+
       # Calculates action name and args for payload.
       # Uses `action_for_#{payload_type}` methods.
       # If this method doesn't return anything
       # it uses fallback with action same as payload type.
-      # Returns array `[is_command?, action, args]`.
+      # Returns array `[action, args]`.
       def action_for_payload
         if payload_type
           send("action_for_#{payload_type}") || action_for_default_payload
         else
-          [false, :unsupported_payload_type, []]
+          [:unsupported_payload_type, []]
         end
       end
 
       def action_for_default_payload
-        [false, payload_type, [payload]]
-      end
-
-      # If payload is a message with command, then returned action is an
-      # action for this command.
-      # Separate method, so it can be easily overriden (ex. MessageContext).
-      #
-      # This is not used for edited messages/posts. It process them as basic updates.
-      def action_for_message
-        cmd, args = self.class.command_from_text(payload['text'], bot_username)
-        cmd &&= self.class.action_for_command(cmd)
-        [true, cmd, args] if cmd
+        [payload_type, [payload]]
       end
-      alias_method :action_for_channel_post, :action_for_message
 
       def action_for_inline_query
-        [false, payload_type, [payload['query'], payload['offset']]]
+        [payload_type, [payload['query'], payload['offset']]]
       end
 
       def action_for_chosen_inline_result
-        [false, payload_type, [payload['result_id'], payload['query']]]
+        [payload_type, [payload['result_id'], payload['query']]]
       end
 
       def action_for_callback_query
-        [false, payload_type, [payload['data']]]
+        [payload_type, [payload['data']]]
       end
 
-      # Silently ignore unsupported messages.
-      # Params are `action, *args`.
-      def action_missing(*)
+      # Silently ignore unsupported messages to not fail when user crafts
+      # an update with usupported command, callback query context, etc.
+      def action_missing(action, *_args)
+        logger.debug { "The action '#{action}' is not defined in #{self.class.name}" } if logger
+        nil
       end
 
       PAYLOAD_TYPES.each do |type|

data/lib/telegram/bot/updates_controller/callback_query_context.rb

@@ -17,8 +17,12 @@ module Telegram
           context, new_data = context_from_callback_query
           if context
             action_name = "#{context}_callback_query"
-            [false, action_name, [new_data]] if action_method?(action_name)
-          end || super
+            if action_method?(action_name)
+              action_options = {type: :callback_query_context, context: context}
+              return [[action_name, action_options], [new_data]]
+            end
+          end
+          super
         end
 
         def context_from_callback_query

data/lib/telegram/bot/updates_controller/commands.rb

@@ -0,0 +1,44 @@
+module Telegram
+  module Bot
+    class UpdatesController
+      #  Support for parsing commands
+      module Commands
+        CMD_REGEX = %r{\A/([a-z\d_]{,31})(@(\S+))?(\s|$)}i
+
+        class << self
+          # Fetches command from text message. All subsequent words are returned
+          # as arguments.
+          # If command has mention (eg. `/test@SomeBot`), it returns commands only
+          # for specified username. Set `username` to `true` to accept
+          # any commands.
+          def command_from_text(text, username = nil)
+            return unless text
+            match = text.match(CMD_REGEX)
+            return unless match
+            mention = match[3]
+            [match[1], text.split.drop(1)] if username == true || !mention || mention == username
+          end
+        end
+
+        # Override it to filter or transform commands.
+        # Default implementation is to downcase and add `!` suffix.
+        def action_for_command(cmd)
+          "#{cmd.downcase}!"
+        end
+
+        # If payload is a message with command, then returned action is an
+        # action for this command.
+        # Separate method, so it can be easily overriden (ex. MessageContext).
+        #
+        # This is not used for edited messages/posts. It process them as basic updates.
+        def action_for_message
+          cmd, args = Commands.command_from_text(payload['text'], bot_username)
+          return unless cmd
+          [[action_for_command(cmd), type: :command, command: cmd], args]
+        end
+
+        alias_method :action_for_channel_post, :action_for_message
+      end
+    end
+  end
+end

data/lib/telegram/bot/updates_controller/message_context.rb

@@ -2,62 +2,42 @@ module Telegram
   module Bot
     class UpdatesController
       # Allows to store context in session and treat next message according to this context.
+      #
+      # It provides `save_context` method to store method name
+      # to be used as action for next update:
+      #
+      #     def set_location!(*)
+      #       save_context(:set_location_from_message)
+      #       respond_with :message, text: 'Where are you?'
+      #     end
+      #
+      #     def set_location_from_messge(city = nil, *)
+      #       # update
+      #     end
+      #
+      #     # OR
+      #     # This will support both `/set_location city_name`, and `/set_location`
+      #     # with subsequent refinement.
+      #     def set_location!(city = nil, *)
+      #       if city
+      #         # update
+      #       else
+      #         save_context(:set_location!)
+      #         respond_with :message, text: 'Where are you?'
+      #       end
+      #     end
       module MessageContext
         extend ActiveSupport::Concern
 
         include Session
 
-        module ClassMethods
-          def context_handlers
-            @_context_handlers ||= {}
-          end
-
-          # Registers handler for context.
-          #
-          #     context_handler :rename do |*|
-          #       resource.update!(name: payload['text'])
-          #     end
-          #
-          #     # To run other action with all the callbacks:
-          #     context_handler :rename do |*words|
-          #       process(:rename, *words)
-          #     end
-          #
-          #     # Or just
-          #     context_handler :rename, :your_action_to_call
-          #     context_handler :rename # to call :rename
-          #
-          def context_handler(context = nil, action = nil, &block)
-            context &&= context.to_sym
-            if block
-              action = "_context_handler_#{context}"
-              define_method(action, &block)
-            end
-            context_handlers[context] = action || context
-          end
-
-          attr_reader :context_to_action
-
-          # Use it to use context value as action name for all contexts
-          # which miss handlers.
-          # For security reasons it supports only action methods and will
-          # raise AbstractController::ActionNotFound if context is invalid.
-          def context_to_action!
-            @context_to_action = true
-          end
-        end
-
         # Action to clear context.
-        def cancel
+        def cancel!
           # Context is already cleared in action_for_message
         end
 
         private
 
-        # Context is read from the session to treat messages
-        # according to previous request.
-        attr_reader :context
-
         # Controller may have multiple sessions, let it be possible
         # to select session for message context.
         def message_context_session
@@ -68,10 +48,11 @@ module Telegram
         # it has higher priority than contextual action.
         def action_for_message
           val = message_context_session.delete(:context)
-          @context = val && val.to_sym
+          context = val && val.to_s
           super || context && begin
-            handler = handler_for_context
-            [true, handler, payload['text'].try!(:split) || []] if handler
+            args = payload['text'].try!(:split) || []
+            action = action_for_message_context(context)
+            [[action, type: :message_context, context: context], args]
           end
         end
 
@@ -80,18 +61,16 @@ module Telegram
           message_context_session[:context] = context
         end
 
-        def handler_for_context
-          self.class.context_handlers[context] || self.class.context_to_action && begin
-            action_name = context.to_s
-            unless action_method?(action_name)
-              raise AbstractController::ActionNotFound,
-                "The action '#{action_name}' could not be set from context " \
-                "for #{self.class.name}. " \
-                'context_to_action! supports only action methods for security reasons. ' \
-                'If you need to call this action use context_handler for it.'
-            end
-            action_name
-          end
+        # Returns action name for message context. By default it's the same as context name.
+        # Raises AbstractController::ActionNotFound if action is not available.
+        # This differs from other cases where invalid actions are silently ignored,
+        # because message context is controlled by developer, and users are not able
+        # to construct update to run any specific context.
+        def action_for_message_context(context)
+          action = context.to_s
+          return action if action_method?(action)
+          raise AbstractController::ActionNotFound,
+            "The context action '#{action}' is not found in #{self.class.name}"
         end
       end
     end

data/lib/telegram/bot/updates_controller/rspec_helpers.rb

@@ -1,37 +1,32 @@
 require 'telegram/bot/updates_controller/testing'
+require 'telegram/bot/rspec/message_helpers'
+require 'telegram/bot/rspec/callback_query_helpers'
 
 RSpec.shared_context 'telegram/bot/updates_controller' do
+  include Telegram::Bot::RSpec::ClientMatchers
+  include_context 'telegram/bot/message_helpers'
+  include_context 'telegram/bot/callback_query', :callback_query
+
   let(:controller_class) { described_class }
   let(:controller) do
-    controller_class.new(bot, update).tap do |x|
+    controller_class.new(*controller_args).tap do |x|
       x.extend Telegram::Bot::UpdatesController::Testing
     end
   end
-  let(:update) { build_update(payload_type, payload) }
+  let(:controller_args) { [bot, deep_stringify(update)] }
+  let(:update) { {payload_type => payload} }
   let(:payload_type) { :some_type }
   let(:payload) { double(:payload) }
   let(:bot) { Telegram::Bot::ClientStub.new(bot_name) }
   let(:bot_name) { 'bot' }
   let(:session) { controller.send(:session) }
-  let(:from_id) { 123 }
-  let(:chat_id) { 456 }
-  let(:default_message_options) { {from: {id: from_id}, chat: {id: chat_id}} }
-
-  include Telegram::Bot::RSpec::ClientMatchers
-
-  def dispatch(bot = self.bot, update = self.update)
-    controller.dispatch_again(bot, update)
-  end
 
-  def dispatch_message(text, options = {})
-    update = build_update :message, default_message_options.merge(options).merge(text: text)
-    dispatch bot, update
-  end
-
-  def build_update(type, content)
-    deep_stringify type => content
+  # Process update.
+  def dispatch(update = self.update, bot = self.bot)
+    controller.dispatch_again(bot, deep_stringify(update))
   end
 
+  # Same as `.as_json` but mocks-friendly.
   def deep_stringify(input)
     case input
     when Array then input.map(&method(__callee__))
@@ -39,15 +34,8 @@ RSpec.shared_context 'telegram/bot/updates_controller' do
     else input
     end
   end
-
-  # Matcher to check response. Make sure to define `let(:chat_id)`.
-  def respond_with_message(expected)
-    send_telegram_message(bot, expected, chat_id: chat_id)
-  end
 end
 
-RSpec.configure do |config|
-  if config.respond_to?(:include_context)
-    config.include_context 'telegram/bot/updates_controller', type: :telegram_bot_controller
-  end
+Telegram::Bot::RSpec.with_include_context do |config|
+  config.include_context 'telegram/bot/updates_controller', type: :telegram_bot_controller
 end

data/lib/telegram/bot/updates_controller/translation.rb

@@ -0,0 +1,47 @@
+module Telegram
+  module Bot
+    class UpdatesController
+      # Provides helpers similar to AbstractController::Translation
+      # but by default uses `action_name_i18n_key` in lazy translation keys
+      # which strips `!` from action names by default. This makes translating
+      # strings for commands more convenient.
+      #
+      # To disable this behaviour use `alias_method :action_name_i18n_key, :action_name`.
+      module Translation
+        extend ActiveSupport::Concern
+
+        module ClassMethods
+          # Class-level helper for lazy translations.
+          def translate(key, options = {})
+            key = "#{controller_path.tr('/', '.')}#{key}" if key.to_s.start_with?('.')
+            I18n.translate(key, options)
+          end
+          alias :t :translate
+        end
+
+        # See toplevel description.
+        def translate(key, options = {})
+          if key.to_s.start_with?('.')
+            path = controller_path.tr('/', '.')
+            defaults = [:"#{path}#{key}"]
+            defaults << options[:default] if options[:default]
+            options[:default] = defaults.flatten
+            key = "#{path}.#{action_name_i18n_key}#{key}"
+          end
+          I18n.translate(key, options)
+        end
+        alias :t :translate
+
+        # Strips trailing `!` from action_name.
+        def action_name_i18n_key
+          action_name.chomp('!')
+        end
+
+        def localize(*args)
+          I18n.localize(*args)
+        end
+        alias :l :localize
+      end
+    end
+  end
+end

data/lib/telegram/bot/version.rb

@@ -1,6 +1,6 @@
 module Telegram
   module Bot
-    VERSION = '0.13.1'.freeze
+    VERSION = '0.14.0'.freeze
 
     def self.gem_version
       Gem::Version.new VERSION

data/telegram-bot.gemspec

@@ -17,6 +17,9 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
+  spec.post_install_message = 'Breaking changes in v0.14! ' \
+    'See upgrade guide at https://github.com/telegram-bot-rb/telegram-bot/wiki/Upgrading-to-0.14'
+
   spec.required_ruby_version = '~> 2.0'
 
   spec.add_dependency 'actionpack', '>= 4.0', '< 6.0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: telegram-bot
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.14.0
 platform: ruby
 authors:
 - Max Melentiev
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-05-28 00:00:00.000000000 Z
+date: 2018-06-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -138,10 +138,17 @@ files:
 - lib/telegram/bot/railtie.rb
 - lib/telegram/bot/routes_helper.rb
 - lib/telegram/bot/rspec.rb
+- lib/telegram/bot/rspec/callback_query_helpers.rb
 - lib/telegram/bot/rspec/client_matchers.rb
 - lib/telegram/bot/rspec/integration.rb
+- lib/telegram/bot/rspec/integration/poller.rb
+- lib/telegram/bot/rspec/integration/rack.rb
+- lib/telegram/bot/rspec/integration/rails.rb
+- lib/telegram/bot/rspec/integration/shared.rb
+- lib/telegram/bot/rspec/message_helpers.rb
 - lib/telegram/bot/updates_controller.rb
 - lib/telegram/bot/updates_controller/callback_query_context.rb
+- lib/telegram/bot/updates_controller/commands.rb
 - lib/telegram/bot/updates_controller/instrumentation.rb
 - lib/telegram/bot/updates_controller/log_subscriber.rb
 - lib/telegram/bot/updates_controller/message_context.rb
@@ -150,6 +157,7 @@ files:
 - lib/telegram/bot/updates_controller/rspec_helpers.rb
 - lib/telegram/bot/updates_controller/session.rb
 - lib/telegram/bot/updates_controller/testing.rb
+- lib/telegram/bot/updates_controller/translation.rb
 - lib/telegram/bot/updates_controller/typed_update.rb
 - lib/telegram/bot/updates_poller.rb
 - lib/telegram/bot/version.rb
@@ -158,7 +166,7 @@ homepage: https://github.com/telegram-bot-rb/telegram-bot
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message: Breaking changes in v0.14! See upgrade guide at https://github.com/telegram-bot-rb/telegram-bot/wiki/Upgrading-to-0.14
 rdoc_options: []
 require_paths:
 - lib