effect 4.0.6 → 4.1.0

package/src/http-api/HttpApiClient.ts

@@ -102,10 +102,28 @@ 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
 
+/**
+ * Runtime brand key used to mark `Upgraded` values.
+ *
+ * @stability unstable
+ * @category type IDs
+ * @since 4.1.0
+ */
+export const UpgradedTypeId = "~effect/http-api/HttpApiClient/Upgraded"
+
+/**
+ * Type-level brand identifier used by `Upgraded` values.
+ *
+ * @stability unstable
+ * @category type IDs
+ * @since 4.1.0
+ */
+export type UpgradedTypeId = typeof UpgradedTypeId
+
 /**
  * The value a client method returns for an endpoint declared with
  * `HttpApiSchema.Upgrade`: the headers of the `101 Switching Protocols`
@@ -113,18 +131,67 @@ 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.
+ *
+ * When the endpoint also declares ordinary success responses, the method
+ * returns either an `Upgraded` value or the decoded ordinary success. Use
+ * {@link isUpgraded} to tell them apart.
  *
  * @stability unstable
  * @category models
  * @since 4.0.6
  */
-export interface Upgraded {
-  readonly headers: Headers.Headers
+export interface Upgraded<Headers = Headers.Headers> {
+  readonly [UpgradedTypeId]: UpgradedTypeId
+  readonly headers: Headers
   readonly socket: Socket.Socket
 }
 
+/**
+ * Returns `true` when a client method result is an upgraded connection.
+ *
+ * **Details**
+ *
+ * An endpoint may declare `HttpApiSchema.Upgrade` alongside ordinary success
+ * responses, because a server can decline an upgrade (RFC 9110 §7.8). The
+ * client method then returns either an `Upgraded` value or the decoded
+ * ordinary success, depending on the response status. This predicate narrows
+ * that union.
+ *
+ * **Example** (Handling a declined upgrade)
+ *
+ * ```ts
+ * import { Effect, Schema } from "effect"
+ * import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup, HttpApiSchema } from "effect/http-api"
+ *
+ * const Api = HttpApi.make("docker").add(
+ *   HttpApiGroup.make("exec").add(
+ *     HttpApiEndpoint.post("start", "/exec/:id/start", {
+ *       params: { id: Schema.String },
+ *       payload: Schema.Struct({ Detach: Schema.Boolean }),
+ *       success: [HttpApiSchema.Upgrade({ protocol: "tcp" }), HttpApiSchema.Empty(200)]
+ *     })
+ *   )
+ * )
+ *
+ * const program = Effect.gen(function*() {
+ *   const client = yield* HttpApiClient.make(Api)
+ *   const result = yield* client.exec.start({ params: { id: "abc" }, payload: { Detach: false } })
+ *   if (HttpApiClient.isUpgraded(result)) {
+ *     const writer = yield* result.socket.writer
+ *     yield* writer.write("ls\n")
+ *   }
+ * })
+ * ```
+ *
+ * @stability unstable
+ * @category guards
+ * @since 4.1.0
+ */
+export const isUpgraded = (u: unknown): u is Upgraded<unknown> => Predicate.hasProperty(u, UpgradedTypeId)
+
 type SuccessDecodingServices<S> = S extends HttpApiSchema.StreamSse<
   infer _Events,
   infer _Error,
@@ -134,9 +201,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 +302,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 +316,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 +464,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 +587,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 +765,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 +967,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 +1033,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> => ({ [UpgradedTypeId]: UpgradedTypeId, 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 +1145,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 +1452,8 @@ const statusOrElse = (response: HttpClientResponse.HttpClientResponse) =>
     new HttpClientError.HttpClientError({
       reason: new HttpClientError.DecodeError({
         request: response.request,
-        response
+        response,
+        description: "undeclared status code"
       })
     })
   )