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: 21

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.

Source Files

View all Source files

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
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.