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

main
mdx 503 lines 15.7 KB
Raw
1 ---
2 title: Connect Services
3 description: Build several Fly Services that call each other's methods over a private network, behind one public entry point.
4 ---
5
6 Each [Service](/fly/compute/services) is its own Fly App. One Service
7 calls another by **binding** it: `Fly.bindService(Users)` returns a
8 typed client for the methods `Users` returns, and the calls travel over
9 Fly's private network to `Users`'s `privateUrl`.
10
11 Two things decide who can call a Service:
12
13 - **The network.** Every App in the organization joins Fly's default
14 private network unless told otherwise. Set
15 `network: yield* Fly.stackNetwork` on each Service to put a stack's
16 Services on a network unique to its stack and stage. Apps on any
17 other network cannot resolve them.
18 - **The binding.** Each Service has a caller token. Only Services that
19 bind it receive the token, so only they can call its methods.
20
21 This guide builds the
22 [fly-microservices example](https://github.com/alchemy-run/alchemy/tree/main/examples/fly-microservices):
23 a private `Users` Service, a private `Orders` Service that calls
24 `Users`, and a public `Gateway` that calls both.
25
26 ## Create the Users Service
27
28 `Users` returns two methods, `list` and `get`. It returns no `fetch`;
29 bound callers call the methods directly.
30
31 ```typescript
32 // src/users.ts
33 import * as Fly from "@alchemy.run/fly";
34 import * as Effect from "effect/Effect";
35
36 export interface User {
37 id: string;
38 name: string;
39 }
40
41 export const USERS: User[] = [
42 { id: "u1", name: "Ada" },
43 { id: "u2", name: "Grace" },
44 ];
45
46 export default class Users extends Fly.Service<Users>()(
47 "Users",
48 Effect.gen(function* () {
49 return {
50 main: import.meta.url,
51 public: false,
52 };
53 }),
54 Effect.gen(function* () {
55 return {
56 list: () => Effect.succeed(USERS),
57 get: (id: string) => Effect.succeed(USERS.find((user) => user.id === id)),
58 };
59 }),
60 ) {}
61 ```
62
63 `public: false` gives the Service's App a private Flycast address and
64 no internet address. The props are an Effect so the next step can
65 `yield*` inside them.
66
67 ## Put Users on the stack's network
68
69 Add `network` so only this stage's Services can reach `Users`:
70
71 ```diff lang="typescript"
72 Effect.gen(function* () {
73 return {
74 main: import.meta.url,
75 public: false,
76 + network: yield* Fly.stackNetwork,
77 };
78 }),
79 ```
80
81 `Fly.stackNetwork` yields a network name built from the stack and
82 stage, such as `flymicroservices-dev`. Fly creates the network with the
83 first App that names it.
84
85 :::caution[Changing `network` replaces the Service]
86 Fly cannot move an App between networks. Alchemy creates the Service
87 on the new network, then deletes the old App. `network` only applies
88 when the Service owns its App; combining it with `app` fails with
89 `Fly.InvalidServiceProps`.
90 :::
91
92 ## Create the Orders Service
93
94 `Orders` is a second private Service on the same network:
95
96 ```typescript
97 // src/orders.ts
98 import * as Fly from "@alchemy.run/fly";
99 import * as Effect from "effect/Effect";
100
101 const ORDERS = [
102 { id: "o1", userId: "u1", item: "keyboard" },
103 { id: "o2", userId: "u2", item: "monitor" },
104 ];
105
106 export default class Orders extends Fly.Service<Orders>()(
107 "Orders",
108 Effect.gen(function* () {
109 return {
110 main: import.meta.url,
111 public: false,
112 network: yield* Fly.stackNetwork,
113 };
114 }),
115 Effect.gen(function* () {
116 return {};
117 }),
118 ) {}
119 ```
120
121 ## Bind Users from Orders
122
123 Bind `Users` in the Orders program:
124
125 ```diff lang="typescript"
126 // src/orders.ts
127 +import Users from "./users.ts";
128 // ...
129 Effect.gen(function* () {
130 + const users = yield* Fly.bindService(Users);
131 return {};
132 }),
133 ```
134
135 `users` is a typed client with `list` and `get`. Binding also makes
136 `Orders` deploy after `Users` and hands `Orders` the address and caller
137 token of `Users`.
138
139 ## Call Users from Orders
140
141 Return a `list` method that looks up each order's user:
142
143 ```diff lang="typescript"
144 Effect.gen(function* () {
145 const users = yield* Fly.bindService(Users);
146 - return {};
147 + return {
148 + list: () =>
149 + Effect.forEach(ORDERS, (order) =>
150 + users
151 + .get(order.userId)
152 + .pipe(Effect.map((user) => ({ ...order, user }))),
153 + ),
154 + };
155 }),
156 ```
157
158 `users.get(order.userId)` is a call over the private network. The
159 result is typed as `User | undefined`, the return type of `get` in
160 `Users`.
161
162 ## Create the public Gateway
163
164 `Gateway` joins the same network and leaves out `public: false`, so it
165 is public:
166
167 ```typescript
168 // src/gateway.ts
169 import * as Fly from "@alchemy.run/fly";
170 import * as Effect from "effect/Effect";
171
172 export default class Gateway extends Fly.Service<Gateway>()(
173 "Gateway",
174 Effect.gen(function* () {
175 return {
176 main: import.meta.url,
177 network: yield* Fly.stackNetwork,
178 };
179 }),
180 Effect.gen(function* () {
181 return {};
182 }),
183 ) {}
184 ```
185
186 A public Service on the network still serves `url`, so `Gateway` is
187 the stack's single entry point from the internet.
188
189 ## Bind Users and Orders from the Gateway
190
191 ```diff lang="typescript"
192 // src/gateway.ts
193 +import Orders from "./orders.ts";
194 +import Users from "./users.ts";
195 // ...
196 Effect.gen(function* () {
197 + const users = yield* Fly.bindService(Users);
198 + const orders = yield* Fly.bindService(Orders);
199 return {};
200 }),
201 ```
202
203 `orders` exposes the `list` method `Orders` returns.
204
205 ## Serve routes from the Gateway
206
207 Call the bound methods from `fetch`:
208
209 ```diff lang="typescript"
210 // src/gateway.ts
211 +import { HttpServerRequest } from "effect/http/HttpServerRequest";
212 +import * as HttpServerResponse from "effect/http/HttpServerResponse";
213 // ...
214 Effect.gen(function* () {
215 const users = yield* Fly.bindService(Users);
216 const orders = yield* Fly.bindService(Orders);
217 - return {};
218 + return {
219 + fetch: Effect.gen(function* () {
220 + const request = yield* HttpServerRequest;
221 + const path = new URL(request.url, "http://gateway").pathname;
222 + if (path === "/users") {
223 + return yield* HttpServerResponse.json(yield* users.list());
224 + }
225 + if (path === "/orders") {
226 + return yield* HttpServerResponse.json(yield* orders.list());
227 + }
228 + return HttpServerResponse.text("try /users or /orders");
229 + }).pipe(Effect.orDie),
230 + };
231 }),
232 ```
233
234 ## Wire the Stack
235
236 Yield the three Services and return their URLs:
237
238 ```typescript
239 // alchemy.run.ts
240 import * as Alchemy from "alchemy";
241 import * as Fly from "@alchemy.run/fly";
242 import * as Effect from "effect/Effect";
243 import Gateway from "./src/gateway.ts";
244 import Orders from "./src/orders.ts";
245 import Users from "./src/users.ts";
246
247 export default Alchemy.Stack(
248 "FlyMicroservices",
249 { providers: Fly.providers(), state: Alchemy.localState() },
250 Effect.gen(function* () {
251 const users = yield* Users;
252 const orders = yield* Orders;
253 const gateway = yield* Gateway;
254
255 return {
256 url: gateway.url,
257 network: gateway.network,
258 usersPrivateUrl: users.privateUrl,
259 ordersPrivateUrl: orders.privateUrl,
260 };
261 }),
262 );
263 ```
264
265 ## Deploy
266
267 ```sh
268 alchemy deploy
269 ```
270
271 Alchemy deploys `Users`, then `Orders`, then `Gateway`, and prints the
272 outputs:
273
274 ```text
275 url: "https://flymicroservices-gateway-dev-a1b2c3d4.fly.dev"
276 network: "flymicroservices-dev"
277 usersPrivateUrl: "http://flymicroservices-users-dev-e5f6a7b8.flycast"
278 ordersPrivateUrl: "http://flymicroservices-orders-dev-c9d0e1f2.flycast"
279 ```
280
281 ## Try it out
282
283 ```sh
284 curl https://flymicroservices-gateway-dev-a1b2c3d4.fly.dev/users
285 # → [{"id":"u1","name":"Ada"},{"id":"u2","name":"Grace"}]
286
287 curl https://flymicroservices-gateway-dev-a1b2c3d4.fly.dev/orders
288 # → [{"id":"o1","userId":"u1","item":"keyboard","user":{"id":"u1","name":"Ada"}}, ...]
289 ```
290
291 The second request crosses two private calls: Gateway → Orders →
292 Users.
293
294 ## How deploy order works
295
296 `Fly.bindService(Users)` makes the caller depend on `Users`. `Orders`
297 binds `Users`, and `Gateway` binds both, so Alchemy deploys `Users`,
298 then `Orders`, then `Gateway`. The caller's deploy writes the bound
299 Service's private address and caller token onto the caller's Machines;
300 the client reads them at runtime.
301
302 The order of `yield*` in the Stack does not matter. The bindings
303 decide it.
304
305 ## Public `url` and private `privateUrl`
306
307 | Service | `url` | `privateUrl` |
308 | --------- | ------------------------------- | ---------------------------------- |
309 | `Users` | `undefined` | `http://{users-app}.flycast` |
310 | `Orders` | `undefined` | `http://{orders-app}.flycast` |
311 | `Gateway` | `https://{gateway-app}.fly.dev` | `http://{gateway-app}.flycast:7780` |
312
313 `url` is the internet endpoint and is set only for a public Service.
314 `privateUrl` is where bound callers reach the Service. A private
315 Service serves plain HTTP on port 80, so its `privateUrl` has no port.
316 A public Service's default ports are an HTTPS redirect (80) and HTTPS
317 (443), so Alchemy publishes an extra plain-HTTP port for bound callers,
318 `bindingPort` (default `7780`).
319
320 You rarely use `privateUrl` directly. `Fly.bindService` resolves it
321 for you.
322
323 ## Security model
324
325 A method call from `Orders` to `Users` is accepted only when all of
326 these hold:
327
328 - **Same network.** `Users` is on the stack's network, so only Apps on
329 that network can resolve `{users-app}.flycast`. Binding a Service on
330 another network fails the caller's deploy with
331 `Fly.ServiceUnreachable`, before the caller's App is created.
332 - **Caller token.** Each Service has its own caller token, generated
333 by Alchemy. A Service receives the token only for the Services it
334 binds, and sends it with every method call. A Service on the same
335 network that did not bind `Users` gets `401` from its methods.
336 - **Fly-Src signature.** Fly's proxy signs every request that arrives
337 over Flycast with an ed25519 `Fly-Src` header naming the calling App
338 and organization. `Users` verifies the signature with Fly's public
339 key and checks the caller is in the same organization. A request
340 from the internet carries no valid signature, so a public Service's
341 methods answer `401` to it, and the extra `bindingPort` answers only
342 private-network requests.
343
344 Fly issues no certificate for `.flycast`, so calls are plain HTTP.
345 They travel inside Fly's private network, which Fly encrypts with
346 WireGuard.
347
348 :::caution[`fetch` routes are not token-protected]
349 The caller token guards methods. A Service's `fetch` routes answer any
350 request that reaches them: anything on the Service's network for a
351 private Service, and the internet for a public one. Put operations
352 that only bound Services should call in methods.
353 :::
354
355 ## What an outside App sees
356
357 An App that is not on the stack's network cannot resolve the private
358 names. From a Machine in an App on the org's default network:
359
360 ```sh
361 wget -qO- http://flymicroservices-users-dev-e5f6a7b8.flycast
362 # wget: bad address 'flymicroservices-users-dev-e5f6a7b8.flycast'
363
364 wget -qO- http://flymicroservices-users-dev-e5f6a7b8.internal
365 # wget: bad address 'flymicroservices-users-dev-e5f6a7b8.internal'
366 ```
367
368 Other stages of the same stack get their own `Fly.stackNetwork`, so
369 `dev` and `prod` Services cannot call each other either.
370
371 ## Call HTTP routes with `client.fetch`
372
373 A bound client also forwards requests to the Service's `fetch`
374 handler. A relative URL resolves against the Service's `privateUrl`:
375
376 ```typescript
377 import * as HttpClientRequest from "effect/http/HttpClientRequest";
378
379 const users = yield* Fly.bindService(Users);
380 const response = yield* users.fetch(HttpClientRequest.get("/hello"));
381 const text = yield* response.text;
382 ```
383
384 Use it for a Service that serves HTTP routes, such as a framework
385 server. These requests carry no caller token; see the
386 [caution above](#security-model).
387
388 ## Stream results from a method
389
390 A method can return a `Stream`. The bound client returns the same
391 `Stream`, delivered element by element:
392
393 ```typescript
394 // in Users
395 streamAll: () => Stream.fromIterable(USERS),
396
397 // in the caller
398 const all = yield* users.streamAll().pipe(Stream.runCollect);
399 ```
400
401 ## Bind one port with `Fly.bindEndpoint`
402
403 `Fly.bindEndpoint` binds a single published port of a Service, for a
404 port other than its main HTTP port. Publish the port on the target.
405 Here both ports forward to the Service's `fetch` on 3000, which reads
406 Fly's `fly-forwarded-port` header to tell them apart:
407
408 ```typescript
409 services: [
410 { protocol: "tcp", internalPort: 3000, ports: [{ port: 80, handlers: ["http"] }] },
411 { protocol: "tcp", internalPort: 3000, ports: [{ port: 9000, handlers: ["http"] }] },
412 ],
413 ```
414
415 Then bind it from the caller:
416
417 ```typescript
418 const admin = yield* Fly.bindEndpoint(Users, { port: 9000 });
419 const stats = yield* admin.client.get("/stats");
420 ```
421
422 `admin.client` is an `HttpClient` whose relative URLs go to
423 `http://{users-app}.flycast:9000`. For a raw TCP port, open your own
424 connection to `yield* admin.host` (`{users-app}.flycast`) and
425 `admin.port`. `yield* admin.url` is the full plain-HTTP URL.
426
427 `bindEndpoint` sends no caller token. It relies on the network and
428 whatever the port itself checks.
429
430 ## Two Services that bind each other
431
432 A class can only bind a Service that already exists as a value. For
433 two Services that bind each other, declare each as a tag class with the
434 shape of its methods:
435
436 ```typescript
437 // src/services.ts
438 interface Named {
439 name: () => Effect.Effect<string>;
440 }
441
442 export class Ping extends Fly.Service<Ping, Named>()("Ping") {}
443 export class Pong extends Fly.Service<Pong, Named>()("Pong") {}
444 ```
445
446 Implement each in its own file with `.make`, binding the other. The
447 file's default export is the implementation the Machine runs:
448
449 ```typescript
450 // src/ping.ts
451 import { Ping, Pong } from "./services.ts";
452
453 export default Ping.make(
454 { main: import.meta.url },
455 Effect.gen(function* () {
456 const pong = yield* Fly.bindService(Pong);
457 return {
458 name: () => Effect.succeed("ping"),
459 fetch: Effect.gen(function* () {
460 return HttpServerResponse.text(`ping hears ${yield* pong.name()}`);
461 }).pipe(Effect.orDie),
462 };
463 }),
464 );
465 ```
466
467 `src/pong.ts` is the same with the roles swapped.
468
469 Provide both implementations to the Stack's Effect:
470
471 ```typescript
472 import PingLive from "./src/ping.ts";
473 import PongLive from "./src/pong.ts";
474
475 Effect.gen(function* () {
476 const ping = yield* Ping;
477 const pong = yield* Pong;
478 return { ping: ping.url, pong: pong.url };
479 }).pipe(Effect.provide(Layer.mergeAll(PingLive, PongLive)));
480 ```
481
482 Alchemy creates a stub of each Service first, then wires the bindings.
483 Only Services that own their App can be part of such a cycle. A
484 Service placed in a shared App with `app` cannot.
485
486 ## Errors
487
488 | Error | When | Fix |
489 | --------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
490 | `Fly.ServiceUnreachable` | The caller and the bound Service are on different networks. Fails before the caller's App is created. | Give both the same `network`, usually `Fly.stackNetwork`. |
491 | `Fly.ServiceNotBindable` | The bound Service publishes no ports (`services: []`), so it has no private address. | Publish a port, or stop binding it. |
492 | `Fly.EndpointNotPublished` | `Fly.bindEndpoint` names a port the Service does not publish. | Add the port to the Service's `services`, or bind a published port. |
493
494 ## Where next
495
496 - [Services](/fly/compute/services) — private Services, `bindingPort`,
497 and grouping Services in one App.
498 - [IPs & certificates](/fly/networking) — public and private
499 Services, and addresses on your own App.
500 - [Blue/green deployments](/fly/compute/deployments) — replace a
501 Service without dropping calls from its callers.
502 - The [fly-microservices example](https://github.com/alchemy-run/alchemy/tree/main/examples/fly-microservices)
503 and the [`Service` reference](/providers/fly/service).