waithook 0.2 → 0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2d3624c5bebd573d8f2e33f66d96d19b93acc3a9
-  data.tar.gz: 25d37ca7b8c923b24c04425ce35f75ed997d9033
+  metadata.gz: a16ae52a0e661142f71a645d2eacf259bab70230
+  data.tar.gz: ff1efd58740c07f102bfc9f54957526c4c13f37c
 SHA512:
-  metadata.gz: 32a2181e21aa618a589c64d7dbd07132ebdc1942c4169bfe26019b8061d05ea18a494d0ffb8e2da343accba7307427c9c69742ed3a05477897ff3d91dd3de847
-  data.tar.gz: 3a96f332074cbd7a5e8364bcebbc42de580ca8575f39ad17c19c28d0f012320c09cd36e7df2d18ad664bd43a3852a682ad79bb608fd3ca7796fb4cf090f930b3
+  metadata.gz: 5f5b498540935c8e52788837cff9b5dbbceeec68bd9a6b6810522112344f0b36efefa067d4ec1ee7047bcd9b6b1332b4c2c78347ed8bbe2135ee041ba8ffc517
+  data.tar.gz: 28446b7fefec07045ad9ce56b3326f599aa66fa59c470c35cc6b87b55ef7a9b9694564422ea4c407a7a62e995095fb7ce92a905efff412409c92fff6d44dc802

data/.gitignore

@@ -1 +1,2 @@
-*.gem
+*.gem
+doc

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    waithook (0.1)
+    waithook (0.2)
       websocket (~> 1.2)
 
 GEM
@@ -10,16 +10,16 @@ GEM
     addressable (2.5.0)
       public_suffix (~> 2.0, >= 2.0.2)
     ansi (1.5.0)
-    builder (3.2.2)
+    builder (3.2.3)
     excon (0.54.0)
-    minitest (5.9.1)
-    minitest-reporters (1.1.12)
+    minitest (5.10.1)
+    minitest-reporters (1.1.14)
       ansi
       builder
       minitest (>= 5.0)
       ruby-progressbar
-    public_suffix (2.0.4)
-    rake (11.3.0)
+    public_suffix (2.0.5)
+    rake (12.0.0)
     ruby-progressbar (1.8.1)
     websocket (1.2.3)
 
@@ -34,4 +34,4 @@ DEPENDENCIES
   waithook!
 
 BUNDLED WITH
-   1.13.6
+   1.14.2

data/README.md

@@ -0,0 +1,46 @@
+# Waithook ruby client
+
+A ruby client [Waithook](http://waithook.com).
+Wiathook is a service to transmit HTTP requests over websocket connection.
+It's kinda Pub/Sub system for HTTP notifications, built for recieving webhook notifications behind proxy or when public IP is unknown (such as cloud CI server).
+
+
+To recieve notifications you should add `http://waithook.com/some_random_string` as notification URL and start listening websocket messages at `wss://waithook.com/some_random_string`.
+
+### Command line usage
+
+Install:
+```sh
+gem install waithook
+```
+
+Subscribe and print incoming requests:
+````sh
+waithook waithook.com/my_path
+```
+
+Subscribe and forvard to other web server:
+````sh
+waithook waithook.com/my_path --forward http://localhost:3000/notify
+```
+
+### Ruby API
+
+```ruby
+waithook = Waithook.subscribe(timeout: 60, raise_on_timeout: true) do |webhook|
+  webhook.json_body['order_id'] == order_id
+end
+
+waithook.send_to("http://localhost:3000/notify")
+```
+
+### Usage examples
+
+* Testing integration with payment gateway
+* Testing github webhooks
+* Testing incoming email processing
+* Testing slack bots
+* Testing facebook webhooks
+
+So waithook just help to deliver webhook to your application when public IP is unknown or not available. It can help when multiple developers testing integration with other service on localhost or your automated tests running in CI.
+

data/Rakefile

@@ -2,3 +2,7 @@
 task :test do
   Dir.glob('./tests/**/*_test.rb').each { |file| require file }
 end
+
+task :doc do
+  `rdoc -f hanna lib/* -m README.md`
+end

data/bin/waithook

@@ -9,8 +9,8 @@ def help_message
     "Waithook command line client.",
     "",
     "Example usage:",
-    "    waithook waithook.herokuapp.com/my_path",
-    "    waithook waithook.herokuapp.com/my_path --forward http://localhost:3000/notify"
+    "    waithook waithook.com/my_path",
+    "    waithook waithook.com/my_path --forward http://localhost:3000/notify"
   ].join("\n")
 end
 

data/example/example.rb

@@ -5,7 +5,7 @@ require './websocket-client'
 
 HOST = 'localhost'
 PORT = 3012
-#HOST = 'waithook.herokuapp.com'
+#HOST = 'waithook.com'
 #PORT = 80
 
 client = WebsocketClient.new(host: HOST, port: PORT, path: 'test-ruby')
@@ -42,7 +42,7 @@ end
 
 #socket = TCPSocket.open(hostname, port)
 #
-#request = WebSocket::Handshake::Client.new(url: 'ws://waithook.herokuapp.com/test-ruby')
+#request = WebSocket::Handshake::Client.new(url: 'ws://waithook.com/test-ruby')
 #puts request
 #
 #socket.print(request)

data/example/many_clients.rb

@@ -7,7 +7,7 @@ require './websocket-client'
 
 HOST = 'localhost'
 PORT = 3012
-#HOST = 'waithook.herokuapp.com'
+#HOST = 'waithook.com'
 #PORT = 80
 
 threads_num = ENV['THREADS'] ? ENV['THREADS'].to_i : 10

data/example/real_server_test.rb

@@ -5,8 +5,8 @@ require './websocket-client'
 
 #HOST = 'localhost'
 #PORT = 3012
-HOST = 'waithook.herokuapp.com'
-PORT = 443
+HOST = 'waithook.com'
+PORT = 80
 
 client = WebsocketClient.new(host: HOST, port: PORT, path: 'test-ruby').connect!.wait_handshake!
 

data/lib/waithook.rb

@@ -10,9 +10,22 @@ require_relative 'waithook/cli'
 
 class Waithook
 
-  SERVER_HOST = "waithook.herokuapp.com"
-  SERVER_PORT = 443
-
+  # Default server host
+  SERVER_HOST = "waithook.com"
+  # Default server port
+  SERVER_PORT = 80
+
+  # Connect to server and start filter incoming messages (optionally)
+  #
+  # Usage:
+  #   Waithook.default_path = 'my-notification-endpoint'
+  #   waithook = Waithook.subscribe(timeout: 10) do |message|
+  #     message.json_body['user_name'] == 'John Doe' # will return messages only passing this criteria
+  #   end
+  #   waithook.forward_to('http://localhost:4567/webhook', raise_on_timeout: true)
+  #
+  # <tt>options</tt> argument is will be passed to #initialize
+  #
   def self.subscribe(options = {}, &block)
     instance = new(options)
     if block
@@ -22,19 +35,35 @@ class Waithook
     instance
   end
 
-  def self.default_path
-    @default_path
-  end
- 
+  # Default path that it will be subscribed to
   def self.default_path=(value)
     @default_path = value
   end
 
+  # Accessor for @default_path
+  def self.default_path
+    @default_path
+  end
+
+  # Filter (Proc), can be used to to filter incoming messages
   attr_accessor :filter
+  # Array of all recieved messages
   attr_accessor :messages
+  # Websocket client, instance of Waithook::WebsocketClient
   attr_reader :client
+  # Connection options, hash
   attr_reader :options
 
+  # Available options:
+  # * :host
+  # * :port
+  # * :auto_connect - whenever connect to server automatically when instance is created (default is true)
+  # * :path
+  # * :timeout
+  # * :logger_level - logger level, default :info
+  # * :output - output stream for default logger. If value == false then it will be silent, default is $stdout
+  # * :logger - custom logger object
+  #
   def initialize(options = {})
     @options = {
       host: SERVER_HOST,
@@ -47,6 +76,7 @@ class Waithook
       raise ArgumentError, ":path is missing. Please add :path to options argument or set Waithook.default_path = 'foo'"
     end
 
+    # TODO: add SSL options
     @client = WebsocketClient.new(
       path: @options[:path],
       host: @options[:host],
@@ -63,6 +93,7 @@ class Waithook
     connect! if @options[:auto_connect]
   end
 
+  # Logger object
   def logger
     @logger ||= LoggerWithTrace.new(@options[:logger] ? $stdout : StringIO.new).setup(
       progname: self.class.name,
@@ -70,6 +101,7 @@ class Waithook
     )
   end
 
+  # Start connection to waithook server
   def connect!
     raise "Waithook connection already started" if @started
     @started = true
@@ -77,15 +109,21 @@ class Waithook
     self
   end
 
+  # Whenever connected to server or not
   def started?
     !!@started
   end
 
+  # Send all incoming webhook requests to running HTTP server
+  #
+  #   webhook = Waithook.subscribe(path: 'my-webhoooks').forward_to('http://localhost:3000/notification')
+  #
   def forward_to(url, options = {})
     webhook = wait_message(options)
     webhook.send_to(url) unless webhook.nil?
   end
 
+  # Wait incoming request information (wait message on websocket connection)
   def wait_message(options = {})
     raise_timeout_error = options.has_key?(:raise_on_timeout) ? options[:raise_on_timeout] : true
     timeout = options[:timeout] || @options[:timeout] || 0
@@ -108,16 +146,24 @@ class Waithook
     return nil
   end
 
+  # Close connection to server
   def close!
     @client.close!
     @started = false
   end
 
+  # Represent incoming request to waithook,
+  # that was send to client as JSON via websocket connection
   class Webhook
+    # Original request URL, e.g. '/my-notification-endpoint?aaa=bbb'
     attr_reader :url
+    # Hash of headers
     attr_reader :headers
+    # Request body (for POST, PATCH, PUT)
     attr_reader :body
+    # Request method ("GET", "POST", "PATCH", etc)
     attr_reader :method
+    # Raw message from waithook server
     attr_reader :message
 
     def initialize(payload)
@@ -129,12 +175,19 @@ class Waithook
       @method = data['method']
     end
 
+    # Returns Hash.
+    # Access request body encoded as JSON (for POST, PATCH, PUT)
     def json_body
       if @body
         @json_body ||= JSON.parse(@body)
       end
     end
 
+    # Send webhook information to other HTTP server
+    #
+    #   webhook = Waithook.subscribe(path: 'my-webhoooks').wait_message
+    #   webhook.send_to('http://localhost:3000/notification')
+    #
     def send_to(url)
       uri = URI.parse(url)
       response = nil

data/lib/waithook/cli.rb

@@ -1,5 +1,5 @@
 class Waithook
-  module WithColor
+  module WithColor #:nodoc:
     extend self
     def black(s);   "\033[30m#{s}\033[0m" end
     def red(s);     "\033[31m#{s}\033[0m" end
@@ -13,8 +13,8 @@ class Waithook
     def bold(s);    "\e[1m#{s}\e[m"       end
   end
 
-  module CLI
-    class ArgError < ArgumentError; end
+  module CLI #:nodoc:
+    class ArgError < ArgumentError; end #:nodoc:
 
     extend self
 

data/lib/waithook/logger_with_trace.rb

@@ -1,8 +1,8 @@
 require 'logger'
 
 # Just add trace level
-class LoggerWithTrace < ::Logger
-  module Severity
+class LoggerWithTrace < ::Logger #:nodoc:
+  module Severity #:nodoc:
     include ::Logger::Severity
     TRACE = -1
   end

data/lib/waithook/version.rb

@@ -1,3 +1,3 @@
 class Waithook
-  VERSION = "0.2"
+  VERSION = "0.3"
 end

data/lib/waithook/websocket_client.rb

@@ -5,21 +5,48 @@ require 'stringio'
 require_relative 'logger_with_trace'
 
 class Waithook
+  # Simple websocket client, internally use websocket gem to construct and parse websocket messages
+  #
+  # Usage:
+  #
+  #   client = WebsocketClient.new(host: HOST, port: PORT, path: 'test-ruby')
+  #   client.send_ping!
+  #   client.send_message!("Hello, server")
+  #   type, data = client.wait_message # => type == :text, data is message content as a string
+  #
   class WebsocketClient
 
     attr_accessor :logger
 
+    # Waiter object, blocking current thread. Better abstraction for ruby's Queue utility class
+    #
+    #   message_waiter = Waiter.new
+    #   Thread.new { sleep 5; message_waiter.notify('Done!!!') }
+    #   message_waiter.wait # => return 'Done!!!' after 5 seconds pause
+    #
     class Waiter
+      # Waiting for someone to call #notify
       def wait
         @queue = Queue.new
         @queue.pop(false)
       end
 
+      # Notify waiting side
       def notify(data)
         @queue.push(data)
       end
     end
 
+    # Available options:
+    # * :host - hostname
+    # * :port - server port (default 80)
+    # * :path - HTTP path
+    # * :ssl  - true/false (will detect base on port if blank)
+    # * :ssl_version
+    # * :verify_mode
+    # * :logger_level - logger level, default :info
+    # * :output - output stream for default logger. If value == false then it will be silent, default is $stdout
+    # * :logger - custom logger object
     def initialize(options = {})
       # required: :host, :path
 
@@ -52,6 +79,7 @@ class Waithook
       end
     end
 
+    # Estabilish connection to server and send initial handshake
     def connect!
       logger.info "Connecting to #{@host} #{@port}"
 
@@ -72,7 +100,7 @@ class Waithook
       end
 
       @is_open = true
-      @handshake = WebSocket::Handshake::Client.new(url: "ws://#{@host}/#{@path}")
+      @handshake = WebSocket::Handshake::Client.new(url: "ws://#{@host}/#{@path.to_s.sub(/^\//, '')}")
 
       logger.trace "Sending handshake:\n#{@handshake}"
 
@@ -82,6 +110,7 @@ class Waithook
       self
     end
 
+    # Return true/false
     def connected?
       !!@is_open
     end
@@ -106,41 +135,46 @@ class Waithook
       end
     end
 
+    # Send <tt>:ping</tt> message to server
     def send_ping!
       _send_frame(:ping)
     end
 
+    # Send <tt>:pong</tt> message to server, usually as a response to :ping message
     def send_pong!
       _send_frame(:pong)
     end
 
+    # Send message to server (type <tt>:text</tt>)
     def send_message!(payload)
       _send_frame(:text, payload)
     end
 
-    def wait_handshake!
-      while !@handshake_received
-        sleep 0.001
-      end
-      self
-    end
-
+    # Wait for new message (thread safe, all waiting threads will recieve a message)
+    # Message format [type, data], e.g. <tt>[:text, "hello world"]</tt>
     def wait_new_message
       waiter = Waiter.new
       @waiters << waiter
       waiter.wait
     end
 
+    # Synchroniously waiting for new message. Not thread safe, only one thread will receive message
+    # Message format [type, data], e.g. <tt>[:text, "hello world"]</tt>
     def wait_message
       @messages.pop
     end
 
-    def wait_connected
+    # Wait until server handshake recieved.
+    # Once it's recieved - we can are listening for new messages
+    # and connection is ready for sending data
+    def wait_handshake!
       return true if @handshake_received
       waiter = Waiter.new
       @connect_waiters << waiter
       waiter.wait
+      self
     end
+    alias_method :wait_connected, :wait_handshake!
 
     def _handshake_recieved!
       @handshake_received = true
@@ -195,6 +229,7 @@ class Waithook
       data.join("")
     end
 
+    # Send <tt>:close</tt> message to socket and close socket connection
     def close!(options = {send_close: true})
       unless @is_open
         logger.info "Already closed"

data/tests/server_test.rb

@@ -128,4 +128,32 @@ describe "Server" do
     assert_equal("test-data", message['body'])
     assert_equal("PUT", message['method'])
   end
+
+  it "should response with challenge value for slack type" do
+    @client = Waithook::WebsocketClient.new(host: HOST, port: PORT, path: PATH + "?type=slack", output: StringIO.new)
+      .connect!.wait_handshake!
+
+    message = {
+      token: "mJbhjRozbVxkrQmthcxndV0X",
+      challenge: "x39xHMiljI4m42XPO9jxui47fRvi0SMZhOlYI0SbFSzNSbQJItus",
+      type: "url_verification"
+    }
+    response = POST(PATH + "?type=slack", JSON.generate(message))
+    assert_equal(response.body, message[:challenge])
+  end
+
+  it "should response with OK for slack when not a json" do
+    response = POST(PATH + "?type=slack", "AAA")
+    assert_equal(response.body, "OK\n")
+  end
+
+  it "should response with OK for slack without challenge" do
+    response = POST(PATH + "?type=slack", "{}")
+    assert_equal(response.body, "OK\n")
+  end
+
+  it "should response with OK for slack when challenge isn't a string" do
+    response = POST(PATH + "?type=slack", '{"challenge": []}')
+    assert_equal(response.body, "OK\n")
+  end
 end

data/waithook.gemspec

@@ -7,8 +7,9 @@ Gem::Specification.new do |s|
   s.email       = ["pavel.evst@gmail.com"]
   s.homepage    = "https://github.com/paxa/waithook-ruby"
   s.summary     = %q{HTTP to WebSocket transmitting client}
-  s.description = "Waithook gem is client lib for waithook service https://waithook.heroku.com"
+  s.description = "Waithook gem is client lib for waithook service http://waithook.com"
   s.license     = 'MIT'
+  s.required_ruby_version = '~> 2.0'
 
   s.files       = `git ls-files`.split("\n")
   s.test_files  = []

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: waithook
 version: !ruby/object:Gem::Version
-  version: '0.2'
+  version: '0.3'
 platform: ruby
 authors:
 - Pavel Evstigneev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-12-29 00:00:00.000000000 Z
+date: 2017-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: websocket
@@ -24,7 +24,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.2'
-description: Waithook gem is client lib for waithook service https://waithook.heroku.com
+description: Waithook gem is client lib for waithook service http://waithook.com
 email:
 - pavel.evst@gmail.com
 executables:
@@ -35,6 +35,7 @@ files:
 - ".gitignore"
 - Gemfile
 - Gemfile.lock
+- README.md
 - Rakefile
 - bin/waithook
 - example/example.rb
@@ -60,9 +61,9 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - "~>"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="