From e138917f41bdf51bfe66dd0a67c555057a83e21e Mon Sep 17 00:00:00 2001 From: "Aleksey.Zamulla" Date: Fri, 20 Jun 2025 18:31:17 +0200 Subject: [PATCH 01/10] update: unix domain sockets, explained --- topics/client-default-request.md | 35 ++++++++++++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/topics/client-default-request.md b/topics/client-default-request.md index 11e35d037..ec81e4e52 100644 --- a/topics/client-default-request.md +++ b/topics/client-default-request.md @@ -22,7 +22,8 @@ The [DefaultRequest](https://api.ktor.io/ktor-client/ktor-client-core/io.ktor.cl ## Install DefaultRequest {id="install_plugin"} -To install `DefaultRequest`, pass it to the `install` function inside a [client configuration block](client-create-and-configure.md#configure-client) ... +To install `DefaultRequest`, pass it to the `install` function inside a [client configuration block](client-create-and-configure.md#configure-client): + ```kotlin import io.ktor.client.* import io.ktor.client.engine.cio.* @@ -33,7 +34,7 @@ val client = HttpClient(CIO) { } ``` -... or call the `defaultRequest` function and [configure](#configure) required request parameters: +Or call the `defaultRequest` function and [configure](#configure) required request parameters: ```kotlin import io.ktor.client.* @@ -99,6 +100,36 @@ defaultRequest { } ``` +### Unix domain sockets + +Unix domain sockets are supported in the CIO engine, for Ktor server as well as Ktor client. + +To use a Unix socket, [configure the server](server-configuration-code.topic#cio-code) +by adding a `unixConnector` specifying the path to the socket, for example: + +```kotlin +val server = embeddedServer(CIO, configure = { + unixConnector("/tmp/test-unix-socket-ktor.sock") +}) { + routing { + get("/") { + call.respondText("Hello, Unix socket world!") + } + } +} +``` + +To set up a Ktor client to communicate to a Ktor server listening to Unix domain sockets, +connect to the same Unix domain socket file using the `unixSocket` function: + +```kotlin +val response = HttpClient(CIO) { + defaultRequest { + unixSocket("/tmp/test-unix-socket-ktor.sock") + } +}.get("/") +``` + ## Example {id="example"} The example below uses the following `DefaultRequest` configuration: From 094a56edf40440987916f5e0f8571edf00198d44 Mon Sep 17 00:00:00 2001 From: "Aleksey.Zamulla" Date: Fri, 20 Jun 2025 19:28:38 +0200 Subject: [PATCH 02/10] update: start with the general request builder, with default request as a special case --- topics/client-default-request.md | 24 ++++++--------------- topics/client-requests.md | 37 +++++++++++++++++++++++++++++--- 2 files changed, 41 insertions(+), 20 deletions(-) diff --git a/topics/client-default-request.md b/topics/client-default-request.md index ec81e4e52..86d2fd9da 100644 --- a/topics/client-default-request.md +++ b/topics/client-default-request.md @@ -102,25 +102,15 @@ defaultRequest { ### Unix domain sockets -Unix domain sockets are supported in the CIO engine, for Ktor server as well as Ktor client. +> Unix domain sockets are supported only in the CIO engine, for Ktor server as well as Ktor client. +> +{style="note"} -To use a Unix socket, [configure the server](server-configuration-code.topic#cio-code) -by adding a `unixConnector` specifying the path to the socket, for example: +You can [build individual requests with Unix domain sockets](client-requests.md#specify-a-unix-domain-socket), +but you can also configure a default request with a socket parameter. -```kotlin -val server = embeddedServer(CIO, configure = { - unixConnector("/tmp/test-unix-socket-ktor.sock") -}) { - routing { - get("/") { - call.respondText("Hello, Unix socket world!") - } - } -} -``` - -To set up a Ktor client to communicate to a Ktor server listening to Unix domain sockets, -connect to the same Unix domain socket file using the `unixSocket` function: +To do that, pass a `unixSocket` call with the path to the socket to the `defaultRequest` function, +for example: ```kotlin val response = HttpClient(CIO) { diff --git a/topics/client-requests.md b/topics/client-requests.md index 3e30dd2e3..caeafca5c 100644 --- a/topics/client-requests.md +++ b/topics/client-requests.md @@ -16,6 +16,7 @@ Learn how to make requests and specify various request parameters: a request URL After [setting up the client](client-create-and-configure.md), you can make HTTP requests. The main way of making HTTP requests is the [request](https://api.ktor.io/ktor-client/ktor-client-core/io.ktor.client.request/request.html) function that can take a URL as a parameter. Inside this function, you can configure various request parameters: * Specify an HTTP method, such as `GET`, `POST`, `PUT`, `DELETE`, `HEAD`, `OPTIONS`, or `PATCH`. * Specify a URL as a string or configure URL components (a domain, a path, query parameters, etc.) separately. +* Specify a Unix domain socket. * Add headers and cookies. * Set the body of a request, for example, a plain text, a data object, or form parameters. @@ -119,6 +120,38 @@ You can configure a URL fragment using the `fragment` property. Note that `fragment` [encodes][percent_encoding] a URL fragment. To disable encoding, use `encodedFragment`. +## Specify a unix domain socket + +> Unix domain sockets are supported only in the CIO engine, for Ktor server as well as Ktor client. +> +{style="note"} + +To use a Unix socket, [configure the server](server-configuration-code.topic#cio-code) +by adding a `unixConnector` with the path to the socket, for example: + +```kotlin +val server = embeddedServer(CIO, configure = { + unixConnector("/tmp/test-unix-socket-ktor.sock") +}) { + routing { + get("/") { + call.respondText("Hello, Unix socket world!") + } + } +} +``` + +Then you can make requests to a server listening to that socket by calling the `unixSocket` function +for a CIO client: + +```kotlin +val responseText: HttpResponse = HttpClient(CIO).request { + unixSocket("/tmp/test-unix-socket-ktor.sock") +} +``` + +You can also set up a Unix domain socket as a part of a [default request](client-default-request.md#unix-domain-sockets). + ## Set request parameters {id="parameters"} In this section, we'll see how to specify various request parameters, including an HTTP method, headers, and cookies. If you need to configure some default parameters for all requests of a specific client, use the [DefaultRequest](client-default-request.md) plugin. @@ -134,8 +167,7 @@ To add headers to the request, you can use the following ways: - The [header](https://api.ktor.io/ktor-client/ktor-client-core/io.ktor.client.request/header.html) function allows you to append a single header. - The `basicAuth` and `bearerAuth` functions add the `Authorization` header with a corresponding HTTP scheme. > For advanced authentication configuration, refer to [](client-auth.md). - - + ### Cookies {id="cookies"} To send cookies, use the [cookie](https://api.ktor.io/ktor-client/ktor-client-core/io.ktor.client.request/cookie.html) function: @@ -147,7 +179,6 @@ To send cookies, use the [cookie](https://api.ktor.io/ktor-client/ktor-client-co Ktor also provides the [HttpCookies](client-cookies.md) plugin that allows you to keep cookies between calls. If this plugin is installed, cookies added using the `cookie` function are ignored. - ## Set request body {id="body"} To set the body of a request, you need to call the `setBody` function exposed by [HttpRequestBuilder](https://api.ktor.io/ktor-client/ktor-client-core/io.ktor.client.request/-http-request-builder/index.html). This function accepts different types of payloads, including plain text, arbitrary class instances, form data, byte arrays, and so on. Below, we'll take a look at several examples. From 3c8eee64746c9111cd38c1491ebb051ca52dc8c9 Mon Sep 17 00:00:00 2001 From: "Aleksey.Zamulla" Date: Fri, 20 Jun 2025 19:30:02 +0200 Subject: [PATCH 03/10] fix: typo --- topics/client-requests.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/topics/client-requests.md b/topics/client-requests.md index caeafca5c..6ad20aab7 100644 --- a/topics/client-requests.md +++ b/topics/client-requests.md @@ -120,7 +120,7 @@ You can configure a URL fragment using the `fragment` property. Note that `fragment` [encodes][percent_encoding] a URL fragment. To disable encoding, use `encodedFragment`. -## Specify a unix domain socket +## Specify a Unix domain socket > Unix domain sockets are supported only in the CIO engine, for Ktor server as well as Ktor client. > From 690c17179cc836808d54d282b36267a89b7a5ce7 Mon Sep 17 00:00:00 2001 From: "Aleksey.Zamulla" Date: Fri, 20 Jun 2025 19:30:42 +0200 Subject: [PATCH 04/10] fix: typo --- topics/client-requests.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/topics/client-requests.md b/topics/client-requests.md index 6ad20aab7..7f3ca0c18 100644 --- a/topics/client-requests.md +++ b/topics/client-requests.md @@ -145,7 +145,7 @@ Then you can make requests to a server listening to that socket by calling the ` for a CIO client: ```kotlin -val responseText: HttpResponse = HttpClient(CIO).request { +val response: HttpResponse = HttpClient(CIO).request { unixSocket("/tmp/test-unix-socket-ktor.sock") } ``` From 0753131ae22aa143ee62a6c0b62d98e409c96adf Mon Sep 17 00:00:00 2001 From: "Aleksey.Zamulla" Date: Mon, 23 Jun 2025 16:02:03 +0200 Subject: [PATCH 05/10] fix: better code --- topics/client-default-request.md | 8 +++++--- topics/client-requests.md | 4 +++- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/topics/client-default-request.md b/topics/client-default-request.md index 86d2fd9da..bf81d455c 100644 --- a/topics/client-default-request.md +++ b/topics/client-default-request.md @@ -113,11 +113,13 @@ To do that, pass a `unixSocket` call with the path to the socket to the `default for example: ```kotlin -val response = HttpClient(CIO) { +val client = HttpClient(CIO) { defaultRequest { unixSocket("/tmp/test-unix-socket-ktor.sock") - } -}.get("/") + } +} + +val response: HttpResponse = client.get("/") ``` ## Example {id="example"} diff --git a/topics/client-requests.md b/topics/client-requests.md index 7f3ca0c18..62a72f394 100644 --- a/topics/client-requests.md +++ b/topics/client-requests.md @@ -145,7 +145,9 @@ Then you can make requests to a server listening to that socket by calling the ` for a CIO client: ```kotlin -val response: HttpResponse = HttpClient(CIO).request { +val client = HttpClient(CIO) + +val response: HttpResponse = client.get("/") { unixSocket("/tmp/test-unix-socket-ktor.sock") } ``` From ff1e38906668247b7e097604efe4f90ae83581e6 Mon Sep 17 00:00:00 2001 From: "Aleksey.Zamulla" Date: Mon, 23 Jun 2025 16:13:54 +0200 Subject: [PATCH 06/10] fix: better code --- topics/client-default-request.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/topics/client-default-request.md b/topics/client-default-request.md index bf81d455c..3a7aa8d0a 100644 --- a/topics/client-default-request.md +++ b/topics/client-default-request.md @@ -113,13 +113,21 @@ To do that, pass a `unixSocket` call with the path to the socket to the `default for example: ```kotlin -val client = HttpClient(CIO) { +val client = HttpClient(CIO) + +// Sending a single request to a Unix domain socket +val response: HttpResponse = client.get("/") { + unixSocket("/tmp/test-unix-socket-ktor.sock") +} + +// Setting up the socket for all requests from that client +val clientDefault = HttpClient(CIO) { defaultRequest { unixSocket("/tmp/test-unix-socket-ktor.sock") } } -val response: HttpResponse = client.get("/") +val response: HttpResponse = clientDefault.get("/") ``` ## Example {id="example"} From 4d21a4b097dd2a87b4ce518759271a821c34061e Mon Sep 17 00:00:00 2001 From: Aleksey Zamulla Date: Tue, 24 Jun 2025 15:21:57 +0200 Subject: [PATCH 07/10] fix: tw review Co-authored-by: Vik Nikolova --- topics/client-default-request.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/topics/client-default-request.md b/topics/client-default-request.md index 3a7aa8d0a..5a37d1b62 100644 --- a/topics/client-default-request.md +++ b/topics/client-default-request.md @@ -102,7 +102,7 @@ defaultRequest { ### Unix domain sockets -> Unix domain sockets are supported only in the CIO engine, for Ktor server as well as Ktor client. +> Unix domain sockets are supported only in the CIO engine. > {style="note"} From 2aed15d242b8a7a1b189e866d501dad2951f585b Mon Sep 17 00:00:00 2001 From: "Aleksey.Zamulla" Date: Wed, 25 Jun 2025 10:52:37 +0200 Subject: [PATCH 08/10] fix: removing server-specific stuff from the client --- topics/client-requests.md | 21 +++------------------ 1 file changed, 3 insertions(+), 18 deletions(-) diff --git a/topics/client-requests.md b/topics/client-requests.md index 62a72f394..17236fd17 100644 --- a/topics/client-requests.md +++ b/topics/client-requests.md @@ -122,26 +122,12 @@ To disable encoding, use `encodedFragment`. ## Specify a Unix domain socket -> Unix domain sockets are supported only in the CIO engine, for Ktor server as well as Ktor client. +> Unix domain sockets are supported only in the CIO engine. +> To use a Unix socket with a Ktor server, [configure the server](server-configuration-code.topic#cio-code) accordingly. > {style="note"} -To use a Unix socket, [configure the server](server-configuration-code.topic#cio-code) -by adding a `unixConnector` with the path to the socket, for example: - -```kotlin -val server = embeddedServer(CIO, configure = { - unixConnector("/tmp/test-unix-socket-ktor.sock") -}) { - routing { - get("/") { - call.respondText("Hello, Unix socket world!") - } - } -} -``` - -Then you can make requests to a server listening to that socket by calling the `unixSocket` function +You can make requests to a server listening to a Unix domain socket by calling the `unixSocket` function for a CIO client: ```kotlin @@ -154,7 +140,6 @@ val response: HttpResponse = client.get("/") { You can also set up a Unix domain socket as a part of a [default request](client-default-request.md#unix-domain-sockets). - ## Set request parameters {id="parameters"} In this section, we'll see how to specify various request parameters, including an HTTP method, headers, and cookies. If you need to configure some default parameters for all requests of a specific client, use the [DefaultRequest](client-default-request.md) plugin. From 48e2cae6b1fc25e21fe498cc2ce4f18327ae13ed Mon Sep 17 00:00:00 2001 From: "Aleksey.Zamulla" Date: Wed, 25 Jun 2025 11:06:35 +0200 Subject: [PATCH 09/10] update: adding UDS to what's new 3.2.0 --- topics/whats-new-320.md | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/topics/whats-new-320.md b/topics/whats-new-320.md index d7ba1c493..4217d8db9 100644 --- a/topics/whats-new-320.md +++ b/topics/whats-new-320.md @@ -203,6 +203,37 @@ Ktor’s HTMX support is available across three experimental modules: All APIs are marked with `@ExperimentalKtorApi` and require opt-in via `@OptIn(ExperimentalKtorApi::class)`. For more information, see [](htmx-integration.md). +## Unix domain sockets + +With 3.2.0, you can set up Ktor clients to connect to Unix domain sockets and Ktor servers to listen to such sockets. +Right now, Unix domain sockets are only supported in the CIO engine. + +Example of a server configuration: + +```kotlin +val server = embeddedServer(CIO, configure = { + unixConnector("/tmp/test-unix-socket-ktor.sock") +}) { + routing { + get("/") { + call.respondText("Hello, Unix socket world!") + } + } +} +``` + +Connecting to that socket using a Ktor client: + +```kotlin +val client = HttpClient(CIO) + +val response: HttpResponse = client.get("/") { + unixSocket("/tmp/test-unix-socket-ktor.sock") +} +``` + +You can also use a Unix domain socket in a [default request](client-default-request.md#unix-domain-sockets). + ## Infrastructure ### Published version catalog From 30322afaec2e917678033d1e785063b9a330c481 Mon Sep 17 00:00:00 2001 From: Aleksey Zamulla Date: Wed, 25 Jun 2025 17:18:49 +0200 Subject: [PATCH 10/10] fix: TW review phrasing Co-authored-by: Vik Nikolova --- topics/whats-new-320.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/topics/whats-new-320.md b/topics/whats-new-320.md index 4217d8db9..46b297422 100644 --- a/topics/whats-new-320.md +++ b/topics/whats-new-320.md @@ -206,7 +206,7 @@ For more information, see [](htmx-integration.md). ## Unix domain sockets With 3.2.0, you can set up Ktor clients to connect to Unix domain sockets and Ktor servers to listen to such sockets. -Right now, Unix domain sockets are only supported in the CIO engine. +Currently, Unix domain sockets are only supported in the CIO engine. Example of a server configuration: