rest-firebase 0.9.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e5623f3812406296167b73e1b26510a060043d0b
-  data.tar.gz: 45ddc73ba69941f7d74cdb183b8af4d6784f59f0
+  metadata.gz: 38ac75dc25a2212b5493f30523502a0c524e5423
+  data.tar.gz: 194f4cafa79ce00c6d33dd9dbdf086ce0c30bda3
 SHA512:
-  metadata.gz: ffac8d5aabfb1468a32a7410a495ca0cb4dc0f8b9055c8b498dc5b209d2bc2e5a33027b45b65a7bd6c3f400fc9c9086036d1f727cbf06dc4b458f53e13d7c8e3
-  data.tar.gz: 11e4cf1a5b78c289e8ce5af68a47c90f19877c7fc9b04a566d28fe87e78e0a26068fcf54b38c35d3c128ad9c940d72ae824805fa1ad845afd148adc2b98407a3
+  metadata.gz: 9e9dfc59ecf61bcdd560d72bfe851464f3a183bc514a98b1c5464d58f013cac9d2de2404be278005ed33f821f5becfd4a38984187fbfa83de96d95619ed04a53
+  data.tar.gz: 502858f091acd477c0e6ad2ed4c142845899ddaa8b16686ef2df5ff4e2134966bf7a54d3fd8c3e43b16a7f7bbfbc6c039a57d18d39ec66e235e01634195ab9e2

data/CHANGES.md

@@ -1,5 +1,9 @@
 # CHANGES
 
+## rest-firebase 0.9.1 -- 2014-06-28
+
+* Now it would properly send JSON payload and headers.
+
 ## rest-firebase 0.9.0 -- 2014-05-13
 
 * Birthday!

data/Rakefile

@@ -10,7 +10,7 @@ $LOAD_PATH.unshift(File.expand_path("#{dir}/rest-core/lib"))
 
 Gemgem.init(dir) do |s|
   s.name     = 'rest-firebase'
-  s.version  = '0.9.0'
+  s.version  = '0.9.1'
   s.homepage = 'https://github.com/CodementorIO/rest-firebase'
 
   s.authors  = ['Codementor', 'Lin Jen-Shin (godfat)']

data/doc/intro.md

@@ -0,0 +1,150 @@
+
+# Codementor introduces you a new Firebase client for Ruby
+
+## Why we pick Firebase
+
+Here at Codementor we implemented all the realtime facilities with
+[Firebase][], which is a great tool and service for realtime communication,
+especially for their JavaScript library which could handle all those edge
+cases like whenever the clients disconnected unexpectedly, how we could
+process the data offline and when we have a chance to reconnect, reconnect
+and resend the offline data, etc, which are definitely common enough and we
+shall not ignore them.
+
+[Firebase]: https://www.firebase.com/
+
+## Why we need a Firebase client for Ruby
+
+However, our server is written in Ruby, and we definitely need someway to let
+the server communicate with the clients (browsers). For example, whenever
+we want to programmatically broadcast some messages to certain users, it
+would be much easier to do this from the server. Picking a Firebase client
+for Ruby would be the most straightforward choice.
+
+## Existing Firebase client for Ruby did not fit our need
+
+Unfortunately, eventually we realized that the existing Firebase client for
+Ruby, namely [firebase-ruby][], did not fit our need. The main reason is that
+it did not support the [streaming feature from Firebase][streaming], which is
+extremely important whenever we want the clients periodically notify the
+server, (e.g. online presence) since the server needs to know the status in
+order to do some other stuffs underneath in realtime. We could probably
+implement this on our server, but why not just use Firebase whenever it's
+already implemented, and we're using it?
+
+[firebase-ruby]: https://github.com/oscardelben/firebase-ruby
+[streaming]: https://www.firebase.com/docs/rest-api.html#streaming-from-the-rest-api
+
+## [rest-firebase][]
+
+Therefore we implemented our own Firebase client for Ruby, that is
+[rest-firebase][]. It was built on top of [rest-core][], thus it has all
+the advantages from rest-core, just like firebase-ruby was built on top
+of [typhoeus][]. The highlights for rest-firebase are:
+
+* Concurrent/asynchronous requests
+* Streaming requests
+* Generate Firebase JWT for you (auto-refresh is WIP)
+
+[rest-firebase]: https://github.com/CodementorIO/rest-firebase
+[rest-core]: https://github.com/godfat/rest-core
+[typhoeus]: https://github.com/typhoeus/typhoeus
+
+### Concurrent/asynchronous requests
+
+At times we want to notify two users at the same time, instead of preparing
+two requests and wait for two requests to be done, we could simply do this:
+(not a working example, just try to demonstrate, see [README.md][] for
+working example)
+
+``` ruby
+f = RestFirebase.new
+f.put("users/#{a.id}", :message => 'Hi')
+f.put("users/#{b.id}", :message => 'Oh')
+```
+
+All requests are non-blocking, and it would only block when we try to look at
+the response. Therefore the above requests would be processed concurrently and
+asynchronously. To learn more about this, check [Concurrent HTTP Requests][].
+
+Also, consequently, if you're not waiting for the requests to be done
+somewhere, you might want to wait `at_exit` to make sure all
+requests are properly done like this:
+
+``` ruby
+at_exit do
+  RestFirebase.shutdown
+end
+```
+
+Which would also shutdown the [thread pool][] if you're using it.
+
+[README.md]: https://github.com/CodementorIO/rest-firebase/blob/master/README.md
+[Concurrent HTTP Requests]: https://github.com/CodementorIO/rest-firebase/blob/master/README.md#concurrent-http-requests
+[thread pool]: https://github.com/godfat/rest-core#thread-pool--connection-pool
+
+### Streaming requests
+
+To receive the online presence events, we have a specialized daemon to listen
+on the presence node from Firebase. Something like below:
+
+``` ruby
+es = RestFirebase.new.event_source('presence')
+es.onerror do |error|
+  Codementor.handle_error(error) unless error.kind_of?(EOFError)
+end
+
+es.onreconnect do
+  firebase.auth = nil # refresh auth
+  !!@start # don't reconnect if we're closing
+end
+
+es.onmessage do |event, data|
+  next unless event == 'put'
+  next unless username = data['path'][%r{^/(\w+)/web$}, 1]
+  onpresence(username, data['data'])
+end
+
+es.start
+sleep(1) while @start
+
+es.close
+```
+
+`onpresence` is the one doing our business logic.
+
+### Generate Firebase JWT for you (auto-refresh is WIP)
+
+We could use Firebase JWT instead of our secret in order to make authorized
+requests. This would be much secure than simply use the secret, which would
+never expire unless we explicitly ask for. Checkout
+[Authenticating Your Server][] for more detail. [rest-firebase][] could
+generate one for you automatically by passing your secret to it like this:
+
+``` ruby
+f = RestFirebase.new :secret => 'secret',
+                     :d => {:auth_data => 'something'}
+f.get('presence') # => attach JWT for auth in the request automatically
+f.auth            # => the JWT
+f.auth = nil      # => remove old JWT
+f.auth            # => generate a fresh new JWT
+```
+
+Read the above document for what `:d` means here. Note that this JWT
+would expire after 24 hours. Every time you initialize a new `RestFirebase`
+it would generate a fresh new JWT, but if you want to keep using the same
+instance, you would probably need to refresh the JWT by yourselves, just like
+what we did when we tried to reconnect it in the streaming example.
+
+[Authenticating Your Server]: https://www.firebase.com/docs/security/custom-login.html#authenticating-your-server
+
+## Summary
+
+In order to take the full advantage of using Firebase with Ruby, we introduce
+you [rest-firebase][], which highlights:
+
+* Concurrent/asynchronous requests
+* Streaming requests
+* Generate Firebase JWT for you (auto-refresh is WIP)
+
+Please feel free to try it and use it. It's released under Apache License 2.0.

data/lib/rest-firebase.rb

@@ -7,7 +7,8 @@ RestFirebase = RC::Builder.client(:d, :secret, :auth) do
   use RC::Timeout       , 10
 
   use RC::DefaultSite   , 'https://SampleChat.firebaseIO-demo.com/'
-  use RC::DefaultHeaders, {'Accept' => 'application/json'}
+  use RC::DefaultHeaders, {'Accept' => 'application/json',
+                           'Content-Type' => 'application/json'}
   use RC::DefaultQuery  , nil
 
   use RC::FollowRedirect, 1
@@ -74,9 +75,14 @@ module RestFirebase::Client
   end
 
   def request env, app=app
-    super(env.merge(REQUEST_PATH    => "#{env[REQUEST_PATH]}.json",
-                    REQUEST_PAYLOAD => Json.encode(env[REQUEST_PAYLOAD])),
-          app)
+    path = "#{env[REQUEST_PATH]}.json"
+    payload = if env[REQUEST_PAYLOAD]
+      {REQUEST_PAYLOAD => Json.encode(env[REQUEST_PAYLOAD])}
+    else
+      {}
+    end
+
+    super(env.merge(REQUEST_PATH => path).merge(payload), app)
   end
 
   def generate_auth opts={}

data/rest-firebase.gemspec

@@ -1,16 +1,16 @@
 # -*- encoding: utf-8 -*-
-# stub: rest-firebase 0.9.0 ruby lib
+# stub: rest-firebase 0.9.1 ruby lib
 
 Gem::Specification.new do |s|
   s.name = "rest-firebase"
-  s.version = "0.9.0"
+  s.version = "0.9.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = [
   "Codementor",
   "Lin Jen-Shin (godfat)"]
-  s.date = "2014-05-13"
+  s.date = "2014-06-28"
   s.description = "Ruby Firebase REST API client built on top of [rest-core][].\n\n[rest-core]: https://github.com/godfat/rest-core"
   s.email = ["help@codementor.io"]
   s.files = [
@@ -23,6 +23,7 @@ Gem::Specification.new do |s|
   "README.md",
   "Rakefile",
   "TODO.md",
+  "doc/intro.md",
   "lib/rest-firebase.rb",
   "rest-firebase.gemspec",
   "task/README.md",

data/test/test_api.rb

@@ -14,6 +14,9 @@ describe RestFirebase do
 
   path = 'https://a.json?auth=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9%0A.eyJ2IjowLCJpYXQiOjAsImQiOm51bGx9%0A.C9JtzZhiCrsClNdAQcE7Irngr2BZJCH4x1p-IHxfrAo%3D%0A'
 
+  json = '{"status":"ok"}'
+  rbon = {'status' => 'ok'}
+
   def firebase
     RestFirebase.new(:secret => 'nnf')
   end
@@ -24,12 +27,15 @@ describe RestFirebase do
   end
 
   should 'put {"status":"ok"}' do
-    json = '{"status":"ok"}'
-    rbon = {'status' => 'ok'}
     stub_request(:put, path).with(:body => json).to_return(:body => json)
     firebase.put('https://a', rbon).should.eq rbon
   end
 
+  should 'have no payload for delete' do
+    stub_request(:delete, path).with(:body => nil).to_return(:body => json)
+    firebase.delete('https://a').should.eq rbon
+  end
+
   should 'parse event source' do
     stub_request(:get, path).to_return(:body => <<-SSE)
 event: put

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rest-firebase
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Codementor
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-13 00:00:00.000000000 Z
+date: 2014-06-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-core
@@ -44,6 +44,7 @@ files:
 - README.md
 - Rakefile
 - TODO.md
+- doc/intro.md
 - lib/rest-firebase.rb
 - rest-firebase.gemspec
 - task/README.md