effect 4.0.6 → 4.0.7

package/src/http-api/HttpApiBuilder.ts

@@ -90,19 +90,33 @@ export const layer = <Id extends string, Groups extends HttpApiGroup.Constraint>
       | Path
     >()
     const routes: Array<HttpRouter.Route<any, any>> = []
+    const routeOwners = new Map<string, string>()
     const availableGroups = Array.from(services.mapUnsafe.keys()).filter((key) =>
       key.startsWith("effect/http-api/HttpApiGroup/")
     )
     const groups = Object.values(api.groups) as ReadonlyArray<HttpApiGroup.Top>
     for (const group of groups) {
-      const groupRoutes = services.mapUnsafe.get(group.key)?.routes as Array<HttpRouter.Route<any, any>>
-      if (groupRoutes === undefined) {
+      const service = services.mapUnsafe.get(group.key) as GroupService | undefined
+      if (service === undefined) {
         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)
+      for (const { endpoint } of service.handlers.values()) {
+        const owner = `${group.identifier}.${endpoint.identifier}`
+        const key = `${endpoint.method} ${HttpApiPath.toRouterPath(endpoint.path, endpoint.params)}`
+        const existing = routeOwners.get(key)
+        if (existing !== undefined) {
+          return yield* Effect.die(
+            new Error(
+              `HttpApiEndpoint "${owner}" (${endpoint.method} ${endpoint.path}) has the same method and path as "${existing}". Declare one endpoint whose query, headers, payload or success schemas cover each variant instead.`
+            )
+          )
+        }
+        routeOwners.set(key, owner)
+      }
+      routes.push(...service.routes)
     }
     yield* (router.addAll(routes) as Effect.Effect<void>)
     if (options?.openapiPath) {
@@ -159,12 +173,8 @@ export const group = <
     for (const item of handlers.handlers.values()) {
       routes.push(handlerToRoute(api, group as any, item, services))
     }
-    return Context.makeUnsafe(
-      new Map([[group.key, {
-        routes,
-        handlers: handlers.handlers
-      }]])
-    )
+    const service: GroupService = { routes, handlers: handlers.handlers }
+    return Context.makeUnsafe(new Map([[group.key, service]]))
   })) as any
 
 /**
@@ -245,6 +255,14 @@ export interface HandlerRuntime {
   readonly uninterruptible: boolean
 }
 
+/**
+ * @internal
+ */
+export interface GroupService {
+  readonly routes: Array<HttpRouter.Route<any, any>>
+  readonly handlers: Map<string, HandlerRuntime>
+}
+
 type HandleAllEntry<Endpoint extends HttpApiEndpoint.Constraint> =
   | HttpApiEndpoint.Handler<
     Endpoint,
@@ -939,6 +957,10 @@ function handlerToHttpEffect(
   const encodeStream = makeStreamEncoder(endpoint, options.success)
   const encodeWithHeaders = makeWithHeadersEncoder(endpoint, options.success, options.headers)
   const upgrade = getUpgradeSuccessSchema(endpoint)
+  const encodeUpgradeHeaders = UndefinedOr.map(
+    upgrade?.headers,
+    (schema) => Schema.encodeUnknownEffect(schema, options.headers)
+  )
 
   const shouldParsePayload = endpoint.payload.size > 0 && !isRaw
   const payloadBy = shouldParsePayload ? buildPayloadDecoders(endpoint.payload, options.payload) : undefined
@@ -967,6 +989,20 @@ function handlerToHttpEffect(
       if (decodeQuery) {
         request.query = yield* HttpApiSchemaError.wrap("Query", decodeQuery(query))
       }
+      if (upgrade !== undefined) {
+        if (!isUpgradeRequest(httpRequest, upgrade.protocol)) {
+          return upgradeRequired(upgrade.protocol)
+        }
+        request.upgrade = (options?: { readonly headers?: unknown }) =>
+          Effect.orDie(
+            encodeUpgradeHeaders === undefined
+              ? httpRequest.upgrade
+              : Effect.flatMap(
+                HttpApiSchemaError.wrap("ResponseHeaders", encodeUpgradeHeaders(options?.headers)),
+                (headers) => httpRequest.upgradeWith({ headers: headers as Record<string, string> })
+              )
+          )
+      }
       if (payloadBy) {
         const result = decodePayload(payloadBy, httpRequest, query)
         if (Response.isHttpServerResponse(result)) {
@@ -976,12 +1012,6 @@ function handlerToHttpEffect(
           request.payload = yield* HttpApiSchemaError.wrap("Payload", result)
         }
       }
-      if (upgrade !== undefined) {
-        if (!isUpgradeRequest(httpRequest, upgrade.protocol)) {
-          return upgradeRequired(upgrade.protocol)
-        }
-        request.socket = yield* Effect.orDie(httpRequest.upgrade)
-      }
       let response = yield* handler(request)
       if (Response.isHttpServerResponse(response)) {
         return response

package/src/http-api/HttpApiClient.ts

@@ -102,7 +102,7 @@ export type SuccessType<S> = S extends HttpApiSchema.WithHeaders<
   : S extends HttpApiSchema.StreamUint8Array ? Stream.Stream<Uint8Array, HttpClientError.HttpClientError, never>
   : S extends HttpApiSchema.StreamNdjson<infer _S> ?
     Stream.Stream<_S["Type"], HttpClientError.HttpClientError | Schema.SchemaError, never>
-  : S extends HttpApiSchema.Upgrade ? Upgraded
+  : S extends HttpApiSchema.Upgrade<infer _Headers> ? [_Headers] extends [never] ? Upgraded : Upgraded<_Headers["Type"]>
   : S extends Schema.Constraint ? S["Type"]
   : never
 
@@ -113,15 +113,16 @@ export type SuccessType<S> = S extends HttpApiSchema.WithHeaders<
  *
  * **Details**
  *
- * See `HttpClientResponse.upgrade` for how the connection behaves and when it
- * closes.
+ * `headers` is decoded with the upgrade's `headers` schema when it declares
+ * one. See `HttpClientResponse.upgrade` for how the connection behaves and
+ * when it closes.
  *
  * @stability unstable
  * @category models
  * @since 4.0.6
  */
-export interface Upgraded {
-  readonly headers: Headers.Headers
+export interface Upgraded<Headers = Headers.Headers> {
+  readonly headers: Headers
   readonly socket: Socket.Socket
 }
 
@@ -134,9 +135,16 @@ type SuccessDecodingServices<S> = S extends HttpApiSchema.StreamSse<
     | _Error["DecodingServices"]
   : S extends HttpApiSchema.StreamUint8Array ? never
   : S extends HttpApiSchema.StreamNdjson<infer _S> ? _S["DecodingServices"]
+  : S extends HttpApiSchema.Upgrade<infer _Headers> ? _Headers["DecodingServices"]
   : S extends Schema.Constraint ? S["DecodingServices"]
   : never
 
+// An uninferred type parameter is instantiated with its constraint, so methods
+// without a streaming payload must constrain `PayloadR` to `never`. `StreamNdjson<any>`
+// also matches item schemas that are only a `Schema.Constraint` (`disableCodecs`)
+type PayloadServicesConstraint<Payload> =
+  [Extract<Payload, HttpApiSchema.StreamUint8Array | HttpApiSchema.StreamNdjson<any>>] extends [never] ? never : unknown
+
 /**
  * Helper types used to describe generated HTTP API clients, including endpoint
  * methods, response modes, and grouped client shapes.
@@ -228,7 +236,10 @@ export declare namespace Client {
     Endpoint extends HttpApiEndpoint.ConstraintRequest,
     E,
     R
-  > = <Mode extends ResponseMode = "decoded-only", PayloadR = never>(
+  > = <
+    Mode extends ResponseMode = "decoded-only",
+    PayloadR extends PayloadServicesConstraint<Endpoint["~Payload"]> = never
+  >(
     request: Simplify<
       HttpApiEndpoint.ClientRequest<
         Endpoint["~Params"],
@@ -239,7 +250,7 @@ export declare namespace Client {
         PayloadR
       >
     >
-  ) => MethodReturn<Endpoint, E, R, Mode, PayloadR>
+  ) => MethodReturn<Endpoint, E, R, Mode, NoInfer<PayloadR>>
 
   /**
    * Extracts client methods for endpoints in top-level groups so they can be exposed
@@ -387,71 +398,11 @@ export const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Con
         options.onGroup?.(onGroupOptions)
       },
       onEndpoint(onEndpointOptions) {
-        const { group, endpoint, errors, successes, mergedAnnotations } = onEndpointOptions
+        const { group, endpoint, mergedAnnotations } = onEndpointOptions
         const parseOptions = HttpApi.getSlotParseOptions(mergedAnnotations)
         const makeUrl = compilePath(endpoint.path, endpoint.params)
-        const decodeMap: Record<number | "orElse", ResponseDecoder> = { orElse: statusOrElse }
-        const errorAlternatives = new Map<number, Array<ResponseAlternative>>()
-        for (const [status, schemas] of errors.entries()) {
-          const grouped = groupSchemasByContentType(schemas)
-          for (const [contentType, schemas] of grouped.entries()) {
-            addResponseAlternative(
-              errorAlternatives,
-              status,
-              contentType,
-              schemasToResponse(schemas, parseOptions.error, parseOptions.headers)
-            )
-          }
-        }
-        for (const [status, alternatives] of errorAlternatives.entries()) {
-          const decode = makeResponseDecoder(alternatives)
-          decodeMap[status] = (response) =>
-            Effect.flatMap(
-              Effect.catchCause(decode(response), (cause) =>
-                Effect.failCause(Cause.combine(
-                  Cause.fail(
-                    new HttpClientError.HttpClientError({
-                      reason: new HttpClientError.StatusCodeError({
-                        request: response.request,
-                        response
-                      })
-                    })
-                  ),
-                  cause
-                ))),
-              Effect.fail
-            )
-        }
-
-        const successAlternatives = new Map<number, Array<ResponseAlternative>>()
-        for (const [status, schemas] of successes.entries()) {
-          const grouped = groupSchemasByContentType(schemas)
-          for (const [contentType, schemas] of grouped.entries()) {
-            addResponseAlternative(
-              successAlternatives,
-              status,
-              contentType,
-              schemasToResponse(schemas, parseOptions.success, parseOptions.headers)
-            )
-          }
-        }
-        for (const streamSuccess of getStreamSuccessSchemas(endpoint)) {
-          const streamSchema = isWithHeadersStreamSuccess(streamSuccess) ? streamSuccess.schema : streamSuccess
-          addResponseAlternative(
-            successAlternatives,
-            HttpApiSchema.getStatusSuccessSchema(streamSuccess),
-            streamSchema.contentType,
-            streamToResponse(streamSuccess, parseOptions.success, parseOptions.headers)
-          )
-        }
-        for (const [status, alternatives] of successAlternatives.entries()) {
-          decodeMap[status] = makeResponseDecoder(alternatives)
-        }
         const upgrade = getUpgradeSuccessSchema(endpoint)
-        if (upgrade !== undefined) {
-          decodeMap[101] = (response) =>
-            Effect.map(response.upgrade, (socket): Upgraded => ({ headers: response.headers, socket }))
-        }
+        const decodeEndpointResponse = makeEndpointDecoder(onEndpointOptions)
 
         const encodeParams = UndefinedOr.map(
           endpoint.params,
@@ -570,7 +521,7 @@ export const makeClient = <ApiId extends string, Groups extends HttpApiGroup.Con
             return response
           }
 
-          const decoded = (decodeMap[response.status] ?? decodeMap.orElse)(response, request?.sseOptions)
+          const decoded = decodeEndpointResponse(response, request?.sseOptions)
           const value = yield* (options.transformResponse === undefined
             ? decoded
             : options.transformResponse(decoded))
@@ -748,6 +699,111 @@ export const endpoint = <
   }).pipe(Effect.map(() => client)) as any
 }
 
+type DecodeResponse<
+  Groups extends HttpApiGroup.Constraint,
+  GroupIdentifier extends HttpApiGroup.Identifier<Groups>,
+  EndpointIdentifier extends HttpApiGroup.EndpointsWithIdentifier<Groups, GroupIdentifier>["identifier"],
+  Endpoint extends HttpApiEndpoint.ConstraintRequest = Extract<
+    HttpApiEndpoint.WithIdentifier<HttpApiGroup.EndpointsWithIdentifier<Groups, GroupIdentifier>, EndpointIdentifier>,
+    HttpApiEndpoint.ConstraintRequest
+  >
+> = (
+  response: HttpClientResponse.HttpClientResponse,
+  options?: {
+    readonly sseOptions?: Sse.DecodeOptions | undefined
+  }
+) => Effect.Effect<
+  SuccessType<Endpoint["~Success"]>,
+  HttpApiEndpoint.Errors<Endpoint> | HttpClientError.HttpClientError | Schema.SchemaError,
+  SuccessDecodingServices<Endpoint["~Success"]> | HttpApiEndpoint.ErrorServicesDecode<Endpoint>
+>
+
+/**
+ * Builds a decoder for raw responses of one endpoint in one API group, using
+ * the same success and error decoding as a generated client method in
+ * `"decoded-only"` mode.
+ *
+ * **When to use**
+ *
+ * Use with `responseMode: "response-only"` when the response head and body
+ * arrive at different times, such as long polling, and the body should be
+ * decoded later.
+ *
+ * **Details**
+ *
+ * The response does not need to come from a generated client. Declared error
+ * responses fail with the decoded error, and undeclared statuses fail with an
+ * `HttpClientError` whose reason is a `DecodeError`. Parse options are resolved
+ * from the API, group and endpoint annotations. The body is only read when the
+ * returned effect runs, so it must run inside the scope that owns the response.
+ * Middleware and `transformResponse` are not applied.
+ *
+ * Building the decoder walks the API declaration, so build it once per
+ * endpoint and reuse it.
+ *
+ * **Example** (Decoding a response body after the head arrives)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Schema } from "effect"
+ * import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/http-api"
+ *
+ * const Api = HttpApi.make("Api").add(
+ *   HttpApiGroup.make("containers").add(
+ *     HttpApiEndpoint.post("wait", "/containers/:id/wait", {
+ *       params: { id: Schema.String },
+ *       success: Schema.Struct({ StatusCode: Schema.Number })
+ *     })
+ *   )
+ * )
+ *
+ * const decodeWait = HttpApiClient.decodeResponse(Api, {
+ *   group: "containers",
+ *   endpoint: "wait"
+ * })
+ *
+ * const program = Effect.gen(function*() {
+ *   const client = yield* HttpApiClient.make(Api)
+ *   // Succeeds as soon as the response head arrives
+ *   const response = yield* client.containers.wait({
+ *     params: { id: "my-container" },
+ *     responseMode: "response-only"
+ *   })
+ *   // Waits for the body, then decodes it with the endpoint schemas
+ *   return yield* decodeWait(response)
+ * })
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.7
+ */
+export const decodeResponse = <
+  ApiId extends string,
+  Groups extends HttpApiGroup.Constraint,
+  const GroupIdentifier extends HttpApiGroup.Identifier<Groups>,
+  const EndpointIdentifier extends HttpApiGroup.EndpointsWithIdentifier<Groups, GroupIdentifier>["identifier"]
+>(
+  api: HttpApi.HttpApi<ApiId, Groups>,
+  options: {
+    readonly group: GroupIdentifier
+    readonly endpoint: EndpointIdentifier
+  }
+): DecodeResponse<Groups, GroupIdentifier, EndpointIdentifier> => {
+  let decode: ResponseDecoder | undefined
+  HttpApi.reflect(api, {
+    predicate: ({ endpoint, group }) => group.identifier === options.group && endpoint.identifier === options.endpoint,
+    onGroup() {},
+    onEndpoint(endpointOptions) {
+      decode = makeEndpointDecoder(endpointOptions)
+    }
+  })
+  return ((response, decodeOptions) => decode!(response, decodeOptions?.sseOptions)) as DecodeResponse<
+    Groups,
+    GroupIdentifier,
+    EndpointIdentifier
+  >
+}
+
 /**
  * Creates a type-safe URL builder that mirrors `HttpApiClient.make`.
  *
@@ -845,6 +901,10 @@ const compilePath = (path: string, schema: Schema.Top | undefined) => {
   return (params: Record<string, string | undefined>) =>
     HttpApiPath.replaceParams(path, paramNames, (key, optional) => {
       const value = params[key]
+      if (value === "." || value === "..") {
+        // dot segments survive encoding and would be resolved by URL normalization
+        throw new Error(`Invalid path parameter: ${key}`)
+      }
       if (value !== undefined) return encodeURIComponent(value)
       if (optional) return undefined
       throw new Error(`Missing path parameter: ${key}`)
@@ -907,6 +967,91 @@ function toCodecArrayBufferWithHeaders(
   ))
 }
 
+const makeEndpointDecoder = (options: {
+  readonly endpoint: HttpApiEndpoint.Top
+  readonly mergedAnnotations: Context.Context<never>
+  readonly successes: ReadonlyMap<number, readonly [Schema.Top, ...Array<Schema.Top>]>
+  readonly errors: ReadonlyMap<number, readonly [Schema.Top, ...Array<Schema.Top>]>
+}): ResponseDecoder => {
+  const { endpoint, errors, successes, mergedAnnotations } = options
+  const parseOptions = HttpApi.getSlotParseOptions(mergedAnnotations)
+  const decodeMap: Record<number | "orElse", ResponseDecoder> = { orElse: statusOrElse }
+  const errorAlternatives = new Map<number, Array<ResponseAlternative>>()
+  for (const [status, schemas] of errors.entries()) {
+    const grouped = groupSchemasByContentType(schemas)
+    for (const [contentType, schemas] of grouped.entries()) {
+      addResponseAlternative(
+        errorAlternatives,
+        status,
+        contentType,
+        schemasToResponse(schemas, parseOptions.error, parseOptions.headers)
+      )
+    }
+  }
+  for (const [status, alternatives] of errorAlternatives.entries()) {
+    const decode = makeResponseDecoder(alternatives)
+    decodeMap[status] = (response) =>
+      Effect.flatMap(
+        Effect.catchCause(decode(response), (cause) =>
+          Effect.failCause(Cause.combine(
+            Cause.fail(
+              new HttpClientError.HttpClientError({
+                reason: new HttpClientError.StatusCodeError({
+                  request: response.request,
+                  response
+                })
+              })
+            ),
+            cause
+          ))),
+        Effect.fail
+      )
+  }
+
+  const successAlternatives = new Map<number, Array<ResponseAlternative>>()
+  for (const [status, schemas] of successes.entries()) {
+    const grouped = groupSchemasByContentType(schemas)
+    for (const [contentType, schemas] of grouped.entries()) {
+      addResponseAlternative(
+        successAlternatives,
+        status,
+        contentType,
+        schemasToResponse(schemas, parseOptions.success, parseOptions.headers)
+      )
+    }
+  }
+  for (const streamSuccess of getStreamSuccessSchemas(endpoint)) {
+    const streamSchema = isWithHeadersStreamSuccess(streamSuccess) ? streamSuccess.schema : streamSuccess
+    const status = HttpApiSchema.getStatusSuccessSchema(streamSuccess)
+    const decode = streamToResponse(streamSuccess, parseOptions.success, parseOptions.headers)
+    for (const contentType of streamSchema.contentTypes) {
+      addResponseAlternative(successAlternatives, status, contentType, decode)
+    }
+  }
+  for (const [status, alternatives] of successAlternatives.entries()) {
+    decodeMap[status] = makeResponseDecoder(alternatives)
+  }
+  const upgrade = getUpgradeSuccessSchema(endpoint)
+  if (upgrade !== undefined) {
+    const decodeHeaders = upgrade.headers === undefined
+      ? Effect.succeed
+      : Schema.decodeUnknownEffect(upgrade.headers, parseOptions.headers)
+    decodeMap[101] = (response) =>
+      // the cleanup must be in place before an interruption can be observed
+      Effect.uninterruptibleMask((restore) =>
+        Effect.flatMap(response.upgrade, (socket) =>
+          restore(decodeHeaders(response.headers)).pipe(
+            Effect.map((headers): Upgraded<unknown> => ({ headers, socket })),
+            // nothing takes the connection on failure, so close it: releasing
+            // the reader's scope closes the connection
+            Effect.onError(() => Effect.ignore(Effect.scoped(socket.reader)))
+          ))
+      )
+  }
+
+  return (response, sseOptions) => (decodeMap[response.status] ?? decodeMap.orElse)(response, sseOptions)
+}
+
 type ResponseDecoder = (
   response: HttpClientResponse.HttpClientResponse,
   sseOptions?: Sse.DecodeOptions
@@ -934,7 +1079,7 @@ function addResponseAlternative(
 
 function makeResponseDecoder(alternatives: ReadonlyArray<ResponseAlternative>): ResponseDecoder {
   const first = alternatives[0]
-  if (alternatives.length === 1 && first !== undefined) {
+  if (first !== undefined && alternatives.every((alternative) => alternative.decode === first.decode)) {
     return first.decode
   }
   return (response, sseOptions) => {
@@ -1241,7 +1386,8 @@ const statusOrElse = (response: HttpClientResponse.HttpClientResponse) =>
     new HttpClientError.HttpClientError({
       reason: new HttpClientError.DecodeError({
         request: response.request,
-        response
+        response,
+        description: "undeclared status code"
       })
     })
   )