@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, 04:45 UTC

main
mdx 174 lines 4.76 KB
Raw
1 ---
2 title: "Part 3: Persist Data with a Volume"
3 description: Mount a Fly disk into your Service with MountVolume and store files that survive deploys.
4 sidebar:
5 order: 3
6 ---
7
8 import Terminal from "../../../../components/Terminal.astro";
9 import PackageManagers from "../../../../components/PackageManagers.astro";
10
11 Your Service from [Part 2](/fly/tutorial/part-2) is stateless.
12 Writes to the Machine's root disk die with the Machine. In this
13 part you mount a Volume so files survive deploys.
14
15 :::caution[One Volume, one Machine]
16 A Fly Volume attaches to one Machine. Two Services cannot mount
17 the same disk. `count: 3` creates three independent Volumes, one
18 per replica.
19 :::
20
21 ## Mount a disk into the Service
22
23 There is no standalone Volume resource. Inside the Service's constructor,
24 `Fly.MountVolume({ path, sizeGb })` creates a per-replica disk in
25 the Service's App and region:
26
27 ```diff lang="typescript"
28 // src/api.ts
29 import * as Fly from "@alchemy.run/fly";
30 import * as Effect from "effect/Effect";
31 import { HttpServerRequest } from "effect/http/HttpServerRequest";
32 import * as HttpServerResponse from "effect/http/HttpServerResponse";
33
34 export default class Api extends Fly.Service<Api>()(
35 "Api",
36 { main: import.meta.url, region: "iad", port: 3000 },
37 Effect.gen(function* () {
38 + const mount = yield* Fly.MountVolume({ path: "/data", sizeGb: 1 });
39
40 return {
41 fetch: /* ... */,
42 };
43 }),
44 ) {}
45 ```
46
47 `MountVolume` is a **binding**: at deploy time it tells the Service
48 "create a 1 GB Volume and put it in `config.mounts` at `/data`", and
49 at runtime it hands you the resolved `mount.path`.
50
51 ## Provide the binding layer
52
53 Bindings declare a capability; layers implement it. Provide
54 `MountVolumeLive` on the Service's constructor Effect:
55
56 ```diff lang="typescript"
57 Effect.gen(function* () {
58 const mount = yield* Fly.MountVolume({ path: "/data", sizeGb: 1 });
59
60 return {
61 fetch: /* ... */,
62 };
63 - }),
64 + }).pipe(Effect.provide(Fly.MountVolumeLive)),
65 ) {}
66 ```
67
68 ## Resolve FileSystem in the constructor
69
70 Yield `FileSystem` in the outer Effect. Close over it in `fetch`.
71 Do not yield it per request.
72
73 ```diff lang="typescript"
74 // src/api.ts
75 +import * as FileSystem from "effect/FileSystem";
76 // ...
77 Effect.gen(function* () {
78 const mount = yield* Fly.MountVolume({ path: "/data", sizeGb: 1 });
79 + const fs = yield* FileSystem.FileSystem;
80
81 return {
82 fetch: /* ... */,
83 };
84 }).pipe(Effect.provide(Fly.MountVolumeLive)),
85 ```
86
87 ## Write files with `PUT /:name`
88
89 The Volume is a directory. Use `fs` from the constructor:
90
91 ```diff lang="typescript"
92 fetch: Effect.gen(function* () {
93 const request = yield* HttpServerRequest;
94 const url = new URL(request.url, "http://service");
95 if (url.pathname === "/health") {
96 return HttpServerResponse.json({ ok: true });
97 }
98 + const file = `${mount.path}${url.pathname}`;
99 +
100 + if (request.method === "PUT") {
101 + const body = yield* request.text;
102 + yield* fs.writeFileString(file, body).pipe(Effect.orDie);
103 + return HttpServerResponse.empty({ status: 204 });
104 + }
105 +
106 return HttpServerResponse.text("Hello from Fly!");
107 }),
108 ```
109
110 ## Read files with `GET /:name`
111
112 Add the read branch, turning a missing file into a 404:
113
114 ```diff lang="typescript"
115 if (request.method === "PUT") {
116 const body = yield* request.text;
117 yield* fs.writeFileString(file, body).pipe(Effect.orDie);
118 return HttpServerResponse.empty({ status: 204 });
119 }
120
121 +if (request.method === "GET") {
122 + const text = yield* fs.readFileString(file).pipe(
123 + Effect.catch(() => Effect.succeed(undefined)),
124 + );
125 + if (text === undefined) {
126 + return HttpServerResponse.text("Not found", { status: 404 });
127 + }
128 + return HttpServerResponse.text(text);
129 +}
130
131 return HttpServerResponse.text("Hello from Fly!");
132 ```
133
134 ## Deploy
135
136 <PackageManagers run="alchemy deploy" />
137
138 <Terminal content={`[u]Plan[/u]: [y]1 to update[/y]
139
140 [y]~[/y] [b]Api[/b] [d](Fly.Service)[/d]
141
142 Proceed?
143 ◉ Yes ○ No
144 [g]✓[/g] [b]Api[/b] [d](Fly.Service)[/d] [y]updated[/y]`} />
145
146 During the Service's deploy, Alchemy creates the Volume and writes
147 it into the Machine's `config.mounts` at `/data`. The disk lives in
148 the Service's region (`iad`).
149
150 ## Try it out
151
152 ```sh
153 # Store a file on the Volume
154 curl -X PUT https://myapp-api-dev-a1b2c3d4.fly.dev/hello.txt -d 'Hello, Volume!'
155
156 # Read it back
157 curl https://myapp-api-dev-a1b2c3d4.fly.dev/hello.txt
158 # → Hello, Volume!
159 ```
160
161 Ship another code change and deploy — the file is still there. If
162 the Machine is replaced, the Volume re-attaches on the next deploy.
163
164 ## Recap
165
166 You now have:
167
168 - A 1 GB Volume in `iad` mounted at `/data` on the API Machine
169 - A Service reading and writing it through Effect's `FileSystem` —
170 no SDK, just files
171 - Data that outlives deploys and Machine replacement
172
173 In [Part 4](/fly/tutorial/part-4), you'll read a secret from `.env`
174 in the Service, then tear the stack down.