google-cloud 0.0.1-preview.1
Google Cloud clients: Firestore, Cloud Storage, Cloud DNS and Cloud KMS
google-cloud#
Google Cloud client libraries for Zena, built on wasi:http and @zena/protobuf so they compile for WebAssembly component targets as well as the zena CLI host.
Installation#
zena pkg add @zena/google-cloud
Libraries#
google-cloud/firestore— Firestore document, collection, query, batch, and transaction client.google-cloud/storage— Cloud Storage client for reading, writing, stating, and deleting objects.google-cloud/dns— Cloud DNS client for managing record sets in a managed zone.google-cloud/kms— Cloud KMS client for asymmetric signing and symmetric encryption/decryption.google-cloud/auth— Default credentials and project ID discovery from the GCE metadata server or environment variables.google-cloud/firestore-v1andgoogle-cloud/storage-v2— Generated protobuf messages and low-level service clients forgoogle.firestore.v1andgoogle.storage.v2.google-cloud/testing/fake-kmsandgoogle-cloud/testing/firestore-emulator— Test helpers for in-process fake Cloud KMS and the Firestore emulator.
Firestore#
import { Direction, Fields, Firestore, Operator, integerValue } from 'google-cloud/firestore';
let db = await Firestore.connect();
let post = db.collection('posts').doc('hello');
await post.set(new Fields().string('title', 'Hello').integer('views', 0));
let snapshot = await post.get();
if (let (true, views) = snapshot.getInteger('views')) {
await post.update(new Fields().integer('views', views + 1));
}
let popular = await db.collection('posts')
.where('views', Operator.GreaterThan, integerValue(100))
.orderBy('views', Direction.Descending)
.limit(10)
.get();
for (let p in popular) {
console.log(p.id);
}
Firestore.connect() discovers the project and credentials as described under Credentials and talks gRPC to the API. new Firestore({projectId, databaseId?, transport}) accepts explicit configuration instead.
- References:
db.collection(path),db.doc(path),collection.doc(id),doc.collection(id).collection.add(fields)creates a document with a random ID. - Writes:
setreplaces a document,createfails withALREADY_EXISTSwhen it exists,updatesets the named top-level fields and fails withNOT_FOUNDwhen it does not exist, anddeleteremoves it. Errors areRpcErrors carrying thegoogle.rpc.Code. - Transforms (applied by the server when the write commits):
Fields.serverTimestamp,increment,incrementDouble,maximum,minimum,arrayUnion, andarrayRemove. In anupdate,deleteFieldremoves a field. They apply to top-level fields and work in batches and transactions as well:post.update(new Fields().increment('views', 1).serverTimestamp('seen')). - Reads:
get()returns aDocumentSnapshot, whoseexistsisfalsefor a missing document.getString,getInteger,getDouble, andgetBooleantake a field path such asauthor.nameand return(true, value)or(false, _)when the field is absent or of another type.get(path)returns the rawValue.db.getAll(refs)reads several documents in one call in the order given. - Queries:
where,orderBy,limit,offset, andselecteach return a new query.get()collects the results;stream()yields each document as it arrives (for await);count()counts them on the server. - Cursors:
startAt,startAfter,endAt, andendBeforetake values for the orderings or aDocumentSnapshot. - Batches & Transactions:
db.batch()collects writes and commits them in one call.db.runTransaction(body)runsbodywith aTransaction, retrying up to five times on contention and rolling back ifbodythrows. - Deadlines:
Firestore.connect({timeout: milliseconds(10000)})gives each call a deadline, failing withDEADLINE_EXCEEDEDif exceeded.
let total = await db.runTransaction<i64>(async (tx: Transaction): Future<i64> => {
let counter = db.doc('counters/visits');
let snapshot = await tx.get(counter);
var n: i64 = 0;
if (let (true, stored) = snapshot.getInteger('n')) {
n = stored;
}
tx.set(counter, new Fields().integer('n', n + 1));
return n + 1;
});
Transports & Emulator#
Firestore.connect()uses gRPC (protobuf/grpc) over HTTP/2. WhenFIRESTORE_EMULATOR_HOSTis set tohost:port,Firestore.connect()connects to the Firestore emulator over cleartext HTTP/2 with theownertoken.Firestore.connectFallback()uses Google's gRPC fallback protocol (protobuf/fallback), which works on HTTP/1.1-onlywasi:httphosts such as stockwasmtime serve.new Firestore({projectId, transport})accepts anyProtoTransport.
Cloud Storage#
import { Storage } from 'google-cloud/storage';
let bucket = Storage.connect().bucket('my-bucket');
await bucket.write('notes/hello.txt', bytes, 'text/plain');
let read = await bucket.read('notes/hello.txt'); // null when absent
let object = await bucket.stat('notes/hello.txt'); // metadata, or null
await bucket.delete('notes/hello.txt'); // true if deleted
Storage.connect() uses the default credentials and talks gRPC to the Cloud Storage API (write streams data in chunks of at most 2 MiB). new Storage(transport) accepts any ProtoTransport, and storage.client exposes the generated StorageClient.
Cloud DNS#
import { CloudDns, RecordSet } from 'google-cloud/dns';
let zone = CloudDns.connect('my-project', 'my-zone');
await zone.put(new RecordSet('_atproto.alice.example.com.', 'TXT', 300, ['"did=did:plc:..."']));
let set = await zone.get('_atproto.alice.example.com.', 'TXT'); // null when absent
await zone.delete('_atproto.alice.example.com.', 'TXT'); // true if deleted
CloudDns uses the Cloud DNS REST API (https://dns.googleapis.com/dns/v1) with default credentials. Names are fully qualified (ending in a .), and put creates or replaces the record set of that name and type.
Cloud KMS#
import { sha256 } from 'zena:crypto';
import { CloudKms, ecPointFromPem } from 'google-cloud/kms';
// Asymmetric signing
let signingKey = CloudKms.connect(
'projects/p/locations/l/keyRings/r/cryptoKeys/k/cryptoKeyVersions/1'
);
let derSignature = await signingKey.asymmetricSign(sha256(message));
let pubKey = await signingKey.publicKey();
let uncompressedPoint = ecPointFromPem(pubKey.pem);
// Symmetric encryption (AEAD)
let symmetricKey = CloudKms.connect('projects/p/locations/l/keyRings/r/cryptoKeys/s');
let ciphertext = await symmetricKey.encrypt(plaintext, additionalData);
let decrypted = await symmetricKey.decrypt(ciphertext, additionalData);
Credentials#
defaultCredentials() (google-cloud/auth):
GOOGLE_OAUTH_ACCESS_TOKEN, when set in the environment, is used directly (for local runs:GOOGLE_OAUTH_ACCESS_TOKEN=$(gcloud auth print-access-token)).- Otherwise, the GCE metadata server (at
GCE_METADATA_HOSTwhen set, ormetadata.google.internal) supplies tokens for the default service account, caching each token until a minute before it expires.
defaultProjectId() reads GOOGLE_CLOUD_PROJECT or GCLOUD_PROJECT when set, falling back to the metadata server.
License#
MIT
/**
* A Cloud DNS client for one managed zone's record sets, over the REST
* API (`https://dns.googleapis.com/dns/v1`), since Cloud DNS has no gRPC
* API.
*
* let zone = CloudDns.connect('my-project', 'my-zone');
* await zone.put(new RecordSet('_atproto.alice.example.com.', 'TXT', 300, ['"did=did:plc:..."']));
* let set = await zone.get('_atproto.alice.example.com.', 'TXT');
* await zone.delete('_atproto.alice.example.com.', 'TXT');
*
* Names are fully qualified, ending in a dot, and a TXT record's data is a
* quoted string, as Cloud DNS takes them. Each call asks its `Credentials`
* for an access token, with the `cloud-platform` or
* `ndev.clouddns.readwrite` scope.
*/
import {Future} from 'zena:async';
import {Own} from 'zena:core';
import {fetch, Response} from 'zena:fetch';
import {JsonArray, JsonObject, JsonValue, parseJson, stringify} from 'zena:json';
import {EncodeSet, percentEncode} from 'zena:url';
import {Credentials} from 'protobuf/runtime';
import {defaultCredentials} from './auth.zena';
/** The origin of the Cloud DNS API. */
export let DNS_ORIGIN = 'https://dns.googleapis.com';
/** An answer from Cloud DNS that is an error, with its HTTP status. */
export class DnsError extends Error {
status: i32;
new(status: i32, message: String) : status = status, super(message);
}
/** A record set: every record of one name and type. */
export final class RecordSet {
/** Fully qualified, ending in a dot. */
name: String;
/** Such as `TXT` or `A`. */
type: String;
/** How long resolvers may keep the records, in seconds. */
ttl: i32;
/** The records' data, as the zone file writes them: a TXT record's quoted. */
rrdatas: Array<String>;
new(this.name, this.type, this.ttl, this.rrdatas);
/** The record set as Cloud DNS takes it. */
toJson(): JsonObject {
let json = new JsonObject();
json['name'] = this.name;
json['type'] = this.type;
json['ttl'] = new Box<f64>(this.ttl as f64);
let rrdatas = new JsonArray();
for (let data in this.rrdatas) {
rrdatas.push(data);
}
json['rrdatas'] = rrdatas;
return json;
}
/** The record set in Cloud DNS's `json`. Throws `DnsError` when it is not one. */
static fromJson(json: JsonValue): RecordSet {
if (!(json is JsonObject)) {
throw new DnsError(0, 'the answer is not a record set');
}
let object = json;
let name = object['name'];
let type = object['type'];
let ttl = object['ttl'];
let rrdatas = object['rrdatas'];
if (!(name is String) || !(type is String)) {
throw new DnsError(0, 'the record set has no name or type');
}
let datas = new GrowableArray<String>();
if (rrdatas is JsonArray) {
let array = rrdatas;
for (var i = 0; i < array.length; i += 1) {
let data = array[i];
if (data is String) {
datas.push(data);
}
}
}
let seconds = if (ttl is Box<f64>) ttl.value as i32 else 0;
return new RecordSet(name, type, seconds, datas);
}
}
/** One managed zone's record sets. */
export final class CloudDns {
#origin: String;
#credentials: Credentials;
/** `/dns/v1/projects/<project>/managedZones/<zone>`. */
#zonePath: String;
/**
* The managed zone `zone`, a name or ID, of `project`, at `origin`,
* the API's own (`DNS_ORIGIN`) unless a test serves it.
*/
new(project: String, zone: String, credentials: Credentials, origin: String = 'https://dns.googleapis.com')
: #origin = origin,
#credentials = credentials,
#zonePath = `/dns/v1/projects/${percentEncode(project, EncodeSet.Component)}/managedZones/${percentEncode(zone, EncodeSet.Component)}`;
/** The managed zone with the default credentials (see `defaultCredentials`). */
static connect(project: String, zone: String): CloudDns {
return new CloudDns(project, zone, defaultCredentials());
}
#recordPath(name: String, type: String): String {
return `${this.#zonePath}/rrsets/${percentEncode(name, EncodeSet.Component)}/${percentEncode(type, EncodeSet.Component)}`;
}
/** The record set of `name` and `type`, or null when there is none. */
async get(name: String, type: String): Future<RecordSet | null> {
let response = await this.#call('GET', this.#recordPath(name, type), null);
if (response.status == 404) {
return null;
}
let text = await checked(response, `getting ${name} ${type}`);
return RecordSet.fromJson(parseJson(text));
}
/**
* Creates `set`, or replaces the record set of its name and type when
* there is one.
*/
async put(set: RecordSet): Future<void> {
let body = stringify(set.toJson());
let created = await this.#call('POST', `${this.#zonePath}/rrsets`, body);
if (created.status != 409) {
await checked(created, `creating ${set.name} ${set.type}`);
return;
}
let patched = await this.#call('PATCH', this.#recordPath(set.name, set.type), body);
await checked(patched, `replacing ${set.name} ${set.type}`);
}
/** Deletes the record set of `name` and `type`. Returns whether there was one. */
async delete(name: String, type: String): Future<boolean> {
let response = await this.#call('DELETE', this.#recordPath(name, type), null);
if (response.status == 404) {
return false;
}
await checked(response, `deleting ${name} ${type}`);
return true;
}
async #call(method: String, path: String, body: String | null): Future<Own<Response>> {
let headers = new GrowableArray<(String, String)>();
headers.push(('accept', 'application/json'));
if (body != null) {
headers.push(('content-type', 'application/json'));
}
let authorization = await this.#credentials.authorization();
if (authorization != null) {
headers.push(('authorization', authorization));
}
return try {
await fetch(`${this.#origin}${path}`, {method, headers, body})
} catch (e) {
throw new DnsError(0, e.message)
};
}
}
/** Returns `response`'s body text when it is a success, or throws `DnsError` naming what `doing` was. */
async function checked(response: Own<Response>, doing: String): Future<String> {
let status = response.status;
let responseText = await response.text();
if (status >= 200 && status < 300) {
return responseText;
}
var message = responseText;
let json = try {
parseJson(responseText)
} catch (e) {
null
};
if (json is JsonObject) {
let error = json['error'];
if (error is JsonObject) {
let text = error['message'];
if (text is String) {
message = text;
}
}
}
throw new DnsError(status, `Cloud DNS, ${doing}: HTTP ${status}: ${message}`);
}
- protobuf protobuf.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1
| Version | Published | Dependencies | Approved by |
|---|---|---|---|
| 0.0.1-preview.1 | 2026-11-19 |
|
|