sockudo 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b7a967b624337aaad0668a3c7fba48c18ca82dbcbf61f48d2637ab6c468a8932
+  data.tar.gz: 6fca4167728cd368e7e0dc93fb3c2986604e2fc35c8fa762c7e2e2606fc33a08
+SHA512:
+  metadata.gz: 1211b8badb256617a74201e39d6c7579a9351cf575a2fd68ee3bbdbada7b877ce6ddcb1ddfb34c37253bd276d8db470e9340f6150c75c653cbf70622aff78fa3
+  data.tar.gz: bbe0e470d9c7cd52119693f250139eeac6ace3b0b54f01a293aed1db9003e5260ff9f7681cf0783fcbd64d967b68e431b75ab8e4783c1c31904838f002d7c54c

data/CHANGELOG.md

@@ -0,0 +1,137 @@
+# Changelog
+
+## 2.0.4
+
+* [ADDED] Add `authenticate_user` method for user authentication flow
+
+## 2.0.3
+
+* [FIXED] Corrected the channels limit when publishing events. Upped from 10 to 100. 
+
+## 2.0.2
+
+* [CHANGED] made encryption_master_key_base64 globally configurable 
+
+## 2.0.1
+
+* [CHANGED] Only include lib and essential docs in gem.
+
+## 2.0.0
+
+* [CHANGED] Use TLS by default.
+* [REMOVED] Support for Ruby 2.4 and 2.5.
+* [FIXED] Handle empty or nil  configuration.
+* [REMOVED] Legacy Push Notification integration.
+* [ADDED] Stalebot and Github actions. 
+
+## 1.4.3
+
+  * [FIXED] Remove newline from end of base64 encoded strings, some decoders don't like
+    them.
+
+## 1.4.2
+==================
+
+  * [FIXED] Return `shared_secret` to support authenticating encrypted channels. Thanks
+    @Benjaminpjacobs
+
+## 1.4.1
+
+  * [CHANGED] Remove rbnacl from dependencies so we don't get errors when it isn't
+    required. Thanks @y-yagi!
+
+## 1.4.0
+
+  * [ADDED] Support for end-to-end encryption.
+
+## 1.3.3
+
+  * [CHANGED] Rewording to clarify "Pusher Channels" or simply "Channels" product name.
+
+## 1.3.2
+
+  * [FIXED] Return a specific error for "Request Entity Too Large" (body over 10KB).
+  * [ADDED] Add a `use_tls` option for SSL (defaults to false).
+  * [ADDED] Add a `from_url` client method (in addition to existing `from_env` option).
+  * [CHANGED] Improved documentation and fixed typos.
+  * [ADDED] Add Ruby 2.4 to test matrix.
+
+## 1.3.1
+
+  * [FIXED] Added missing client batch methods to default client delegations
+  * [CHANGED] Document raised exception in the `authenticate` method
+  * [FIXED] Fixes em-http-request from using v2.5.0 of `addressable` breaking builds.
+
+## 1.3.0
+
+  * [ADDED] Add support for sending push notifications on up to 10 interests.
+
+## 1.2.1
+
+  * [FIXED] Fixes Rails 5 compatibility. Use duck-typing to detect request object
+
+## 1.2.0
+
+  * [CHANGED] Minor release for Native notifications
+
+## 1.2.0.rc1
+
+  * [ADDED] Add support for Native notifications
+
+## 1.1.0
+
+  * [ADDED] Add support for batch events
+
+## 1.0.0
+
+ * [CHANGED] No breaking changes, this release is just to follow semver and show that we
+are stable.
+
+## 0.18.0
+
+  * [ADDED] Introduce `Pusher::Client.from_env`
+  * [FIXED] Improve error handling on missing config
+
+## 0.17.0
+
+  * [ADDED] Introduce the `cluster` option.
+
+## 0.16.0
+
+  * [CHANGED] Bump httpclient version to 2.7
+  * [REMOVED] Ruby 1.8.7 is not supported anymore.
+
+## 0.15.2
+
+  * [CHANGED] Documented `Pusher.channel_info`, `Pusher.channels`
+  * [ADDED] Added `Pusher.channel_users`
+
+## 0.15.1
+
+  * [FIXED] Fixed a bug where the `authenticate` method added in 0.15.0 wasn't exposed on the Pusher class.
+
+## 0.15.0
+
+  * [ADDED] Added `Pusher.authenticate` method for authenticating private and presence channels.
+    This is prefered over the older `Pusher['a_channel'].authenticate(...)` style.
+
+## 0.14.6
+
+  * [CHANGED] Updated to use the `pusher-signature` gem instead of `signature`.
+    This resolves namespace related issues.
+
+## 0.14.5
+
+  * [SECURITY] Prevent auth delegation trough crafted socket IDs
+
+## 0.14.4
+
+  * [SECURITY] Prevent timing attack, update signature to v0.1.8
+  * [SECURITY] Prevent POODLE. Disable SSLv3, update httpclient to v2.5
+  * [FIXED] Fix channel name character limit.
+  * [ADDED] Adds support for listing users on a presence channel
+
+## 0.14.2
+
+  * [CHANGED] Bump httpclient to v2.4. See #62 (POODLE SSL)
+  * [CHANGED] Fix limited channel count at README.md. Thanks @tricknotes

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010-2013 Pusher
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,289 @@
+# sockudo
+
+Official Ruby server SDK for [Sockudo](https://github.com/sockudo/sockudo) — a fast, self-hosted WebSocket server with full Pusher HTTP API compatibility.
+
+## Supported Platforms
+
+- **Ruby 3.0 or greater**
+- Rails and other Ruby frameworks are supported provided you are running a supported Ruby version.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'sockudo'
+```
+
+Then run `bundle install`, or install directly:
+
+```bash
+gem install sockudo
+```
+
+## Getting Started
+
+```ruby
+require 'sockudo'
+
+sockudo = Sockudo::Client.new(
+  app_id: 'your-app-id',
+  key:    'your-app-key',
+  secret: 'your-app-secret',
+  host:   '127.0.0.1',
+  port:    6001,
+  use_tls: false
+)
+
+sockudo.trigger('my-channel', 'my-event', { message: 'hello world' })
+```
+
+## Configuration
+
+### Instance Configuration
+
+```ruby
+sockudo = Sockudo::Client.new(
+  app_id:  'your-app-id',
+  key:     'your-app-key',
+  secret:  'your-app-secret',
+  host:    '127.0.0.1',
+  port:    6001,
+  use_tls: false
+)
+```
+
+`use_tls` is optional and defaults to `true`. It sets the scheme and port accordingly. A custom `port` value takes precedence over `use_tls`.
+
+### Global Configuration
+
+```ruby
+Sockudo.app_id  = 'your-app-id'
+Sockudo.key     = 'your-app-key'
+Sockudo.secret  = 'your-app-secret'
+Sockudo.host    = '127.0.0.1'
+Sockudo.port    = 6001
+Sockudo.use_tls = false
+```
+
+### From Environment Variable
+
+If `SOCKUDO_URL` is set in the environment, use `from_env` to configure automatically:
+
+```ruby
+# Reads SOCKUDO_URL in the form: http://KEY:SECRET@HOST:PORT/apps/APP_ID
+sockudo = Sockudo::Client.from_env
+```
+
+Global configuration is also automatically read from `SOCKUDO_URL` when set.
+
+### HTTP Proxy
+
+```ruby
+Sockudo.http_proxy = 'http://user:password@proxy-host:8080'
+```
+
+## Publishing Events
+
+### Single Channel
+
+```ruby
+sockudo.trigger('my-channel', 'my-event', { message: 'hello world' })
+```
+
+### Multiple Channels
+
+```ruby
+sockudo.trigger(['channel-1', 'channel-2'], 'my-event', { message: 'hello world' })
+```
+
+Up to 10 channels per call.
+
+### Excluding a Socket Recipient
+
+Pass a `socket_id` option to prevent the triggering connection from receiving its own event:
+
+```ruby
+sockudo.trigger('my-channel', 'my-event', { message: 'hello' }, { socket_id: '123.456' })
+```
+
+### Batch Events
+
+Send multiple events in a single HTTP request (up to 10 per call):
+
+```ruby
+sockudo.trigger_batch([
+  { channel: 'channel-1', name: 'event-1', data: { x: 1 } },
+  { channel: 'channel-2', name: 'event-2', data: { x: 2 } },
+  { channel: 'channel-3', name: 'event-3', data: { x: 3 } },
+])
+```
+
+## Idempotent Publishing
+
+Pass an `idempotency_key` to safely retry publishes without causing duplicate deliveries:
+
+```ruby
+sockudo.trigger(
+  'my-channel',
+  'my-event',
+  { message: 'hello' },
+  { idempotency_key: 'order-shipped-order-789' }
+)
+```
+
+The server deduplicates publishes with the same key within the configured window.
+
+## Channel Authorization
+
+### Private Channel
+
+```ruby
+auth = sockudo.authenticate('private-my-channel', params[:socket_id])
+# Returns JSON: {"auth":"key:signature"}
+```
+
+### Presence Channel
+
+```ruby
+auth = sockudo.authenticate(
+  'presence-my-channel',
+  params[:socket_id],
+  user_id: 'user-123',
+  user_info: { name: 'Jane Doe', role: 'admin' }
+)
+# Returns JSON: {"auth":"key:signature","channel_data":"..."}
+```
+
+## User Authentication
+
+```ruby
+auth = sockudo.authenticate_user(params[:socket_id], { id: 'user-123', name: 'Jane Doe' })
+```
+
+## Webhooks
+
+Create a webhook object from a `Rack::Request` (available as `request` in Rails controllers and Sinatra handlers):
+
+```ruby
+webhook = sockudo.webhook(request)
+
+if webhook.valid?
+  webhook.events.each do |event|
+    case event['name']
+    when 'channel_occupied'
+      puts "Channel occupied: #{event['channel']}"
+    when 'channel_vacated'
+      puts "Channel vacated: #{event['channel']}"
+    when 'client_event'
+      puts "Client event: #{event['event']} on #{event['channel']}"
+    end
+  end
+
+  render plain: 'ok'
+else
+  render plain: 'invalid', status: 401
+end
+```
+
+## Application State
+
+```ruby
+# Info about a channel
+info = sockudo.channel_info('my-channel')
+occupied = info[:occupied]
+
+# User count for a presence channel
+info = sockudo.channel_info('presence-my-channel', info: 'user_count')
+user_count = info[:user_count]
+
+# List channels (optionally filtered)
+result = sockudo.channels(filter_by_prefix: 'presence-')
+
+# Users in a presence channel
+result = sockudo.channel_users('presence-my-channel')
+```
+
+## Async Requests
+
+There are two reasons to use async methods: avoiding blocking in a request-response cycle, or running inside an event loop.
+
+### With EventMachine
+
+Add `em-http-request` to your Gemfile and run with the EventMachine reactor active (e.g. inside Thin):
+
+```ruby
+sockudo.get_async('/channels').callback { |response|
+  puts response[:channels].inspect
+}.errback { |error|
+  puts "Error: #{error}"
+}
+
+sockudo.trigger_async('my-channel', 'my-event', { message: 'hello' }).callback { |response|
+  puts 'Triggered'
+}
+```
+
+### Without EventMachine (Threaded)
+
+If the EventMachine reactor is not running, async requests are made using threads managed by `httpclient`. An `HTTPClient::Connection` object is returned immediately.
+
+```ruby
+sockudo.trigger_async('my-channel', 'my-event', { message: 'hello' })
+```
+
+## Error Handling
+
+All errors are descendants of `Sockudo::Error`:
+
+```ruby
+begin
+  sockudo.trigger('my-channel', 'my-event', { message: 'hello' })
+rescue Sockudo::AuthenticationError => e
+  # invalid credentials
+rescue Sockudo::HTTPError => e
+  # network or HTTP-level error
+rescue Sockudo::Error => e
+  # catch-all
+end
+```
+
+## Logging
+
+Assign any logger compatible with Ruby's standard `Logger` interface:
+
+```ruby
+# Rails
+Sockudo.logger = Rails.logger
+
+# Default: logs at INFO level to STDOUT
+```
+
+## Testing
+
+```bash
+bundle install
+bundle exec rake spec
+```
+
+## Pusher SDK Compatibility
+
+Sockudo implements the full Pusher HTTP API. If you prefer to use the official `pusher` gem or are migrating from Pusher, point it at your Sockudo instance:
+
+```ruby
+require 'pusher'
+
+pusher = Pusher::Client.new(
+  app_id: 'your-app-id',
+  key:    'your-app-key',
+  secret: 'your-app-secret',
+  host:   '127.0.0.1',
+  port:    6001
+)
+```
+
+All standard Pusher SDK calls work against a self-hosted Sockudo server without modification.
+
+## License
+
+MIT

data/lib/sockudo/channel.rb

@@ -0,0 +1,179 @@
+require 'openssl'
+require 'multi_json'
+
+module Sockudo
+  # Delegates operations for a specific channel from a client
+  class Channel
+    attr_reader :name
+    INVALID_CHANNEL_REGEX = /[^A-Za-z0-9_\-=@,.;]/
+
+    def initialize(_, name, client = Sockudo)
+      if Sockudo::Channel::INVALID_CHANNEL_REGEX.match(name)
+        raise Sockudo::Error, "Illegal channel name '#{name}'"
+      elsif name.length > 200
+        raise Sockudo::Error, "Channel name too long (limit 164 characters) '#{name}'"
+      end
+      @name = name
+      @client = client
+    end
+
+    # Trigger event asynchronously using EventMachine::HttpRequest
+    #
+    # [Deprecated] This method will be removed in a future gem version. Please
+    # switch to Sockudo.trigger_async or Sockudo::Client#trigger_async instead
+    #
+    # @param (see #trigger!)
+    # @return [EM::DefaultDeferrable]
+    #   Attach a callback to be notified of success (with no parameters).
+    #   Attach an errback to be notified of failure (with an error parameter
+    #   which includes the HTTP status code returned)
+    # @raise [LoadError] unless em-http-request gem is available
+    # @raise [Sockudo::Error] unless the eventmachine reactor is running. You
+    #   probably want to run your application inside a server such as thin
+    #
+    def trigger_async(event_name, data, socket_id = nil)
+      params = {}
+      if socket_id
+        validate_socket_id(socket_id)
+        params[:socket_id] = socket_id
+      end
+      @client.trigger_async(name, event_name, data, params)
+    end
+
+    # Trigger event
+    #
+    # [Deprecated] This method will be removed in a future gem version. Please
+    # switch to Sockudo.trigger or Sockudo::Client#trigger instead
+    #
+    # @example
+    #   begin
+    #     Sockudo['my-channel'].trigger!('an_event', {:some => 'data'})
+    #   rescue Sockudo::Error => e
+    #     # Do something on error
+    #   end
+    #
+    # @param data [Object] Event data to be triggered in javascript.
+    #   Objects other than strings will be converted to JSON
+    # @param socket_id Allows excluding a given socket_id from receiving the
+    #   event - see http://sockudo.com/docs/publisher_api_guide/publisher_excluding_recipients for more info
+    #
+    # @raise [Sockudo::Error] on invalid Sockudo response - see the error message for more details
+    # @raise [Sockudo::HTTPError] on any error raised inside http client - the original error is available in the original_error attribute
+    #
+    def trigger!(event_name, data, socket_id = nil)
+      params = {}
+      if socket_id
+        validate_socket_id(socket_id)
+        params[:socket_id] = socket_id
+      end
+      @client.trigger(name, event_name, data, params)
+    end
+
+    # Trigger event, catching and logging any errors.
+    #
+    # [Deprecated] This method will be removed in a future gem version. Please
+    # switch to Sockudo.trigger or Sockudo::Client#trigger instead
+    #
+    # @note CAUTION! No exceptions will be raised on failure
+    # @param (see #trigger!)
+    #
+    def trigger(event_name, data, socket_id = nil)
+      trigger!(event_name, data, socket_id)
+    rescue Sockudo::Error => e
+      Sockudo.logger.error("#{e.message} (#{e.class})")
+      Sockudo.logger.debug(e.backtrace.join("\n"))
+    end
+
+    # Request info for a channel
+    #
+    # @example Response
+    #   [{:occupied=>true, :subscription_count => 12}]
+    #
+    # @param info [Array] Array of attributes required (as lowercase strings)
+    # @return [Hash] Hash of requested attributes for this channel
+    # @raise [Sockudo::Error] on invalid Sockudo response - see the error message for more details
+    # @raise [Sockudo::HTTPError] on any error raised inside http client - the original error is available in the original_error attribute
+    #
+    def info(attributes = [])
+      @client.channel_info(name, :info => attributes.join(','))
+    end
+
+    # Request users for a presence channel
+    # Only works on presence channels (see: http://sockudo.com/docs/client_api_guide/client_presence_channels and https://sockudo.com/docs/rest_api)
+    #
+    # @example Response
+    #   [{:id=>"4"}]
+    #
+    # @param params [Hash] Hash of parameters for the API - see REST API docs
+    # @return [Hash] Array of user hashes for this channel
+    # @raise [Sockudo::Error] on invalid Sockudo response - see the error message for more details
+    # @raise [Sockudo::HTTPError] on any error raised inside Net::HTTP - the original error is available in the original_error attribute
+    #
+    def users(params = {})
+      @client.channel_users(name, params)[:users]
+    end
+
+    # Compute authentication string required as part of the authentication
+    # endpoint response. Generally the authenticate method should be used in
+    # preference to this one
+    #
+    # @param socket_id [String] Each Sockudo socket connection receives a
+    #   unique socket_id. This is sent from sockudo.js to your server when
+    #   channel authentication is required.
+    # @param custom_string [String] Allows signing additional data
+    # @return [String]
+    #
+    # @raise [Sockudo::Error] if socket_id or custom_string invalid
+    #
+    def authentication_string(socket_id, custom_string = nil)
+      string_to_sign = [socket_id, name, custom_string].compact.map(&:to_s).join(':')
+
+      _authentication_string(socket_id, string_to_sign, @client.authentication_token, custom_string)
+    end
+
+    # Generate the expected response for an authentication endpoint.
+    # See http://sockudo.com/docs/authenticating_users for details.
+    #
+    # @example Private channels
+    #   render :json => Sockudo['private-my_channel'].authenticate(params[:socket_id])
+    #
+    # @example Presence channels
+    #   render :json => Sockudo['presence-my_channel'].authenticate(params[:socket_id], {
+    #     :user_id => current_user.id, # => required
+    #     :user_info => { # => optional - for example
+    #       :name => current_user.name,
+    #       :email => current_user.email
+    #     }
+    #   })
+    #
+    # @param socket_id [String]
+    # @param custom_data [Hash] used for example by private channels
+    #
+    # @return [Hash]
+    #
+    # @raise [Sockudo::Error] if socket_id or custom_data is invalid
+    #
+    # @private Custom data is sent to server as JSON-encoded string
+    #
+    def authenticate(socket_id, custom_data = nil)
+      custom_data = MultiJson.encode(custom_data) if custom_data
+      auth = authentication_string(socket_id, custom_data)
+      r = {:auth => auth}
+      r[:channel_data] = custom_data if custom_data
+      r
+    end
+
+    def shared_secret(encryption_master_key)
+      return unless encryption_master_key
+
+      secret_string = @name + encryption_master_key
+      digest = OpenSSL::Digest::SHA256.new
+      digest << secret_string
+      digest.digest
+    end
+
+    private
+
+    include Sockudo::Utils
+  end
+end