@devries-cameron20 / t3code Mirror · read-only
Fork 0

The best way to control Claude Code, Codex and more from any computer or phone

Mirrored from https://github.com/Camo67/t3code.git

Synced Nov 21, 06:00 UTC

main
mdx 149 lines 4.2 KB
Raw
1 ---
2 title: Cloud Run jobs
3 description: Run batch work to completion with GCP.Run.Job — trigger it from a service with RunJob, or nightly with Cloud Scheduler.
4 ---
5
6 `GCP.Run.Job` runs an Effect program that starts, does its work, and
7 exits. Nothing is billed between runs. Use it for nightly reports,
8 backfills, and draining a queue in batches.
9
10 ## Declare a job
11
12 A job returns a `run` Effect instead of `fetch`:
13
14 ```typescript
15 // src/Summarize.ts
16 import * as GCP from "@alchemy.run/gcp";
17 import * as Effect from "effect/Effect";
18 import { Reports } from "./resources.ts";
19
20 export default class Summarize extends GCP.Run.Job<Summarize>()(
21 "Summarize",
22 { main: import.meta.url },
23 Effect.gen(function* () {
24 const reports = yield* GCP.Storage.WriteBucket(Reports);
25
26 return {
27 run: Effect.gen(function* () {
28 const day = new Date().toISOString().slice(0, 10);
29 yield* reports.put(`daily/${day}.json`, JSON.stringify({ day }), {
30 contentType: "application/json",
31 });
32 }).pipe(Effect.orDie),
33 };
34 }).pipe(Effect.provide(GCP.Storage.WriteBucketHttp)),
35 ) {}
36 ```
37
38 Bindings work the same as on a service. The job gets its own service
39 account and only the roles its bindings ask for.
40
41 ## Retries and timeouts
42
43 ```diff lang="typescript"
44 export default class Summarize extends GCP.Run.Job<Summarize>()(
45 "Summarize",
46 - { main: import.meta.url },
47 + { main: import.meta.url, maxRetries: 1, timeout: "300s" },
48 ```
49
50 A failed run retries `maxRetries` times, then the execution fails.
51 `timeout` caps each attempt.
52
53 ## Start it from a service
54
55 `RunJob` gives a service permission to start the job and returns a
56 function that does it:
57
58 ```typescript
59 // src/Admin.ts
60 import Summarize from "./Summarize.ts";
61
62 export default class Admin extends GCP.Function<Admin>()(
63 "Admin",
64 { main: import.meta.url },
65 Effect.gen(function* () {
66 const runSummarize = yield* GCP.Run.RunJob(Summarize);
67
68 return {
69 fetch: Effect.gen(function* () {
70 const operation = yield* runSummarize();
71 return yield* HttpServerResponse.json(
72 { operation: operation.name },
73 { status: 202 },
74 );
75 }).pipe(Effect.orDie),
76 };
77 }).pipe(Effect.provide(GCP.Run.RunJobHttp)),
78 ) {}
79 ```
80
81 `runSummarize()` returns as soon as the execution starts, not when it
82 finishes.
83
84 ## Run it on a schedule
85
86 A Cloud Scheduler job can start the job directly, with no service in
87 between. Give the job's own account permission to run it, then point
88 the scheduler at the Cloud Run API:
89
90 ```typescript
91 // src/Nightly.ts
92 import * as GCP from "@alchemy.run/gcp";
93 import * as Output from "alchemy/Output";
94 import * as Effect from "effect/Effect";
95 import Summarize from "./Summarize.ts";
96
97 export const Nightly = Effect.gen(function* () {
98 const job = yield* Summarize;
99
100 const runner = yield* GCP.IAM.Member("NightlyRunner", {
101 kind: "run.job",
102 name: job.name,
103 role: "roles/run.invoker",
104 member: Output.interpolate`serviceAccount:${job.serviceAccount}`,
105 });
106
107 return yield* GCP.CloudScheduler.Job("Nightly", {
108 schedule: "0 2 * * *",
109 timeZone: "Etc/UTC",
110 httpTarget: {
111 uri: Output.interpolate`https://run.googleapis.com/v2/${job.name}:run`,
112 httpMethod: "POST",
113 body: "{}",
114 oauthToken: {
115 serviceAccountEmail: Output.map(runner.member, (member) =>
116 member.replace(/^serviceAccount:/, ""),
117 ),
118 scope: "https://www.googleapis.com/auth/cloud-platform",
119 },
120 },
121 });
122 });
123 ```
124
125 Reading `runner.member` makes the scheduler wait for the grant.
126 Yield `Nightly` from your Stack.
127
128 ## Read the execution name
129
130 Cloud Run sets `CLOUD_RUN_EXECUTION` in the job's environment. Log it
131 to find a run in the console:
132
133 ```typescript
134 const execution = yield* Effect.sync(() => process.env.CLOUD_RUN_EXECUTION);
135 ```
136
137 ## Example
138
139 [`examples/gcp-scheduled-job`](https://github.com/alchemy-run/alchemy/tree/main/examples/gcp-scheduled-job)
140 rolls BigQuery orders into a daily JSON summary in Cloud Storage,
141 nightly and on demand.
142
143 ## Where next
144
145 - [Pub/Sub](/gcp/messaging/pubsub) — a job that drains a subscription
146 into BigQuery.
147 - [Cloud Scheduler](/gcp/messaging/scheduler) — schedules that call a
148 service.
149 - [Run reference](/providers/gcp/run#job) — every prop and attribute.