google-cloud 0.0.1-preview.1

Google Cloud clients: Firestore, Cloud Storage, Cloud DNS and Cloud KMS

Readme Files Dependencies Versions

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-v1 and google-cloud/storage-v2 — Generated protobuf messages and low-level service clients for google.firestore.v1 and google.storage.v2.
  • google-cloud/testing/fake-kms and google-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: set replaces a document, create fails with ALREADY_EXISTS when it exists, update sets the named top-level fields and fails with NOT_FOUND when it does not exist, and delete removes it. Errors are RpcErrors carrying the google.rpc.Code.
  • Transforms (applied by the server when the write commits): Fields.serverTimestamp, increment, incrementDouble, maximum, minimum, arrayUnion, and arrayRemove. In an update, deleteField removes 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 a DocumentSnapshot, whose exists is false for a missing document. getString, getInteger, getDouble, and getBoolean take a field path such as author.name and return (true, value) or (false, _) when the field is absent or of another type. get(path) returns the raw Value. db.getAll(refs) reads several documents in one call in the order given.
  • Queries: where, orderBy, limit, offset, and select each 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, and endBefore take values for the orderings or a DocumentSnapshot.
  • Batches & Transactions: db.batch() collects writes and commits them in one call. db.runTransaction(body) runs body with a Transaction, retrying up to five times on contention and rolling back if body throws.
  • Deadlines: Firestore.connect({timeout: milliseconds(10000)}) gives each call a deadline, failing with DEADLINE_EXCEEDED if 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. When FIRESTORE_EMULATOR_HOST is set to host:port, Firestore.connect() connects to the Firestore emulator over cleartext HTTP/2 with the owner token.
  • Firestore.connectFallback() uses Google's gRPC fallback protocol (protobuf/fallback), which works on HTTP/1.1-only wasi:http hosts such as stock wasmtime serve.
  • new Firestore({projectId, transport}) accepts any ProtoTransport.

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_HOST when set, or metadata.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

6.5 KiB Raw
/**
 * 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
VersionPublishedDependenciesApproved by
0.0.1-preview.1 2026-11-19
  • protobuf protobuf.zena-lang.pkg.zena-lang.dev ~0.0.1-preview.1