README
¶
Firego
Deprecated in favor of firebase/firebase-admin-go.
A Firebase client written in Go
Installation
go get -u gopkg.in/zabawaba99/firego.v1
Usage
Import firego
import "gopkg.in/zabawaba99/firego.v1"
Create a new firego reference
f := firego.New("https://my-firebase-app.firebaseIO.com", nil)
with existing http client
f := firego.New("https://my-firebase-app.firebaseIO.com", client)
Request Timeouts
By default, the Firebase
reference will timeout after 30 seconds of trying
to reach a Firebase server. You can configure this value by setting the global
timeout duration
firego.TimeoutDuration = time.Minute
Authentication
You can authenticate with your service_account.json
file by using the
golang.org/x/oauth2
package (thanks @m00sey for the snippet)
d, err := ioutil.ReadFile("our_service_account.json")
if err != nil {
return nil, err
}
conf, err := google.JWTConfigFromJSON(d, "https://www.googleapis.com/auth/userinfo.email",
"https://www.googleapis.com/auth/firebase.database")
if err != nil {
return nil, err
}
fb := firego.New("https://you.firebaseio.com", conf.Client(oauth2.NoContext))
// use the authenticated fb instance
Legacy Tokens
f.Auth("some-token-that-was-created-for-me")
f.Unauth()
Visit Fireauth if you'd like to generate your own auth tokens
Get Value
var v map[string]interface{}
if err := f.Value(&v); err != nil {
log.Fatal(err)
}
fmt.Printf("%s\n", v)
Querying
Take a look at Firebase's query parameters for more information on what each function does.
var v map[string]interface{}
if err := f.StartAt("a").EndAt("c").LimitToFirst(8).OrderBy("field").Value(&v); err != nil {
log.Fatal(err)
}
fmt.Printf("%s\n", v)
Set Value
v := map[string]string{"foo":"bar"}
if err := f.Set(v); err != nil {
log.Fatal(err)
}
Push Value
v := "bar"
pushedFirego, err := f.Push(v)
if err != nil {
log.Fatal(err)
}
var bar string
if err := pushedFirego.Value(&bar); err != nil {
log.Fatal(err)
}
// prints "https://my-firebase-app.firebaseIO.com/-JgvLHXszP4xS0AUN-nI: bar"
fmt.Printf("%s: %s\n", pushedFirego, bar)
Update Child
v := map[string]string{"foo":"bar"}
if err := f.Update(v); err != nil {
log.Fatal(err)
}
Remove Value
if err := f.Remove(); err != nil {
log.Fatal(err)
}
Watch a Node
notifications := make(chan firego.Event)
if err := f.Watch(notifications); err != nil {
log.Fatal(err)
}
defer f.StopWatching()
for event := range notifications {
fmt.Printf("Event %#v\n", event)
}
fmt.Printf("Notifications have stopped")
Change reference
You can use a reference to save or read data from a specified reference
userID := "bar"
usersRef,err := f.Ref("users/"+userID)
if err != nil {
log.Fatal(err)
}
v := map[string]string{"id":userID}
if err := usersRef.Set(v); err != nil {
log.Fatal(err)
}
Check the GoDocs or Firebase Documentation for more details
Running Tests
In order to run the tests you need to go get -t ./...
first to go-get the test dependencies.
Issues Management
Feel free to open an issue if you come across any bugs or if you'd like to request a new feature.
Contributing
- Fork it
- Create your feature branch (
git checkout -b new-feature
) - Commit your changes (
git commit -am 'Some cool reflection'
) - Push to the branch (
git push origin new-feature
) - Create new Pull Request
Documentation
¶
Overview ¶
Package firego is a REST client for Firebase (https://firebase.com).
Index ¶
- Constants
- Variables
- type ChildEventFunc
- type DataSnapshot
- type ErrTimeout
- type Event
- type Firebase
- func (fb *Firebase) Auth(token string)
- func (fb *Firebase) Child(child string) *Firebase
- func (fb *Firebase) ChildAdded(fn ChildEventFunc) error
- func (fb *Firebase) ChildChanged(fn ChildEventFunc) error
- func (fb *Firebase) ChildRemoved(fn ChildEventFunc) error
- func (fb *Firebase) EndAt(value string) *Firebase
- func (fb *Firebase) EndAtValue(value interface{}) *Firebase
- func (fb *Firebase) EqualTo(value string) *Firebase
- func (fb *Firebase) EqualToValue(value interface{}) *Firebase
- func (fb *Firebase) IncludePriority(v bool)
- func (fb *Firebase) LimitToFirst(value int64) *Firebase
- func (fb *Firebase) LimitToLast(value int64) *Firebase
- func (fb *Firebase) OrderBy(value string) *Firebase
- func (fb *Firebase) Push(v interface{}) (*Firebase, error)
- func (fb *Firebase) Ref(path string) (*Firebase, error)
- func (fb *Firebase) Remove() error
- func (fb *Firebase) RemoveEventFunc(fn ChildEventFunc)
- func (fb *Firebase) Set(v interface{}) error
- func (fb *Firebase) SetURL(url string)
- func (fb *Firebase) Shallow(v bool)
- func (fb *Firebase) StartAt(value string) *Firebase
- func (fb *Firebase) StartAtValue(value interface{}) *Firebase
- func (fb *Firebase) StopWatching()
- func (fb *Firebase) String() string
- func (fb *Firebase) Transaction(fn TransactionFn) error
- func (fb *Firebase) URL() string
- func (fb *Firebase) Unauth()
- func (fb *Firebase) Update(v interface{}) error
- func (fb *Firebase) Value(v interface{}) error
- func (fb *Firebase) Watch(notifications chan Event) error
- type TransactionFn
Examples ¶
Constants ¶
const ( // EventTypePut is the event type sent when new data is inserted to the // Firebase instance. EventTypePut = "put" // EventTypePatch is the event type sent when data at the Firebase instance is // updated. EventTypePatch = "patch" // EventTypeError is the event type sent when an unknown error is encountered. EventTypeError = "event_error" // EventTypeAuthRevoked is the event type sent when the supplied auth parameter // is no longer valid. EventTypeAuthRevoked = "auth_revoked" )
Variables ¶
var TimeoutDuration = 30 * time.Second
TimeoutDuration is the length of time any request will have to establish a connection and receive headers from Firebase before returning an ErrTimeout error.
Functions ¶
This section is empty.
Types ¶
type ChildEventFunc ¶
type ChildEventFunc func(snapshot DataSnapshot, previousChildKey string)
ChildEventFunc is the type of function that is called for every new child added under a firebase reference. The snapshot argument contains the data that was added. The previousChildKey argument contains the key of the previous child that this function was called for.
type DataSnapshot ¶
type DataSnapshot struct { // Key retrieves the key for the source location of this snapshot Key string // Value retrieves the data contained in this snapshot. Value interface{} }
DataSnapshot instances contains data from a Firebase reference.
func (*DataSnapshot) Child ¶
func (d *DataSnapshot) Child(name string) (DataSnapshot, bool)
Child gets a DataSnapshot for the location at the specified relative path. The relative path can either be a simple child key (e.g. 'fred') or a deeper slash-separated path (e.g. 'fred/name/first').
type ErrTimeout ¶
type ErrTimeout struct {
// contains filtered or unexported fields
}
ErrTimeout is an error type is that is returned if a request exceeds the TimeoutDuration configured.
type Event ¶
type Event struct { // Type of event that was received Type string // Path to the data that changed Path string // Data that changed Data interface{} // contains filtered or unexported fields }
Event represents a notification received when watching a firebase reference.
type Firebase ¶
type Firebase struct {
// contains filtered or unexported fields
}
Firebase represents a location in the cloud.
func (*Firebase) Child ¶
Child creates a new Firebase reference for the requested child with the same configuration as the parent.
func (*Firebase) ChildAdded ¶
func (fb *Firebase) ChildAdded(fn ChildEventFunc) error
ChildAdded listens on the firebase instance and executes the callback for every child that is added.
You cannot set the same function twice on a Firebase reference, if you do the first function will be overridden and you will not be able to close the connection.
func (*Firebase) ChildChanged ¶
func (fb *Firebase) ChildChanged(fn ChildEventFunc) error
ChildChanged listens on the firebase instance and executes the callback for every child that is changed.
You cannot set the same function twice on a Firebase reference, if you do the first function will be overridden and you will not be able to close the connection.
func (*Firebase) ChildRemoved ¶
func (fb *Firebase) ChildRemoved(fn ChildEventFunc) error
ChildRemoved listens on the firebase instance and executes the callback for every child that is deleted.
You cannot set the same function twice on a Firebase reference, if you do the first function will be overridden and you will not be able to close the connection.
func (*Firebase) EndAt ¶
EndAt creates a new Firebase reference with the requested EndAt configuration. The value that is passed in is automatically escaped if it is a string value. Numeric strings are automatically converted to numbers.
EndAt(7) // -> endAt=7 EndAt("7") // -> endAt=7 EndAt("foo") // -> endAt="foo" EndAt(`"foo"`) // -> endAt="foo"
Reference https://firebase.google.com/docs/database/rest/retrieve-data#section-rest-filtering
func (*Firebase) EndAtValue ¶
EndAtValue creates a new Firebase reference with the requested EndAt configuration. The value that is passed in is automatically escaped if it is a string value. Numeric strings are preserved as strings.
EndAtValue(7) // -> endAt=7 EndAtValue("7") // -> endAt="7" EndAtValue("foo") // -> endAt="foo" EndAtValue(`"foo"`) // -> endAt="foo"
Reference https://firebase.google.com/docs/database/rest/retrieve-data#section-rest-filtering
func (*Firebase) EqualTo ¶
EqualTo sends the query string equalTo so that one can find nodes with exactly matching values. The value that is passed in is automatically escaped if it is a string value. Numeric strings are automatically converted to numbers.
EqualTo(7) // -> equalTo=7 EqualTo("7") // -> equalTo=7 EqualTo("foo") // -> equalTo="foo" EqualTo(`"foo"`) // -> equalTo="foo"
Reference https://firebase.google.com/docs/database/rest/retrieve-data#section-rest-filtering
func (*Firebase) EqualToValue ¶
EqualToValue sends the query string equalTo so that one can find nodes with exactly matching values. The value that is passed in is automatically escaped if it is a string value. Numeric strings are preserved as strings.
EqualToValue(7) // -> equalTo=7 EqualToValue("7") // -> equalTo="7" EqualToValue("foo") // -> equalTo="foo" EqualToValue(`"foo"`) // -> equalTo="foo"
Reference https://firebase.google.com/docs/database/rest/retrieve-data#section-rest-filtering
func (*Firebase) IncludePriority ¶
IncludePriority determines whether or not to ask Firebase for the values priority. By default, the priority is not returned.
Reference https://www.firebase.com/docs/rest/api/#section-param-format
func (*Firebase) LimitToFirst ¶
LimitToFirst creates a new Firebase reference with the requested limitToFirst configuration.
Reference https://firebase.google.com/docs/database/rest/retrieve-data#limit-queries
func (*Firebase) LimitToLast ¶
LimitToLast creates a new Firebase reference with the requested limitToLast configuration.
Reference https://firebase.google.com/docs/database/rest/retrieve-data#limit-queries
func (*Firebase) OrderBy ¶
OrderBy creates a new Firebase reference with the requested OrderBy configuration. The value that is passed in is automatically escaped if it is a string value.
OrderBy("foo") // -> orderBy="foo" OrderBy(`"foo"`) // -> orderBy="foo" OrderBy("$key") // -> orderBy="$key"
Reference https://firebase.google.com/docs/database/rest/retrieve-data#orderby
func (*Firebase) RemoveEventFunc ¶
func (fb *Firebase) RemoveEventFunc(fn ChildEventFunc)
RemoveEventFunc removes the given function from the firebase reference.
func (*Firebase) Shallow ¶
Shallow limits the depth of the data returned when calling Value. If the data at the location is a JSON primitive (string, number or boolean), its value will be returned. If the data is a JSON object, the values for each key will be truncated to true.
Reference https://firebase.google.com/docs/database/rest/retrieve-data#shallow
func (*Firebase) StartAt ¶
StartAt creates a new Firebase reference with the requested StartAt configuration. The value that is passed in is automatically escaped if it is a string value. Numeric strings are automatically converted to numbers.
StartAt(7) // -> startAt=7 StartAt("7") // -> startAt=7 StartAt("foo") // -> startAt="foo" StartAt(`"foo"`) // -> startAt="foo"
Reference https://firebase.google.com/docs/database/rest/retrieve-data#section-rest-filtering
func (*Firebase) StartAtValue ¶
StartAtValue creates a new Firebase reference with the requested StartAt configuration. The value that is passed in is automatically escaped if it is a string value. Numeric strings are preserved as strings.
StartAtValue(7) // -> startAt=7 StartAtValue("7") // -> startAt="7" StartAtValue("foo") // -> startAt="foo" StartAtValue(`"foo"`) // -> startAt="foo"
Reference https://firebase.google.com/docs/database/rest/retrieve-data#section-rest-filtering
func (*Firebase) StopWatching ¶
func (fb *Firebase) StopWatching()
StopWatching stops tears down all connections that are watching.
func (*Firebase) Transaction ¶
func (fb *Firebase) Transaction(fn TransactionFn) error
Transaction runs a transaction on the data at this location. The TransactionFn parameter will be called, possibly multiple times, with the current data at this location. It is responsible for inspecting that data and specifying either the desired new data at the location or that the transaction should be aborted.
Since the provided function may be called repeatedly for the same transaction, be extremely careful of any side effects that may be triggered by this method.
Best practices for this method are to rely only on the data that is passed in.
func (*Firebase) Unauth ¶
func (fb *Firebase) Unauth()
Unauth removes the current token being used to authenticate to Firebase.
type TransactionFn ¶
type TransactionFn func(currentSnapshot interface{}) (result interface{}, err error)
TransactionFn is used to run a transaction on a Firebase reference. See Firebase.Transaction for more information.