GCP.Run reference

EventarcEventSource

Source: src/GCP/Run/EventarcEventSource.ts Kind: Layer · Provides: GCP.Eventarc.EventSource

HTTP implementation of GCP.Eventarc.EventSource for GCP.Run.Service / GCP.Function and GCP.CloudFunctions.Function.

Deploy-time: grants the host’s runtime service account roles/eventarc.eventReceiver on the project and roles/run.invoker on the host (and, for Cloud Storage events, the Storage service agent roles/pubsub.publisher on the project, which direct Storage events require), then creates the trigger with that account as its identity. Each grant and the trigger block until GCP reports them in place and healthy. Runtime: claims deliveries on the path, verifies the OIDC token, decodes the binary-mode CloudEvent, and runs the handler; a 2xx acks, a failed handler answers 500 and Eventarc redelivers.

GetService

Source: src/GCP/Run/GetService.ts

Runtime binding for Cloud Run services.get.

Bind this operation to a Service in a Function/Action init phase. Provide GetServiceHttp.

GetService: Reading a Service

const getService = yield* GCP.Run.GetService(api);
const live = yield* getService();

GetServiceHttp

Source: src/GCP/Run/GetServiceHttp.ts Kind: Layer · Provides: GCP.Run.GetService

HTTP implementation of GetService.

GetWorkerPool

Source: src/GCP/Run/GetWorkerPool.ts

Runtime binding for Cloud Run workerPools.get.

Bind this operation to a WorkerPool in a Function/Action init phase. Provide GetWorkerPoolHttp.

GetWorkerPool: Reading a Worker Pool

const getWorkerPool = yield* GCP.Run.GetWorkerPool(pool);
const live = yield* getWorkerPool();

GetWorkerPoolHttp

Source: src/GCP/Run/GetWorkerPoolHttp.ts Kind: Layer · Provides: GCP.Run.GetWorkerPool

HTTP implementation of GetWorkerPool.

InvokeService

Source: src/GCP/Run/InvokeService.ts

Runtime binding that calls a private Cloud Run Service from another Cloud Run host with Google-signed identity — the GCP analog of AWS.Lambda.InvokeFunction.

At deploy time it grants roles/run.invoker on the target service to the host’s runtime service account and binds the target’s uri into the host. At runtime it mints an ID token (audience = the target uri) from the metadata server, caches it until shortly before expiry, and sends it as Authorization: Bearer. The target keeps invokerIamDisabled off, so anything without a token gets 403.

Provide InvokeServiceHttp.

InvokeService: Calling a private service

Forward a request to a private backend

export default class Gateway extends GCP.Function<Gateway>()(
  "Gateway",
  { main: import.meta.url, invokerIamDisabled: true },
  Effect.gen(function* () {
    const quotes = yield* GCP.Run.InvokeService(Quotes);
    return {
      fetch: Effect.gen(function* () {
        const response = yield* quotes.fetch("/quote").pipe(Effect.orDie);
        return HttpServerResponse.text(yield* response.text, {
          status: response.status,
        });
      }),
    };
  }).pipe(Effect.provide(GCP.Run.InvokeServiceHttp)),
) {}

POST a JSON body

const response = yield* orders.fetch("/orders", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ sku: "abc", quantity: 1 }),
});
const order = yield* response.json;

InvokeServiceHttp

Source: src/GCP/Run/InvokeServiceHttp.ts Kind: Layer · Provides: GCP.Run.InvokeService

HTTP implementation of InvokeService: ID tokens from the Cloud Run metadata server, requests over the ambient HttpClient.

Job

Source: src/GCP/Run/Job.ts

A Cloud Run Job — a container that runs to completion.

Changing jobId or location replaces the job.

Job: Creating a Job

Generated name

const job = yield* GCP.Run.Job("Migrate", {
  containers: [
    { image: "us-docker.pkg.dev/cloudrun/container/job:latest" },
  ],
});

Explicit id, labels, and retries

const job = yield* GCP.Run.Job("Migrate", {
  jobId: "order-migrate",
  location: "us-central1",
  labels: { env: "prod" },
  maxRetries: 1,
  timeout: "120s",
  containers: [
    {
      image: "us-docker.pkg.dev/cloudrun/container/job:latest",
      env: [{ name: "STAGE", value: "prod" }],
    },
  ],
});

Job: Effect-native Job with bindings

export class Warm extends GCP.Run.Job<Warm>()(
  "Warm",
  { main: import.meta.url },
  Effect.gen(function* () {
    const redis = yield* GCP.Redis.ReadWriteRedis(cache);
    return {
      run: redis.set("warmed", "1"),
    };
  }).pipe(Effect.provide(GCP.Redis.ReadWriteRedisHttp)),
) {}

Job: Running a Job

const runJob = yield* GCP.Run.RunJob(job);
yield* runJob();

RunJob

Source: src/GCP/Run/RunJob.ts

Runtime binding for Cloud Run jobs.run.

Triggers a new execution of the bound Job. Provide RunJobHttp.

RunJob: Running Jobs

Trigger an execution

const runJob = yield* GCP.Run.RunJob(job);
yield* runJob();

Override task count

const runJob = yield* GCP.Run.RunJob(job);
yield* runJob({
  body: { overrides: { taskCount: 1 } },
});

RunJobHttp

Source: src/GCP/Run/RunJobHttp.ts Kind: Layer · Provides: GCP.Run.RunJob

HTTP implementation of RunJob.

ScheduleEventSource

Source: src/GCP/Run/ScheduleEventSource.ts Kind: Layer · Provides: GCP.CloudScheduler.ScheduleEventSource

Implementation of GCP.CloudScheduler.ScheduleEventSource for HTTP hosts (GCP.Run.Service / GCP.Function, GCP.CloudFunctions.Function).

Deploy-time: grants the host’s runtime service account roles/run.invoker on the host and creates a Cloud Scheduler job that POSTs to the host’s URL with an OIDC token for that account. Runtime: claims the job’s deliveries on its path, verifies the token, and runs the handler with the X-CloudScheduler-* headers. 204 marks the run successful; a failed handler answers 500 and the job’s retry policy applies.

ScheduleEventSource: Running on a schedule

Effect.gen(function* () {
  yield* GCP.CloudScheduler.consumeSchedule(
    "Sweep",
    { schedule: "every 5 minutes" },
    (event) => Effect.log(`sweep ${event.scheduleTime}`),
  );
}).pipe(Effect.provide(GCP.Run.ScheduleEventSource));

Service

Source: src/GCP/Run/Service.ts

A Cloud Run service (Knative serving revision + traffic).

Changing serviceId or location replaces the service. Updates to template create a new revision.

This is GCP’s effectful HTTP platform — the analog of AWS.Lambda.Function / Cloudflare.Worker. Pass main plus an Effect implementation; bindings grant IAM onto the runtime service account and inject env, the way AWS policyStatements land on the execution role.

Service: Creating a Service

Generated name, default hello image

const api = yield* GCP.Run.Service("api", {});

Explicit id, image, env, and labels

const api = yield* GCP.Run.Service("api", {
  serviceId: "order-api",
  location: "us-central1",
  description: "order HTTP API",
  labels: { env: "prod" },
  ingress: "INGRESS_TRAFFIC_ALL",
  template: {
    timeout: "60s",
    containers: [
      {
        image: "us-docker.pkg.dev/cloudrun/container/hello",
        env: [{ name: "ENV", value: "prod" }],
      },
    ],
  },
});

Service: Effect-native Function with bindings

const tweets = yield* GCP.PubSub.Topic("tweets", {});
const cache = yield* GCP.Redis.Instance("Cache", { memorySizeGb: 1 });

export class TweetBot extends GCP.Run.Service<TweetBot>()(
  "TweetBot",
  { main: import.meta.url },
  Effect.gen(function* () {
    const publish = yield* GCP.PubSub.Publish(tweets);
    const redis = yield* GCP.Redis.ReadWriteRedis(cache);
    return {
      fetch: Effect.gen(function* () {
        const text = (yield* redis.get("last-tweet")) ?? "hello twitter";
        yield* publish({
          body: { messages: [{ data: btoa(text) }] },
        });
        return HttpServerResponse.text("queued");
      }),
    };
  }).pipe(
    Effect.provide([
      GCP.PubSub.PublishHttp,
      GCP.Redis.ReadWriteRedisHttp,
    ]),
  ),
) {}

Service: Updating a Service

const api = yield* GCP.Run.Service("api", {
  template: {
    timeout: "120s",
    containers: [{ image: "us-docker.pkg.dev/cloudrun/container/hello" }],
  },
});

Template changes create a new revision. The runtime service account is kept.

Service: Destroying a Service

Service: Reading a Service

const getService = yield* GCP.Run.GetService(api);
const live = yield* getService();

TopicEventSource

Source: src/GCP/Run/TopicEventSource.ts Kind: Layer · Provides: GCP.PubSub.TopicEventSource

Push implementation of GCP.PubSub.TopicEventSource for HTTP hosts (GCP.Run.Service / GCP.Function, GCP.CloudFunctions.Function).

Deploy-time: grants the host’s runtime service account roles/run.invoker on the host and creates a push subscription to the host’s URL, signed with an OIDC token for that account. Runtime: claims POST deliveries on the push path, verifies the token, and runs the handler. 204 acks the message; a failed handler answers 500 and Pub/Sub redelivers per the subscription’s retry policy.

TopicPullEventSource

Source: src/GCP/Run/TopicPullEventSource.ts Kind: Layer · Provides: GCP.PubSub.TopicEventSource

Pull implementation of GCP.PubSub.TopicEventSource for hosts without an inbound URL (GCP.Run.Job, GCP.Run.WorkerPool; any host with ServerHost).

Deploy-time: creates a pull subscription owned by the host and grants the host’s runtime service account roles/pubsub.subscriber on it (through the Pull / Acknowledge bindings). Runtime: a background loop pulls batches, runs the handler, and acks the batch once the handler succeeds. A failed handler leaves the batch unacked, so Pub/Sub redelivers after the ack deadline.

WorkerPool

Source: src/GCP/Run/WorkerPool.ts

A Cloud Run worker pool (pull-based revision + instance split).

Changing workerPoolId or location replaces the pool. Updates to template create a new revision.

WorkerPool: Creating a Worker Pool

Generated name, default worker image

const pool = yield* GCP.Run.WorkerPool("workers", {});

Explicit id, image, env, and labels

const pool = yield* GCP.Run.WorkerPool("workers", {
  workerPoolId: "order-workers",
  location: "us-central1",
  description: "order pull workers",
  labels: { env: "prod" },
  scaling: { manualInstanceCount: 1 },
  template: {
    containers: [
      {
        image: "us-docker.pkg.dev/cloudrun/container/worker-pool",
        env: [{ name: "ENV", value: "prod" }],
      },
    ],
  },
});

WorkerPool: Reading a Worker Pool

const getWorkerPool = yield* GCP.Run.GetWorkerPool(pool);
const live = yield* getWorkerPool();

WorkerPool: Effect-native Worker Pool with bindings

export class Workers extends GCP.Run.WorkerPool<Workers>()(
  "Workers",
  { main: import.meta.url, scaling: { manualInstanceCount: 1 } },
  Effect.gen(function* () {
    const redis = yield* GCP.Redis.ReadWriteRedis(cache);
    return {
      run: redis.set("worker", "up"),
    };
  }).pipe(Effect.provide(GCP.Redis.ReadWriteRedisHttp)),
) {}