Package io.ktor.http

Types

Link copied to clipboard
class BadContentTypeFormatException(value: String) : Exception

Exception thrown when a content type string is malformed.

Link copied to clipboard
sealed class CacheControl

Represents a value for a Cache-Control header

Link copied to clipboard
class ContentDisposition(disposition: String, parameters: List<HeaderValueParam>) : HeaderValueWithParameters

Represents Content-Disposition header value

Link copied to clipboard
sealed class ContentRange

Represents a Range header's particular range

Link copied to clipboard
class ContentType : HeaderValueWithParameters

Represents a value for a Content-Type header.

Link copied to clipboard
interface ContentTypeMatcher

Interface for any objects that can match a ContentType.

Link copied to clipboard
data class Cookie(name: String, value: String, encoding: CookieEncoding, maxAge: Int, expires: GMTDate?, domain: String?, path: String?, secure: Boolean, httpOnly: Boolean, extensions: Map<String, String?>)

Represents a cookie with name, content and a set of settings such as expiration, visibility and security. A cookie with neither expires nor maxAge is a session cookie.

Link copied to clipboard
enum CookieEncoding : Enum<CookieEncoding>

Cooke encoding strategy

Link copied to clipboard
object EmptyHeaders : Headers
Link copied to clipboard
interface Headers : StringValues

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

Link copied to clipboard
class HeadersBuilder(size: Int) : StringValuesBuilderImpl
Link copied to clipboard
class HeadersImpl(values: Map<String, List<String>>) : StringValuesImpl, Headers
Link copied to clipboard
class HeadersSingleImpl(name: String, values: List<String>) : StringValuesSingleImpl, Headers
Link copied to clipboard
data class HeaderValue(value: String, params: List<HeaderValueParam>)

Represents a header value. Similar to HeaderValueWithParameters

Link copied to clipboard
data class HeaderValueParam(name: String, value: String)

Represents a single value parameter

Link copied to clipboard
abstract class HeaderValueWithParameters(content: String, parameters: List<HeaderValueParam>)

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

Link copied to clipboard
object HttpHeaders
Link copied to clipboard
interface HttpMessage

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

Link copied to clipboard
interface HttpMessageBuilder

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

Link copied to clipboard
data class HttpMethod(value: String)

Represents an HTTP method (verb)

Link copied to clipboard
data class HttpProtocolVersion(name: String, major: Int, minor: Int)

Represents an HTTP protocol version.

Link copied to clipboard
data class HttpStatusCode(value: Int, description: String)

Represents an HTTP status code and description.

Link copied to clipboard
class IllegalHeaderNameException(headerName: String, position: Int) : IllegalArgumentException

Thrown when an illegal header name was used. A header name should only consist from visible characters without delimiters "double quote" and the following characters: (),/:;<=>?@[\]{}.

Link copied to clipboard
class IllegalHeaderValueException(headerValue: String, position: Int) : IllegalArgumentException

Thrown when an illegal header value was used. A header value should only consist from visible characters, spaces and/or HTAB (0x09).

Link copied to clipboard
class LinkHeader(uri: String, params: List<HeaderValueParam>) : HeaderValueWithParameters

Represents a Link header value as per RFC 5988

Link copied to clipboard
interface Parameters : StringValues

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

Link copied to clipboard
interface ParametersBuilder : StringValuesBuilder
Link copied to clipboard
class ParametersBuilderImpl(size: Int) : StringValuesBuilderImpl, ParametersBuilder
Link copied to clipboard
class ParametersImpl(values: Map<String, List<String>>) : StringValuesImpl, Parameters
Link copied to clipboard
class ParametersSingleImpl(name: String, values: List<String>) : StringValuesSingleImpl, Parameters
Link copied to clipboard
data class RangesSpecifier(unit: String, ranges: List<ContentRange>)

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

Link copied to clipboard
enum RangeUnits : Enum<RangeUnits>

Possible content range units: bytes and none

Link copied to clipboard
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.

Link copied to clipboard
class UnsafeHeaderException(header: String) : IllegalArgumentException

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

Link copied to clipboard
class Url

Represents an immutable URL

Link copied to clipboard
class URLBuilder(protocol: URLProtocol, host: String, port: Int, user: String?, password: String?, pathSegments: List<String>, parameters: Parameters, fragment: String, trailingQuery: Boolean)

A URL builder with all mutable components

Link copied to clipboard
class URLDecodeException(message: String) : Exception

URL decoder exception

Link copied to clipboard
class URLParserException(urlString: String, cause: Throwable) : IllegalStateException

Thrown when failed to parse URL

Link copied to clipboard
data class URLProtocol(name: String, defaultPort: Int)

Represents URL protocol

Functions

Link copied to clipboard
fun StringValuesBuilder.append(name: String, value: HeaderValueWithParameters)

Append formatted header value to the builder

Link copied to clipboard
fun URLBuilder.appendEncodedPathSegments(vararg components: String): URLBuilder

Adds components to current encodedPath

fun URLBuilder.appendEncodedPathSegments(segments: List<String>): URLBuilder

Adds components to current encodedPath

Link copied to clipboard
fun URLBuilder.appendPathSegments(vararg components: String): URLBuilder

Adds components to current encodedPath

fun URLBuilder.appendPathSegments(segments: List<String>): URLBuilder

Adds components to current encodedPath

Link copied to clipboard
fun Appendable.appendUrlFullPath(encodedPath: String, encodedQueryParameters: ParametersBuilder, trailingQuery: Boolean)
Link copied to clipboard
fun HttpMessage.cacheControl(): List<HeaderValue>

Parse CacheControl header.

Link copied to clipboard
fun HeaderValueWithParameters.charset(): Charset?

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

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

Parse charset from Content-Type header value.

fun HttpMessageBuilder.charset(charset: Charset): Unit?
Link copied to clipboard
fun URLBuilder.clone(): URLBuilder

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

Link copied to clipboard
fun HttpMessage.contentLength(): Long?
fun HttpMessageBuilder.contentLength(): Long?

Parse Content-Length header value.

fun HttpMessageBuilder.contentLength(length: Int)
Link copied to clipboard
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

Link copied to clipboard
fun HttpMessage.contentType(): ContentType?
fun HttpMessageBuilder.contentType(): ContentType?

Parse Content-Type header value.

fun HttpMessageBuilder.contentType(type: ContentType)

Set Content-Type header.

Link copied to clipboard
fun HttpMessageBuilder.cookies(): List<Cookie>

Parse Set-Cookie header value.

Link copied to clipboard
fun Url.copy(protocol: URLProtocol = this.protocol, host: String = this.host, specifiedPort: Int = this.specifiedPort, encodedPath: String = this.encodedPath, parameters: Parameters = this.parameters, fragment: String = this.fragment, user: String? = this.user, password: String? = this.password, trailingQuery: Boolean = this.trailingQuery): Url
Link copied to clipboard
fun HttpMessage.date(): Date?

Parse Date header.

Link copied to clipboard
fun decodeCookieValue(encodedValue: String, encoding: CookieEncoding): String

Decode cookie value using the specified encoding

Link copied to clipboard
fun String.decodeURLPart(start: Int = 0, end: Int = length, charset: Charset = Charsets.UTF_8): String

Decode percent encoded URL part within the specified range [start, end). This function is not intended to decode urlencoded forms so it doesn't decode plus character to space.

Link copied to clipboard
fun String.decodeURLQueryComponent(start: Int = 0, end: Int = length, plusIsSpace: Boolean = false, charset: Charset = Charsets.UTF_8): String

Decode URL query component

Link copied to clipboard
fun ContentType.Companion.defaultForFile(file: File): ContentType
fun ContentType.Companion.defaultForFile(file: Path): ContentType
Link copied to clipboard
fun ContentType.Companion.defaultForFileExtension(extension: String): ContentType
Link copied to clipboard
fun ContentType.Companion.defaultForFilePath(path: String): ContentType

Default ContentType for file path

Link copied to clipboard
fun encodeCookieValue(value: String, encoding: CookieEncoding): String

Encode cookie value using the specified encoding

Link copied to clipboard
fun String.encodeOAuth(): String

Encode this in percent encoding specified here: https://tools.ietf.org/html/rfc5849#section-3.6

Link copied to clipboard
fun String.encodeURLParameter(spaceToPlus: Boolean = false): String

Encode this as query parameter key.

Link copied to clipboard
fun String.encodeURLPath(): String

Encode URL path or component. It escapes all illegal or ambiguous characters

Link copied to clipboard
fun String.encodeURLQueryComponent(encodeFull: Boolean = false, spaceToPlus: Boolean = false, charset: Charset = Charsets.UTF_8): String

Encode url part as specified in https://tools.ietf.org/html/rfc3986#section-2

Link copied to clipboard
fun String.escapeIfNeeded(): String

Escape using double quotes if needed or keep as is if no dangerous strings found

Link copied to clipboard
fun HttpMessage.etag(): String?
fun HttpMessageBuilder.etag(): String?

Parse E-Tag header value.

fun HeadersBuilder.etag(entityTag: String)

Set E-Tag header

Link copied to clipboard
fun HttpMessage.expires(): Date?
fun HttpMessageBuilder.expires(): Date?

Parse Expires header.

Link copied to clipboard
fun ContentType.fileExtensions(): List<String>

Recommended file name extensions for this content type

Link copied to clipboard
fun Parameters.formUrlEncode(): String

Encode form parameters

fun List<Pair<String, String?>>.formUrlEncode(): String

Encode form parameters from a list of pairs

Link copied to clipboard
fun Parameters.formUrlEncodeTo(out: Appendable)

Encode form parameters to the specified out appendable

fun List<Pair<String, String?>>.formUrlEncodeTo(out: Appendable)

Encode form parameters from a list of pairs to the specified out appendable

Link copied to clipboard
fun String.fromCookieToGmtDate(): GMTDate

Convert valid cookie date String to GMTDate trying first the RFC6265 standard, falling back on fromHttpToGmtDate

Link copied to clipboard
fun ContentType.Companion.fromFileExtension(ext: String): List<ContentType>

Recommended content type by file name extension

Link copied to clipboard
fun ContentType.Companion.fromFilePath(path: String): List<ContentType>

Recommended content types by file path

Link copied to clipboard
fun String.fromHttpToGmtDate(): GMTDate

Convert valid http date String to GMTDate trying various http date formats from HTTP_DATE_FORMATS

Link copied to clipboard
fun headersOf(): Headers

Returns empty headers

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

Returns Headers instance from pairs

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

Link copied to clipboard
fun hostIsIp(host: String): Boolean

Check if host is IPv4 or IPv6 address.

Link copied to clipboard
fun HttpMessageBuilder.ifModifiedSince(date: Date)

Set If-Modified-Since header.

Link copied to clipboard
fun HttpMessageBuilder.ifNoneMatch(value: String)

Set If-None-Match header value.

Link copied to clipboard
operator fun Url.Companion.invoke(fullUrl: String): Url

Construct Url from String

Link copied to clipboard
fun URLProtocol.isSecure(): Boolean

Check if the protocol is secure

Link copied to clipboard
fun HttpStatusCode.isSuccess(): Boolean

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

Link copied to clipboard
fun URLProtocol.isWebsocket(): Boolean

Check if the protocol is websocket

Link copied to clipboard
fun HttpMessage.lastModified(): Date?
fun HttpMessageBuilder.lastModified(): Date?

Parse Last-Modified header.

Link copied to clipboard
fun HttpMessageBuilder.maxAge(seconds: Int)

Append Max-Age header value.

Link copied to clipboard
fun ParametersBuilder(size: Int = 8): ParametersBuilder
Link copied to clipboard
fun parametersOf(): Parameters

Returns an empty parameters instance

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

Creates a parameters instance from the specified pairs

fun parametersOf(map: Map<String, List<String>>): Parameters

Creates a parameters instance from the entries of the given map

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

Link copied to clipboard
fun parseAndSortContentTypeHeader(header: String?): List<HeaderValue>

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

Link copied to clipboard
fun parseAndSortHeader(header: String?): List<HeaderValue>

Parse header value and sort multiple values according to qualities

Link copied to clipboard
fun parseClientCookiesHeader(cookiesHeader: String, skipEscaped: Boolean = true): Map<String, String>

Parse client's Cookie header value

Link copied to clipboard
fun parseHeaderValue(text: String?): List<HeaderValue>
fun parseHeaderValue(text: String?, parametersOnly: Boolean): List<HeaderValue>

Parse header value respecting multi-values

Link copied to clipboard
fun parseQueryString(query: String, startIndex: Int = 0, limit: Int = 1000, decode: Boolean = true): Parameters

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

Link copied to clipboard
fun parseRangesSpecifier(rangeSpec: String): RangesSpecifier?

Parse Range header value

Link copied to clipboard
fun parseServerSetCookieHeader(cookiesHeader: String): Cookie

Parse server's Set-Cookie header value

Link copied to clipboard
fun String.parseUrlEncodedParameters(defaultEncoding: Charset = Charsets.UTF_8, limit: Int = 1000): Parameters

Parse URL query parameters. Shouldn't be used for urlencoded forms because of + character.

Link copied to clipboard
fun URLBuilder.path(vararg path: String)
Link copied to clipboard
fun URLBuilder.pathComponents(vararg components: String): URLBuilder
fun URLBuilder.pathComponents(components: List<String>): URLBuilder
Link copied to clipboard
operator fun Parameters.plus(other: Parameters): Parameters

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

Link copied to clipboard
fun String.quote(): String

Escape string using double quotes

Link copied to clipboard
fun renderCookieHeader(cookie: Cookie): String

Format Cookie header value

Link copied to clipboard
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

Link copied to clipboard
fun URLBuilder.set(scheme: String? = null, host: String? = null, port: Int? = null, path: String? = null, block: URLBuilder.() -> Unit = {})

Sets the url parts using the specified scheme, host, port and path. Pass null to keep existing value in the URLBuilder.

Link copied to clipboard
fun HttpMessage.setCookie(): List<Cookie>

Parse Set-Cookie header value.

Link copied to clipboard
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(urlString: String): URLBuilder

Take url parts from urlString throws URLParserException

fun URLBuilder.takeFrom(uri: URI): URLBuilder

Take URI components from uri

fun URLBuilder.takeFrom(url: URL): URLBuilder

Take URI components from url

Link copied to clipboard
fun Iterable<Pair<String, String>>.toHeaderParamsList(): List<HeaderValueParam>

Construct a list of HeaderValueParam from an iterable of pairs

Link copied to clipboard
fun GMTDate.toHttpDate(): String

Convert GMTDate to valid http date String

Link copied to clipboard
fun Url.toURI(): URI

Convert Url to URI

Link copied to clipboard
fun Url(builder: URLBuilder): Url

Construct Url from builder without building origin.

fun Url(urlString: String): Url

Construct Url from urlString.

fun Url(uri: URI): Url

Helper method that concisely creates a Url from a URI

Link copied to clipboard
fun URLBuilder(builder: URLBuilder): URLBuilder

Construct URLBuilder from builder.

fun URLBuilder(url: Url): URLBuilder

Construct URLBuilder from url.

fun URLBuilder(urlString: String): URLBuilder

Construct URLBuilder from urlString.

Link copied to clipboard
fun HttpMessageBuilder.userAgent(content: String)

Set User-Agent header value.

Link copied to clipboard
fun HttpMessage.vary(): List<String>?
fun HttpMessageBuilder.vary(): List<String>?

Parse Vary header value.

Link copied to clipboard
fun ContentType.withCharset(charset: Charset): ContentType

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

Link copied to clipboard
fun ContentType.withCharsetIfNeeded(charset: Charset): ContentType

Creates a copy of this type with the added charset parameter with charset value if ContentType is not ignored

Properties

Link copied to clipboard
val URLBuilder.authority: String

URLBuilder authority.

Link copied to clipboard
val Url.authority: String

Url authority.

Link copied to clipboard
const val DEFAULT_PORT: Int = 0

Select default port value from protocol.

Link copied to clipboard
var URLBuilder.encodedPath: String
Link copied to clipboard
Link copied to clipboard
val Url.fullPath: String

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

Link copied to clipboard
val Url.hostWithPort: String

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

Link copied to clipboard
expect val URLBuilder.Companion.origin: String

Hostname of current origin.

actual val URLBuilder.Companion.origin: String

Hostname of current origin.

actual val URLBuilder.Companion.origin: String

Hostname of current origin.

actual val URLBuilder.Companion.origin: String

Hostname of current origin.

Link copied to clipboard
val Url.protocolWithAuthority: String

A Url protocol and authority.