effect 4.0.5 → 4.0.6

package/src/http-api/HttpApiSchema.ts

@@ -10,6 +10,7 @@
  * @stability unstable
  * @since 4.0.0
  */
+import * as ByteSize from "../ByteSize.ts"
 import * as Sse from "../encoding/Sse.ts"
 import { constVoid, type LazyArg } from "../Function.ts"
 import { hasBody, type HttpMethod } from "../http/HttpMethod.ts"
@@ -19,6 +20,7 @@ import * as Predicate from "../Predicate.ts"
 import * as Schema from "../Schema.ts"
 import * as SchemaAST from "../SchemaAST.ts"
 import * as SchemaTransformation from "../SchemaTransformation.ts"
+import * as Socket from "../socket/Socket.ts"
 import * as Stream from "../Stream.ts"
 
 declare module "../Schema.ts" {
@@ -120,8 +122,12 @@ export type StatusLiteral = HttpStatus.Literal
  *
  * **Details**
  *
- * This is equivalent to calling `.annotate({ httpApiStatus: code })` on the
- * schema. You can pass either a numeric status code (for example, `201`) or a
+ * The status is stored with `.annotateKey({ httpApiStatus: code })`, so a named
+ * schema reused with different statuses still emits a single OpenAPI component.
+ * If the schema has checks or already has an `httpApiStatus` annotation, it is
+ * stored with `.annotate({ httpApiStatus: code })` instead. A later
+ * `.annotate({ httpApiStatus })` takes precedence, and a later check drops the
+ * status. You can pass either a numeric status code (for example, `201`) or a
  * common literal name (for example, `"Created"`).
  *
  * @stability unstable
@@ -142,7 +148,10 @@ export function status(code: StatusLiteral): {
  */
 export function status(code: number | StatusLiteral) {
   const statusCode = typeof code === "string" ? HttpStatus.fromLiteral(code) : code
-  return <S extends Schema.Top>(self: S): S["Rebuild"] => self.annotate({ httpApiStatus: statusCode })
+  return <S extends Schema.Top>(self: S): S["Rebuild"] =>
+    self.ast.checks !== undefined || hasStatusAnnotation(self.ast)
+      ? self.annotate({ httpApiStatus: statusCode })
+      : self.annotateKey({ httpApiStatus: statusCode })
 }
 
 /**
@@ -251,7 +260,7 @@ export function asNoContent<S extends Schema.Constraint>(options: {
   }
 }
 
-type StreamMode = "sse" | "uint8array"
+type StreamMode = "sse" | "uint8array" | "ndjson"
 
 /**
  * Mode describing whether an SSE stream emits full events or raw data values.
@@ -282,6 +291,9 @@ export type StreamSseMode = "events" | "data"
  * application event. Endpoint construction rejects event schemas that declare
  * the reserved name statically.
  *
+ * `StreamSse` is response-only. The `payload` slot's type excludes it, and
+ * endpoint construction rejects it.
+ *
  * @stability unstable
  * @category models
  * @since 4.0.0
@@ -339,13 +351,14 @@ export interface SseEventFromData<Data extends Schema.Constraint> extends
 {}
 
 /**
- * Schema for a streaming `Uint8Array` success response.
+ * Schema for a streaming `Uint8Array` body.
  *
  * **Details**
  *
- * This declaration stores the response content type for later endpoint,
- * server, client, and OpenAPI integrations. It is intentionally separate from
- * the buffered `asUint8Array` response encoding.
+ * It works as a success response or as a request payload. It is intentionally
+ * separate from the buffered `asUint8Array` encoding. As a payload, the handler
+ * receives the body as it is read, and `maxBytes` caps the bytes read. It has
+ * no default and does not fall back to `MaxBodySize`.
  *
  * @stability unstable
  * @category models
@@ -366,22 +379,91 @@ export interface StreamUint8Array extends
   readonly _tag: "StreamUint8Array"
   readonly mode: "uint8array"
   readonly contentType: string
+  readonly maxBytes: ByteSize.ByteSize | undefined
 }
 
 /**
- * Schema for a streaming HTTP API success response.
+ * Schema for a stream of newline-delimited JSON elements.
+ *
+ * **Details**
+ *
+ * Each element is encoded as one line of JSON followed by `\n`, including the
+ * last. When decoding, `\n`, `\r\n` and a bare `\r` end a line, empty lines are
+ * skipped, a leading BOM is stripped and invalid UTF-8 fails. The first
+ * malformed line or element that fails to decode ends the stream, after every
+ * element before it has been delivered. A missing final newline is accepted if
+ * the last line parses.
+ *
+ * `maxElementBytes` caps the UTF-8 bytes of one line, without its terminator.
+ * `maxBytes` caps the whole body and has no default.
+ *
+ * As a request payload, the handler receives the elements as the body is
+ * read. Malformed lines and elements that fail to decode are an
+ * `HttpApiSchemaError`, and limit breaches are an `HttpApiPayloadTooLarge`.
+ *
+ * **Gotchas**
+ *
+ * There is no `error` schema. A failure mid-stream aborts the connection, so
+ * the reader sees a body read error, never a clean end. Typed failures
+ * mid-stream are a {@link StreamSse} feature. A body cut cleanly at a line
+ * boundary can't be told apart from a complete one.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface StreamNdjson<S extends Schema.Constraint> extends
+  Schema.BottomLazy<
+    SchemaAST.Declaration,
+    StreamNdjson<S>
+  >
+{
+  readonly "Type": Stream.Stream<S["Type"], unknown, never>
+  readonly "Encoded": Stream.Stream<S["Type"], unknown, never>
+  readonly "DecodingServices": S["DecodingServices"]
+  readonly "EncodingServices": S["EncodingServices"]
+  readonly "Rebuild": StreamNdjson<S>
+  readonly "~type.make.in": Stream.Stream<S["Type"], unknown, never>
+  readonly "~type.make": Stream.Stream<S["Type"], unknown, never>
+  readonly "Iso": Stream.Stream<S["Type"], unknown, never>
+  readonly [StreamSchemaTypeId]: typeof StreamSchemaTypeId
+  readonly _tag: "StreamNdjson"
+  readonly mode: "ndjson"
+  readonly contentType: string
+  readonly schema: S
+  readonly maxBytes: ByteSize.ByteSize | undefined
+  readonly maxElementBytes: ByteSize.ByteSize
+}
+
+/**
+ * Schema for a streaming HTTP API body.
+ *
+ * **Details**
+ *
+ * {@link StreamUint8Array} and {@link StreamNdjson} describe the body in either
+ * direction, with the endpoint slot deciding which. {@link StreamSse} is for
+ * success responses only.
  *
  * @stability unstable
  * @category models
  * @since 4.0.0
  */
-export type StreamSchema = StreamSse<Sse.EventCodec, Schema.Top, unknown> | StreamUint8Array
+export type StreamSchema =
+  | StreamSse<Sse.EventCodec, Schema.Top, unknown>
+  | StreamUint8Array
+  | StreamNdjson<Schema.Top>
 
 const streamSchema = Schema.declare(Stream.isStream)
 
+const defaultMaxElementBytes = ByteSize.mebibytes(1)
+
 /**
  * Creates a Server-Sent Events streaming success response schema.
  *
+ * **Details**
+ *
+ * `StreamSse` is response-only. Endpoint construction rejects it in `payload`.
+ *
  * @stability unstable
  * @category constructors
  * @since 4.0.0
@@ -390,6 +472,10 @@ export const StreamSse: {
   /**
    * Creates a Server-Sent Events streaming success response schema.
    *
+   * **Details**
+   *
+   * `StreamSse` is response-only. Endpoint construction rejects it in `payload`.
+   *
    * @stability unstable
    * @category constructors
    * @since 4.0.0
@@ -404,6 +490,10 @@ export const StreamSse: {
   /**
    * Creates a Server-Sent Events streaming success response schema.
    *
+   * **Details**
+   *
+   * `StreamSse` is response-only. Endpoint construction rejects it in `payload`.
+   *
    * @stability unstable
    * @category constructors
    * @since 4.0.0
@@ -440,7 +530,12 @@ export const StreamSse: {
 }
 
 /**
- * Creates a streaming `Uint8Array` success response schema.
+ * Creates a streaming `Uint8Array` body schema.
+ *
+ * **Details**
+ *
+ * `contentType` defaults to `application/octet-stream`. `maxBytes` only applies
+ * to request payloads and has no default.
  *
  * @stability unstable
  * @category constructors
@@ -448,12 +543,64 @@ export const StreamSse: {
  */
 export const StreamUint8Array = (options?: {
   readonly contentType?: string | undefined
+  readonly maxBytes?: ByteSize.Input | undefined
 }): StreamUint8Array =>
   Schema.make<StreamUint8Array>(streamSchema.ast, {
     [StreamSchemaTypeId]: StreamSchemaTypeId,
     _tag: "StreamUint8Array",
     mode: "uint8array",
-    contentType: options?.contentType ?? defaultStreamContentType("uint8array")
+    contentType: options?.contentType ?? defaultStreamContentType("uint8array"),
+    maxBytes: options?.maxBytes === undefined ? undefined : ByteSize.fromInputUnsafe(options.maxBytes)
+  })
+
+/**
+ * Creates a schema for a stream of newline-delimited JSON elements.
+ *
+ * **Details**
+ *
+ * `contentType` defaults to `application/x-ndjson` and `maxElementBytes` to 1
+ * MiB. `maxBytes` has no default.
+ *
+ * **Example** (Declaring an NDJSON request payload)
+ *
+ * ```ts import.meta.vitest
+ * import { Schema } from "effect"
+ * import { HttpApiEndpoint, HttpApiSchema } from "effect/http-api"
+ *
+ * const Event = Schema.Struct({ id: Schema.Number })
+ * const payload = HttpApiSchema.StreamNdjson({ schema: Event, maxBytes: "100 MiB" })
+ *
+ * // The handler receives a Stream of Events
+ * const importEvents = HttpApiEndpoint.post("importEvents", "/events", {
+ *   payload,
+ *   success: Schema.Number
+ * })
+ *
+ * importEvents.path // => "/events"
+ * payload.contentType // => "application/x-ndjson"
+ * payload.maxElementBytes // => 1048576n
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const StreamNdjson = <S extends Schema.Constraint>(options: {
+  readonly schema: S
+  readonly contentType?: string | undefined
+  readonly maxBytes?: ByteSize.Input | undefined
+  readonly maxElementBytes?: ByteSize.Input | undefined
+}): StreamNdjson<S> =>
+  Schema.make<StreamNdjson<S>>(streamSchema.ast, {
+    [StreamSchemaTypeId]: StreamSchemaTypeId,
+    _tag: "StreamNdjson",
+    mode: "ndjson",
+    contentType: options.contentType ?? defaultStreamContentType("ndjson"),
+    schema: options.schema,
+    maxBytes: options.maxBytes === undefined ? undefined : ByteSize.fromInputUnsafe(options.maxBytes),
+    maxElementBytes: options.maxElementBytes === undefined
+      ? defaultMaxElementBytes
+      : ByteSize.fromInputUnsafe(options.maxElementBytes)
   })
 
 /**
@@ -474,12 +621,109 @@ export const isStreamSse = (u: unknown): u is StreamSse<Sse.EventCodec, Schema.T
 export const isStreamUint8Array = (u: unknown): u is StreamUint8Array =>
   isStreamSchema(u) && u._tag === "StreamUint8Array"
 
+/**
+ * @internal
+ */
+export const isStreamNdjson = (u: unknown): u is StreamNdjson<Schema.Top> =>
+  isStreamSchema(u) && u._tag === "StreamNdjson"
+
+const UpgradeTypeId = "~effect/http-api/HttpApiSchema/Upgrade"
+
+/**
+ * Schema for a success response that switches the connection to another
+ * protocol with an HTTP/1.1 upgrade.
+ *
+ * **Details**
+ *
+ * Created with {@link Upgrade}. The response is `101 Switching Protocols`, and
+ * the connection then carries raw bytes in both directions as a `Socket`.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface Upgrade extends
+  Schema.Bottom<
+    Socket.Socket,
+    Socket.Socket,
+    never,
+    never,
+    SchemaAST.Declaration,
+    Upgrade
+  >
+{
+  readonly "Rebuild": Upgrade
+  readonly [UpgradeTypeId]: typeof UpgradeTypeId
+  readonly protocol: string
+}
+
+const upgradeSchema = Schema.declare(Socket.isSocket).pipe(status(101))
+
+/**
+ * Declares an endpoint success that upgrades the connection to `protocol`,
+ * such as Docker's `tcp` for container attach.
+ *
+ * **When to use**
+ *
+ * Use as the only success schema of an endpoint that hands over its
+ * connection as a raw byte stream after `101 Switching Protocols`. For
+ * WebSocket, upgrade the request with `HttpServerRequest.upgrade` and
+ * connect with `Socket.makeWebSocket` instead.
+ *
+ * **Details**
+ *
+ * The handler receives the connection as `socket`. The `101` response is
+ * sent when the handler acquires the socket's reader, so a handler can still
+ * fail with a declared error before then. Requests that do not ask for
+ * `protocol` get `426 Upgrade Required`.
+ *
+ * The client sends `Connection: Upgrade` and `Upgrade: protocol`, and returns
+ * the response headers with the connection. Other responses are decoded as
+ * the endpoint's errors.
+ *
+ * The endpoint cannot declare a payload or other success schemas.
+ *
+ * **Example** (Declaring an attach endpoint)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ * import { HttpApiEndpoint, HttpApiSchema } from "effect/http-api"
+ *
+ * const attach = HttpApiEndpoint.post("attach", "/containers/:id/attach", {
+ *   params: { id: Schema.String },
+ *   success: HttpApiSchema.Upgrade({ protocol: "tcp" })
+ * })
+ * ```
+ *
+ * @stability unstable
+ * @category constructors
+ * @since 4.0.6
+ */
+export const Upgrade = (options: {
+  readonly protocol: string
+}): Upgrade => {
+  if (options.protocol.toLowerCase() === "websocket") {
+    throw new Error("Upgrade does not support WebSocket")
+  }
+  return Schema.make<Upgrade>(upgradeSchema.ast, {
+    [UpgradeTypeId]: UpgradeTypeId,
+    protocol: options.protocol
+  })
+}
+
+/**
+ * @internal
+ */
+export const isUpgrade = (u: unknown): u is Upgrade => Schema.isSchema(u) && Predicate.hasProperty(u, UpgradeTypeId)
+
 function defaultStreamContentType(mode: StreamMode): string {
   switch (mode) {
     case "sse":
       return "text/event-stream"
     case "uint8array":
       return "application/octet-stream"
+    case "ndjson":
+      return "application/x-ndjson"
   }
 }
 
@@ -645,6 +889,9 @@ export function WithHeaders(
   if (isWithHeaders(schema)) {
     throw new Error("WithHeaders schemas cannot be nested")
   }
+  if (isUpgrade(schema)) {
+    throw new Error("WithHeaders cannot wrap an upgrade")
+  }
   return Schema.make<WithHeaders<Schema.Top, Schema.Top>>(withHeadersValueSchema.ast, {
     [WithHeadersTypeId]: WithHeadersTypeId,
     schema,
@@ -809,6 +1056,9 @@ export function encodeToWithHeaders<
 }) {
   return (self: S): encodeToWithHeaders<S, Body, Headers> => {
     const body = options.body
+    if (isUpgrade(body)) {
+      throw new Error("encodeToWithHeaders cannot wrap an upgrade")
+    }
     const headers = Schema.Struct(options.headers)
     const status = resolveHttpApiStatus(body.ast)
     const encoding = resolveHttpApiEncoding(body.ast)
@@ -1049,7 +1299,19 @@ const resolveHttpApiEncoding = SchemaAST.resolveAt<Encoding>("~httpApiEncoding")
  */
 export const getWithHeadersAnnotation = SchemaAST.resolveAt<WithHeadersAnnotation>("~httpApiWithHeaders")
 
-const resolveHttpApiStatus = SchemaAST.resolveAt<number>("httpApiStatus")
+const resolveHttpApiStatusAnnotation = SchemaAST.resolveAt<number>("httpApiStatus")
+
+function hasStatusAnnotation(ast: SchemaAST.AST): boolean {
+  const annotations = SchemaAST.resolve(ast)
+  return annotations !== undefined && "httpApiStatus" in annotations
+}
+
+// An `httpApiStatus` annotation, even `undefined`, overrides the key context set by
+// `status`, which a later check drops, matching annotations
+function resolveHttpApiStatus(ast: SchemaAST.AST): number | undefined {
+  if (hasStatusAnnotation(ast)) return resolveHttpApiStatusAnnotation(ast)
+  return ast.checks === undefined ? ast.context?.annotations?.httpApiStatus : undefined
+}
 
 const defaultJsonEncoding: Encoding = {
   _tag: "Json",

package/src/http-api/HttpApiSwagger.ts

@@ -17,11 +17,12 @@ import type * as Layer from "../Layer.ts"
 import type * as HttpApi from "./HttpApi.ts"
 import type * as HttpApiGroup from "./HttpApiGroup.ts"
 import * as Html from "./internal/html.ts"
-import * as internal from "./internal/httpApiSwagger.ts"
 import * as OpenApi from "./OpenApi.ts"
 
 const makeHandler = <Id extends string, Groups extends HttpApiGroup.Constraint>(options: {
   readonly api: HttpApi.HttpApi<Id, Groups>
+  readonly javascript: string
+  readonly css: string
 }) => {
   const makeResponse = Function.memoize((api: HttpApi.HttpApi<Id, Groups>) => {
     const spec = OpenApi.fromApi(api)
@@ -31,7 +32,7 @@ const makeHandler = <Id extends string, Groups extends HttpApiGroup.Constraint>(
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
   <title>${Html.escape(spec.info.title)} Documentation</title>
-  <style>${internal.css}</style>
+  <style>${options.css}</style>
 </head>
 <body>
   <div id="swagger-ui"></div>
@@ -39,7 +40,7 @@ const makeHandler = <Id extends string, Groups extends HttpApiGroup.Constraint>(
     ${Html.escapeJson(spec)}
   </script>
   <script>
-    ${internal.javascript}
+    ${options.javascript}
     window.onload = () => {
       window.ui = SwaggerUIBundle({
         spec: JSON.parse(document.getElementById("swagger-spec").textContent),
@@ -57,6 +58,11 @@ const makeHandler = <Id extends string, Groups extends HttpApiGroup.Constraint>(
  * Mounts Swagger UI for an `HttpApi` at the configured path, defaulting to
  * `/docs`, using the OpenAPI specification generated from the API.
  *
+ * **Details**
+ *
+ * The bundled Swagger UI assets are loaded when the layer is built, not when
+ * this module is imported.
+ *
  * @stability unstable
  * @category layers
  * @since 4.0.0
@@ -68,6 +74,7 @@ export const layer = <Id extends string, Groups extends HttpApiGroup.Constraint>
   }
 ): Layer.Layer<never, never, HttpRouter.HttpRouter> =>
   HttpRouter.use(Effect.fnUntraced(function*(router) {
-    const handler = makeHandler({ api })
+    const { css, javascript } = yield* Effect.promise(() => import("./internal/httpApiSwagger.ts"))
+    const handler = makeHandler({ api, javascript, css })
     yield* router.add("GET", options?.path ?? "/docs", handler)
   }))

package/src/http-api/HttpApiTest.ts

@@ -11,17 +11,19 @@
  */
 import * as Context from "../Context.ts"
 import * as Effect from "../Effect.ts"
+import * as Exit from "../Exit.ts"
 import type { FileSystem } from "../FileSystem.ts"
 import type { Generator } from "../http/Etag.ts"
 import * as HttpClient from "../http/HttpClient.ts"
+import * as HttpEffect from "../http/HttpEffect.ts"
 import type { HttpPlatform } from "../http/HttpPlatform.ts"
 import * as HttpRouter from "../http/HttpRouter.ts"
 import * as HttpServerRequest from "../http/HttpServerRequest.ts"
 import * as HttpServerResponse from "../http/HttpServerResponse.ts"
-import * as preResponseHandler from "../http/internal/preResponseHandler.ts"
+import { CurrentRequestState, RequestState } from "../http/internal/requestState.ts"
 import * as Layer from "../Layer.ts"
 import type { Path } from "../Path.ts"
-import type { Scope } from "../Scope.ts"
+import * as Scope from "../Scope.ts"
 import type * as HttpApi from "./HttpApi.ts"
 import type { HandlerRuntime } from "./HttpApiBuilder.ts"
 import * as HttpApiBuilder from "./HttpApiBuilder.ts"
@@ -37,6 +39,17 @@ import type * as HttpApiGroup from "./HttpApiGroup.ts"
  * Handlers for the selected groups are taken from the environment; unselected
  * groups are wired with placeholder handlers that fail if called.
  *
+ * Each call runs its handler in a request scope that is a child of the
+ * `Scope` the client was created in. A streaming response keeps that scope
+ * open until its body ends, and a body that is never read is closed with the
+ * owning `Scope`.
+ *
+ * A `Stream` payload reaches the handler unbuffered: each element is pulled
+ * from the caller's stream as the handler reads it. If the caller's stream
+ * fails, reading the request body fails with it. Client aborts and socket
+ * behavior such as draining unread bodies, closing the connection, or
+ * answering with `499` are not emulated.
+ *
  * @stability unstable
  * @category testing
  * @since 4.0.0
@@ -62,7 +75,7 @@ export const groups = Effect.fnUntraced(function*<
   | Generator
   | HttpPlatform
   | Path
-  | Scope
+  | Scope.Scope
 > {
   let context = yield* Effect.context<HttpApiGroup.ToService<ApiId, SelectedGroups>>()
 
@@ -100,18 +113,29 @@ export const groups = Effect.fnUntraced(function*<
     Layer.provide(Layer.succeedContext(context))
   ) as any
   const handler = yield* HttpRouter.toHttpEffect(layer)
-  const httpClient = HttpClient.make(Effect.fnUntraced(function*(request) {
+  const scope = yield* Effect.scope
+  const httpClient = HttpClient.make((request) => {
+    const requestScope = Scope.forkUnsafe(scope)
     const serverRequest = HttpServerRequest.fromClientRequest(request)
-    const response = yield* handler.pipe(
+    const state = new RequestState()
+    let transferred = false
+    return handler.pipe(
       Effect.flatMap((response) => {
-        const preResponse = preResponseHandler.requestPreResponseHandlers.get(serverRequest.source)
+        const preResponse = state.preResponseHandler
         return preResponse === undefined ? Effect.succeed(response) : preResponse(serverRequest, response)
       }),
+      Effect.map((response) => {
+        const transfer = HttpEffect.scopeTransferToStream(response)
+        transferred = transfer !== response
+        return HttpServerResponse.toClientResponse(transfer, { request })
+      }),
       Effect.provideService(HttpServerRequest.HttpServerRequest, serverRequest),
-      Effect.orDie
+      Effect.provideService(CurrentRequestState, state),
+      Effect.provideService(Scope.Scope, requestScope),
+      Effect.orDie,
+      Effect.onExit((exit) => transferred && Exit.isSuccess(exit) ? Effect.void : Scope.close(requestScope, exit))
     )
-    return HttpServerResponse.toClientResponse(response, { request })
-  }, Effect.scoped))
+  })
 
   return yield* HttpApiClient.makeWith(api, {
     httpClient,