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

main
mdx 304 lines 8.05 KB
Raw
1 ---
2 title: "Part 2: Add a Cloud Run Service"
3 description: Put an HTTP service on Cloud Run, bind the Cloud Storage Bucket, and implement GET/PUT routes.
4 sidebar:
5 order: 2
6 ---
7
8 import Terminal from "../../../../components/Terminal.astro";
9 import PackageManagers from "../../../../components/PackageManagers.astro";
10
11 In [Part 1](/gcp/tutorial/part-1) you deployed a Cloud Storage Bucket.
12 Now you put an HTTP service on Cloud Run that reads and writes objects
13 in it.
14
15 :::note
16 Alchemy builds a container image for the service on your machine, so
17 Docker has to be running when you deploy.
18 :::
19
20 ## Create the service file
21
22 A Cloud Run service is a class with an infrastructure definition and a
23 runtime implementation. Create `src/api.ts`:
24
25 ```typescript
26 // src/api.ts
27 import * as GCP from "@alchemy.run/gcp";
28 import * as Effect from "effect/Effect";
29
30 export default class Api extends GCP.Function<Api>()(
31 "Api",
32 { main: import.meta.url },
33 Effect.gen(function* () {
34 return {};
35 }),
36 ) {}
37 ```
38
39 `GCP.Function` is a Cloud Run service. `main: import.meta.url` makes
40 this file the entrypoint: Alchemy bundles it into a container image,
41 pushes it to Artifact Registry, and deploys it.
42
43 ## Serve HTTP with `fetch`
44
45 Return a `fetch` handler to answer requests:
46
47 ```diff lang="typescript"
48 // src/api.ts
49 import * as GCP from "@alchemy.run/gcp";
50 import * as Effect from "effect/Effect";
51 +import * as HttpServerResponse from "effect/http/HttpServerResponse";
52
53 export default class Api extends GCP.Function<Api>()(
54 "Api",
55 { main: import.meta.url },
56 Effect.gen(function* () {
57 - return {};
58 + return {
59 + fetch: Effect.succeed(HttpServerResponse.text("Hello from Cloud Run!")),
60 + };
61 }),
62 ) {}
63 ```
64
65 :::note
66 The outer generator is the **Construction phase**. It runs when you
67 deploy and again when the container starts. The inner `fetch` is the
68 **Runtime phase**. It runs for each request.
69 :::
70
71 ## Make it public
72
73 Cloud Run asks every caller for a Google identity token by default.
74 Turn that off so anyone can call the service:
75
76 ```diff lang="typescript"
77 export default class Api extends GCP.Function<Api>()(
78 "Api",
79 - { main: import.meta.url },
80 + { main: import.meta.url, invokerIamDisabled: true },
81 Effect.gen(function* () {
82 return {
83 fetch: Effect.succeed(HttpServerResponse.text("Hello from Cloud Run!")),
84 };
85 }),
86 ) {}
87 ```
88
89 ## Move the Bucket into the service
90
91 Declare the Bucket next to the code that uses it:
92
93 ```diff lang="typescript"
94 Effect.gen(function* () {
95 + const bucket = yield* GCP.Storage.Bucket("Bucket", {});
96
97 return {
98 fetch: Effect.succeed(HttpServerResponse.text("Hello from Cloud Run!")),
99 };
100 }),
101 ```
102
103 The logical id is still `Bucket`, so this is the same Bucket you
104 deployed in Part 1. Moving a declaration doesn't recreate it.
105
106 ## Bind the Bucket
107
108 Ask for read and write access to the Bucket:
109
110 ```diff lang="typescript"
111 Effect.gen(function* () {
112 const bucket = yield* GCP.Storage.Bucket("Bucket", {});
113 + const files = yield* GCP.Storage.ReadWriteBucket(bucket);
114
115 return {
116 fetch: Effect.succeed(HttpServerResponse.text("Hello from Cloud Run!")),
117 };
118 }),
119 ```
120
121 `ReadWriteBucket` gives you a client with `get`, `put`, `list`, and
122 `delete`. On deploy it grants the service `roles/storage.objectUser`
123 on this Bucket and nothing else. Use `ReadBucket` or `WriteBucket`
124 when you need less.
125
126 ## Write objects with `PUT /:key`
127
128 Use the URL path as the object name and store the request body:
129
130 ```diff lang="typescript"
131 // src/api.ts
132 import * as GCP from "@alchemy.run/gcp";
133 import * as Effect from "effect/Effect";
134 +import { HttpServerRequest } from "effect/http/HttpServerRequest";
135 import * as HttpServerResponse from "effect/http/HttpServerResponse";
136
137 export default class Api extends GCP.Function<Api>()(
138 "Api",
139 { main: import.meta.url, invokerIamDisabled: true },
140 Effect.gen(function* () {
141 const bucket = yield* GCP.Storage.Bucket("Bucket", {});
142 const files = yield* GCP.Storage.ReadWriteBucket(bucket);
143
144 return {
145 - fetch: Effect.succeed(HttpServerResponse.text("Hello from Cloud Run!")),
146 + fetch: Effect.gen(function* () {
147 + const request = yield* HttpServerRequest;
148 + const key = new URL(request.originalUrl, "http://localhost").pathname.slice(1);
149 +
150 + if (request.method === "PUT") {
151 + const body = yield* request.text;
152 + yield* files.put(key, body, { contentType: "text/plain" });
153 + return HttpServerResponse.empty({ status: 204 });
154 + }
155 +
156 + return HttpServerResponse.text("Method not allowed", { status: 405 });
157 + }),
158 };
159 }),
160 ) {}
161 ```
162
163 `put` takes the object name, a string or bytes, and options like
164 `contentType`.
165
166 ## Read objects with `GET /:key`
167
168 Add a `GET` branch:
169
170 ```diff lang="typescript"
171 if (request.method === "PUT") {
172 const body = yield* request.text;
173 yield* files.put(key, body, { contentType: "text/plain" });
174 return HttpServerResponse.empty({ status: 204 });
175 }
176
177 +if (request.method === "GET") {
178 + const object = yield* files.get(key);
179 + if (object === undefined) {
180 + return HttpServerResponse.text("Not found", { status: 404 });
181 + }
182 + return HttpServerResponse.uint8Array(object.body, {
183 + contentType: object.contentType ?? "application/octet-stream",
184 + });
185 +}
186
187 return HttpServerResponse.text("Method not allowed", { status: 405 });
188 ```
189
190 `get` returns `undefined` for a missing object, so a 404 is a plain
191 `if`.
192
193 ## Turn unhandled errors into 500s
194
195 Apply `Effect.orDie` once at the end of `fetch`:
196
197 ```diff lang="typescript"
198 fetch: Effect.gen(function* () {
199 // ... PUT and GET branches ...
200 return HttpServerResponse.text("Method not allowed", { status: 405 });
201 -}),
202 +}).pipe(Effect.orDie),
203 ```
204
205 Any failure you didn't handle becomes a 500.
206
207 ## Provide the client
208
209 Bindings declare what the service needs. Provide the layer that
210 implements the Bucket client at the end of the service:
211
212 ```diff lang="typescript"
213 export default class Api extends GCP.Function<Api>()(
214 "Api",
215 { main: import.meta.url, invokerIamDisabled: true },
216 Effect.gen(function* () {
217 // ... bucket, binding, fetch ...
218 - }),
219 + }).pipe(Effect.provide(GCP.Storage.ReadWriteBucketHttp)),
220 ) {}
221 ```
222
223 Every binding has a matching `Http` layer: `ReadWriteBucket` →
224 `ReadWriteBucketHttp`. Forget one and the type error names it.
225
226 ## Add the service to the Stack
227
228 Yield `Api` in the Stack and return its URL:
229
230 ```diff lang="typescript"
231 // alchemy.run.ts
232 import * as Alchemy from "alchemy";
233 import * as GCP from "@alchemy.run/gcp";
234 import * as Effect from "effect/Effect";
235 +import Api from "./src/api.ts";
236
237 export default Alchemy.Stack(
238 "MyApp",
239 {
240 providers: GCP.providers(),
241 state: GCP.state(),
242 },
243 Effect.gen(function* () {
244 - const bucket = yield* GCP.Storage.Bucket("Bucket", {});
245 + const api = yield* Api;
246
247 return {
248 - bucketName: bucket.bucketName,
249 + url: api.uri,
250 };
251 }),
252 );
253 ```
254
255 The Bucket is still part of the Stack. `Api` declares it.
256
257 ## Deploy
258
259 <PackageManagers run="alchemy deploy" />
260
261 <Terminal content={`[u]Plan[/u]: [g]1 to create[/g]
262
263 [g]+[/g] [b]Api[/b] [d](GCP.Run.Service)[/d]
264 [d]•[/d] [b]Bucket[/b] [d](GCP.Storage.Bucket)[/d]
265
266 Proceed?
267 ◉ Yes ○ No
268 [d]•[/d] [b]Bucket[/b] [d](GCP.Storage.Bucket)[/d] [d]no change[/d]
269 [g]✓[/g] [b]Api[/b] [d](GCP.Run.Service)[/d] [g]created[/g]
270 {
271 [s2]url: "https://myapp-live-sam-api-a1b2c3-uc.a.run.app",
272 }`} />
273
274 Alchemy builds the image, creates a service account for the service,
275 grants it access to the Bucket, and deploys the revision. The first
276 deploy takes a couple of minutes. Later deploys only rebuild when your
277 code changes.
278
279 ## Try it out
280
281 ```sh
282 curl -X PUT "$URL/hello.txt" -d 'Hello, world!'
283
284 curl "$URL/hello.txt"
285 # → Hello, world!
286 ```
287
288 ## Recap
289
290 You now have:
291
292 - A Cloud Run service with GET and PUT routes on a public URL
293 - A Bucket bound to the service, with IAM granted from the binding
294 - Stack outputs showing the service URL
295
296 In [Part 3](/gcp/tutorial/part-3), you write tests that deploy the
297 Stack and call the service over HTTP.
298
299 :::tip[Want to build something now?]
300 Skip ahead to [Firestore](/gcp/data/firestore),
301 [Pub/Sub](/gcp/messaging/pubsub), or
302 [Cloud Scheduler](/gcp/messaging/scheduler), and come back for
303 testing, stages, and CI/CD later.
304 :::