@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, 03:37 UTC

main
mdx 241 lines 9.01 KB
Raw
1 ---
2 title: Local Provider
3 description: Build the local implementation of a resource — dual registration with ProviderLayer.dual and the LocalProvider runner for long-running processes.
4 ---
5
6 During `alchemy dev`, some resources shouldn't touch the cloud at all: a
7 Worker runs in a local `workerd`, a dev server is a child process on your
8 machine. A **local provider** is the implementation that serves a resource
9 type in dev, alongside the **live provider** used by `alchemy deploy`.
10
11 This guide is about *building* one. For the user-facing dev model — and
12 opting a resource out of local emulation with `remote()` — see
13 [Local development](/environments/local-development). If you haven't built
14 a provider before, start with
15 [Custom Provider](/infrastructure-as-code/custom-provider) — a local
16 provider is just a second implementation of the same lifecycle contract.
17
18 ## What the engine does for you
19
20 The engine remembers which implementation reconciled each resource. Moving
21 a resource between local and live is planned as a **replacement**, and
22 every instance is deleted by the provider that created it — so a deploy
23 right after a dev session tears the local instances down with *your* local
24 provider. You implement the lifecycle; the engine owns the switching.
25
26 ## Register both: `ProviderLayer.dual`
27
28 ```typescript
29 import * as ProviderLayer from "alchemy/Local/ProviderLayer";
30 import * as Layer from "effect/Layer";
31
32 export const WorkerProvider = () =>
33 ProviderLayer.dual(Worker, {
34 live: () => LiveWorkerProvider(),
35 local: () =>
36 LocalWorkerProvider().pipe(Layer.provide(localRuntimeServices())),
37 });
38 ```
39
40 `dual` registers the run's default mode eagerly and builds the other
41 **lazily** — e.g. the local provider is only constructed during a deploy
42 if it has an instance to tear down.
43
44 ### Route deploy-time data-plane calls: `dataPlane`
45
46 Binding clients can be invoked at deploy time — inside an `Action` body or
47 a plan-time `execute` — and their API calls must target whatever data
48 plane the bound resource actually lives on. Pass the local mode's
49 environment override (endpoint, credentials, region — the same layer the
50 local lifecycle runs under) as `dataPlane`:
51
52 ```typescript
53 ProviderLayer.dual(Bucket, {
54 live: () => BucketProvider(),
55 local: () => provideProviderContext(BucketProvider(), flociServices()),
56 dataPlane: flociServices,
57 });
58 ```
59
60 With it registered, a client bound to a local-mode resource is routed to
61 the emulator even when the ambient profile carries live credentials, while
62 a client bound to an `Alchemy.remote()` resource keeps hitting the real
63 cloud — per bound resource, within the same Action.
64
65 ### Compose local deps inside the thunk
66
67 Mode-specific dependency layers (`workerd`, Docker) go inside the `local`
68 thunk, never globally — that's what keeps a plain `alchemy deploy` from
69 constructing local machinery it doesn't need.
70
71 :::note[Share dependency layers by reference]
72 Variant builds are memoized by layer identity. If several local providers
73 share a dependency layer (Cloudflare's `localRuntimeServices()`), the
74 factory must return a module-memoized reference so they all get one
75 instance per stack build.
76 :::
77
78 ## Long-running processes: `LocalProvider.make`
79
80 A process-shaped local provider has a problem ordinary providers don't:
81 the "physical resource" is a running process that **state can't see** — a
82 resource can be marked `created` while its process died with the last dev
83 session. `LocalProvider.make` owns that machinery; you write how to boot
84 one instance.
85
86 ### Declare the provider with `start`
87
88 ```typescript
89 import * as LocalProvider from "alchemy/Local/LocalProvider";
90 import * as Effect from "effect/Effect";
91
92 export const DevProviderLocal = () =>
93 LocalProvider.make(
94 Dev,
95 import.meta.resolve("./Local.ts", import.meta.url),
96 Effect.gen(function* () {
97 const { spawn } = yield* CommandExecutor;
98
99 return {
100 start: Effect.fn(function* ({ news }) {
101 const child = yield* spawn(news);
102 const url = yield* waitForUrl(child);
103 return { url };
104 }),
105 } satisfies LocalProvider.LocalProviderSpec<Dev>;
106 }),
107 );
108 ```
109
110 `start` boots one instance in the ambient `Scope` and returns Attributes at
111 *readiness* — the process keeps running after `start` returns, until the
112 runner closes the scope on restart or delete.
113
114 ### Handle processes that die on their own
115
116 ```diff lang="typescript"
117 start: Effect.fn(function* ({ news, invalidate }) {
118 const child = yield* spawn(news);
119 const url = yield* waitForUrl(child);
120 + yield* child.exitCode.pipe(
121 + Effect.exit,
122 + Effect.flatMap(() => invalidate),
123 + Effect.forkScoped,
124 + );
125 return { url };
126 }),
127 ```
128
129 `invalidate` drops the instance from the running registry, so the next plan
130 reports `update` and reconcile boots a fresh one.
131
132 ### Narrow the restart surface with `resolveConfig`
133
134 ```diff lang="typescript"
135 return {
136 + // Only these fields decide whether a running instance must restart.
137 + resolveConfig: ({ news }) =>
138 + Effect.succeed({ command: news.command, env: news.env }),
139 start: Effect.fn(function* ({ config, invalidate }) {
140 - const child = yield* spawn(news);
141 + const child = yield* spawn(config);
142 // ...
143 }),
144 };
145 ```
146
147 The runner canonically hashes `resolveConfig`'s result to decide
148 noop-vs-restart, and hands the same value to `start` — so "what changed?"
149 and "what starts?" can never drift.
150
151 :::tip[Config must be plain data]
152 `resolveConfig` runs inside `diff` on every plan: keep it cheap,
153 side-effect-free, and free of closures or live objects. Derive plain
154 *descriptors* here and materialize runtime-rich structures from them inside
155 `start`.
156 :::
157
158 ### Clean up cross-restart state with `stop`
159
160 ```diff lang="typescript"
161 return {
162 resolveConfig: ({ news }) => ...,
163 start: Effect.fn(function* ({ config, invalidate }) { ... }),
164 + // Delete-only: NOT called on restarts.
165 + stop: Effect.fn(function* ({ id }) {
166 + yield* stopProxy(id);
167 + }),
168 };
169 ```
170
171 Anything acquired by `start` dies with the instance scope; `stop` is only
172 for state that intentionally *survives* restarts — like a URL proxy kept so
173 the address stays stable across rebuilds.
174
175 ### What the runner generates
176
177 - **`diff`** — running instance + equal config hash → `noop`; anything
178 else → `update`. A fresh dev session has an empty registry, so processes
179 restart even though they were previously `created`.
180 - **`reconcile`** — reuses the running instance on a hash match; otherwise
181 tears it down and forks `start` in a scope that outlives the deploy.
182 - **`delete`** — tears down only the matching `instanceId` (a replacement's
183 old-generation delete can't kill its successor), then runs `stop`.
184 - **`list`** — every running instance's Attributes.
185
186 :::note[The dev sidecar]
187 The second argument (`serverEntryUrl`) serves the provider over RPC: during
188 `alchemy dev` the registry of running processes lives in a sidecar that
189 survives user-code hot reloads. Outside dev, the provider is constructed
190 in-process and no sidecar is spawned.
191 :::
192
193 ## Not everything is a process
194
195 If the local "instance" is just an entry in a shared registry — Cloudflare's
196 local Queue is an entry in `LocalRuntimeState`, reconciled with three
197 idempotent map operations — skip `LocalProvider.make` and write a plain
198 provider registered via `dual`.
199
200 ## Testing
201
202 ```typescript
203 const { test } = Test.make({ providers, dev: true }); // dev-mode default
204
205 test.provider("promotes a dev worker to a live worker", (stack) =>
206 Effect.gen(function* () {
207 yield* program.pipe(stack.deploy); // local (dev default)
208 // Same props, pinned live: planned as a REPLACEMENT — the live
209 // provider creates the deployed worker, the local provider kills
210 // workerd.
211 yield* program.pipe(Alchemy.remote(), stack.deploy);
212 yield* stack.destroy();
213 }),
214 );
215 ```
216
217 `Test.make({ dev: true })` gives the file `alchemy dev` semantics, and
218 `remote()` works in tests exactly like in programs.
219
220 ## Reference implementations
221
222 - [`Command/Dev.ts`](https://github.com/alchemy-run/alchemy/blob/main/packages/alchemy/src/Command/Dev.ts)
223 — the smallest `LocalProvider.make` provider: spawn a command, extract
224 its URL, restart on prop changes.
225 - [`Cloudflare/Workers/LocalWorkerProvider.ts`](https://github.com/alchemy-run/alchemy/blob/main/packages/cloudflare/src/Workers/LocalWorkerProvider.ts)
226 — the full-size one: bundler watch loop, `workerd` instances, a URL
227 proxy torn down in `stop`.
228 - [`Cloudflare/Queues/Queue.ts`](https://github.com/alchemy-run/alchemy/blob/main/packages/cloudflare/src/Queues/Queue.ts)
229 — the registry-style counter-example: a plain local provider under
230 `dual`.
231
232 ## Where next
233
234 - [Local development](/environments/local-development) — the user-facing
235 dev loop, and opting resources out of local emulation with `remote()`.
236 - [Custom Provider](/infrastructure-as-code/custom-provider) — the
237 lifecycle contract both implementations share.
238 - [Resource lifecycle](/infrastructure-as-code/resource-lifecycle) —
239 when each lifecycle method fires, including replacements.
240 - [Testing Providers](/testing/testing-providers) — the `test.provider`
241 harness used above.