pusher-client-nc

= pusher-client (Ruby)

pusher-client is a ruby gem for consuming WebSockets from the Pusher[http://pusherapp.com] web service.

The connection to Pusher can optionally be maintained in its own thread (see Asynchronous Usage).

This gem is compatible with jruby since 0.2.

== Installation

gem install pusher-client

== Single-Threaded Usage

The application will pause at socket.connect and handle events from Pusher as they happen.

require 'pusher-client'

PusherClient.logger = Logger.new(STDOUT) options = {:secret => YOUR_APP_SECRET} socket = PusherClient::Socket.new(YOUR_APP_KEY, options)

Subscribe to a public channel

socket.subscribe('channel')

Subscribe to an authenticated channel

socket.subscribe('presence-channel', 'user_id')

Subscribe to an authenticated channel with optional :user_info

socket.subscribe('presence-channel', 'user_id', { :name => 'name' })

Subscribe to array of channels

['channel1', 'channel2'].each do |c| socket.subscribe("presence-#{c}", 'user_id') end

Bind to global events (a catch-all for any 'event' across subscribed channels)

socket.bind('event') do |data| puts data end

Bind to events that occur on a specific channel

socket['channel'].bind('event') do |data| puts data end

socket.connect

== Asynchronous Usage

The socket will remain open in the background as long as your main application thread is running, and you can continue to subscribe/unsubscribe to channels and bind new events.

require 'pusher-client'

PusherClient.logger = Logger.new(STDOUT) options = {:secret => YOUR_APP_SECRET} socket = PusherClient::Socket.new(YOUR_APP_KEY, options) socket.connect(true) # Connect asynchronously

Subscribe to a channel

socket.subscribe('channel')

Bind to a global event

socket.bind('event') do |data| puts data end

loop do sleep(1) # Keep your main thread running end

For further documentation, read the source & test suite. Some features of the JavaScript client are not yet implemented.

== Gotchas

When binding to a global event, note that you still must be subscribed to the channels the event may be sent on. You can't just bind a global event without subscribing to any channels and call it a day.

== Contributing to pusher-client

• Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
• Check out the issue tracker to make sure someone already hasn't requested it and/or contributed it
• Fork the project
• Start a feature/bugfix branch
• Commit and push until you are happy with your contribution
• Make sure to add tests for it. This is important so I don't break it in a future version unintentionally.
• Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.

== TODOs

• Implement Channel instances associated with Subscription instances.
• Remove Subscriptions#find_for_bind workaround for lack of Channel instances
• Remove the duplication between Socket#subscribe and #subscribe_existing
• Test Socket.rb bind('pusher:connection_disconnected')
• Identify subscriptions on :channel and :user_id (rather than :user_data).

== Copyright

Copyright (c) 2010 Logan Koester. See LICENSE.txt for further details.