EFF-700: Improve HttpApi addHttpApi / middleware missing-service failures (#1725)

Author: tim-smart

.changeset/eff-700-httpapi-middleware-errors.md

@@ -0,0 +1,12 @@
+---
+"effect": patch
+---
+
+Improve unstable HttpApi runtime failures for missing server middleware and missing group implementations.
+
+- HttpApiBuilder.applyMiddleware now resolves middleware services via ServiceMap.getUnsafe, so missing middleware fails with a clear "Service not found: <middleware>" error instead of an opaque is not a function TypeError.
+- HttpApiBuilder.layer now reports missing groups with actionable context (group identifier, service key, suggested HttpApiBuilder.group(...) call, and available group keys).
+- Added regression tests in packages/platform-node/test/HttpApi.test.ts covering:
+  - addHttpApi + API-level middleware applied across merged groups
+  - missing middleware service diagnostics
+  - missing addHttpApi group layer diagnostics

packages/effect/src/unstable/httpapi/HttpApiBuilder.ts

@@ -72,10 +72,16 @@ export const layer = <Id extends string, Groups extends HttpApiGroup.Any>(
       | Path
     >()
     const routes: Array<HttpRouter.Route<any, any>> = []
+    const availableGroups = Array.from(services.mapUnsafe.keys()).filter((key) =>
+      key.startsWith("effect/httpapi/HttpApiGroup/")
+    )
     for (const group of Object.values(api.groups)) {
       const groupRoutes = services.mapUnsafe.get(group.key) as Array<HttpRouter.Route<any, any>>
       if (groupRoutes === undefined) {
-        return yield* Effect.die(`HttpApiGroup "${group.key}" not found`)
+        const available = availableGroups.length === 0 ? "none" : availableGroups.join(", ")
+        return yield* Effect.die(
+          `HttpApiGroup "${group.identifier}" not found (key: "${group.key}"). Did you forget to provide HttpApiBuilder.group(api, "${group.identifier}", ...)? Available groups: ${available}`
+        )
       }
       routes.push(...groupRoutes)
     }
@@ -630,13 +636,13 @@ const getRequestMediaType = (request: HttpServerRequest): string => {
 const applyMiddleware = <A extends Effect.Effect<any, any, any>>(
   group: HttpApiGroup.AnyWithProps,
   endpoint: HttpApiEndpoint.AnyWithProps,
-  services: ServiceMap.ServiceMap<never>,
+  services: ServiceMap.ServiceMap<any>,
   handler: A
 ) => {
   const options = { group, endpoint }
   for (const key_ of endpoint.middlewares) {
     const key = key_ as any as HttpApiMiddleware.AnyService
-    const service = services.mapUnsafe.get(key_.key) as HttpApiMiddleware.HttpApiMiddleware<any, any, any>
+    const service = ServiceMap.getUnsafe(services, key as any) as HttpApiMiddleware.HttpApiMiddleware<any, any, any>
     const apply = HttpApiMiddleware.isSecurity(key)
       ? makeSecurityMiddleware(key, service as any)
       : service

packages/platform-node/test/HttpApi.test.ts

@@ -2,6 +2,7 @@ import { NodeHttpServer } from "@effect/platform-node"
 import { assert, describe, it } from "@effect/vitest"
 import {
   Array,
+  Cause,
   DateTime,
   Effect,
   Equal,
@@ -434,6 +435,158 @@ describe("HttpApi", () => {
         assert.strictEqual(yield* authedClient.group.a(), "token")
       }).pipe(Effect.provide(ApiLive))
     })
+
+    it.effect("addHttpApi + middleware works across merged groups", () => {
+      class M1 extends HttpApiMiddleware.Service<M1>()("Http/M1") {}
+      class M2 extends HttpApiMiddleware.Service<M2>()("Http/M2") {}
+
+      const calls: Array<string> = []
+
+      const V0 = HttpApi.make("v0").add(
+        HttpApiGroup.make("users").add(
+          HttpApiEndpoint.get("list", "/users", {
+            success: Schema.String
+          })
+        )
+      )
+      const Api = HttpApi.make("api")
+        .add(
+          HttpApiGroup.make("health").add(
+            HttpApiEndpoint.get("health", "/health", {
+              success: Schema.String
+            })
+          )
+        )
+        .addHttpApi(V0)
+        .middleware(M1)
+        .middleware(M2)
+
+      const HealthLive = HttpApiBuilder.group(
+        Api,
+        "health",
+        (handlers) => handlers.handle("health", () => Effect.succeed("ok"))
+      )
+      const UsersLive = HttpApiBuilder.group(
+        Api,
+        "users",
+        (handlers) => handlers.handle("list", () => Effect.succeed("ok"))
+      )
+      const M1Live = Layer.succeed(
+        M1,
+        (effect, { endpoint, group }) =>
+          Effect.sync(() => calls.push(`m1:${group.identifier}.${endpoint.name}`)).pipe(
+            Effect.flatMap(() => effect)
+          )
+      )
+      const M2Live = Layer.succeed(
+        M2,
+        (effect, { endpoint, group }) =>
+          Effect.sync(() => calls.push(`m2:${group.identifier}.${endpoint.name}`)).pipe(
+            Effect.flatMap(() => effect)
+          )
+      )
+
+      const ApiLive = HttpRouter.serve(
+        HttpApiBuilder.layer(Api).pipe(
+          Layer.provide(HealthLive),
+          Layer.provide(UsersLive),
+          Layer.provide(M1Live),
+          Layer.provide(M2Live)
+        ),
+        { disableListenLog: true, disableLogger: true }
+      ).pipe(Layer.provideMerge(NodeHttpServer.layerTest))
+
+      return Effect.gen(function*() {
+        yield* assertServerJson(yield* HttpClient.get("/health"), 200, "ok")
+        yield* assertServerJson(yield* HttpClient.get("/users"), 200, "ok")
+        assert.deepStrictEqual(calls, [
+          "m2:health.health",
+          "m1:health.health",
+          "m2:users.list",
+          "m1:users.list"
+        ])
+      }).pipe(Effect.provide(ApiLive))
+    })
+
+    it.effect("missing middleware layer fails with service not found error", () => {
+      class M extends HttpApiMiddleware.Service<M>()("Server/MissingMiddleware") {}
+
+      const Api = HttpApi.make("api").add(
+        HttpApiGroup.make("group")
+          .add(
+            HttpApiEndpoint.get("a", "/a", {
+              success: Schema.String
+            })
+          )
+          .middleware(M)
+      )
+      const GroupLive = HttpApiBuilder.group(
+        Api,
+        "group",
+        (handlers) => handlers.handle("a", () => Effect.succeed("ok"))
+      )
+      const ApiLive = HttpRouter.serve(
+        HttpApiBuilder.layer(Api).pipe(Layer.provide(GroupLive)),
+        { disableListenLog: true, disableLogger: true }
+      ).pipe(Layer.provideMerge(NodeHttpServer.layerTest))
+
+      return HttpClient.get("/a").pipe(
+        Effect.provide(ApiLive),
+        Effect.sandbox,
+        Effect.flip,
+        Effect.flatMap((cause) =>
+          Effect.sync(() => {
+            const defect = Cause.squash(cause)
+            assert.instanceOf(defect, Error)
+            assert.include(defect.message, "Service not found: Server/MissingMiddleware")
+            assert.isFalse(defect.message.includes("is not a function"))
+          })
+        )
+      ) as Effect.Effect<void, HttpClientResponse.HttpClientResponse>
+    })
+  })
+
+  it.effect("missing addHttpApi group layer has actionable error", () => {
+    const HealthApi = HttpApiGroup.make("health").add(
+      HttpApiEndpoint.get("health", "/health", {
+        success: Schema.String
+      })
+    )
+    const V0 = HttpApi.make("v0").add(
+      HttpApiGroup.make("users").add(
+        HttpApiEndpoint.get("list", "/users", {
+          success: Schema.String
+        })
+      )
+    )
+    const Api = HttpApi.make("api")
+      .add(HealthApi)
+      .addHttpApi(V0)
+
+    const UsersLive = HttpApiBuilder.group(
+      Api,
+      "users",
+      (handlers) => handlers.handle("list", () => Effect.succeed("ok"))
+    )
+    const ApiLive = HttpRouter.serve(
+      HttpApiBuilder.layer(Api).pipe(Layer.provide(UsersLive)),
+      { disableListenLog: true, disableLogger: true }
+    ).pipe(Layer.provideMerge(NodeHttpServer.layerTest))
+
+    return HttpClient.get("/users").pipe(
+      Effect.provide(ApiLive),
+      Effect.sandbox,
+      Effect.flip,
+      Effect.flatMap((cause) =>
+        Effect.sync(() => {
+          const defect = Cause.squash(cause)
+          assert.strictEqual(typeof defect, "string")
+          assert.include(defect, "HttpApiGroup \"health\" not found")
+          assert.include(defect, "HttpApiBuilder.group(api, \"health\", ...)")
+          assert.include(defect, "Available groups: effect/httpapi/HttpApiGroup/users")
+        })
+      )
+    ) as Effect.Effect<void, HttpClientResponse.HttpClientResponse>
   })
 
   describe("payload option", () => {