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

main
mdx 263 lines 7.32 KB
Raw
1 ---
2 title: Effect HTTP API on Cloud Run
3 description: Build a schema-validated HTTP API with Effect's HttpApi module, deploy it to Cloud Run, and call it from a typed client.
4 sidebar:
5 order: 2
6 ---
7
8 `HttpApi` gives you real REST endpoints, with paths, query strings,
9 and typed bodies, behind a typed client. Use it when the API's callers
10 aren't all Effect, or aren't TypeScript. The concept lives at
11 [Effect HTTP](/apis/effect-http). This page wires it onto Cloud Run.
12
13 ## Define the schema
14
15 ```typescript
16 // src/Job.ts
17 import * as Schema from "effect/Schema";
18
19 export const JobId = Schema.String;
20
21 export class Job extends Schema.Class<Job>("Job")({
22 id: JobId,
23 content: Schema.String,
24 }) {}
25
26 export class JobNotFound extends Schema.TaggedErrorClass<JobNotFound>()(
27 "JobNotFound",
28 { id: Schema.String },
29 { httpApiStatus: 404 },
30 ) {}
31 ```
32
33 `httpApiStatus: 404` sets the status the error is sent with.
34
35 ## Declare the API
36
37 ```typescript
38 // src/JobApi.ts
39 import * as Schema from "effect/Schema";
40 import * as HttpApi from "effect/http-api/HttpApi";
41 import * as HttpApiEndpoint from "effect/http-api/HttpApiEndpoint";
42 import * as HttpApiGroup from "effect/http-api/HttpApiGroup";
43 import { Job, JobId, JobNotFound } from "./Job.ts";
44
45 export const getJob = HttpApiEndpoint.get("getJob", "/", {
46 success: Job,
47 error: JobNotFound,
48 query: { jobId: JobId },
49 });
50
51 export const createJob = HttpApiEndpoint.post("createJob", "/", {
52 success: JobId,
53 payload: Schema.Struct({ content: Schema.String }),
54 });
55
56 export const JobApi = HttpApi.make("JobApi").add(
57 HttpApiGroup.make("Jobs").add(getJob, createJob),
58 );
59 ```
60
61 `JobApi` is a plain value. The server and the client both import it.
62
63 ## Implement it on Cloud Run
64
65 Bind a Firestore database, implement the handlers, and turn the API
66 into a `fetch` handler:
67
68 ```typescript
69 // src/JobService.ts
70 import * as GCP from "@alchemy.run/gcp";
71 import * as Effect from "effect/Effect";
72 import * as Layer from "effect/Layer";
73 import * as Etag from "effect/http/Etag";
74 import * as HttpPlatform from "effect/http/HttpPlatform";
75 import * as HttpRouter from "effect/http/HttpRouter";
76 import * as HttpApiBuilder from "effect/http-api/HttpApiBuilder";
77 import { Job, JobNotFound } from "./Job.ts";
78 import { JobApi } from "./JobApi.ts";
79
80 export default class JobService extends GCP.Function<JobService>()(
81 "JobService",
82 { main: import.meta.url, invokerIamDisabled: true },
83 Effect.gen(function* () {
84 const jobs = yield* GCP.Firestore.Database("Jobs", {
85 type: "FIRESTORE_NATIVE",
86 });
87 const db = yield* GCP.Firestore.ReadWriteDatabase(jobs);
88
89 const jobsGroup = HttpApiBuilder.group(JobApi, "Jobs", (handlers) =>
90 handlers
91 .handle("getJob", ({ query }) =>
92 db.get(`jobs/${query.jobId}`).pipe(
93 Effect.orDie,
94 Effect.flatMap((doc) =>
95 doc
96 ? Effect.succeed(
97 new Job({
98 id: query.jobId,
99 content: String(doc.fields.content ?? ""),
100 }),
101 )
102 : Effect.fail(new JobNotFound({ id: query.jobId })),
103 ),
104 ),
105 )
106 .handle("createJob", ({ payload }) =>
107 Effect.gen(function* () {
108 const id = crypto.randomUUID();
109 yield* db.set(`jobs/${id}`, { content: payload.content });
110 return id;
111 }).pipe(Effect.orDie),
112 ),
113 );
114
115 return {
116 fetch: yield* HttpRouter.toHttpEffect(
117 HttpApiBuilder.layer(JobApi).pipe(Layer.provide(jobsGroup)),
118 ),
119 };
120 }).pipe(
121 Effect.provide(
122 Layer.mergeAll(
123 GCP.Firestore.ReadWriteDatabaseHttp,
124 HttpPlatform.layer,
125 Etag.layer,
126 ),
127 ),
128 ),
129 ) {}
130 ```
131
132 Handlers get typed input and must return the declared types. Firestore
133 errors become 500s through `Effect.orDie`. `JobNotFound` stays typed
134 and is sent as a 404.
135
136 ## Add it to the Stack
137
138 ```typescript
139 // alchemy.run.ts
140 import * as Alchemy from "alchemy";
141 import * as GCP from "@alchemy.run/gcp";
142 import * as Effect from "effect/Effect";
143 import JobService from "./src/JobService.ts";
144
145 export default Alchemy.Stack(
146 "JobApi",
147 { providers: GCP.providers(), state: GCP.state() },
148 Effect.gen(function* () {
149 const service = yield* JobService;
150 return { url: service.uri };
151 }),
152 );
153 ```
154
155 ```sh
156 bun alchemy deploy
157 ```
158
159 Invalid payloads get a 400 with the validation errors.
160
161 ## Call it from a typed test
162
163 The same `JobApi` value builds a typed client:
164
165 ```typescript
166 // test/api.test.ts
167 import * as Alchemy from "alchemy";
168 import * as GCP from "@alchemy.run/gcp";
169 import * as Test from "@alchemy.run/test/Bun";
170 import { expect } from "bun:test";
171 import * as Effect from "effect/Effect";
172 import * as Schedule from "effect/Schedule";
173 import * as HttpApiClient from "effect/http-api/HttpApiClient";
174 import Stack from "../alchemy.run.ts";
175 import { JobApi } from "../src/JobApi.ts";
176
177 const { test, beforeAll, deploy } = Test.make({
178 providers: GCP.providers(),
179 state: GCP.state(),
180 });
181
182 const stack = beforeAll(deploy(Stack), { timeout: 600_000 });
183
184 test(
185 "create and fetch a job",
186 Effect.gen(function* () {
187 const { url } = yield* stack;
188 const client = yield* HttpApiClient.make(JobApi, { baseUrl: url });
189
190 const jobId = yield* client.Jobs.createJob({
191 payload: { content: "Ship the docs" },
192 }).pipe(
193 Effect.retry({ schedule: Schedule.exponential("1 second"), times: 8 }),
194 );
195
196 const job = yield* client.Jobs.getJob({ query: { jobId } });
197 expect(job.content).toBe("Ship the docs");
198
199 const missing = yield* client.Jobs.getJob({
200 query: { jobId: "nope" },
201 }).pipe(Effect.flip);
202 expect(missing._tag).toBe("JobNotFound");
203 }),
204 { timeout: 120_000 },
205 );
206 ```
207
208 The first call retries while the new Firestore grant reaches the
209 service.
210
211 ## Call it from another service
212
213 Keep the API service private and call it from another Cloud Run
214 service. `GCP.Run.InvokeService` with `api` returns a typed
215 `HttpApiClient` whose requests carry an ID token:
216
217 ```typescript
218 // inside the calling service's Effect
219 const jobs = yield* GCP.Run.InvokeService(JobService, { api: JobApi });
220 const job = yield* jobs.Jobs.getJob({ query: { jobId } });
221 ```
222
223 `GCP.Run.ServeHttpApi` is a shorter way to serve the API. It adds the
224 platform layers and builds the router once per instance:
225
226 ```typescript
227 return { fetch: GCP.Run.ServeHttpApi(JobApi, jobsGroup) };
228 ```
229
230 ## Run it as a sidecar
231
232 Declare the API as a `GCP.Run.Container` and bind it with
233 `GCP.Run.bindContainer` to call it over `localhost`:
234
235 ```typescript
236 // src/JobSidecar.ts
237 import * as GCP from "@alchemy.run/gcp";
238 import * as Effect from "effect/Effect";
239 import { JobApi } from "./JobApi.ts";
240 import { jobsGroup } from "./handlers.ts";
241
242 export default class JobSidecar extends GCP.Run.Container<JobSidecar>()(
243 "JobSidecar",
244 { main: import.meta.url, port: 3000, startupProbe: { tcpSocket: {} } },
245 Effect.gen(function* () {
246 return { fetch: GCP.Run.ServeHttpApi(JobApi, jobsGroup) };
247 }),
248 ) {}
249 ```
250
251 ```typescript
252 // inside the calling service's Effect
253 const jobs = yield* GCP.Run.bindContainer(JobSidecar, { api: JobApi });
254 const job = yield* jobs.Jobs.getJob({ query: { jobId } });
255 ```
256
257 ## Where next
258
259 - [Effect HTTP](/apis/effect-http) — endpoints, groups, and clients in
260 depth.
261 - [Effect RPC on Cloud Run](/gcp/apis/effect-rpc) — when every caller
262 is Effect.
263 - [Firestore](/gcp/data/firestore) — the client used above.