Documentation ¶
Overview ¶
Package firebase gives a thin wrapper around the firebase REST API. It tries to mirror the Official firebase API somewhat closely. https://www.firebase.com/docs/web/api/
Index ¶
Constants ¶
const (
KeyProp = "$key"
)
Variables ¶
This section is empty.
Functions ¶
func SetStreamTimeout ¶
SetStreamTimeout replaces the connection pool for SSE streaming connections with a new one, using the given duration as the value of its read timeout.
The impetus behind this function is that firebase disruptions of long-lived SSE clients happen occasionally. Connections are observed to remain alive but no longer report events. This function enables consumers of this library to force-set a timeout value for all stream connections to bound the amount of time they may remain open.
WARNING: This function should only be called while there are no SSE stream connections open.
Types ¶
type Api ¶
type Api interface { // Call is responsible for performing HTTP transactions such as GET, POST, // PUT, PATCH, and DELETE. It is used to communicate with Firebase by all // of the Client methods, except for Watch. // // Arguments are as follows: // - `method`: The http method for this call // - `path`: The full firebase url to call // - `body`: Data to be marshalled to JSON (it's the responsibility of Call to do the marshalling and unmarshalling) // - `params`: Additional parameters to be passed to firebase // - `dest`: The object to save the unmarshalled response body to. // It's up to this method to unmarshal correctly, the default implemenation just uses `json.Unmarshal` Call(method, path, auth string, body interface{}, params map[string]string, dest interface{}) error // Stream is responsible for implementing a SSE/Event Source client that // communicates with Firebase to watch changes to a location in real-time. // // Arguments are as follows: // - `path`: The full firebase url to call // - `body`: Data to be marshalled to JSON // - `params`: Additional parameters to be passed to firebase // - `stop`: a channel that makes Stream stop listening for events and return when it receives anything // // Return values: // - `<-RawEvent`: A channel that emits events as they arrive from the stream // - `error`: Non-nil if an error is encountered setting up the listener. Stream(path, auth string, body interface{}, params map[string]string, stop <-chan bool) (<-chan RawEvent, error) }
Api is the internal interface for interacting with Firebase. The internal implementation of this interface is responsible for all HTTP operations that communicate with Firebase.
Users of this library can implement their own Api-conformant types for testing purposes. To use your own test Api type, pass it in to the NewClient function.
type Client ¶
type Client interface { // String returns the absolute URL path for the client String() string // Key returns the last part of the URL path for the client. Key() string // Value GETs the value referenced by the client and unmarshals it into // the passed in destination. Value(destination interface{}) error // Watch streams changes to the Client's path in real-time, in a separate // goroutine. // // Arguments // // unmarshaller: Responsible for unmarshalling each resource change event's // payload into the desired type. If unmarshaller is nil, each event will // be unmarshalled into a map[string]interface{} object. // // stop: Sending any boolean value to this channel will stop the Watching // the client's path. // // Return Values // // <-chan StreamEvent - A channel that sends each received event. // // error - If non-nil, a fatal error was encountered trying to start the // Watch method's internal goroutine. Watch(unmarshaller EventUnmarshaller, stop <-chan bool) (<-chan StreamEvent, error) // Shallow returns a list of keys at a particular location // Only supports objects, unlike the REST artument which supports // literals. If the location is a literal, use Client#Value() Shallow() Client // Child returns a reference to the child specified by `path`. This does not // actually make a request to firebase, but you can then manipulate the reference // by calling one of the other methods (such as `Value`, `Update`, or `Set`). Child(path string) Client // Query functions. They map directly to the Firebase operations. // https://www.firebase.com/docs/rest/guide/retrieving-data.html#section-rest-queries OrderBy(prop string) Client EqualTo(value interface{}) Client StartAt(value interface{}) Client EndAt(value interface{}) Client LimitToFirst(limit uint) Client LimitToLast(limit uint) Client // Creates a new value under this reference. // Returns a reference to the newly created value. // https://www.firebase.com/docs/web/api/firebase/push.html Push(value interface{}, params map[string]string) (Client, error) // Overwrites the value at the specified path and returns a reference // that points to the path specified by `path` Set(path string, value interface{}, params map[string]string) (Client, error) // Update performs a partial update with the given value at the specified path. // Returns an error if the update could not be performed. // https://www.firebase.com/docs/web/api/firebase/update.html Update(path string, value interface{}, params map[string]string) error // Remove deletes the data at the current reference. // https://www.firebase.com/docs/web/api/firebase/remove.html Remove(path string, params map[string]string) error // Rules returns the security rules for the database. // https://www.firebase.com/docs/rest/api/#section-security-rules Rules(params map[string]string) (*Rules, error) // SetRules overwrites the existing security rules with the new rules given. // https://www.firebase.com/docs/rest/api/#section-security-rules SetRules(rules *Rules, params map[string]string) error }
type EventUnmarshaller ¶
EventUnmarshaller callback accepts the path of the event, and the data payload as a raw JSON byte slice. The data payload is unmarshalled to any type of the implementor's choosing. The unmarshalled object is returned as an interface{}, or an error is returned if the unmarshal fails.
type FirebaseError ¶
type FirebaseError struct {
Message string `json:"error"`
}
FirebaseError is a Go representation of the error message sent back by Firebase when a request results in an error.
func (*FirebaseError) Error ¶
func (f *FirebaseError) Error() string
type RawEvent ¶
type RawEvent struct { // Event contains the string value of the message's "event:" section. Event string // Data contains the string value of the message's "data:" section. Data string // Error contains an error value when the connection was terminated // abnormally. Error error }
RawEvent contains the raw event and data payloads of Firebase Event Source protocol messages. This is emitted by the Api's Stream method.
type ServerTimestamp ¶
ServerTimestamp is a Go binding for Firebase's ServerValue.TIMESTAMP fields. When marshalling a variable of ServerTimestamp type into JSON (i.e. to send to Firebase), it takes the following JSON representation, no matter what time value the variable has been assigned:
{".sv":"timestamp"}
When this JSON value is sent to Firebase, it is substituted into a number equal to milliseconds since the epoch, as measured by Firebase's servers.
When reading a value of this type from Firebase, you receive a number equal to milliseconds since the epoch. That value was computed by Firebase when the JSON detailed above was written. A JSON unmarshal of this type will convert a number of ms since the epoch into a time.Time value.
NOTE: This approach results in non-symmetric marshal/unmarshal behavior (i.e. unmarshal(marshal(ServerTimestamp{})) will return an error). It is intended to be used only when reading/writing this value from Firebase.
See the Firebase's documentation of ServerValues and timestamps for more details: https://www.firebase.com/docs/rest/api/#section-server-values
func (ServerTimestamp) MarshalJSON ¶
func (t ServerTimestamp) MarshalJSON() ([]byte, error)
func (*ServerTimestamp) UnmarshalJSON ¶
func (t *ServerTimestamp) UnmarshalJSON(b []byte) error
type StreamEvent ¶
type StreamEvent struct { // Event is the type of event, denoted in the protocol by "event: text". Event string // Path of the changed resource. Path string // Resource is unmarshalled by unmarshaller callback supplied to Watch. Resource interface{} // The unparsed string found the event's "data:" section RawData string // UnmarshallerError contains a non-fatal error encountered when attempting // to parse the "data:" section to create the Resource object. UnmarshallerError error // Error contains an error value when something else goes wrong (i.e. // the connection is lost, permission is denied to the watched location, // a corrupted event is received, etc.). If the error is fatal, the // channel emitting these events will be subsequently closed after this // error is delivered. Error error }
StreamEvent contains a parsed Firebase Event Source protocol message received when a watched location changes. This is emitted by the Client's Watch method.