Skip to content
EvolveEvolveEvolve

cloud-adapter-gcp

@evolve-framework/cloud-adapter-gcp · v1.0.0

Runs Evolve services on Google Cloud. Services send each other events, store files and read configuration through interfaces defined in @evolve-framework/core; this package implements those interfaces with Pub/Sub, Cloud Storage, Parameter Manager and Secret Manager. It also has a ready-made service that receives Pub/Sub push deliveries, so receiving events needs no route of your own. The same service code then runs on Google Cloud by choosing this package at the entry point, with no Google Cloud SDK calls in the business logic.

When to use

  • A service publishes internal events to a Pub/Sub topic.
  • A service on Cloud Run or GKE receives internal events from a Pub/Sub push subscription.
  • A service writes files to Cloud Storage, or reads its configuration from Parameter Manager or Secret Manager.

Get started

  1. Install the package with the peer dependencies it needs. It comes from the Evolve registry, which needs a one-time sign-in.

    pnpm add @evolve-framework/cloud-adapter-gcp @evolve-framework/core fastify
    Requirements3
    @evolve-framework/core>= 1.0.0 < 2.0.0
    @types/node>=22optional
    fastify>= 5.12.1 < 6.0.0

For example:

import { createPubSubHandler, PubSubPublisher } from "@evolve-framework/cloud-adapter-gcp";
import type { Message } from "@evolve-framework/core/messaging";


// Publishing: any service hands internal events to a topic.
export const publisher = new PubSubPublisher(
  "projects/shop-prd/topics/internal-events",
);


// Consuming: a service a push subscription delivers to. In a service this is
// the composed module's `handleInternalEvent`, which dispatches each event by
// its type.
const handleInternalEvent = async (event: unknown): Promise<void> => {
  console.log("received", (event as Message).type);
};


await createPubSubHandler(handleInternalEvent).start({
  path: "/events",
  httpHost: "0.0.0.0",
  httpPort: Number(process.env.PORT ?? 8080),
});

Adapters

GoogleCloudStorageClient

Stores files in Cloud Storage, as core's StorageClient, and signs V4 URLs to one object.

import { GoogleCloudStorageClient } from "@evolve-framework/cloud-adapter-gcp";
new GoogleCloudStorageClient(storage?: Storage)
MethodDescription
save( bucket: string, key: string, data: string, options?: SaveOptions, ): Promise<void>Writes data as the object key in bucket, replacing what was stored there, with options.ContentType as its content type.
signUpload( bucket: string, key: string, options: SignedUploadOptions, ): Promise<string>The Content-Type is part of the signature, so the PUT has to send it.
signRead( bucket: string, key: string, options: SignedUrlOptions, ): Promise<string>A URL a client GETs the object from until it expires.
stat(bucket: string, key: string): Promise<StoredObject | undefined>The object, or undefined when nothing was stored under the key.

PubSubPublisher

Publishes internal events to one Pub/Sub topic.

import { PubSubPublisher } from "@evolve-framework/cloud-adapter-gcp";
new PubSubPublisher(topicName: string)
MethodDescription
publish( data: Message, options?: PublishMessageOptions, ): Promise<void>Hand a message to the provider.

Entry points

@evolve-framework/cloud-adapter-gcpMessaging: PubSubPublisher and createPubSubHandler.6 exports