Package io.ktor.http

Types

CacheControl

sealed class CacheControl

Represents a value for a Cache-Control header

ContentDisposition

class ContentDisposition : HeaderValueWithParameters

Represents Content-Disposition header value

ContentRange

sealed class ContentRange

Represents a Range header’s particular range

ContentType

class ContentType : HeaderValueWithParameters

Represents a value for a Content-Type header.

Cookie

data class Cookie

Represents a cooke value

CookieEncoding

enum class CookieEncoding

Cooke encoding strategy

EmptyHeaders

object EmptyHeaders : Headers

EmptyParameters

object EmptyParameters : Parameters

HeaderValue

data class HeaderValue

Represents a header value. Similar to HeaderValueWithParameters

HeaderValueParam

data class HeaderValueParam

Represents a single value parameter

HeaderValueWithParameters

abstract class HeaderValueWithParameters

Represents a header value that consist of content followed by parameters. Useful for headers such as Content-Type, Content-Disposition and so on.

Headers

interface Headers : StringValues

Represents HTTP headers as a map from case-insensitive names to collection of String values

HeadersBuilder

class HeadersBuilder : StringValuesBuilder

HeadersImpl

class HeadersImpl : Headers, StringValuesImpl

HeadersSingleImpl

class HeadersSingleImpl : Headers, StringValuesSingleImpl

HttpHeaders

object HttpHeaders

HttpMessage

interface HttpMessage

A message either from the client or the server, that has headers associated.

HttpMessageBuilder

interface HttpMessageBuilder

A builder message either for the client or the server, that has a headers builder associated.

HttpMethod

data class HttpMethod

Represents an HTTP method (verb)

HttpProtocolVersion

data class HttpProtocolVersion

Represents an HTTP protocol version.

HttpStatusCode

data class HttpStatusCode

Represents an HTTP status code and description.

LinkHeader

class LinkHeader : HeaderValueWithParameters

Represents a Link header value as per RFC 5988

Parameters

interface Parameters : StringValues

Represents HTTP parameters as a map from case-insensitive names to collection of String values

ParametersBuilder

class ParametersBuilder : StringValuesBuilder

ParametersImpl

class ParametersImpl : Parameters, StringValuesImpl

ParametersSingleImpl

class ParametersSingleImpl : 
    Parameters,
    StringValuesSingleImpl

RangeUnits

enum class RangeUnits

Possible content range units: bytes and none

RangesSpecifier

data class RangesSpecifier

Range specifier for partial content requests (RFC 2616 sec 14.35.1)

RequestConnectionPoint

interface RequestConnectionPoint

Represents request address information is used to make a call. There are at least two possible instances: “local” is how we see request at the server application and “actual” is what we can recover from proxy provided headers.

URLBuilder

class URLBuilder

A URL builder with all mutable components

URLProtocol

data class URLProtocol

Represents URL protocol

Url

data class Url

Represents an immutable URL

Exceptions

BadContentTypeFormatException

class BadContentTypeFormatException : Exception

Exception thrown when a content type string is malformed.

URLDecodeException

class URLDecodeException : Exception

URL decoder exception

URLParserException

class URLParserException : IllegalStateException

Thrown when failed to parse URL

UnsafeHeaderException

class UnsafeHeaderException : IllegalArgumentException

Thrown when an attempt to set unsafe header detected. A header is unsafe if listed in HttpHeaders.UnsafeHeaders.

Extensions for External Classes

java.time.temporal.Temporal

kotlin.Long

kotlin.String

kotlin.collections.Iterable

kotlin.collections.List

Properties

DEFAULT_PORT

const val DEFAULT_PORT: Int

Select default port value from protocol.

fullPath

val Url.fullPath: String

Full encoded path with query string but without domain, port and schema

hostWithPort

val Url.hostWithPort: String

Host:port pair, not normalized so port is always specified even if the port is schema’s default

httpDateFormat

val httpDateFormat: DateTimeFormatter

Default HTTP date format

Functions

URLBuilder

fun URLBuilder(urlString: String): URLBuilder

Construct URLBuilder from urlString.

fun URLBuilder(url: Url): URLBuilder

Construct URLBuilder from url.

fun URLBuilder(builder: URLBuilder): URLBuilder

Construct URLBuilder from builder.

Url

fun Url(urlString: String): Url

Construct Url from urlString.

fun Url(builder: URLBuilder): Url

Construct Url from builder without building origin.

append

fun StringValuesBuilder.append(
    name: String,
    value: HeaderValueWithParameters
): Unit

Append formatted header value to the builder

cacheControl

fun HttpMessage.cacheControl(): List<HeaderValue>

Parse CacheControl header.

charset

fun HeaderValueWithParameters.charset(): Charset?

Extracts a Charset value from the given Content-Type, Content-Disposition or similar header value.

fun HttpMessageBuilder.charset(charset: Charset): Unit?
fun HttpMessageBuilder.charset(): Charset?
fun HttpMessage.charset(): Charset?

Parse charset from Content-Type header value.

clone

fun URLBuilder.clone(): URLBuilder

Create a copy of this builder. Modifications in a copy is not reflected in the original instance and vise-versa.

contentLength

fun HttpMessageBuilder.contentLength(length: Int): Unit
fun HttpMessageBuilder.contentLength(): Long?
fun HttpMessage.contentLength(): Long?

Parse Content-Length header value.

contentRangeHeaderValue

fun contentRangeHeaderValue(
    range: LongRange?,
    fullLength: Long? = null,
    unit: RangeUnits = RangeUnits.Bytes
): String
fun contentRangeHeaderValue(
    range: LongRange?,
    fullLength: Long? = null,
    unit: String = RangeUnits.Bytes.unitToken
): String

Format Content-Range header value

contentType

fun HttpMessageBuilder.contentType(type: ContentType): Unit

Set Content-Type header.

fun HttpMessageBuilder.contentType(): ContentType?
fun HttpMessage.contentType(): ContentType?

Parse Content-Type header value.

cookies

Parse Set-Cookie header value.

date

fun HttpMessage.date(): Date?

Parse Date header.

decodeCookieValue

fun decodeCookieValue(
    encodedValue: String,
    encoding: CookieEncoding
): String

Decode cookie value using the specified encoding

encodeCookieValue

fun encodeCookieValue(
    value: String,
    encoding: CookieEncoding
): String

Encode cookie value using the specified encoding

etag

fun HeadersBuilder.etag(entityTag: String): Unit

Set E-Tag header

fun HttpMessage.etag(): String?

Parse E-Tag header value.

expires

fun HeadersBuilder.expires(expires: LocalDateTime): Unit

Set ‘Expires` header value from expires

fun HttpMessageBuilder.expires(): Date?
fun HttpMessage.expires(): Date?

Parse Expires header.

fileExtensions

fun ContentType.fileExtensions(): List<String>

Recommended file name extensions for this content type

formUrlEncode

fun Parameters.formUrlEncode(): String

Encode form parameters

formUrlEncodeTo

fun Parameters.formUrlEncodeTo(out: Appendable): Unit

Encode form parameters to the specified out appendable

headersOf

fun headersOf(): Headers

Returns empty headers

fun headersOf(name: String, value: String): Headers

Returns Headers instance containing only one header with the specified name and value

fun headersOf(name: String, values: List<String>): Headers

Returns Headers instance containing only one header with the specified name and values

fun headersOf(
    vararg pairs: Pair<String, List<String>>
): Headers

Returns Headers instance from pairs

hostIsIp

fun hostIsIp(host: String): Boolean

Check if host is IPv4 or IPv6 address.

ifModifiedSince

fun HttpMessageBuilder.ifModifiedSince(date: Date): Unit

Set If-Modified-Since header.

ifNoneMatch

fun HttpMessageBuilder.ifNoneMatch(value: String): Unit

Set If-None-Match header value.

isSecure

fun URLProtocol.isSecure(): Boolean

Check if the protocol is secure

isSuccess

fun HttpStatusCode.isSuccess(): Boolean

Checks if a given status code is a success code according to HTTP standards.

isWebsocket

fun URLProtocol.isWebsocket(): Boolean

Check if the protocol is websocket

lastModified

fun HeadersBuilder.lastModified(
    dateTime: ZonedDateTime
): Unit

Set ‘Last-Modified` header value from dateTime

fun HttpMessageBuilder.lastModified(): Date?
fun HttpMessage.lastModified(): Date?

Parse Last-Modified header.

link

fun ApplicationResponse.link(header: LinkHeader): Unit

Append Link header to HTTP response

fun ApplicationResponse.link(
    uri: String,
    vararg rel: String
): Unit

Append Link header to HTTP response with specified uri and rel

maxAge

fun HttpMessageBuilder.maxAge(seconds: Int): Unit

Append Max-Age header value.

parametersOf

fun parametersOf(): Parameters

Returns an empty parameters instance

fun parametersOf(name: String, value: String): Parameters

Creates a parameters instance containing only single pair

fun parametersOf(
    name: String,
    values: List<String>
): Parameters

Creates a parameters instance containing only single pair of name with multiple values

fun parametersOf(
    vararg pairs: Pair<String, List<String>>
): Parameters

Creates a parameters instance from the specified pairs

parseAndSortContentTypeHeader

fun parseAndSortContentTypeHeader(
    header: String?
): List<HeaderValue>

Parse Content-Type header values and sort them by quality and asterisks quantity

parseAndSortHeader

fun parseAndSortHeader(header: String?): List<HeaderValue>

Parse header value and sort multiple values according to qualities

parseClientCookiesHeader

fun parseClientCookiesHeader(
    cookiesHeader: String,
    skipEscaped: Boolean = true
): Map<String, String>

Parse client’s Cookie header value

parseHeaderValue

fun parseHeaderValue(text: String?): List<HeaderValue>
fun parseHeaderValue(
    text: String?,
    parametersOnly: Boolean
): List<HeaderValue>

Parse header value respecting multi-values

parseQueryString

fun parseQueryString(
    query: String,
    startIndex: Int = 0,
    limit: Int = 1000
): Parameters

Parse query string withing starting at the specified startIndex but up to limit pairs

parseRangesSpecifier

fun parseRangesSpecifier(rangeSpec: String): RangesSpecifier?

Parse Range header value

parseServerSetCookieHeader

fun parseServerSetCookieHeader(cookiesHeader: String): Cookie

Parse server’s Set-Cookie header value

plus

operator fun Parameters.plus(other: Parameters): Parameters

Plus operator function that creates a new parameters instance from the original one concatenating with other

push

fun ApplicationCall.push(pathAndQuery: String): Unit
fun ApplicationCall.push(
    encodedPath: String,
    parameters: Parameters
): Unit

Produces HTTP/2 push from server to client or sets HTTP/1.x hint header or does nothing. Exact behaviour is up to engine implementation.

fun ApplicationCall.push(
    block: ResponsePushBuilder.() -> Unit
): Unit

Produces HTTP/2 push from server to client or sets HTTP/1.x hint header or does nothing (may call or not call block). Exact behaviour is up to engine implementation.

renderCookieHeader

fun renderCookieHeader(cookie: Cookie): String

Format Set-Cookie header value

renderSetCookieHeader

fun renderSetCookieHeader(cookie: Cookie): String
fun renderSetCookieHeader(
    name: String,
    value: String,
    encoding: CookieEncoding = CookieEncoding.URI_ENCODING,
    maxAge: Int = 0,
    expires: GMTDate? = null,
    domain: String? = null,
    path: String? = null,
    secure: Boolean = false,
    httpOnly: Boolean = false,
    extensions: Map<String, String?> = emptyMap(),
    includeEncoding: Boolean = true
): String

Format Set-Cookie header value

setCookie

fun HttpMessage.setCookie(): List<Cookie>

Parse Set-Cookie header value.

takeFrom

fun URLBuilder.takeFrom(urlString: String): URLBuilder

Take url parts from urlString throws URLParserException

fun URLBuilder.takeFrom(url: URLBuilder): URLBuilder

Take components from another url builder

fun URLBuilder.takeFrom(url: Url): URLBuilder

Take components from another url

fun URLBuilder.takeFrom(uri: URI): Unit

Take URI components from uri

fun URLBuilder.takeFrom(url: URL): Unit

Take URI components from url

toHttpDate

fun GMTDate.toHttpDate(): String

Convert GMTDate to valid http date String

toURI

fun Url.toURI(): URI

Convert Url to URI

userAgent

fun HttpMessageBuilder.userAgent(content: String): Unit

Set User-Agent header value.

vary

fun HttpMessage.vary(): List<String>?

Parse Vary header value.

withCharset

fun ContentType.withCharset(charset: Charset): ContentType

Creates a copy of this type with the added charset parameter with charset value.

Companion Object Properties

ExceptionFailed

val HttpStatusCode.Companion.ExceptionFailed: HttpStatusCode

Companion Object Functions

defaultForFile

fun ContentType.Companion.defaultForFile(
    file: File
): ContentType
fun ContentType.Companion.defaultForFile(
    file: Path
): ContentType

defaultForFileExtension

fun ContentType.Companion.defaultForFileExtension(
    extension: String
): ContentType

Default ContentType for extension

defaultForFilePath

fun ContentType.Companion.defaultForFilePath(
    path: String
): ContentType

Default ContentType for file path

fromFileExtension

fun ContentType.Companion.fromFileExtension(
    ext: String
): List<ContentType>

Recommended content type by file name extension

fromFilePath

fun ContentType.Companion.fromFilePath(
    path: String
): List<ContentType>

Recommended content types by file path

invoke

operator fun Url.Companion.invoke(fullUrl: String): Url

Construct Url from String