-
Notifications
You must be signed in to change notification settings - Fork 412
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* removed config.md and make configurations part of Server page * added server configurations * markdwon appearing fine in docusaurus generated page * added one missing configuration * Server documentation changed according to PR comments * change note to tip Co-authored-by: Sumant Awasthi <sumant.awasthi@D11-Sumant.Awasthi> Co-authored-by: amitsingh <amitksingh1490@gmail.com>
- Loading branch information
1 parent
adfa7cf
commit 77fa788
Showing
2 changed files
with
109 additions
and
3 deletions.
There are no files selected for viewing
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,109 @@ | ||
# ZIO HTTP Server | ||
|
||
This section describes, ZIO HTTP Server and different configurations you can provide while creating the Server | ||
|
||
## Start a ZIO HTTP Server with default configurations | ||
```scala | ||
override def run(args: List[String]): URIO[zio.ZEnv, ExitCode] = | ||
Server.start(8090, app.silent).exitCode | ||
``` | ||
## Start a ZIO HTTP Server with custom configurations. | ||
1. Imports required by the customised server. | ||
```scala | ||
import zhttp.http._ | ||
import zhttp.service.server.ServerChannelFactory | ||
import zhttp.service.{EventLoopGroup, Server} | ||
import zio._ | ||
import scala.util.Try | ||
``` | ||
2. The Server can be built incrementally with a `++` each returning a new Server overriding any default configuration. (More properties are given in the [Server Configurations](#server-configurations) section below.) | ||
```scala | ||
private val server = | ||
Server.port(PORT) ++ // Setup port | ||
Server.maxRequestSize(8 * 1024) ++ // handle max request size of 8 KB (default 4 KB) | ||
Server.app(fooBar ++ app) // Setup the Http app | ||
``` | ||
3. And then use ```Server.make``` to get a "managed" instance use it to run a server forever | ||
```scala | ||
override def run(args: List[String]): URIO[zio.ZEnv, ExitCode] = { | ||
server.make | ||
.use(start => | ||
console.putStrLn(s"Server started on port ${start.port}") | ||
*> ZIO.never, | ||
).provideCustomLayer(ServerChannelFactory.auto ++ EventLoopGroup.auto(2)) | ||
.exitCode | ||
``` | ||
**Tip :** `ServerChannelFactory.auto ++ EventLoopGroup.auto(num Threads)` is supplied as an external dependency to choose netty transport type. One can leave it as `auto` to let the application handle it for you. | ||
Also in `EventLoopGroup.auto(numThreads)` you can choose number of threads based on number of available processors. | ||
|
||
### Binding Server to a socket address | ||
One can bind server to Inet address in multiple ways, either by providing a port number or | ||
- If no port is provided, the default port is 8080 | ||
- If specified port is 0, it will use a dynamically selected port. | ||
|
||
<details> | ||
<summary><b>A complete example </b></summary> | ||
|
||
- Example below shows how the server can be started in forever mode to serve HTTP requests: | ||
|
||
```scala | ||
import zhttp.http._ | ||
import zhttp.service._ | ||
import zhttp.service.server.ServerChannelFactory | ||
import zio._ | ||
|
||
import scala.util.Try | ||
|
||
object HelloWorldAdvanced extends App { | ||
// Set a port | ||
private val PORT = 8090 | ||
|
||
private val fooBar: HttpApp[Any, Nothing] = Http.collect[Request] { | ||
case Method.GET -> !! / "foo" => Response.text("bar") | ||
case Method.GET -> !! / "bar" => Response.text("foo") | ||
} | ||
|
||
private val app = Http.collectM[Request] { | ||
case Method.GET -> !! / "random" => random.nextString(10).map(Response.text) | ||
case Method.GET -> !! / "utc" => clock.currentDateTime.map(s => Response.text(s.toString)) | ||
} | ||
|
||
private val server = | ||
Server.port(PORT) ++ // Setup port | ||
Server.paranoidLeakDetection ++ // Paranoid leak detection (affects performance) | ||
Server.app(fooBar +++ app) // Setup the Http app | ||
|
||
override def run(args: List[String]): URIO[zio.ZEnv, ExitCode] = { | ||
// Configure thread count using CLI | ||
val nThreads: Int = args.headOption.flatMap(x => Try(x.toInt).toOption).getOrElse(0) | ||
|
||
// Create a new server | ||
server.make | ||
.use(_ => | ||
// Waiting for the server to start | ||
console.putStrLn(s"Server started on port $PORT") | ||
|
||
// Ensures the server doesn't die after printing | ||
*> ZIO.never, | ||
) | ||
.provideCustomLayer(ServerChannelFactory.auto ++ EventLoopGroup.auto(nThreads)) | ||
.exitCode | ||
} | ||
} | ||
``` | ||
</details> | ||
|
||
## Server Configurations | ||
|
||
| **Configuration** | **Purpose and usage** | | ||
| ----------- | ----------- | | ||
| `Server.app(httpApp)` | Mount routes. Refer to complete example above | | ||
| `Server.maxRequestSize(8 * 1024)` | handle max request size of 8 KB (default 4 KB) | | ||
| `Server.port(portNum)` or `Server.bind(portNum)` | Bind server to the port, refer to examples above | | ||
| `Server.ssl(sslOptions)` | Creates a new server with ssl options. [HttpsHelloWorld](https://github.com/dream11/zio-http/blob/main/example/src/main/scala/example/HttpsHelloWorld.scala) | | ||
| `Server.acceptContinue` | Sends a [100 CONTINUE](https://www.w3.org/Protocols/rfc2616/rfc2616-sec8.html#sec8.2.3) | | ||
| `Server.disableFlowControl` | Refer [Netty FlowControlHandler](https://netty.io/4.1/api/io/netty/handler/flow/FlowControlHandler.html) | | ||
| `Server.disableLeakDetection` | Disable any leak detection Refer netty's [ResourceLeakDetector](https://netty.io/4.0/api/io/netty/util/ResourceLeakDetector.Level.html) | | ||
| `Server.simpleLeakDetection` | Simplistic leak detection comes with small over head. Refer netty's [ResourceLeakDetector](https://netty.io/4.0/api/io/netty/util/ResourceLeakDetector.Level.html) | | ||
| `Server.paranoidLeakDetection` | Comes with highest possible overhead (for testing purposes only). Refer netty's [ResourceLeakDetector](https://netty.io/4.0/api/io/netty/util/ResourceLeakDetector.Level.html) | | ||
| `Server.consolidateFlush` | Flushing content is done in batches. Can potentially improve performance. | |