From 477157a4acd33324887ae8234fcc2be2d4f13203 Mon Sep 17 00:00:00 2001 From: Milad Khajavi Date: Sat, 27 Apr 2024 11:11:10 +0330 Subject: [PATCH] Cleanup Documentation (#2797) * move overview section to reference section. * move template to body section. * organize sidebar. * zio version. --- build.sbt | 3 +- docs/faq.md | 2 +- docs/installation.md | 4 +- docs/reference/{ => aop}/handler_aspect.md | 0 docs/reference/{ => aop}/middleware.md | 2 +- docs/reference/{ => aop}/protocol-stack.md | 0 docs/{ => reference/body}/binary_codecs.md | 0 docs/reference/{ => body}/body.md | 0 docs/reference/{ => body}/form.md | 0 docs/reference/{ => body}/template.md | 0 docs/reference/client.md | 2 +- docs/reference/endpoint.md | 4 +- docs/reference/handler.md | 2 +- docs/reference/{ => headers}/headers.md | 0 .../{ => headers/session}/cookies.md | 0 docs/reference/{ => headers/session}/flash.md | 0 docs/{overview.md => reference/index.md} | 34 ++++++++-------- docs/reference/request.md | 2 +- docs/reference/{ => response}/response.md | 2 +- docs/reference/{ => response}/status.md | 2 +- docs/reference/{ => routing}/path_codec.md | 0 docs/reference/{ => routing}/route_pattern.md | 0 docs/reference/{ => routing}/routes.md | 2 +- docs/reference/server.md | 4 +- docs/sidebars.js | 40 +++++++++---------- docs/testing-http-apps.md | 4 +- 26 files changed, 55 insertions(+), 54 deletions(-) rename docs/reference/{ => aop}/handler_aspect.md (100%) rename docs/reference/{ => aop}/middleware.md (99%) rename docs/reference/{ => aop}/protocol-stack.md (100%) rename docs/{ => reference/body}/binary_codecs.md (100%) rename docs/reference/{ => body}/body.md (100%) rename docs/reference/{ => body}/form.md (100%) rename docs/reference/{ => body}/template.md (100%) rename docs/reference/{ => headers}/headers.md (100%) rename docs/reference/{ => headers/session}/cookies.md (100%) rename docs/reference/{ => headers/session}/flash.md (100%) rename docs/{overview.md => reference/index.md} (81%) rename docs/reference/{ => response}/response.md (99%) rename docs/reference/{ => response}/status.md (99%) rename docs/reference/{ => routing}/path_codec.md (100%) rename docs/reference/{ => routing}/route_pattern.md (100%) rename docs/reference/{ => routing}/routes.md (98%) diff --git a/build.sbt b/build.sbt index 599cfb0793..3d8e9838f0 100644 --- a/build.sbt +++ b/build.sbt @@ -327,7 +327,8 @@ lazy val docs = project ), publish / skip := true, mdocVariables ++= Map( - "ZIO_SCHEMA_VERSION" -> ZioSchemaVersion + "ZIO_SCHEMA_VERSION" -> ZioSchemaVersion, + "ZIO_VERSION" -> ZioVersion ) ) .dependsOn(zioHttpJVM) diff --git a/docs/faq.md b/docs/faq.md index 5b98151901..4ba3609e84 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -18,7 +18,7 @@ If you prefer not to use ZIO HTTP but still want to build HTTP applications usin ### How Can I Serialize/Deserialize Data to/from JSON in Requests and Responses? -ZIO HTTP provides built-in support for JSON serialization and deserialization using [ZIO Schema](https://zio.dev/zio-schema/). You can derive JSON codecs for your custom data types using ZIO Schema and use them to encode/decode data to/from request/response bodies. Check out the [BinaryCodecs](./binary_codecs.md) section in the documentation for more details. +ZIO HTTP provides built-in support for JSON serialization and deserialization using [ZIO Schema](https://zio.dev/zio-schema/). You can derive JSON codecs for your custom data types using ZIO Schema and use them to encode/decode data to/from request/response bodies. Check out the [BinaryCodecs](./reference/body/binary_codecs.md) section in the documentation for more details. ### How Can I Handle CORS Requests in ZIO HTTP? diff --git a/docs/installation.md b/docs/installation.md index 220134524c..bfc8b5afca 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -35,9 +35,9 @@ This template includes the following plugins: These dependencies in the g8 template were added to enable an efficient development process. -### Hot-reload Changes +### Hot-reload Changes (Watch Mode) -Sbt-revolver can watch application resources for change and automatically re-compile and then re-start the application under development. This provides a fast development-turnaround, the closest we can get to real hot-reloading. +[Sbt-revolver](https://github.com/spray/sbt-revolver) can watch application resources for change and automatically re-compile and then re-start the application under development. This provides a fast development-turnaround, the closest we can get to real hot-reloading. We can start our application from _sbt_ with the following command: diff --git a/docs/reference/handler_aspect.md b/docs/reference/aop/handler_aspect.md similarity index 100% rename from docs/reference/handler_aspect.md rename to docs/reference/aop/handler_aspect.md diff --git a/docs/reference/middleware.md b/docs/reference/aop/middleware.md similarity index 99% rename from docs/reference/middleware.md rename to docs/reference/aop/middleware.md index cb7c0b5e0c..b22ce59445 100644 --- a/docs/reference/middleware.md +++ b/docs/reference/aop/middleware.md @@ -213,7 +213,7 @@ val urlRewrite: Middleware[Any] = ## Built-in Middlewares -In this section we are going to introduce built-in middlewares that are provided by ZIO HTTP. Please note that the `Middleware` object also inherits many other middlewares from the `HandlerAspect`, that we will introduce them on the [HandlerAspect](./handler_aspect.md) page. +In this section we are going to introduce built-in middlewares that are provided by ZIO HTTP. Please note that the `Middleware` object also inherits many other middlewares from the `HandlerAspect`, that we will introduce them on the [HandlerAspect](handler_aspect.md) page. ### Access Control Allow Origin (CORS) Middleware diff --git a/docs/reference/protocol-stack.md b/docs/reference/aop/protocol-stack.md similarity index 100% rename from docs/reference/protocol-stack.md rename to docs/reference/aop/protocol-stack.md diff --git a/docs/binary_codecs.md b/docs/reference/body/binary_codecs.md similarity index 100% rename from docs/binary_codecs.md rename to docs/reference/body/binary_codecs.md diff --git a/docs/reference/body.md b/docs/reference/body/body.md similarity index 100% rename from docs/reference/body.md rename to docs/reference/body/body.md diff --git a/docs/reference/form.md b/docs/reference/body/form.md similarity index 100% rename from docs/reference/form.md rename to docs/reference/body/form.md diff --git a/docs/reference/template.md b/docs/reference/body/template.md similarity index 100% rename from docs/reference/template.md rename to docs/reference/body/template.md diff --git a/docs/reference/client.md b/docs/reference/client.md index 0fb8ef947d..c66d0fd771 100644 --- a/docs/reference/client.md +++ b/docs/reference/client.md @@ -187,7 +187,7 @@ val program = for { ``` :::note -To learn more about headers and how they work, check out our dedicated section called [Header Operations](./headers.md#headers-operations) on the headers page. +To learn more about headers and how they work, check out our dedicated section called [Header Operations](headers/headers.md#headers-operations) on the headers page. ::: ## Composable URLs diff --git a/docs/reference/endpoint.md b/docs/reference/endpoint.md index 34a7e6f554..c740b0e151 100644 --- a/docs/reference/endpoint.md +++ b/docs/reference/endpoint.md @@ -449,9 +449,9 @@ import utils._ printSource("zio-http-example/src/main/scala/example/endpoint/GenerateEndpointFromOpenAPIExample.scala") ``` -## Generating ZIO‌ CLI App from Endpoint API +## Generating ZIO CLI App from Endpoint API -The ZIO‌ CLI is a ZIO‌ library that provides a way to build command-line applications using ZIO facilities. With ZIO‌ HTTP, we can generate a ZIO CLI client from the `Endpoint` API. +The ZIO CLI is a ZIO library that provides a way to build command-line applications using ZIO facilities. With ZIO HTTP, we can generate a ZIO CLI client from the `Endpoint` API. To do this, first, we need to add the following line to the `build.sbt` file: diff --git a/docs/reference/handler.md b/docs/reference/handler.md index 187cd5fa6b..cc2a9ef9c8 100644 --- a/docs/reference/handler.md +++ b/docs/reference/handler.md @@ -582,7 +582,7 @@ Routes( ) ``` -This will log every request coming to these handlers. ZIO HTTP supports various `HandlerAspects` that you can learn about in the [Middleware](middleware.md) section. +This will log every request coming to these handlers. ZIO HTTP supports various `HandlerAspects` that you can learn about in the [Middleware](aop/middleware.md) section. ### Sandboxing Errors diff --git a/docs/reference/headers.md b/docs/reference/headers/headers.md similarity index 100% rename from docs/reference/headers.md rename to docs/reference/headers/headers.md diff --git a/docs/reference/cookies.md b/docs/reference/headers/session/cookies.md similarity index 100% rename from docs/reference/cookies.md rename to docs/reference/headers/session/cookies.md diff --git a/docs/reference/flash.md b/docs/reference/headers/session/flash.md similarity index 100% rename from docs/reference/flash.md rename to docs/reference/headers/session/flash.md diff --git a/docs/overview.md b/docs/reference/index.md similarity index 81% rename from docs/overview.md rename to docs/reference/index.md index 79e4cf642d..1c2cf1b77f 100644 --- a/docs/overview.md +++ b/docs/reference/index.md @@ -1,19 +1,17 @@ --- -id: overview -title: Overview +id: index +title: Introduction to ZIO HTTP --- -**ZIO HTTP** is a powerful library that is used to build highly performant HTTP-based services and clients using functional scala and ZIO and uses [Netty](https://netty.io/) as its core. - -ZIO HTTP has powerful functional domains that help in creating, modifying, and composing apps easily. Let's start with the HTTP domain. +ZIO HTTP offers an expressive API for creating HTTP applications. It uses a domain-specific language (DSL) to define routes and handlers. Both server and client are designed in terms of **HTTP as a function**, so they are functions from `Request` to `Response`. ## Core Concepts -The core concepts of ZIO HTTP are: +ZIO HTTP has powerful functional domains that help in creating, modifying, and composing apps easily. Let's take a look at the core domain: - `Routes` - A collection of `Route`s. If the error type of the routes is `Response`, then they can be served. -- `Route` - A single route that can be matched against a http `Request` and produce a `Response`. It comprises a `RoutePattern` and a `Handler`: - 1. `RoutePattern` - A pattern that can be matched against a http request. It is a combination of `Method` and `PathCodec` which can be used to match the method and path of the request. +- `Route` - A single route that can be matched against an HTTP `Request` and produce a `Response`. It comprises a `RoutePattern` and a `Handler`: + 1. `RoutePattern` - A pattern that can be matched against an HTTP `Request`. It is a combination of `Method` and `PathCodec` which can be used to match the `Method` and `Path` of the `Request`. 2. `Handler` - A function that can convert a `Request` into a `Response`. Let's see each of these concepts inside a simple example: @@ -61,9 +59,7 @@ object ExampleServer extends ZIOAppDefault { ### 1.Routes -The `Routes` provides input-dependent routing to different `Handler` values. - -The `Handler` and `Route` can be transformed to `Routes` by the `.toRoutes` method. To serve the routes, all errors should be handled by converting them into a `Response` using for example the `.handleError` method. +The `Routes` is a collection of `Route` values. It can be created using its default constructor: ```scala mdoc:invisible import zio.http._ @@ -80,9 +76,13 @@ val app: Routes[Any, Response] = .handleError(e => Response.internalServerError(e.getMessage)) ``` +The `Handler` and `Route` can be transformed to `Routes` by the `.toRoutes` method. To serve the routes, all errors should be handled by converting them into a `Response` using for example the `.handleError` method. + +For handling routes, ZIO HTTP has a [`Routes`](routing/routes.md) value, which allows us to aggregate a collection of individual routes. Behind the scenes, ZIO HTTP builds an efficient prefix-tree whenever needed to optimize dispatch. + ### 2. Route -Each `Route` is a combination of a [`RoutePattern`](reference/route_pattern.md) and a [`Handler`](reference/handler.md). The `RoutePattern` is a combination of a `Method` and a [`PathCodec`](reference/path_codec.md) that can be used to match the method and path of the request. The `Handler` is a function that can convert a `Request` into a `Response`. +Each `Route` is a combination of a [`RoutePattern`](routing/route_pattern.md) and a [`Handler`](handler.md). The `RoutePattern` is a combination of a `Method` and a [`PathCodec`](routing/path_codec.md) that can be used to match the method and path of the request. The `Handler` is a function that can convert a `Request` into a `Response`. The `PathCodec` can be parameterized to extract values from the path. In such cases, the `Handler` should be a function that accepts the extracted values besides the `Request`: @@ -97,7 +97,7 @@ val routes = Routes( ) ``` -To learn more about routes, see the [Routes](reference/routes.md) page. +To learn more about routes, see the [Routes](routing/routes.md) page. ### 3. Handler @@ -140,7 +140,7 @@ val routes = Routes( ) ``` -To learn more about the request, see the [Request](reference/request.md) page. +To learn more about the request, see the [Request](request.md) page. ## Accessing Services from The Environment @@ -198,7 +198,7 @@ val routes = ) ``` -We have a more detailed explanation of the WebSocket connection on the [Socket](reference/socket/socket.md) page. +We have a more detailed explanation of the WebSocket connection on the [Socket](socket/socket.md) page. ## Server @@ -220,7 +220,7 @@ object HelloWorld extends ZIOAppDefault { } ``` -Finally, we provided the default server with the port `8090` to the app. To learn more about the server, see the [Server](reference/server.md) page. +Finally, we provided the default server with the port `8090` to the app. To learn more about the server, see the [Server](server.md) page. ## Client @@ -243,4 +243,4 @@ object ClientExample extends ZIOAppDefault { } ``` -In the above example, we obtained the `Client` service from the environment and sent a `GET` request to the server. Finally, to run the client app, we provided the default `Client` and `Scope` services to the app. For more information about the client, see the [Client](reference/client.md) page. +In the above example, we obtained the `Client` service from the environment and sent a `GET` request to the server. Finally, to run the client app, we provided the default `Client` and `Scope` services to the app. For more information about the client, see the [Client](client.md) page. diff --git a/docs/reference/request.md b/docs/reference/request.md index 525437ea20..0c119e3dcf 100644 --- a/docs/reference/request.md +++ b/docs/reference/request.md @@ -230,7 +230,7 @@ Using the `Request#queryParameters` method, we can access the query parameters o ### Modifying Query Parameters -When we are working with ZIO HTTP‌ Client, we need to create a new `Request` and may need to set/update/remove query parameters. In such cases, we have the following methods available: `addQueryParam`, `addQueryParams`, `removeQueryParam`, `removeQueryParams`, `setQueryParams`, and `updateQueryParams`. +When we are working with ZIO HTTP Client, we need to create a new `Request` and may need to set/update/remove query parameters. In such cases, we have the following methods available: `addQueryParam`, `addQueryParams`, `removeQueryParam`, `removeQueryParams`, `setQueryParams`, and `updateQueryParams`. ```scala mdoc:compile-only import zio._ diff --git a/docs/reference/response.md b/docs/reference/response/response.md similarity index 99% rename from docs/reference/response.md rename to docs/reference/response/response.md index d86a3e3608..2cd71b24ef 100644 --- a/docs/reference/response.md +++ b/docs/reference/response/response.md @@ -353,4 +353,4 @@ Response.ok.addFlash(flash) ### Working with Headers -There are various methods to work with headers in `Response` which we have discussed in the [Headers](headers.md#headers-operations) page. +There are various methods to work with headers in `Response` which we have discussed in the [Headers](../headers/headers.md#headers-operations) page. \ No newline at end of file diff --git a/docs/reference/status.md b/docs/reference/response/status.md similarity index 99% rename from docs/reference/status.md rename to docs/reference/response/status.md index 8c5dd3ba79..9ffd9309ea 100644 --- a/docs/reference/status.md +++ b/docs/reference/response/status.md @@ -1,6 +1,6 @@ --- id: status -title: Status Code +title: Status Codes --- HTTP status codes are standard response codes given by web services on the Internet. The codes help identify the cause of the problem when a web page or other resource does not load properly. diff --git a/docs/reference/path_codec.md b/docs/reference/routing/path_codec.md similarity index 100% rename from docs/reference/path_codec.md rename to docs/reference/routing/path_codec.md diff --git a/docs/reference/route_pattern.md b/docs/reference/routing/route_pattern.md similarity index 100% rename from docs/reference/route_pattern.md rename to docs/reference/routing/route_pattern.md diff --git a/docs/reference/routes.md b/docs/reference/routing/routes.md similarity index 98% rename from docs/reference/routes.md rename to docs/reference/routing/routes.md index bc74461a6f..bde01ba8e3 100644 --- a/docs/reference/routes.md +++ b/docs/reference/routing/routes.md @@ -167,7 +167,7 @@ val routes: Routes[Any, Response] = ??? val newRoutes = routes @@ HandlerAspect.dropTrailingSlash ``` -To learn more about middlewares, see the [Middleware](middleware.md) section. +To learn more about middlewares, see the [Middleware](../aop/middleware.md) section. ## Handling Errors in Routes diff --git a/docs/reference/server.md b/docs/reference/server.md index 80efe5ec2d..27fc0677ce 100644 --- a/docs/reference/server.md +++ b/docs/reference/server.md @@ -208,7 +208,7 @@ connection: close Hello World!⏎ ``` -The‌ ZIO HTTP server by default supports keep-alive connections. To disable it, we can use the `Server.Config#keepAlive` method, by setting it to `false`: +The ZIO HTTP server by default supports keep-alive connections. To disable it, we can use the `Server.Config#keepAlive` method, by setting it to `false`: ```scala mdoc:compile-only import zio.http._ @@ -546,7 +546,7 @@ printSource("zio-http-example/src/main/scala/example/ServeOnAnyOpenPort.scala") When a ZIO HTTP server is running, it handles incoming requests from clients, processes them, and sends back appropriate responses. In-flight requests are requests that have been received by the server but have not yet been fully processed or responded to. These requests might be in various stages of processing, such as waiting for database queries to complete or for resources to become available. -When we're shutting down the server, it's important to handle these in-flight requests gracefully. ZIO‌ HTTP has a built-in mechanism to allow in-flight requests to finalize before shutting down the server. The default behavior is to wait for 10 seconds for in-flight requests to finalize before shutting down the server. During this time, the server will not accept new requests, but it will continue to process existing requests until they're fully completed. +When we're shutting down the server, it's important to handle these in-flight requests gracefully. ZIO HTTP has a built-in mechanism to allow in-flight requests to finalize before shutting down the server. The default behavior is to wait for 10 seconds for in-flight requests to finalize before shutting down the server. During this time, the server will not accept new requests, but it will continue to process existing requests until they're fully completed. To change the default graceful shutdown timeout, we can use the `Server.Config#gracefulShutdownTimeout` method. It takes a `Duration` as an argument, and returns a new `Server.Config` with the specified graceful shutdown timeout: diff --git a/docs/sidebars.js b/docs/sidebars.js index 5dde97296f..c3d357b674 100644 --- a/docs/sidebars.js +++ b/docs/sidebars.js @@ -7,10 +7,10 @@ const sidebars = { link: { type: "doc", id: "index" }, items: [ "installation", - "overview", { type: "category", collapsed: true, + link: { type: "doc", id: "reference/index" }, label: "Reference", items: [ "reference/server", @@ -19,9 +19,9 @@ const sidebars = { type: "category", label: "Routing", items: [ - "reference/routes", - "reference/route_pattern", - "reference/path_codec", + "reference/routing/routes", + "reference/routing/route_pattern", + "reference/routing/path_codec", ], }, "reference/handler", @@ -29,36 +29,38 @@ const sidebars = { type: "category", label: "HTTP Messages", items: [ + "reference/request", + "reference/response/response", { type: "category", label: "Headers", items: [ - "reference/headers", - "reference/cookies", - "reference/flash", + "reference/headers/headers", + "reference/headers/session/cookies", + "reference/headers/session/flash", ], }, - "reference/request", - { - type: "category", - label: "Response", - items: ["reference/response", "reference/status"], - }, { type: "category", label: "Message Body", - items: ["reference/body", "reference/form"], + items: [ + "reference/body/body", + "reference/body/form", + "reference/body/binary_codecs", + "reference/body/template", + ], }, + "reference/response/status", ], }, "reference/endpoint", { type: "category", - label: "HTTP Middleware", + label: "Aspects", items: [ - "reference/protocol-stack", - "reference/middleware", - "reference/handler_aspect", + "reference/aop/protocol-stack", + "reference/aop/middleware", + "reference/aop/handler_aspect", ], }, { @@ -69,10 +71,8 @@ const sidebars = { "reference/socket/websocketframe", ], }, - "reference/template", ], }, - "binary_codecs", "testing-http-apps", "faq", { diff --git a/docs/testing-http-apps.md b/docs/testing-http-apps.md index 2d2dc9211f..1c857beeae 100644 --- a/docs/testing-http-apps.md +++ b/docs/testing-http-apps.md @@ -33,8 +33,8 @@ object ExampleSpec extends ZIOSpecDefault { Also, ZIO HTTP provides a testkit called `zio-http-testkit` that includes `TestClient` and `TestServer` utilities which helps us to test our HTTP applications without the need for having a real live client and server instances. ```scala -libraryDependencies += "dev.zio" %% "zio-test" % ZioVersion % Test -libraryDependencies += "dev.zio" %% "zio-test-sbt" % ZioVersion % Test +libraryDependencies += "dev.zio" %% "zio-test" % "@ZIO_VERSION@" % Test +libraryDependencies += "dev.zio" %% "zio-test-sbt" % "@ZIO_VERSION@" % Test libraryDependencies += "dev.zio" %% "zio-http-testkit" % "@VERSION@" % Test testFrameworks += new TestFramework("zio.test.sbt.ZTestFramework") ```