tessl/maven-io-ktor--ktor

A multiplatform asynchronous framework for creating microservices, web applications, and HTTP clients written in Kotlin from the ground up

—

Pending

Overview

Eval results

Files

HTTP Request Operations

Name: tessl/maven-io-ktor--ktor
Author: tessl

HTTP method extensions and request building functionality for making various types of HTTP requests with type-safe configuration.

Capabilities

HTTP Method Extensions

Convenient extension functions for common HTTP methods with various parameter combinations.

/**
 * Perform a GET request
 * @param urlString The URL to request
 * @param block Configuration block for the request
 * @return HttpResponse from the server
 */
suspend fun HttpClient.get(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpResponse

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

suspend fun HttpClient.get(
    block: HttpRequestBuilder.() -> Unit
): HttpResponse

/**
 * Perform a POST request
 * @param urlString The URL to request
 * @param block Configuration block for the request
 * @return HttpResponse from the server
 */
suspend fun HttpClient.post(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpResponse

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

suspend fun HttpClient.post(
    block: HttpRequestBuilder.() -> Unit
): HttpResponse

/**
 * Perform a PUT request
 * @param urlString The URL to request
 * @param block Configuration block for the request
 * @return HttpResponse from the server
 */
suspend fun HttpClient.put(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpResponse

/**
 * Perform a DELETE request
 * @param urlString The URL to request
 * @param block Configuration block for the request
 * @return HttpResponse from the server
 */
suspend fun HttpClient.delete(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpResponse

/**
 * Perform a PATCH request
 * @param urlString The URL to request
 * @param block Configuration block for the request
 * @return HttpResponse from the server
 */
suspend fun HttpClient.patch(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpResponse

/**
 * Perform an OPTIONS request
 * @param urlString The URL to request
 * @param block Configuration block for the request
 * @return HttpResponse from the server
 */
suspend fun HttpClient.options(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpResponse

/**
 * Perform a HEAD request
 * @param urlString The URL to request
 * @param block Configuration block for the request
 * @return HttpResponse from the server
 */
suspend fun HttpClient.head(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpResponse

Usage Examples:

import io.ktor.client.*
import io.ktor.client.request.*
import io.ktor.http.*

val client = HttpClient()

// Simple GET request
val response = client.get("https://api.example.com/users")

// POST with body and headers
val postResponse = client.post("https://api.example.com/users") {
    header(HttpHeaders.ContentType, ContentType.Application.Json)
    setBody("""{"name": "John", "email": "john@example.com"}""")
}

// PUT with query parameters
val putResponse = client.put("https://api.example.com/users/123") {
    parameter("include", "profile")
    setBody(userUpdateData)
}

// DELETE request
val deleteResponse = client.delete("https://api.example.com/users/123")

Prepared Request Extensions

Extensions that return HttpStatement for deferred execution, allowing for more control over request execution.

/**
 * Prepare a GET request for deferred execution
 * @param urlString The URL to request
 * @param block Configuration block for the request
 * @return HttpStatement for deferred execution
 */
suspend fun HttpClient.prepareGet(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpStatement

suspend fun HttpClient.preparePost(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpStatement

suspend fun HttpClient.preparePut(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpStatement

suspend fun HttpClient.prepareDelete(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpStatement

suspend fun HttpClient.preparePatch(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpStatement

suspend fun HttpClient.prepareOptions(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpStatement

suspend fun HttpClient.prepareHead(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpStatement

Usage Examples:

import io.ktor.client.*
import io.ktor.client.request.*
import io.ktor.client.statement.*

val client = HttpClient()

// Prepare request for later execution
val statement = client.prepareGet("https://api.example.com/users")

// Execute the request
val response = statement.execute()

// Or execute with custom handling
val result = statement.execute { response ->
    if (response.status.isSuccess()) {
        response.bodyAsText()
    } else {
        "Error: ${response.status}"
    }
}

Generic Request Methods

Generic request functions that accept any HTTP method and provide maximum flexibility.

/**
 * Perform a generic HTTP request
 * @param block Configuration block for the request
 * @return HttpResponse from the server
 */
suspend fun HttpClient.request(
    block: HttpRequestBuilder.() -> Unit
): HttpResponse

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

suspend fun HttpClient.request(
    url: Url,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpResponse

/**
 * Prepare a generic HTTP request for deferred execution
 * @param block Configuration block for the request
 * @return HttpStatement for deferred execution
 */
suspend fun HttpClient.prepareRequest(
    block: HttpRequestBuilder.() -> Unit
): HttpStatement

suspend fun HttpClient.prepareRequest(
    urlString: String,
    block: HttpRequestBuilder.() -> Unit = {}
): HttpStatement

Usage Examples:

import io.ktor.client.*
import io.ktor.client.request.*
import io.ktor.http.*

val client = HttpClient()

// Generic request with custom method
val response = client.request {
    method = HttpMethod.Patch
    url("https://api.example.com/users/123")
    header("Authorization", "Bearer $token")
    setBody(patchData)
}

// Prepared generic request
val statement = client.prepareRequest("https://api.example.com/data") {
    method = HttpMethod.Get
    parameter("limit", 50)
}

HttpRequestBuilder Class

Mutable builder for constructing HTTP requests with DSL syntax.

/**
 * Builder for constructing HTTP requests
 */
class HttpRequestBuilder : HttpMessageBuilder {
    /** URL builder for the request */
    val url: URLBuilder
    
    /** HTTP method for the request */
    var method: HttpMethod = HttpMethod.Get
    
    /** Headers builder for the request */
    override val headers: HeadersBuilder
    
    /** Request body content */
    var body: Any = EmptyContent
    
    /** Type information for the body */
    var bodyType: TypeInfo?
    
    /** Execution context for the request */
    var executionContext: Job
    
    /** Attributes for storing request metadata */
    val attributes: Attributes
    
    /**
     * Configure the URL
     * @param block Configuration block for URLBuilder
     */
    fun url(block: URLBuilder.(URLBuilder) -> Unit)
    
    /**
     * Build the final request data
     * @return Immutable HttpRequestData
     */
    fun build(): HttpRequestData
    
    /**
     * Configure request attributes
     * @param block Configuration block for attributes
     */
    fun setAttributes(block: Attributes.() -> Unit)
    
    /**
     * Set an engine capability
     * @param key The capability key
     * @param capability The capability value
     */
    fun <T : Any> setCapability(
        key: HttpClientEngineCapability<T>,
        capability: T
    )
    
    /**
     * Get an engine capability
     * @param key The capability key
     * @return Capability value or null if not set
     */
    fun <T : Any> getCapabilityOrNull(
        key: HttpClientEngineCapability<T>
    ): T?
}

Usage Examples:

import io.ktor.client.*
import io.ktor.client.request.*
import io.ktor.http.*

// Using request builder in a request block
val response = client.post {
    // Configure URL
    url {
        protocol = URLProtocol.HTTPS
        host = "api.example.com"
        path("users")
    }
    
    // Set method and headers
    method = HttpMethod.Post
    header("Content-Type", "application/json")
    header("Authorization", "Bearer $token")
    
    // Set body
    setBody(userData)
    
    // Configure attributes
    setAttributes {
        put(customAttribute, "value")
    }
}

HttpRequestData Class

Immutable request data that is passed to HTTP engines for execution.

/**
 * Immutable HTTP request data
 */
class HttpRequestData(
    val url: Url,
    val method: HttpMethod,
    val headers: Headers,
    val body: OutgoingContent,
    val executionContext: Job,
    val attributes: Attributes
) {
    /**
     * Get an engine capability
     * @param key The capability key
     * @return Capability value or null if not set
     */
    fun <T> getCapabilityOrNull(
        key: HttpClientEngineCapability<T>
    ): T?
    
    /** Set of required engine capabilities */
    internal val requiredCapabilities: Set<HttpClientEngineCapability<*>>
}

Request Configuration Extensions

Utility extensions for common request configuration patterns.

/**
 * Set request header
 * @param key Header name
 * @param value Header value
 */
fun HttpMessageBuilder.header(key: String, value: Any?)

/**
 * Configure headers
 * @param block Configuration block for headers
 * @return HeadersBuilder instance
 */
fun HttpMessageBuilder.headers(
    block: HeadersBuilder.() -> Unit
): HeadersBuilder

/**
 * Set User-Agent header
 * @param agent User agent string
 */
fun HttpRequestBuilder.userAgent(agent: String)

/**
 * Set Accept header
 * @param contentType Content type to accept
 */
fun HttpRequestBuilder.accept(contentType: ContentType)

/**
 * Set request body
 * @param body Body content
 */
fun HttpRequestBuilder.setBody(body: Any)

/**
 * Add URL parameter
 * @param key Parameter name
 * @param value Parameter value
 */
fun HttpRequestBuilder.parameter(key: String, value: Any?)

Usage Examples:

import io.ktor.client.*
import io.ktor.client.request.*
import io.ktor.http.*

val response = client.get("https://api.example.com/users") {
    // Headers
    header("X-Custom-Header", "value")
    userAgent("MyApp/1.0")
    accept(ContentType.Application.Json)
    
    // Parameters
    parameter("limit", 10)
    parameter("offset", 0)
    parameter("include", "profile")
}

Types

Request operation related types:

/**
 * HTTP methods enumeration
 */
enum class HttpMethod(val value: String) {
    Get("GET"),
    Post("POST"),
    Put("PUT"),
    Delete("DELETE"),
    Head("HEAD"),
    Options("OPTIONS"),
    Patch("PATCH")
}

/**
 * URL builder for constructing URLs
 */
class URLBuilder {
    var protocol: URLProtocol
    var host: String
    var port: Int
    var pathSegments: List<String>
    var parameters: ParametersBuilder
    var fragment: String
    
    fun path(vararg components: String)
    fun build(): Url
}

/**
 * Parameters builder for URL parameters
 */
interface ParametersBuilder {
    fun append(name: String, value: String)
    fun appendAll(name: String, values: Iterable<String>)
    fun set(name: String, value: String)
    fun remove(name: String)
    fun clear()
}

/**
 * Empty content object for requests without body
 */
object EmptyContent : OutgoingContent.NoContent()

Install with Tessl CLI