cloud-adapter-gcp API

Everything the package exports, by the path you import it from. Open an export for its signature and options.

@evolve-framework/cloud-adapter-gcp

Messaging: PubSubPublisher and createPubSubHandler. Storage: GoogleCloudStorageClient. Configuration: gcpParameterManagerSource and gcpSecretManagerSource

Classes

GoogleCloudStorageClientStores 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)

Method	Description
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.

PubSubPublisherPublishes internal events to one Pub/Sub topic.

import { PubSubPublisher } from "@evolve-framework/cloud-adapter-gcp";

new PubSubPublisher(topicName: string)

Method	Description
publish( data: Message, options?: PublishMessageOptions, ): Promise<void>	Hand a message to the provider.

Functions

createPubSubHandlerA service receiving Pub/Sub push deliveries: start() serves a POST route that decodes each message and hands it to handlerFn, answering 500 when it throws so Pub/Sub redelivers, plus GET /healthcheck.

import { createPubSubHandler } from "@evolve-framework/cloud-adapter-gcp";

function createPubSubHandler(handlerFn: MessageHandler<unknown>): PubSubHandler

Returns PubSubHandler

gcpParameterManagerSourceReads Google Cloud Parameter Manager.

import { gcpParameterManagerSource } from "@evolve-framework/cloud-adapter-gcp";

Unlike every other source, this is not a namespace of separate entries: one parameter version holds the whole configuration as a document, so a single request returns everything.

renderParameterVersion is used rather than reading the version directly because it substitutes the REF(...) placeholders that point at Secret Manager, server-side. That makes this the cheapest option on Google Cloud by a wide margin — the entire configuration, secrets included, for one call, where Secret Manager costs a request per secret. It needs roles/parametermanager.parameterAccessor.

function gcpParameterManagerSource(
  options: GcpParameterManagerSourceOptions,
): ConfigSource

Option	Type	Description
project	string	The Google Cloud project holding the parameter.
parameter	string	The parameter holding this service's configuration.
client	ParameterManagerClient	Injected, as with every client in this package.
location?	string	The parameter's location. Defaults to global.
version?	string	The parameter version to read. Defaults to latest.
prefix?	string	Tried before the bare name, folded like any other prefix.
prefixFallback?	boolean
keys?	KeyTransformer
parse?	((raw: string) => unknown)	Parses the rendered payload. JSON by default; pass YAML.parse for a parameter stored as YAML rather than having this package depend on a parser.

Returns ConfigSource

gcpSecretManagerSourceReads Google Secret Manager.

import { gcpSecretManagerSource } from "@evolve-framework/cloud-adapter-gcp";

Listing returns secret names and no payloads, so only the fields a config actually declares are ever accessed. That matters here beyond the round trip: reading a secret version is an entry in the project's audit log, and a config wanting four secrets should not leave a trail through every secret in the project.

function gcpSecretManagerSource(
  options: GcpSecretManagerSourceOptions,
): ConfigSource

Option	Type	Description
project	string	The Google Cloud project holding the secrets.
client	SecretManagerServiceClient	Injected so a caller configures credentials once for the service, and so a test can hand over a stub — these clients speak gRPC, so an HTTP interceptor would never see the call.
prefix?	string	Tried before the bare name, folded like any other prefix.
prefixFallback?	boolean
keys?	KeyTransformer
lookup?	"index" | "direct"
filter?	string	Restricts which secrets are listed, using Secret Manager filter syntax.
version?	string	The secret version to read. Defaults to the latest.

Returns ConfigSource

Types

PubSubPayload

import { type PubSubPayload } from "@evolve-framework/cloud-adapter-gcp";

export type PubSubPayload = {
  message: {
    data: string;
    messageId: string;
    message_id: string;
    publishTime: string;
    publish_time: string;
  };
};

Not listed: 2 options types. They appear as the tables under the constructors and functions they type.