firebasedb

README

Firebase Realtime Database GO client

Package firebasedb implements a REST client for the Firebase Realtime Database. The API is as close as possible to the official JavaScript API.

Credits

• Steven Berlanga for another implementation of Firebase in go. I also used some tricks from his travis config.
• Sameer Ajmani for his presentation Advanced Go Concurrency Patterns that I used to implement the Streams.

Documentation

Overview

Package firebasedb implements a REST client for the Firebase Realtime Database (https://firebase.google.com/docs/database/). The API is as close as possible to the official JavaScript API.

Similar / related project:

https://github.com/zabawaba99/firego
https://github.com/cosn/firebase

Reference / documentation:

https://firebase.google.com/docs/reference/rest/database
https://firebase.google.com/docs/database/rest/structure-data
https://firebase.google.com/docs/database/rest/retrieve-data
https://firebase.google.com/docs/database/rest/save-data
https://firebase.google.com/docs/reference/js/firebase.database.Database
https://firebase.google.com/docs/reference/js/firebase.database.Reference
https://firebase.google.com/docs/reference/js/firebase.database.Query
https://www.firebase.com/docs/rest/api

This packages uses the "Advanced Go Concurrency Patterns" presented by Sameer Ajmani:

https://blog.golang.org/advanced-go-concurrency-patterns

Index

• type Authenticator
• type Event
  • func (e Event) Value(v interface{}) (path string, err error)
• type Reference
  • func NewReference(url string) Reference
  • func (r Reference) Auth(auth Authenticator) Reference
  • func (r Reference) Child(path string) Reference
  • func (r Reference) Debug(w io.Writer) Reference
  • func (r Reference) EndAt(n interface{}) Reference
  • func (r Reference) EqualTo(n interface{}) Reference
  • func (r Reference) Export() Reference
  • func (r Reference) Key() string
  • func (r Reference) LimitToFirst(n int) Reference
  • func (r Reference) LimitToLast(n int) Reference
  • func (r Reference) OrderByChild(childKey string) Reference
  • func (r Reference) OrderByKey() Reference
  • func (r Reference) OrderByValue() Reference
  • func (r Reference) Parent() Reference
  • func (r Reference) PassKeepAlive(value bool) Reference
  • func (r Reference) Pretty() Reference
  • func (r Reference) Push(value interface{}) (name string, err error)
  • func (r Reference) Ref(path string) Reference
  • func (r Reference) RefFromUrl(url urllib.URL) Reference
  • func (r Reference) Remove() (err error)
  • func (r Reference) Retry(backOff *backoff.ExponentialBackOff) Reference
  • func (r Reference) Root() Reference
  • func (r Reference) Rules() Reference
  • func (r Reference) Set(value interface{}) (err error)
  • func (r Reference) SetWithResult(value interface{}, result interface{}) (err error)
  • func (r Reference) Shallow() Reference
  • func (r Reference) Silent() Reference
  • func (r Reference) StartAt(n interface{}) Reference
  • func (r Reference) String() string
  • func (r Reference) Subscribe() (*Subscription, error)
  • func (r Reference) Update(value interface{}) (err error)
  • func (r Reference) UpdateWithResult(value interface{}, result interface{}) (err error)
  • func (r Reference) Value(value interface{}) (err error)
  • func (r Reference) WithHttpClient(c *http.Client) Reference
• type Secret
  • func (s Secret) ParamName() string
  • func (s Secret) Renew() error
  • func (s Secret) String() string
• type Subscription
  • func (s *Subscription) Close() error
  • func (s *Subscription) Events() <-chan Event

Examples

• Reference.PassKeepAlive
• Reference.StartAt
• Reference.String
• Reference.Value

Types

type Authenticator

type Authenticator interface {
	String() string
	ParamName() string // usually "auth" ou "access_token"
	Renew() error
}

Authenticator is the interface used to add authentication data to the requests. The String() method returns the current token and Renew() is called if the current token has expired.

type Event

type Event struct {
	Type string // can be put, patch, keep-alive, cancel, or auth_revoked
	Err  error
	// contains filtered or unexported fields
}

Event is the type used to represent streaming events. The type of the event can be read directly from the type. The data is extracted using the Value method

See https://firebase.google.com/docs/reference/rest/database/#section-streaming for more details.

func (Event) Value

func (e Event) Value(v interface{}) (path string, err error)

Value unmarshals data from an event. It returns the data in v and the path of the event in the path return attribute.

type Reference

type Reference struct {
	Attempts int
	Error    error
	// contains filtered or unexported fields
}

Reference represents a specific location in the database and can be used for reading or writing data to that database location.

func NewReference

func NewReference(url string) Reference

NewReference creates a new Firebase DB reference at url passed as parameter.

func (Reference) Auth

func (r Reference) Auth(auth Authenticator) Reference

Auth authenticates the request to allow access to data protected by Firebase Realtime Database Rules. The argument is an object that implements the Authenticator interface. The String() method can either returns a Firebase app's secret or an authentication token.

Note that when the reference is used in a streaming submission, a "auth_revoked" event will trigger a re-authentication, and reopen the http connection. *This will result in an additional "put" event*.

See https://firebase.google.com/docs/reference/rest/database/#section-param-auth and https://firebase.google.com/docs/reference/rest/database/user-auth for more details.

func (Reference) Child

func (r Reference) Child(path string) Reference

Childs returns a reference for the location at the specified relative path.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#child for more details.

func (Reference) Debug

func (r Reference) Debug(w io.Writer) Reference

func (Reference) EndAt

func (r Reference) EndAt(n interface{}) Reference

EndAt creates a query with the specified ending point.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#endAt or https://firebase.google.com/docs/reference/js/firebase.database.Query#endAt for more details

func (Reference) EqualTo

func (r Reference) EqualTo(n interface{}) Reference

EqualTo creates a query which includes children which match the specified value.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#equalTo or https://firebase.google.com/docs/reference/js/firebase.database.Query#equalTo for more details

func (Reference) Export

func (r Reference) Export() Reference

Export returns a reference that include priority information in the response.

See https://firebase.google.com/docs/reference/rest/database/#section-param-format for more details.

func (Reference) Key

func (r Reference) Key() string

Key returns the last part of the current path. For example, "ada" is the key for https://sample-app.firebaseio.com/users/ada.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#key for more detail.

func (Reference) LimitToFirst

func (r Reference) LimitToFirst(n int) Reference

LimitToFirst generates a new query limited to the first specific number of children.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#limitToFirst or https://firebase.google.com/docs/reference/js/firebase.database.Query#limitToFirst for more details

func (Reference) LimitToLast

func (r Reference) LimitToLast(n int) Reference

LimitToLast generates a new query limited to the last specific number of children.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#limitToLast or https://firebase.google.com/docs/reference/js/firebase.database.Query#limitToLast for more details

func (Reference) OrderByChild

func (r Reference) OrderByChild(childKey string) Reference

OrderByChild generates a new query ordered by the specified child key.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#orderByChild or https://firebase.google.com/docs/reference/js/firebase.database.Query#orderByChild for more details

func (Reference) OrderByKey

func (r Reference) OrderByKey() Reference

OrderedByKey generates a new query ordered by key.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#orderByKey https://firebase.google.com/docs/reference/js/firebase.database.Query#orderByKey for more details

func (Reference) OrderByValue

func (r Reference) OrderByValue() Reference

OrderByValue generates a new query ordered by child values.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#orderByValue or https://firebase.google.com/docs/reference/js/firebase.database.Query#orderByValue for more details

func (Reference) Parent

func (r Reference) Parent() Reference

Parent returns the parent location of a reference.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#parent for more details.

func (Reference) PassKeepAlive

func (r Reference) PassKeepAlive(value bool) Reference

PassKeepAlive sets the passKeepAlive flag of the Reference. When the references is used in the Subscribe() method, the passKeepAlive flag controls the automatic handling if keep-alive messages.

Example

const dinoFactsUrl = "https://dinosaur-facts.firebaseio.com/"
db := NewReference(dinoFactsUrl)

// Get an events subscription that filters out keep-alive events (default)
s0, err := db.Ref("dinosaurs").PassKeepAlive(false).Subscribe()
if err != nil {
	log.Fatal(err)
}
s0.Close()

// Get an events subscription that includes keep-alive events
s1, err := db.Ref("dinosaurs").PassKeepAlive(true).Subscribe()
if err != nil {
	log.Fatal(err)
}
s1.Close()

func (Reference) Pretty

func (r Reference) Pretty() Reference

Pretty is used to view the data in a human-readable format. This is usually only used for debugging purposes.

See https://firebase.google.com/docs/reference/rest/database/#section-param-print for more details.

func (Reference) Push

func (r Reference) Push(value interface{}) (name string, err error)

Push generates a new child location using a unique key and returns this key in the parameter "name".

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#push for more details.

func (Reference) Ref

func (r Reference) Ref(path string) Reference

Ref returns a reference to the root or the specified path. See https://firebase.google.com/docs/reference/js/firebase.database.Reference#ref or https://firebase.google.com/docs/reference/js/firebase.database.Database#ref for more details.

func (Reference) RefFromUrl

func (r Reference) RefFromUrl(url urllib.URL) Reference

RefFromUrl returns a reference to the root or the path specified in url. err is set if the host of the url is not the same as the current database.

See https://firebase.google.com/docs/reference/js/firebase.database.Database#refFromURL for more details.

func (Reference) Remove

func (r Reference) Remove() (err error)

Remove deletes the data at the database location given by the reference r. Any data at child locations will also be deleted.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#remove for more details.

func (Reference) Retry

func (r Reference) Retry(backOff *backoff.ExponentialBackOff) Reference

Retry sets the retry policy for the Reference. When a references has the retry policy set, then the library will retry the requests in case of failures.

func (Reference) Root

func (r Reference) Root() Reference

Root returns the root location of a reference.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#root for more details.

func (Reference) Rules

func (r Reference) Rules() Reference

Rules returns a reference to the rules settings of the database.

func (Reference) Set

func (r Reference) Set(value interface{}) (err error)

Set write data to the database location given by the Reference r. This will overwrite any data at this location and all child locations.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#set for more details.

func (Reference) SetWithResult

func (r Reference) SetWithResult(value interface{}, result interface{}) (err error)

SetWithResult does the same as the Set function and, additionally, stores the resulting node in result.

func (Reference) Shallow

func (r Reference) Shallow() Reference

Shallow is an advanced feature, designed to help you work with large datasets without needing to download everything. Set this to true to limit the depth of the data returned at a location. If the data at the location is a JSON primitive (string, number or boolean), its value will simply be returned. If the data snapshot at the location is a JSON object, the values for each key will be truncated to true.

See https://firebase.google.com/docs/reference/rest/database/#section-param-shallow for more details.

func (Reference) Silent

func (r Reference) Silent() Reference

Silent is used to suppress the output from the server when writing data. The resulting response will be empty and indicated by a 204 No Content HTTP status code.

See https://firebase.google.com/docs/reference/rest/database/#section-param-print for more details.

func (Reference) StartAt

func (r Reference) StartAt(n interface{}) Reference

StartAt creates a query with the specified starting point.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#startAt or https://firebase.google.com/docs/reference/js/firebase.database.Query#startAt for more details.

Example

const dinoFactsUrl = "https://dinosaur-facts.firebaseio.com/"

type dinosaurFact struct {
	Appeared int64   `json:"appeared"`
	Height   float32 `json:"height"`
	Length   float32 `json:"length"`
	Order    string  `json:"order"`
	Vanished int64   `json:"vanished"`
	Weight   int32   `json:"weight"`
}

type dinosaurs map[string]dinosaurFact

db := NewReference(dinoFactsUrl)
if db.Error != nil {
	log.Fatalf("Error opening database: %v", db.Error)
}
var dinos = dinosaurs{}
db.Ref("dinosaurs").OrderByChild("height").StartAt(3).EndAt(5).Value(&dinos)

var keys []string
for k := range dinos {
	keys = append(keys, k)
}
sort.Strings(keys)
for _, k := range keys {
	fmt.Printf("The %s's height is %v\n", k, dinos[k].Height)
}

Output:

The stegosaurus's height is 4
The triceratops's height is 3

func (Reference) String

func (r Reference) String() string

String returns the absolute URL for this location.

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#toString for more details.

Example

const dinoFactsUrl = "https://dinosaur-facts.firebaseio.com/"
db := NewReference(dinoFactsUrl)
fmt.Println(db.Ref("dinosaurs").Child("stegosaurus").String())

Output:

https://dinosaur-facts.firebaseio.com/dinosaurs/stegosaurus

func (Reference) Subscribe

func (r Reference) Subscribe() (*Subscription, error)

Subscribe returns a subscription on the reference. The returned subscription is used to access the streamed events.

func (Reference) Update

func (r Reference) Update(value interface{}) (err error)

Update writes multiple values to the database at once. The "value" argument contains multiple property/value pairs that will be written to the database together. Each child property can either be a simple property (for example, "name"), or a relative path (for example, "name/first") from the current location to the data to update.

As opposed to the set() method, update() can be use to selectively update only the referenced properties at the current location (instead of replacing all the child properties at the current location).

See https://firebase.google.com/docs/reference/js/firebase.database.Reference#update for more details.

func (Reference) UpdateWithResult

func (r Reference) UpdateWithResult(value interface{}, result interface{}) (err error)

UpdateWithResult does the same as the Update function and, additionally, stores the updated node in result.

func (Reference) Value

func (r Reference) Value(value interface{}) (err error)

Value reads from the database and store the content in value. It gives an error if it the request fails or if it can't decode the returned payload.

Example

const dinoFactsUrl = "https://dinosaur-facts.firebaseio.com/"

type dinosaurFact struct {
	Appeared int64   `json:"appeared"`
	Height   float32 `json:"height"`
	Length   float32 `json:"length"`
	Order    string  `json:"order"`
	Vanished int64   `json:"vanished"`
	Weight   int32   `json:"weight"`
}

type dinosaurs map[string]dinosaurFact

db := NewReference(dinoFactsUrl)
if db.Error != nil {
	log.Fatalf("Error opening database: %v", db.Error)
}
var dinos = dinosaurs{}
db.Ref("dinosaurs").Value(&dinos)
var keys []string
for k := range dinos {
	keys = append(keys, k)
}
sort.Strings(keys)
for _, k := range keys {
	fmt.Printf("The %s's height is %v\n", k, dinos[k].Height)
}

Output:

The bruhathkayosaurus's height is 25
The lambeosaurus's height is 2.1
The linhenykus's height is 0.6
The pterodactyl's height is 0.6
The stegosaurus's height is 4
The triceratops's height is 3

func (Reference) WithHttpClient

func (r Reference) WithHttpClient(c *http.Client) Reference

WithHttpClient sets a custom HTTP client for the REST requests. If set to nil (default), then http.DefaultClient is used.

type Secret

type Secret struct {
	Token string
}

Secret implements the Authenticator interface and is used with static Database secret.

func (Secret) ParamName

func (s Secret) ParamName() string

ParamName returns "auth"

func (Secret) Renew

func (s Secret) Renew() error

Renew is not allowed for static secret and thus always returns an error.

func (Secret) String

func (s Secret) String() string

String returns the static Database secret

type Subscription

type Subscription struct {
	LastKeepAlive time.Time
	// contains filtered or unexported fields
}

Subscription is the interface for event subscriptions. Subscriptions are returned by the Subscribe method.

func (*Subscription) Close

func (s *Subscription) Close() error

Close closes the subscription and finishes the request.

func (*Subscription) Events

func (s *Subscription) Events() <-chan Event

Events returns the event channel from the subscription.