firego

package module
v1.0.0-...-3bcc4b6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 31, 2019 License: MIT Imports: 16 Imported by: 23

README

Firego

Deprecated in favor of firebase/firebase-admin-go.


Build Status Coverage Status

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

  1. Fork it
  2. Create your feature branch (git checkout -b new-feature)
  3. Commit your changes (git commit -am 'Some cool reflection')
  4. Push to the branch (git push origin new-feature)
  5. Create new Pull Request

Documentation

Overview

Package firego is a REST client for Firebase (https://firebase.com).

Index

Examples

Constants

View Source
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

View Source
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.

func (Event) Value

func (e Event) Value(v interface{}) error

Value converts the raw payload of the event into the given interface.

type Firebase

type Firebase struct {
	// contains filtered or unexported fields
}

Firebase represents a location in the cloud.

func New

func New(url string, client *http.Client) *Firebase

New creates a new Firebase reference, if client is nil, http.DefaultClient is used.

func (*Firebase) Auth

func (fb *Firebase) Auth(token string)

Auth sets the custom Firebase token used to authenticate to Firebase.

Example
package main

import (
	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com", nil)
	fb.Auth("my-token")
}
Output:

func (*Firebase) Child

func (fb *Firebase) Child(child string) *Firebase

Child creates a new Firebase reference for the requested child with the same configuration as the parent.

Example
package main

import (
	"log"

	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com", nil)
	childFB := fb.Child("some/child/path")

	log.Printf("My new ref %s\n", childFB)
}
Output:

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

func (fb *Firebase) EndAt(value string) *Firebase

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

Example
package main

import (
	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com", nil)
	// Set value
	fb = fb.EndAt("a")
	// Remove query parameter
	fb = fb.EndAt("")
}
Output:

func (*Firebase) EndAtValue

func (fb *Firebase) EndAtValue(value interface{}) *Firebase

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

func (fb *Firebase) EqualTo(value string) *Firebase

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

func (fb *Firebase) EqualToValue(value interface{}) *Firebase

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

func (fb *Firebase) IncludePriority(v bool)

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

Example
package main

import (
	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com", nil)
	// Set value
	fb.IncludePriority(true)
	// Remove query parameter
	fb.IncludePriority(false)
}
Output:

func (*Firebase) LimitToFirst

func (fb *Firebase) LimitToFirst(value int64) *Firebase

LimitToFirst creates a new Firebase reference with the requested limitToFirst configuration.

Reference https://firebase.google.com/docs/database/rest/retrieve-data#limit-queries

Example
package main

import (
	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com", nil)
	// Set value
	fb = fb.LimitToFirst(5)
	// Remove query parameter
	fb = fb.LimitToFirst(-1)
}
Output:

func (*Firebase) LimitToLast

func (fb *Firebase) LimitToLast(value int64) *Firebase

LimitToLast creates a new Firebase reference with the requested limitToLast configuration.

Reference https://firebase.google.com/docs/database/rest/retrieve-data#limit-queries

Example
package main

import (
	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com", nil)
	// Set value
	fb = fb.LimitToLast(8)
	// Remove query parameter
	fb = fb.LimitToLast(-1)
}
Output:

func (*Firebase) OrderBy

func (fb *Firebase) OrderBy(value string) *Firebase

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

Example
package main

import (
	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com", nil)
	// Set value
	fb = fb.OrderBy("a")
	// Remove query parameter
	fb = fb.OrderBy("")
}
Output:

func (*Firebase) Push

func (fb *Firebase) Push(v interface{}) (*Firebase, error)

Push creates a reference to an auto-generated child location.

Example
package main

import (
	"log"

	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com", nil)
	newRef, err := fb.Push("my-value")
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("My new ref %s\n", newRef)
}
Output:

func (*Firebase) Ref

func (fb *Firebase) Ref(path string) (*Firebase, error)

Ref returns a copy of an existing Firebase reference with a new path.

func (*Firebase) Remove

func (fb *Firebase) Remove() error

Remove the Firebase reference from the cloud.

Example
package main

import (
	"log"

	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com/some/value", nil)
	if err := fb.Remove(); err != nil {
		log.Fatal(err)
	}
}
Output:

func (*Firebase) RemoveEventFunc

func (fb *Firebase) RemoveEventFunc(fn ChildEventFunc)

RemoveEventFunc removes the given function from the firebase reference.

func (*Firebase) Set

func (fb *Firebase) Set(v interface{}) error

Set the value of the Firebase reference.

Example
package main

import (
	"log"

	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com", nil)

	v := map[string]interface{}{
		"foo": "bar",
		"bar": 1,
		"bez": []string{"hello", "world"},
	}
	if err := fb.Set(v); err != nil {
		log.Fatal(err)
	}
}
Output:

func (*Firebase) SetURL

func (fb *Firebase) SetURL(url string)

SetURL changes the url for a firebase reference.

func (*Firebase) Shallow

func (fb *Firebase) Shallow(v bool)

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

Example
package main

import (
	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com", nil)
	// Set value
	fb.Shallow(true)
	// Remove query parameter
	fb.Shallow(false)
}
Output:

func (*Firebase) StartAt

func (fb *Firebase) StartAt(value string) *Firebase

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

Example
package main

import (
	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com", nil)
	// Set value
	fb = fb.StartAt("a")
	// Remove query parameter
	fb = fb.StartAt("")
}
Output:

func (*Firebase) StartAtValue

func (fb *Firebase) StartAtValue(value interface{}) *Firebase

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.

Example
package main

import (
	"log"
	"time"

	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com/some/value", nil)
	notifications := make(chan firego.Event)
	if err := fb.Watch(notifications); err != nil {
		log.Fatal(err)
	}

	go func() {
		for range notifications {
		}
		log.Println("Channel closed")
	}()
	time.Sleep(10 * time.Millisecond) // let go routine start

	fb.StopWatching()
}
Output:

func (*Firebase) String

func (fb *Firebase) String() string

String returns the string representation of the Firebase reference.

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) URL

func (fb *Firebase) URL() string

URL returns firebase reference URL

func (*Firebase) Unauth

func (fb *Firebase) Unauth()

Unauth removes the current token being used to authenticate to Firebase.

func (*Firebase) Update

func (fb *Firebase) Update(v interface{}) error

Update the specific child with the given value.

Example
package main

import (
	"log"

	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com/some/value", nil)
	if err := fb.Update("new-value"); err != nil {
		log.Fatal(err)
	}
}
Output:

func (*Firebase) Value

func (fb *Firebase) Value(v interface{}) error

Value gets the value of the Firebase reference.

Example
package main

import (
	"log"

	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com/some/value", nil)
	var v interface{}
	if err := fb.Value(v); err != nil {
		log.Fatal(err)
	}

	log.Printf("My value %v\n", v)
}
Output:

func (*Firebase) Watch

func (fb *Firebase) Watch(notifications chan Event) error

Watch listens for changes on a firebase instance and passes over to the given chan.

Only one connection can be established at a time. The second call to this function without a call to fb.StopWatching will close the channel given and return nil immediately.

Example
package main

import (
	"log"

	"github.com/zabawaba99/firego"
)

func main() {
	fb := firego.New("https://someapp.firebaseio.com/some/value", nil)
	notifications := make(chan firego.Event)
	if err := fb.Watch(notifications); err != nil {
		log.Fatal(err)
	}

	for event := range notifications {
		log.Println("Event Received")
		log.Printf("Type: %s\n", event.Type)
		log.Printf("Path: %s\n", event.Path)
		log.Printf("Data: %v\n", event.Data)
		if event.Type == firego.EventTypeError {
			log.Print("Error occurred, loop ending")
		}
	}
}
Output:

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.

Directories

Path Synopsis
Package firetest provides utilities for Firebase testing
Package firetest provides utilities for Firebase testing

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL