firestore-serde

firestore-serde is a serializer/deserializer implementation for Firestore Values and Documents.

This allows you to store arbitrary Rust values in a Firestore database, but this crate does not handle any of the communication with the Firestore service. Instead, it's meant to fit into a stack of other crates:

• tonic for connecting to Firebase over gRPC.
• googapis for Firebase gRPC message definitions, derived from the official API definitions using prost.
• google-authz for authentication/credential discovery.

Preliminaries

Firestore is a cloud-based, proprietary document database from Google (not to be confused with Firebase or Cloud Datastore, which are also proprietary document databases from Google).

Google does not provide official Rust bindings for Google Cloud Platform, but they do provide API specifications for REST and gRPC APIs. As a result, a number of Rust projects have appeared to produce Rust bindings from these specifications:

• Byron/google-apis-rs produces bindings for the REST APIs, implemented on top of the hyper HTTP library.
• mechiru/googapis produces bindings for the gRPC APIs, implemented on top of the tonic gRPC library.

There is a 1:1 mapping between REST API calls and gRPC API calls. Unfortunately, there is a known issue in the REST API spec for Firestore which breaks querying, so I recommend not using the REST API. As a consequence, this crate only supports the gRPC API. If you do want to use the REST API, see the firestore-db-and-auth-rs crate instead of this one.

The unit of data retrieval in Firestore is a Document, which is a map of string fields to Values. Values themselves are a rich type which can represent arrays and maps composed of other values. As such, we can represent many Rust types in an intuitive way as both Values and Documents. This crate provides a serde serializer and deserializer to do just that.

Usage

This crate provides four primary functions:

// Conversions between Rust types and Value gRPC type.

pub fn to_grpc_value<T>(value: &T)
    -> Result<Value, SerializationError>
    where T: Serialize;

pub fn from_grpc_value<T>(value: &Value)
    -> Result<T, DeserializationError>
    where T: DeserializeOwned;

// Conversions between Rust types and Document gRPC type.

pub fn to_document<T>(value: &T)
    -> Result<Document, SerializationError>
    where T: Serialize;

pub fn from_document<T>(document: Document)
    -> Result<T, DeserializationError>
    where T: DeserializeOwned;

Note that the from_document takes ownership of its argument, so if you need the original Document after conversion you will have to clone it.

Timestamps

The chrono crate supports serializable timestamps, by converting the timestamp to a string or number. Without intervention, firestore-serde doesn't differentiate between these and other numbers or strings, so they are turned into ValueType::IntegerValue and ValueType::StringValue respectively.

This is fine if you always deserialize the values to Rust, but if you want to access the data in other ways (for example, the web-based data console), it's often useful to store time data in Firestore's ValueType::TimestampValue. To do this, add firestore-serde-timestamp as a dependency and tell Serde to use it as the encoding:

use serde::{Serialize, Deserialize};
use chrono::{DateTime, Utc};

#[derive(Serialize, Deserialize)]
struct MyStruct {
    #[serde(with="firestore_serde_timestamp::timestamp")]
    some_timestamp: DateTime<Utc>,
}

API versions

There are currently two versions of the gRPC API, google.firestore.v1.* and google.firestore.v1beta1.*. Each version is represented by a different namespace which is isolated from the other, so even types which are used in common by both (e.g. Document and Value) are represented by different protocol buffers.

firestore-serde uses the v1 namespace by default, but it is possible to change that with a feature flag. In your Cargo.toml, specify the dependency as follows:

[dependencies]
firestore-serde = {version = "0.1.0", default-features=false, features=["google-firestore-v1beta1"]}

It is important that you disable default-features, because firestore-serde will refuse to compile if both google-firestore-v1 and google-firestore-v1beta1 are enabled.