|
| 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, or process work, |
| 17 | +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 | + observeRpcEffect( |
| 28 | + WS_METHODS.projectsCreateNew, |
| 29 | + projectFolders.createNamedProject(input).pipe( |
| 30 | + Effect.mapError((cause) => new ProjectCreateNewError({ cause })), |
| 31 | + ), |
| 32 | + { "rpc.aggregate": "orchestration" }, |
| 33 | + ), |
| 34 | +``` |
| 35 | + |
| 36 | +## Shape of a service module |
| 37 | + |
| 38 | +One module per service, in this order: imports, errors and schemas, the `Context.Service` tag with |
| 39 | +its interface inline, `make`, then `layer`. [`WorkspacePaths.ts`](../../apps/server/src/workspace/WorkspacePaths.ts) |
| 40 | +and [`T3ProjectFileLoader.ts`](../../apps/server/src/project/T3ProjectFileLoader.ts) are good |
| 41 | +references. |
| 42 | + |
| 43 | +```ts |
| 44 | +export class FooWriteError extends Schema.TaggedError<FooWriteError>()("FooWriteError", { |
| 45 | + path: Schema.String, |
| 46 | + cause: Schema.Defect(), |
| 47 | +}) { |
| 48 | + override get message(): string { |
| 49 | + return "Failed to write the foo file."; |
| 50 | + } |
| 51 | +} |
| 52 | + |
| 53 | +export class Foo extends Context.Service< |
| 54 | + Foo, |
| 55 | + { readonly write: (input: { readonly path: string }) => Effect.Effect<void, FooWriteError> } |
| 56 | +>()("t3/area/Foo") {} |
| 57 | + |
| 58 | +const make = Effect.gen(function* () { |
| 59 | + const fileSystem = yield* FileSystem.FileSystem; |
| 60 | + // ... |
| 61 | + return Foo.of({ write }); |
| 62 | +}); |
| 63 | + |
| 64 | +export const layer = Layer.effect(Foo, make); |
| 65 | +``` |
| 66 | + |
| 67 | +- **Imports.** Consumers use the module as a namespace: `import * as Foo from "./Foo.ts"`, then |
| 68 | + `yield* Foo.Foo` and `Foo.layer`. Never `import { layer as fooLayer }`. |
| 69 | +- **Dependencies** come from the environment (`yield* FileSystem.FileSystem`), never as parameters to |
| 70 | + `make`. |
| 71 | +- **`make`** stays private unless another module imports it. Knip fails CI on an unused export. |
| 72 | +- **Errors** are `Schema.TaggedError` classes with structured attributes and a `cause` when they wrap |
| 73 | + a failure. The message is fixed or built from attributes, never from `cause`. Construct the error |
| 74 | + where the failure happens; map it to a transport error only in the transport. Catch known tags |
| 75 | + with `Effect.catchTags`. |
| 76 | +- **Tests** exercise behavior through the service, with test layers only for external dependencies. |
| 77 | + Don't mock the logic under test. |
| 78 | + |
| 79 | +## Before you push |
| 80 | + |
| 81 | +- Does any handler you touched do more than decode, call, and map errors? |
| 82 | +- Could an agent (MCP) or a scheduled task use this capability? If not, is that deliberate? |
| 83 | +- Did you extend the domain's existing service before adding a new one? |
| 84 | +- Did you run knip? A new export with no importer fails it. |
0 commit comments