Ruby firepower for your Firebase battery!
Firebase is a real-time backend that allows one to store key-value pairs in a hierarchical fashion, without having to manage additional servers. Firebase offers api's for a variety of client libs such as javascript, REST, IOS and now Ruby ;-). A cool feature of firebase is that it allows disparate clients to broadcast updates and sync up across the wire. Checkout http://firebase.com for the firehose...
$ gem install bigbertha
Sign up for a firebase account and create a new firebase of your liking. In the following code samples, we will use the following as our base url:
Then you can specify an entry point into the data using the following call:
ref = Bigbertha::Ref.new( 'https://zerodarkthirty.firebaseio.com' )
NOTE: You don't have to start a the root, but usually a good idea since this api offers ways to traverse the hierarchy up or down. But more on this later...
Firebase supports the following data types:
data = {
a: 0,
b: %s(Hello World),
c: 10.5
}
ref.set( data )
Yields:
NOTE: Set is a destructive operation and will replace the previous content for the reference it is called from.
Thus
data = {
a: 0
}
ref.set( data )
Yields
Hence replacing the previously assigned content.
ref.set( %w(Hello World) )
Yields:
The preferred method to construct lists in your firebase is to use the push operation, which will automatically provide ordering to your list.
ref.push( "BumbleBee" )
ref.push( "Tuna" )
Yields:
NOTE: The list indexes will be autogenerated by firebase to ensure correct ordering on retrieval.
data = {
a: {
a_1: %s(Hello World),
a_2: 10.5
},
b: {
b_1: 10,
b_2: true
}
}
ref.set( data )
Yields:
Fetching data in the hierarchy is done via the read operation.
# Setup...
data = {
a: {
a_1: %s(Hello World),
a_2: 10.5
},
b: {
b_1: 10,
b_2: true
}
}
ref.set( data )
ref.child( :a, :a_2 ).read # => 10.5
# or...
ref.child( :a, :a_2 ).val # => 10.5
a_val = ref.child( :a ).read
a_val.a_1 # => 'Hello World'
a_val[:a_1] # => 'Hello World' or use hash indexing...
a_val.a_2 # => 10.5
You can use the #update on a reference to modify nodes in the hierarchy
# Setup...
data = {
a: {
a_1: %s(Hello World),
a_2: {
a_2_1: 10.5,
a_2_2: "Word!"
}
},
b: {
b_1: 10,
b_2: true
}
}
ref.set( data )
ref.child( :a ).update( a_1:"BumbleBee Tuna" )
ref.child( 'a/a_2' ).update( a_2_2:"You bet!" )
ref.child( 'a' ).child( 'a_3' ).update( a_3_1:"You better!" )
Yields:
Note: the last call inserts a branch new node in the hierarchy. We could have use set here as well to perform the insert.
You can leverage #inc/#dec to increment/decrement counter like data.
IMPORTANT! Sadly Firebase currently does not offer transactions using their REST api, hence there is no guarantees about the atomicity of read/write operations ;-(
Use the #remove operation to delete nodes at any level in the hierarchy.
# Setup...
data = {
a: {
a_1: %s(Hello World),
a_2: {
a_2_1: 10.5,
a_2_2: "Word!"
}
},
b: {
b_1: 10,
b_2: true
}
}
ref.set( data )
ref.child( 'a/a_2/a_2_2' ).remove
ref.child( :b ).remove
NOTE: Calling remove on the root ref will delete the entire hierarchy.
You can traverse the hierarchy using the #child or #parent. These calls can be chained.
data = {
a: {
a_1: %s(Hello World),
a_2: {
a_2_1: 10.5,
a_2_2: "Word!"
}
},
b: {
b_1: 10,
b_2: true
}
}
ref.set( data )
a_2_2_ref = ref.child( 'a/a_2/a_2_2' )
# or...
a_2_2_ref = ref.child( :a ).child( :a_2 ).child( :a_2_2 )
# or...
a_2_2_ref = ref.child( :a, :a_2, :a_2_2 )
# or...
a_2_2_ref = ref.child( %w(a a_2 a_2_2) )
a_2_2_ref.name #=> 'a_2_2'
a_2_ref = a_2_2_ref.parent
a_2_ref.name # => 'a_2'
a_ref = a_2_2_ref.parent.parent
a_ref.name # => 'a'
Firebase provides for setting priorities on ordered list in order to affect the retrieval. By default priority is null. Setting priority affects the retrieval as follows (See firebase web site for details!):
a_ref = ref.push( {a:1, b:2} )
b_ref = ref.push( {c:1, d:2} )
a_ref.set_priority( 20 )
b_ref.set_priority( 10 )
a_ref.parent.read #=> {-IrNhTASqxqEpNMw8NGq: {c: 1, d: 2}, -IrNhT2vsoQ1WlgSG6op: {a: 1, b: 2} }
You can secure you firebase store using a secret token and grant access for permissions on the store using rules. Please refer to the firebase docs for details.
Note: We've encapsulated the Firebase auth token generator ruby implementation to make generating tokens more convenient.
> bb_auth_token -h
> bb_auth_token SECRET --data "{\"user\":\"bozo\"}"
ref = Bigbertha::Ref.new( 'https://bozo.firebaseio.com', auth_token|secret )
ref.set( tmp: { a: 0, b: 1 } )
ref.set_rules(
{
'.read' => true,
'.write' => "auth.user == 'bozo'",
"tmp" => {
'.read' => true,
'.write' => false
}
}
)
res = ref.child(:tmp).read # => { a: 0, b: 1 }
ref.set( tmp: {d:0} ) } # => Bigbertha::Action::PermissionDeniedError
Fernand Galiana
Still work in progress. So please feel free to contact me if you run into issues or just want to touch base...
Bigbertha is released under the MIT license.