firestore-serde
is a serializer/deserializer implementation for Firestore Value
s and Document
s.
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 overgRPC
.googapis
for Firebase gRPC message definitions, derived from the official API definitions usingprost
.google-authz
for authentication/credential discovery.
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 thehyper
HTTP library.mechiru/googapis
produces bindings for the gRPC APIs, implemented on top of thetonic
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 Value
s. Value
s 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 Value
s and Document
s. This crate provides a
serde
serializer and deserializer to do just that.
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.
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>,
}
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.