Comprehensive documentation >> Docs rewrite

README.md

@@ -6,52 +6,178 @@
 
 ZIO HTTP is a scala library for building http apps. It is powered by ZIO and [Netty](https://netty.io/) and aims at being the defacto solution for writing, highly scalable and performant web applications using idiomatic Scala.
 
-[![Development](https://img.shields.io/badge/Project%20Stage-Development-green.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/zio-http/workflows/Continuous%20Integration/badge.svg) [![Sonatype Releases](https://img.shields.io/nexus/r/https/oss.sonatype.org/dev.zio/zio-http_2.13.svg?label=Sonatype%20Release)](https://oss.sonatype.org/content/repositories/releases/dev/zio/zio-http_2.13/) [![Sonatype Snapshots](https://img.shields.io/nexus/s/https/oss.sonatype.org/dev.zio/zio-http_2.13.svg?label=Sonatype%20Snapshot)](https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-http_2.13/) [![javadoc](https://javadoc.io/badge2/dev.zio/zio-http-docs_2.13/javadoc.svg)](https://javadoc.io/doc/dev.zio/zio-http-docs_2.13) [![ZIO Http](https://img.shields.io/github/stars/zio/zio-http?style=social)](https://github.com/zio/zio-http)
+[![Development](https://img.shields.io/badge/Project%20Stage-Development-green.svg)](https://github.com/zio/zio/wiki/Project-Stages) ![CI Badge](https://github.com/zio/zio-http/workflows/Continuous%20Integration/badge.svg) [![Sonatype Snapshots](https://img.shields.io/nexus/s/https/oss.sonatype.org/dev.zio/zio-http_2.13.svg?label=Sonatype%20Snapshot)](https://oss.sonatype.org/content/repositories/snapshots/dev/zio/zio-http_2.13/) [![ZIO Http](https://img.shields.io/github/stars/zio/zio-http?style=social)](https://github.com/zio/zio-http)
 
 ## Installation
 
 Setup via `build.sbt`:
 
 ```scala
-libraryDependencies += "dev.zio" %% "zio-http" % "3.0.0-RC4"
+package example
+
+import zio._
+
+import zio.http._
+
+object RequestStreaming extends ZIOAppDefault {
+
+  val app: HttpApp[Any] = 
+    Routes(
+      Method.GET / "text" -> handler(Response.text("Hello World!"))
+    ).toHttpApp
+
+    // Creating HttpData from the stream
+    // This works for file of any size
+    val data = Body.fromStream(stream)
+
+    Response(body = data)
+  }
+
+  // Run it like any simple app
+  val run: UIO[ExitCode] =
+    Server.serve(app).provide(Server.default).exitCode
+}
 ```
 
-**NOTES ON VERSIONING:**
+ZIO-HTTP provides a core library, `zhttp-http`, which includes the base HTTP implementation and server/client capabilities based on ZIO. Additional functionality like serverless support, templating, and websockets are available through separate add-on modules. ZIO-HTTP applications can be easily integrated into different deployment platforms, such as server-based, serverless, or compiled to native binaries.
+
+The principles of ZIO-HTTP are:
+
+- Application as a Function: HTTP services in ZIO-HTTP are composed of simple functions. The `HttpApp` type represents a function from an `HttpRequest` to a `ZIO` effect that produces an `HttpResponse`.
+- Immutability: Entities in ZIO-HTTP are immutable by default, promoting functional programming principles.
+- Symmetric: The same `HttpApp` interface is used for both defining HTTP services and making HTTP requests. This enables easy testing and integration of services without requiring an HTTP container.
+- Minimal Dependencies: The core `zhttp-http` module has minimal dependencies, and additional add-on modules only include dependencies required for specific functionality.
+- Testability: ZIO-HTTP supports easy in-memory and port-based testing of individual endpoints, applications, websockets/SSE, and complete suites of microservices.
+- Portability: ZIO-HTTP applications are portable across different deployment platforms, making them versatile and adaptable.
+
+By leveraging the power of ZIO and the simplicity of functional programming, ZIO-HTTP provides a robust and flexible toolkit for building scalable and composable HTTP services in Scala.
+
+## Quickstart
+
+Eager to start coding without delay? If you're in a hurry, you can follow the [quickstart](https://github.com/zio/zio-http/tree/main/zio-http-example) guide or explore the [examples repository](https://github.com/zio/zio-http/tree/main/zio-http-example), which demonstrates different use cases and features of ZIO-HTTP.
+
+## Module feature overview
+
+Core:
+
+- Lightweight and performant HTTP handler and message objects
+- Powerful routing system with support for path-based and parameterized routes
+- Typesafe HTTP message construction and deconstruction
+- Extensible filters for common HTTP functionalities such as caching, compression, and request/response logging
+- Support for cookie handling
+- Servlet implementation for integration with Servlet containers
+- Built-in support for launching applications with an embedded server backend
+
+Client:
+
+- Robust and flexible HTTP client with support for synchronous and asynchronous operations
+- Adapters for popular HTTP client libraries such as Apache HttpClient, OkHttp, and Jetty HttpClient
+- Websocket client with blocking and non-blocking modes
+- GraphQL client integration for consuming GraphQL APIs
+
+Server:
+
+- Lightweight server backend spin-up for various platforms including Apache, Jetty, Netty, and SunHttp
+- Support for SSE (Server-Sent Events) and Websocket communication
+- Easy customization of underlying server backend
+- Native-friendly for compilation with GraalVM and Quarkus
+
+Serverless:
+
+- Function-based support for building serverless HTTP and event-driven applications
+- Adapters for AWS Lambda, Google Cloud Functions, Azure Functions, and other serverless platforms
+- Custom AWS Lambda runtime for improved performance and reduced startup time
 
-- Older library versions `1.x` or `2.x` with organization `io.d11` of ZIO Http are derived from Dream11, the organization that donated ZIO Http to the ZIO organization in 2022. 
-- Newer library versions, starting in 2023 and resulting from the ZIO organization (`dev.zio`) started with `0.0.x`, reaching `1.0.0` release candidates in April of 2023
+Contract:
 
-## Getting Started
+- Typesafe HTTP contract definition with support for path parameters, query parameters, headers, and request/response bodies
+- Automatic validation of incoming requests based on contract definition
+- Self-documenting routes with built-in support for OpenAPI (Swagger) descriptions
 
-A simple Http server can be built using a few lines of code.
+Templating:
+
+- Pluggable templating system support for popular template engines such as Dust, Freemarker, Handlebars, and Thymeleaf
+- Caching and hot-reload template support for efficient rendering
+
+Message Formats:
+
+- First-class support for various message formats such as JSON, XML, YAML, and CSV
+- Seamless integration with popular libraries like Jackson, Gson, and Moshi for automatic marshalling and unmarshalling
+
+Resilience:
+
+- Integration with Resilience4J for implementing resilience patterns such as circuit breakers, retries, rate-limiting, and bulkheading
+
+Metrics:
+
+- Support for integrating zio-http applications with Micrometer for monitoring and metrics collection
+
+Security:
+
+- OAuth support for implementing authorization flows with popular providers like Auth0, Google, Facebook, and more
+- Digest authentication support for secure client-server communication
+
+Cloud Native:
+
+- Tooling and utilities for operating zio-http applications in cloud environments such as Kubernetes and CloudFoundry
+- Support for 12-factor configuration, dual-port servers, and health checks
+
+Testing:
+
+- Approval testing extensions for testing zio-http Request and Response messages
+- Chaos testing API for injecting failure modes and evaluating application behavior under different failure conditions
+- Matchers for popular testing frameworks like Hamkrest, Kotest, and Strikt
+
+Service Virtualization:
+
+- Record and replay HTTP contracts to simulate virtualized services using Servirtium Markdown format
+- Includes Servirtium MiTM (Man-in-the-Middle) server for capturing and replaying HTTP interactions
+
+WebDriver:
+
+- Lightweight implementation of Selenium WebDriver for testing zio-http applications
+
+These features provide a comprehensive set of tools and capabilities for building scalable, performant, and secure HTTP applications with zio-http.
+
+## Example
+
+This brief illustration is intended to showcase the ease and capabilities of zio-http. Additionally, refer to the quickstart guide for a minimalistic starting point that demonstrates serving and consuming HTTP services with dynamic routing.
+
+To install, add these dependencies to your `build.sbt`:
 
 ```scala
+package example
+
 import zio._
+import zio.http.HttpAppMiddleware.basicAuth
 import zio.http._
 
-object HelloWorld extends ZIOAppDefault {
+object BasicAuth extends ZIOAppDefault {
 
-  val app: HttpApp[Any] = 
-    Routes(
-      Method.GET / "text" -> handler(Response.text("Hello World!"))
-    ).toHttpApp
+  // Define an HTTP application that requires a JWT claim
+  val user: HttpApp[Any, Nothing] = Http.collect[Request] { case Method.GET -> Root / "user" / name / "greet" =>
+    Response.text(s"Welcome to the ZIO party! ${name}")
+  }
+
+  // Compose all the HttpApps together
+  val app: HttpApp[Any, Nothing] = user @@ basicAuth("admin", "admin")
 
-  override val run =
-    Server.serve(app).provide(Server.default)
+  // Run the application like any simple app
+  val run = Server.serve(app).provide(Server.default)
 }
 ```
 
-## Steps to run an example
+## Explanation of the code above
+
+- The BasicAuth object extends ZIOAppDefault, which is a trait that provides a default implementation for running ZIO applications.
 
-1. Edit the [RunSettings](https://github.com/zio/zio-http/blob/main/project/BuildHelper.scala#L107) - modify `className` to the example you'd like to run.
-2. From sbt shell, run `~example/reStart`. You should see `Server started on port: 8080`.
-3. Send curl request for defined `http Routes`, for eg : `curl -i "http://localhost:8080/text"` for `example.HelloWorld`.
+- The code imports the necessary dependencies from  ZIO and ZIO HTTP.
 
-## Watch Mode
+- The user value represents an HTTP application that requires a JWT claim. It uses the Http.collect combinator to pattern match on GET requests with a specific path pattern (Root / "user" / name / "greet") and responds with a greeting message that includes the extracted name.
 
-You can use the [sbt-revolver] plugin to start the server and run it in watch mode using `~ reStart` command on the SBT console.
+- The app value is created by composing the user HTTP application with the basicAuth middleware. The basicAuth function takes a username and password as arguments and returns a middleware that performs basic authentication. It applies basic authentication with the username "admin" and password "admin" to the user application.
 
-[sbt-revolver]: https://github.com/spray/sbt-revolver
+- Finally, the server is run using the Server.serve method. The app is provided as the HTTP application, and Server.default is provided as the server configuration. The server configuration contains default settings for the server, such as the port to listen on. The run value represents the execution of the server. It starts the ZIO runtime and executes the server, making it ready to receive and respond to HTTP requests.
 
 ## Documentation
 

docs/Reference/json-handling.md

@@ -0,0 +1,96 @@
+---
+id: json-handling
+title: "Json Handling"
+---
+
+**JSON Handling in ZIO HTTP**
+
+ZIO HTTP provides built-in support for handling JSON data in your applications. This allows you to easily parse incoming JSON requests, serialize data into JSON responses, and work with JSON data structures in a type-safe manner. Here's an overview of how JSON handling is typically done in ZIO HTTP.
+
+**Parsing JSON Requests**
+
+To parse incoming JSON requests, you can use the `zio-json` library, which integrates seamlessly with ZIO HTTP. `zio-json` provides a type-safe API for working with JSON data. Here's an example of how you can parse a JSON request body:
+
+```scala
+import zio.http._
+import zio.json._
+import zio._
+
+case class MyRequest(name: String, age: Int)
+
+val httpApp: HttpApp[Any, Throwable] = Http.collectM {
+  case request @ Method.POST -> Root / "api" / "endpoint" =>
+    request
+      .asJsonDecode[MyRequest]
+      .flatMap { myRequest =>
+        // Handle the parsed JSON request
+        // myRequest will be an instance of MyRequest
+        // ...
+        // Return an HTTP response
+        ZIO.succeed(Response.text("Request handled successfully"))
+      }
+}
+```
+
+In this example, we define a case class `MyRequest` that represents the expected structure of the JSON request body. We use the `.asJsonDecode` method to parse the request body into an instance of `MyRequest`. If the parsing is successful, we can access the parsed request and perform further processing.
+
+**Serializing JSON Responses**
+
+To serialize data into JSON responses, you can use the `.asJsonEncode` method provided by the `zio-json` library. Here's an example of how you can serialize a response object into JSON:
+
+```scala
+import zio.http._
+import zio.json._
+import zio._
+
+case class MyResponse(message: String)
+
+val httpApp: HttpApp[Any, Throwable] = Http.collect {
+  case Method.GET -> Root / "api" / "endpoint" =>
+    val myResponse = MyResponse("Hello, World!")
+    Response.jsonString(myResponse.asJson.spaces2)
+}
+```
+
+In this example, we define a case class `MyResponse` that represents the data we want to serialize into JSON. We use the `.asJson` method to convert the response object into a JSON value, and then use `Response.jsonString` to create an HTTP response with the JSON payload.
+
+**Working with JSON Data Structures**
+
+`zio-json` provides a type-safe API for working with JSON data structures. You can use case classes or ADTs (Algebraic Data Types) to represent JSON objects and their fields. By deriving the necessary JSON codecs using annotations or manually defining them, you can ensure type safety during JSON parsing and serialization.
+
+Here's an example of how you can define a case class with nested objects and use it for JSON handling:
+
+```scala
+import zio.http._
+import zio.json._
+import zio._
+
+case class Address(city: String, country: String)
+case class Person(name: String, age: Int, address: Address)
+
+object Person {
+  implicit val addressCodec: JsonCodec[Address] = DeriveJsonCodec.gen[Address]
+  implicit val personCodec: JsonCodec[Person] = DeriveJsonCodec.gen[Person]
+}
+
+val httpApp: HttpApp[Any, Throwable] = Http.collectM {
+  case request @ Method.POST -> Root / "api" / "endpoint" =>
+    request
+      .asJsonDecode[Person]
+      .flatMap { person =>
+        // Handle the parsed JSON request
+        // person will be an instance of Person with nested Address object
+        // ...
+        // Return an HTTP response
+
+
+        ZIO.succeed(Response.text("Request handled successfully"))
+      }
+}
+```
+
+In this example, we define case classes `Address` and `Person` to represent a nested JSON structure. We derive the necessary JSON codecs using `DeriveJsonCodec.gen`. This allows ZIO HTTP to automatically handle the parsing and serialization of these objects.
+
+**Summary**
+
+ZIO HTTP provides seamless integration with `zio-json`, allowing you to easily handle JSON requests and responses in a type-safe manner. By using case classes or ADTs and deriving the necessary JSON codecs, you can ensure proper parsing and serialization of JSON data structures.

docs/Reference/metrics.md

@@ -0,0 +1,70 @@
+---
+id: metrics
+title: "Metrics reference"
+---
+
+### Reference on metrics
+
+1. APIs and Classes:
+   - `zio.metrics.Metric`: Provides APIs for creating and managing metrics.
+     - `Metric.counterInt(name: String): Counter[RuntimeFlags]`: Creates a counter metric of type `Int` with the given name.
+     - `Metric.gauge(name: String): Gauge[Double]`: Creates a gauge metric of type `Double` with the given name.
+     - `Metric.histogram(name: String, boundaries: MetricKeyType.Histogram.Boundaries): Histogram[Double]`: Creates a histogram metric of type `Double` with the given name and boundaries.
+   - `zio.metrics.MetricLabel`: Represents a label associated with a metric.
+
+2. Functions:
+   - `metrics`: A function that adds metrics to a ZIO-HTTP server.
+     - Parameters:
+       - `pathLabelMapper: PartialFunction[Request, String] = Map.empty`: A mapping function to map incoming paths to patterns.
+       - `concurrentRequestsName: String = "http_concurrent_requests_total"`: Name of the concurrent requests metric.
+       - `totalRequestsName: String = "http_requests_total"`: Name of the total requests metric.
+       - `requestDurationName: String = "http_request_duration_seconds"`: Name of the request duration metric.
+       - `requestDurationBoundaries: MetricKeyType.Histogram.Boundaries = Metrics.defaultBoundaries`: Boundaries for the request duration metric.
+       - `extraLabels: Set[MetricLabel] = Set.empty`: A set of extra labels that will be tagged with all metrics.
+     - Returns: An `HttpAppMiddleware` that adds metrics to the server.
+
+3. Usage Example:
+```scala
+import zio.http.{RequestHandlerMiddlewares, _}
+import zio.metrics.Metric.{Counter, Gauge, Histogram}
+import zio.metrics.{Metric, MetricKeyType, MetricLabel}
+
+private[zio] trait Metrics { self: RequestHandlerMiddlewares =>
+  // ...
+
+  def metrics(
+    pathLabelMapper: PartialFunction[Request, String] = Map.empty,
+    concurrentRequestsName: String = "http_concurrent_requests_total",
+    totalRequestsName: String = "http_requests_total",
+    requestDurationName: String = "http_request_duration_seconds",
+    requestDurationBoundaries: MetricKeyType.Histogram.Boundaries = Metrics.defaultBoundaries,
+    extraLabels: Set[MetricLabel] = Set.empty,
+  ): HttpAppMiddleware[Nothing, Any, Nothing, Any] = {
+    // ...
+  }
+
+  // ...
+}
+
+object Metrics {
+  // ...
+}
+```
+
+To use the `metrics` function, you can create an instance of a `Metrics` object and call the `metrics` method, providing the desired parameters. Here's an example:
+
+```scala
+import zio.http.HttpAppMiddleware.metrics
+
+val app: HttpApp[Any, Nothing] = ???
+val metricsMiddleware = new Metrics with RequestHandlerMiddlewares {}
+val middleware = metricsMiddleware.metrics(
+  pathLabelMapper = { case Method.GET -> Root / "user" / _ =>
+    "/user/:id"
+  },
+  extraLabels = Set(MetricLabel("test", "http_requests_total with path label mapper")),
+)
+val appWithMetrics = middleware(app)
+```
+
+This example creates an HTTP app `app` and applies the `metrics` middleware with custom parameters. The `pathLabelMapper` is used to map specific paths to patterns, and extra labels are provided. The resulting `appWithMetrics` is the original app with the metrics middleware applied.