@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
md 163 lines 9.67 KB
Rendered Raw
1 # Effect services
2
3 Server features are Effect services. Transports call them: WebSocket RPC handlers in
4 [`ws.ts`](../../apps/server/src/ws.ts), HTTP routes, MCP tools, scheduled tasks, and the CLI. This
5 page holds the rules for writing them. The
6 [Effect Service Conventions](../../.macroscope/check-run-agents/effect-service-conventions.md)
7 review check enforces the same rules; keep the two in step.
8
9 ## Where a feature lives
10
11 A server capability is a method on a service in its domain folder (`project/`, `workspace/`, `git/`,
12 `provider/`, ...). Extend the service that already owns the domain; add a new one only when none
13 does.
14
15 A transport handler does three things: decode the request, call one service method, and map the
16 service's typed errors to the transport's error. Nothing else. Filesystem, Git, process, or
17 persistence work, folder naming, multi-step dispatch, retries, and rollback belong in the service.
18
19 The reason is reach. Users trigger a capability from the WebSocket, agents reach it through MCP
20 tools, and scheduled tasks and the CLI run it too. Logic written into one handler is missing from
21 the others, and testing it needs a socket. Plain functions for pure work (a slug, an SVG, a
22 message) are fine next to the service; the capability itself is the method.
23
24 ```ts
25 // ws.ts: a thin handler
26 [WS_METHODS.projectsCreateNew]: (input) =>
27 projectFolders
28 .createNamedProject(input)
29 .pipe(Effect.mapError((cause) => new ProjectCreateNewError({ cause }))),
30 ```
31
32 Handlers don't add their own spans or request metrics. Group middleware authorizes every call
33 ([`RpcAuthorization.ts`](../../apps/server/src/auth/RpcAuthorization.ts)), and the server's group
34 also instruments it
35 ([`RpcInstrumentation.ts`](../../apps/server/src/observability/RpcInstrumentation.ts)). A handler
36 with per-call context, such as a thread id, adds it with `Effect.annotateCurrentSpan`.
37
38 ## Shape of a service module
39
40 One module per service, in this order: imports, errors and schemas, the `Context.Service` tag with
41 its interface inline, `make`, then `layer`. [`WorkspacePaths.ts`](../../apps/server/src/workspace/WorkspacePaths.ts)
42 and [`T3ProjectFileLoader.ts`](../../apps/server/src/project/T3ProjectFileLoader.ts) are good
43 references.
44
45 ```ts
46 export class FooWriteError extends Schema.TaggedError<FooWriteError>()("FooWriteError", {
47 path: Schema.String,
48 cause: Schema.Defect(),
49 }) {
50 override get message(): string {
51 return "Failed to write the foo file.";
52 }
53 }
54
55 export class Foo extends Context.Service<
56 Foo,
57 { readonly write: (input: { readonly path: string }) => Effect.Effect<void, FooWriteError> }
58 >()("t3/area/Foo") {}
59
60 const make = Effect.gen(function* () {
61 const fileSystem = yield* FileSystem.FileSystem;
62 // ...
63 return Foo.of({ write });
64 });
65
66 export const layer = Layer.effect(Foo, make);
67 ```
68
69 - **Imports.** Import Effect modules as namespaces from their subpaths:
70 `import * as Effect from "effect/Effect"`, never `import { Effect } from "effect"`. Consumers use
71 a service module the same way: `import * as Foo from "./Foo.ts"`, then `yield* Foo.Foo` and
72 `Foo.layer`. Never `import { layer as fooLayer }`. Named imports are fine for packages like
73 `@t3tools/contracts` and for modules used only for a pure helper, error, schema, config value, or
74 type. A barrel exposes a whole service module as `export * as TokenStore from "./tokenStore.ts"`,
75 not as renamed `make` and `layer` exports.
76 - **Interface.** No standalone `FooShape`; name the type `Foo["Service"]`.
77 - **Dependencies** come from the environment (`yield* FileSystem.FileSystem`), never as parameters
78 to `make`, so the types of `make` and `layer` show what they need. Never hide one in a module
79 global, a closure over a singleton, or a `Layer.succeed` that calls runtime-backed or imperative
80 APIs. Tests may pass service instances directly. Configuration, immutable values, and deliberate
81 callbacks are fine as parameters; they aren't services.
82 - **`make`** exists when the module owns construction and stays private unless another module
83 imports it. Knip fails CI on an unused export. Don't write `make = Effect.succeed(...)` to force
84 `Layer.effect`; use the constructor that fits, like `Layer.succeed` or `Layer.sync`.
85 - **Names.** A module named for its implementation uses plain `make` and `layer`
86 ([`NodePtyAdapter.ts`](../../apps/server/src/terminal/NodePtyAdapter.ts)). A port module that also
87 holds implementations names them, like `makeCloudflaredRelayClient` and `layerCloudflared`.
88 - **Moves.** Moving a service deletes the old files and updates every consumer, including
89 orchestration, MCP, tests, and integration harnesses. No re-export shims.
90 - **Tests** exercise behavior through the service, with test layers only for external dependencies.
91 Don't mock the logic under test.
92
93 ## Effect functions and tracing
94
95 Reusable functions use `Effect.fn("Service.operation")`, not an arrow or declaration returning
96 `Effect.gen`. The named form creates a span; `Effect.fn(function* ...)` only captures stack
97 frames. Keep `Effect.gen` for inline programs and layer construction. Use
98 `Effect.fnUntraced(function* ...)` for inline handlers that share the enclosing operation's span.
99
100 Default to named spans for service operations and I/O. Use `Effect.fnUntraced` deliberately for
101 per-chunk/per-event work, tight loops, or helpers already covered by the same operation's span.
102 Explain the reason beside the function or a group of related functions. A loop is not by itself
103 an exemption: its outer operation can still have a useful span without tracing each iteration.
104 Move existing span names and options into `Effect.fn` instead of adding a second span for the same
105 operation; annotate the current span for attributes that depend on function arguments. Keep an
106 explicit `withSpan` inside an untraced function when an outer tracer override must cover span creation.
107
108 Pass effect combinators after the generator body. A transform that needs the function's input
109 receives it after the effect. Use `Effect.fn.Return<A, E, R>` when the generator needs an explicit
110 return type, and preserve generic parameters, laziness, scope, and interruption behavior.
111
112 ## Runtime boundaries
113
114 `ManagedRuntime.make`, `runPromise`, and `runPromiseExit` belong at application and framework
115 boundaries: React, native callbacks, the CLI, HTTP adapters. Never in a domain service, repository,
116 persistence code, or service constructor. A named adapter may bridge a service into a Promise API,
117 but no Effect service depends on it.
118
119 Compose a shared resource once in an application-owned layer and provide its context to integration
120 runtimes. Don't create a managed or Atom runtime per feature to hand it out. When acquisition can
121 fail and callers need a fallback, keep the failure typed: an error on the operation or an explicit
122 optional-service layer. Don't route around the layer with an imperative runtime.
123
124 ## Errors
125
126 - **Attributes.** Failures are `Schema.TaggedError` classes with structured attributes: the
127 operation or stage, the resource path or entity id, a normalized category or status. The message
128 is fixed or built from those attributes, never from `cause`, `cause.message`, or a stringified
129 defect. No `detail` field that copies `cause.message`.
130 - **Cause.** An error that wraps a failure keeps the immediate underlying error as `cause`; make it
131 required when every construction wraps one. Validation and domain errors with nothing underneath
132 have none.
133 - **Safe values.** Attributes and log annotations stay bounded: no raw payloads, command arguments
134 or output, signed URLs, credentials, query strings, or arbitrary defect text. The exact value
135 lives only in `cause`. Expose a category, length, count, or a URL's protocol and host instead.
136 `DeviceBootError.diagnostics` is a deliberate exception: authorized device users and agents
137 need the device hub's launch command and failure text to diagnose host setup. It is capped at
138 2,000 characters and included in the error message; other service errors keep the rule above.
139 - **Translation.** Construct the error where the failure happens, and map it to a transport error
140 only in the transport. A translation boundary passes through domain errors already in the target
141 channel and wraps only unknown or lower-level failures. Map each failure where its context is
142 known; don't wrap a whole pipeline in one generic error.
143 - **Discriminators.** Don't encode one distinction twice, as a specific tag and a single-value
144 `operation`, `reason`, `kind`, or `phase` literal. Split classes when the distinction drives
145 control flow or the user-facing message; a field that only helps diagnostics stays a field. A
146 message that reaches HTTP, RPC, persisted state, or the UI is behavior, and a refactor keeps it.
147 - **Mappers.** Don't write a helper that only does `(...args) => new SomeError({ ...args })`. Keep
148 a mapper only when it normalizes, passes domain errors through, or adds context. A mapper that
149 belongs to the target error is a static factory on that class.
150 - **Predicates** are exported directly as `export const isFoo = Schema.is(Foo)`, not a function
151 wrapping a private `Schema.is`.
152 - **Catching.** Catch known tags with `Effect.catchTags({ ... })`, even for one tag, not `catchTag`
153 or `catchIf` with a schema predicate. `Effect.catch` is for handling the whole channel; `catchIf`
154 is for structural checks like a platform error code.
155
156 ## Before you push
157
158 - Does any handler you touched do more than decode, call, and map errors?
159 - Could an agent (MCP) or a scheduled task use this capability? If not, is that deliberate?
160 - Did you extend the domain's existing service before adding a new one?
161 - Did you run knip? A new export with no importer fails it.
162 - Does every directive you added that disables a lint, type-checker, or LSP diagnostic say why, in
163 a `-- reason` suffix or a comment above it?