https://github.com/tarcieri/pistachio

HTTP push middleware for Rack powered by Stash
https://github.com/tarcieri/pistachio

Last synced: about 1 month ago
JSON representation

HTTP push middleware for Rack powered by Stash

• Host: GitHub
• URL: https://github.com/tarcieri/pistachio
• Owner: tarcieri
• License: mit
• Created: 2010-12-01T03:04:28.000Z (almost 14 years ago)
• Default Branch: master
• Last Pushed: 2011-02-16T06:04:55.000Z (over 13 years ago)
• Last Synced: 2024-09-17T03:09:21.385Z (about 2 months ago)
• Language: Ruby
• Homepage:
• Size: 102 KB
• Stars: 8
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.rdoc
  • License: LICENSE

Awesome Lists containing this project

README

        
= Pistachio

HTTP push middleware for Rack powered by Stash.

Need events delivered to an HTTP client in realtime? Perhaps you've

investigated solutions like Comet/Bayeux, BOSH, or WebSockets. Not happy

with those solutions and just want something simple?

Pistachio provides a simple HTTP long polling middleware for Rack, which is

backed by the Stash gem. Stash provides an abstract interface to data

structures servers, namely Redis.  Servers like Redis provide a list data

type, which can easily be used as a message queue. Redis also supports a

"blocking  pop" from a list, where clients will either receive the next 

message in the list immediately, or if the list is empty Redis will block 

until the next message is available (or a timeout occurs).

Pistachio combines this all into a single, easy-to-use Rack middleware for

delivering realtime push notification events to HTTP clients like web browsers.

== Using Pistachio in your Rack application

Add the following to your config.ru file:

  Pistachio.setup :default, :adapter   => :redis, 

                            :namespace => 'myapp_name',

                            :path      => '/message_path'

                            

  use Pistachio::Middleware

  

This will configure Pistachio to talk to Redis, store its messages in the

'myapp_name' Redis namespace, and mount the Pistachio Rack middleware

under the /message_path path.

All messages must be sent to a given named endpoint. To send a message via

Pistachio within your Rack application, do:

  Pistachio[:foobar] << "my totally awesome message"

Messages sent to the 'foobar' endpoint can be retrieved by making an HTTP GET

request to /message_path/foobar. This will return one of two HTTP statuses:

* 200: a message was retrieved successfully

* 504: the request timed out before a message was received

By default Pistachio uses a 30 second timeout. You can adjust this with the

':timeout' parameter to Pistachio.setup.

It's the responsibility of the client to hit the given message endpoint in a

loop. If the client gets a 504 response it should retry. Any other HTTP

responses should be considered errors, in which case it'd be good if the

client utilized exponential backoff to avoid hammering Pistachio when errors

are occurring.

No reference clients are presently available. Pull requests happily accepted!

== Copyright

Copyright (c) 2010 Tony Arcieri. See file LICENSE for further details.