HttpClient

class HttpClient : CoroutineScope, Closeable

Asynchronous client to perform HTTP requests.

This is a generic implementation that uses a specific engine HttpClientEngine.

Constructors

<init>

HttpClient(
    engine: HttpClientEngine,
    userConfig: HttpClientConfig<out HttpClientEngineConfig> = HttpClientConfig())

Asynchronous client to perform HTTP requests.

Properties

attributes

val attributes: Attributes

Typed attributes used as a lightweight container for this client.

coroutineContext

val coroutineContext: <ERROR CLASS>

dispatcher

val dispatcher: CoroutineDispatcher

Dispatcher handles io operations

engine

val engine: HttpClientEngine

: HttpClientEngine for executing requests.

engineConfig

val engineConfig: HttpClientEngineConfig

Client engine config

receivePipeline

val receivePipeline: HttpReceivePipeline

Pipeline used for receiving request

requestPipeline

val requestPipeline: HttpRequestPipeline

Pipeline used for processing all the requests sent by this client.

responsePipeline

val responsePipeline: HttpResponsePipeline

Pipeline used for processing all the responses sent by the server.

sendPipeline

val sendPipeline: HttpSendPipeline

Pipeline used for sending the request

Functions

close

fun close(): Unit

Closes the underlying engine.

config

fun config(block: HttpClientConfig<*>.() -> Unit): HttpClient

Returns a new HttpClient copying this client configuration, and additionally configured by the block parameter.

execute

suspend fun execute(
    builder: HttpRequestBuilder
): HttpClientCall

Creates a new HttpRequest from a request data and a specific client call.

Extension Functions

call

suspend fun HttpClient.call(
    block: suspend HttpRequestBuilder.() -> Unit = {}
): HttpClientCall

Constructs a HttpClientCall from this HttpClient and with the specified HttpRequestBuilder configured inside the block.

suspend fun HttpClient.call(
    builder: HttpRequestBuilder
): HttpClientCall

Constructs a HttpClientCall from this HttpClient and with the specified HTTP request builder.

suspend fun HttpClient.call(
    urlString: String,
    block: suspend HttpRequestBuilder.() -> Unit = {}
): HttpClientCall
suspend fun HttpClient.call(
    url: Url,
    block: suspend HttpRequestBuilder.() -> Unit = {}
): HttpClientCall
suspend fun HttpClient.call(
    url: URL,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpClientCall

Constructs a HttpClientCall from this HttpClient, an url and an optional block configuring a HttpRequestBuilder.

cookies

suspend fun HttpClient.cookies(url: Url): List<Cookie>

Gets all the cookies for the specified url for this HttpClient.

suspend fun HttpClient.cookies(
    urlString: String
): List<Cookie>

Gets all the cookies for the specified urlString for this HttpClient.

decodeChunked

fun CoroutineScope.decodeChunked(
    input: ByteReadChannel
): DecoderJob

Start a chunked stream decoder coroutine

defaultTransformers

fun HttpClient.defaultTransformers(): Unit

Install default transformers. Usually installed by default so there is no need to use it unless you have disabled it via HttpClientConfig.useDefaultTransformers.

delete

suspend fun <T> HttpClient.delete(
    builder: HttpRequestBuilder
): T

Executes a HttpClient DELETE request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.delete(
    scheme: String = "http",
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    body: Any = EmptyContent,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient DELETE request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.delete(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient DELETE request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.delete(
    url: Url,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient HEAD request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.delete(
    url: URL,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient HEAD request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

embeddedServer

fun <TEngine : ApplicationEngine, TConfiguration : Configuration> CoroutineScope.embeddedServer(
    factory: ApplicationEngineFactory<TEngine, TConfiguration>,
    port: Int = 80,
    host: String = "0.0.0.0",
    watchPaths: List<String> = emptyList(),
    parentCoroutineContext: <ERROR CLASS> = EmptyCoroutineContext,
    configure: TConfiguration.() -> Unit = {},
    module: Application.() -> Unit
): TEngine

Creates an embedded server with the given factory, listening on host:port

feature

fun <B : Any, F : Any> HttpClient.feature(
    feature: HttpClientFeature<B, F>
): F?

Try to get a feature installed in this client. Returns null if the feature was not previously installed.

get

suspend fun <T> HttpClient.get(
    builder: HttpRequestBuilder
): T

Executes a HttpClient GET request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.get(
    scheme: String = "http",
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    body: Any = EmptyContent,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient GET request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.get(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): T
suspend fun <T> HttpClient.get(
    url: URL,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient GET request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.get(
    url: Url,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient GET request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

head

suspend fun <T> HttpClient.head(
    builder: HttpRequestBuilder
): T

Executes a HttpClient HEAD request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.head(
    scheme: String = "http",
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    body: Any = EmptyContent,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient HEAD request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.head(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): T
suspend fun <T> HttpClient.head(
    url: URL,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient HEAD request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.head(
    url: Url,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient HEAD request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

httpServer

fun CoroutineScope.httpServer(
    settings: HttpServerSettings,
    handler: HttpRequestHandler
): HttpServer

Start an http server with settings invoking handler for every request

options

suspend fun <T> HttpClient.options(
    builder: HttpRequestBuilder
): T

Executes a HttpClient OPTIONS request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.options(
    scheme: String = "http",
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    body: Any = EmptyContent,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient OPTIONS request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.options(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): T
suspend fun <T> HttpClient.options(
    url: URL,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient OPTIONS request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.options(
    url: Url,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient OPTIONS request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

parseMultipart

fun CoroutineScope.parseMultipart(
    input: ByteReadChannel,
    headers: HttpHeadersMap
): ReceiveChannel<MultipartEvent>
fun CoroutineScope.parseMultipart(
    input: ByteReadChannel,
    contentType: CharSequence,
    contentLength: Long?
): ReceiveChannel<MultipartEvent>
fun CoroutineScope.parseMultipart(
    boundaryPrefixed: ByteBuffer,
    input: ByteReadChannel,
    totalLength: Long?
): ReceiveChannel<MultipartEvent>

Starts a multipart parser coroutine producing multipart events

patch

suspend fun <T> HttpClient.patch(
    builder: HttpRequestBuilder
): T

Executes a HttpClient PATCH request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.patch(
    scheme: String = "http",
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    body: Any = EmptyContent,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient PATCH request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.patch(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): T
suspend fun <T> HttpClient.patch(
    url: URL,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient PATCH request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.patch(
    url: Url,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient PATCH request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

pinger

fun CoroutineScope.pinger(
    outgoing: SendChannel<Frame>,
    period: Duration,
    timeout: Duration,
    pool: ObjectPool<ByteBuffer> = KtorDefaultPool
): SendChannel<Pong>

Launch pinger coroutine on CoroutineScope that is sending ping every specified period to outgoing channel, waiting for and verifying client’s pong frames. It is also handling timeout and sending timeout close frame

fun CoroutineScope.pinger(
    outgoing: SendChannel<Frame>,
    periodMillis: Long,
    timeoutMillis: Long,
    pool: ObjectPool<ByteBuffer> = KtorDefaultPool
): SendChannel<Pong>

Launch pinger coroutine on CoroutineScope that is sending ping every specified periodMillis to outgoing channel, waiting for and verifying client’s pong frames. It is also handling timeoutMillis and sending timeout close frame

ponger

fun CoroutineScope.ponger(
    outgoing: SendChannel<Pong>,
    pool: ObjectPool<ByteBuffer> = KtorDefaultPool
): SendChannel<Ping>

Launch a ponger actor job on the CoroutineScope sending pongs to outgoing channel. It is acting for every client’s ping frame and replying with corresponding pong

post

suspend fun <T> HttpClient.post(
    builder: HttpRequestBuilder
): T

Executes a HttpClient POST request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.post(
    scheme: String = "http",
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    body: Any = EmptyContent,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient POST request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.post(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): T
suspend fun <T> HttpClient.post(
    url: URL,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient POST request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.post(
    url: Url,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient POST request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

put

suspend fun <T> HttpClient.put(
    builder: HttpRequestBuilder
): T

Executes a HttpClient PUT request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.put(
    scheme: String = "http",
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    body: Any = EmptyContent,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient PUT request, with the specified scheme, host, port, path and body. And allows to further configure the request, using a block receiving an HttpRequestBuilder.

suspend fun <T> HttpClient.put(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): T
suspend fun <T> HttpClient.put(
    url: URL,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient PUT request, with the specified url as URL and an optional block receiving an HttpRequestBuilder for further configuring the request.

suspend fun <T> HttpClient.put(
    url: Url,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Executes a HttpClient PUT request, with the specified url as Url and an optional block receiving an HttpRequestBuilder for further configuring the request.

request

suspend fun <T> HttpClient.request(
    builder: HttpRequestBuilder = HttpRequestBuilder()
): T

Executes a HttpClient request, with the information from the builder and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.request(
    block: HttpRequestBuilder.() -> Unit
): T

Executes a HttpClient request, with the information configured in builder block and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.request(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit
): T

Executes a HttpClient request, with the urlString and the information configured in builder block and tries to receive a specific type T, if fails, an exception is thrown.

suspend fun <T> HttpClient.request(
    url: Url,
    block: HttpRequestBuilder.() -> Unit
): T

Executes a HttpClient request, with the url and the information configured in builder block and tries to receive a specific type T, if fails, an exception is thrown.

startConnectionPipeline

fun CoroutineScope.startConnectionPipeline(
    input: ByteReadChannel,
    output: ByteWriteChannel,
    timeout: WeakTimeoutQueue,
    handler: HttpRequestHandler
): Job

Start connection HTTP pipeline invoking handler for every request. Note that handler could be invoked multiple times concurrently due to HTTP pipeline nature

submitForm

suspend fun <T> HttpClient.submitForm(
    formParameters: Parameters = Parameters.Empty,
    encodeInQuery: Boolean = false,
    block: HttpRequestBuilder.() -> Unit = {}
): T
suspend fun <T> HttpClient.submitForm(
    url: String,
    formParameters: Parameters = Parameters.Empty,
    encodeInQuery: Boolean = false,
    block: HttpRequestBuilder.() -> Unit = {}
): T
suspend fun <T> HttpClient.submitForm(
    scheme: String = "http",
    host: String = "localhost",
    port: Int = 80,
    path: String = "/",
    formParameters: Parameters = Parameters.Empty,
    encodeInQuery: Boolean = false,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Submit formParameters request.

submitFormWithBinaryData

suspend fun <T> HttpClient.submitFormWithBinaryData(
    formData: List<PartData>,
    block: HttpRequestBuilder.() -> Unit = {}
): T
suspend fun <T> HttpClient.submitFormWithBinaryData(
    scheme: String = "http",
    host: String = "localhost",
    port: Int = 80,
    path: String = "/",
    formData: List<PartData> = emptyList(),
    block: HttpRequestBuilder.() -> Unit = {}
): T

Send HttpMethod.Post request with formData encoded in body. formData encoded using multipart/form-data format. https://tools.ietf.org/html/rfc2045

suspend fun <T> HttpClient.submitFormWithBinaryData(
    url: String,
    formData: List<PartData>,
    block: HttpRequestBuilder.() -> Unit = {}
): T

Send HttpMethod.Post request with formData encoded in body. url destination formData encoded using multipart/form-data format.

webSocket

suspend fun HttpClient.webSocket(
    request: HttpRequestBuilder.() -> Unit,
    block: suspend DefaultClientWebSocketSession.() -> Unit
): Unit
suspend fun HttpClient.webSocket(
    method: HttpMethod = HttpMethod.Get,
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend DefaultClientWebSocketSession.() -> Unit
): Unit
suspend fun HttpClient.webSocket(
    urlString: String,
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend DefaultClientWebSocketSession.() -> Unit
): Unit

Open block with DefaultClientWebSocketSession.

webSocketRaw

suspend fun HttpClient.webSocketRaw(
    method: HttpMethod = HttpMethod.Get,
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend ClientWebSocketSession.() -> Unit
): Unit

Create raw ClientWebSocketSession: no ping-pong and other service messages are used.

webSocketRawSession

suspend fun HttpClient.webSocketRawSession(
    method: HttpMethod = HttpMethod.Get,
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    block: HttpRequestBuilder.() -> Unit = {}
): ClientWebSocketSession

Create raw ClientWebSocketSession: no ping-pong and other service messages are used.

webSocketSession

suspend fun HttpClient.webSocketSession(
    block: HttpRequestBuilder.() -> Unit
): DefaultClientWebSocketSession
suspend fun HttpClient.webSocketSession(
    method: HttpMethod = HttpMethod.Get,
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    block: HttpRequestBuilder.() -> Unit = {}
): DefaultClientWebSocketSession

Open DefaultClientWebSocketSession.

writeMultipleRanges

fun CoroutineScope.writeMultipleRanges(
    channelProducer: (LongRange) -> ByteReadChannel,
    ranges: List<LongRange>,
    fullLength: Long?,
    boundary: String,
    contentType: String
): ByteReadChannel

Start multirange response writer coroutine

ws

suspend fun HttpClient.ws(
    urlString: String,
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend DefaultClientWebSocketSession.() -> Unit
): Unit

Open DefaultClientWebSocketSession.

suspend fun HttpClient.ws(
    method: HttpMethod = HttpMethod.Get,
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend DefaultClientWebSocketSession.() -> Unit
): Unit
suspend fun HttpClient.ws(
    request: HttpRequestBuilder.() -> Unit,
    block: suspend DefaultClientWebSocketSession.() -> Unit
): Unit

Open block with DefaultClientWebSocketSession.

wsRaw

suspend fun HttpClient.wsRaw(
    method: HttpMethod = HttpMethod.Get,
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend ClientWebSocketSession.() -> Unit
): Unit

Create raw ClientWebSocketSession: no ping-pong and other service messages are used.

wss

suspend fun HttpClient.wss(
    request: HttpRequestBuilder.() -> Unit,
    block: suspend DefaultClientWebSocketSession.() -> Unit
): Unit
suspend fun HttpClient.wss(
    urlString: String,
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend DefaultClientWebSocketSession.() -> Unit
): Unit
suspend fun HttpClient.wss(
    method: HttpMethod = HttpMethod.Get,
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend DefaultClientWebSocketSession.() -> Unit
): Unit

Open block with secure DefaultClientWebSocketSession.

wssRaw

suspend fun HttpClient.wssRaw(
    method: HttpMethod = HttpMethod.Get,
    host: String = "localhost",
    port: Int = DEFAULT_PORT,
    path: String = "/",
    request: HttpRequestBuilder.() -> Unit = {},
    block: suspend ClientWebSocketSession.() -> Unit
): Unit

Create secure raw ClientWebSocketSession: no ping-pong and other service messages are used.