or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/maven-io-ktor--ktor-client-encoding-tvosarm64

Ktor HTTP client content encoding plugin for tvOS ARM64 that provides compression and decompression support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/io.ktor/ktor-client-encoding-tvosarm64@2.3.x

To install, run

npx @tessl/cli install tessl/maven-io-ktor--ktor-client-encoding-tvosarm64@2.3.0

index.mddocs/

Ktor Client Encoding

Ktor Client Encoding is an HTTP client plugin that provides automatic content compression and decompression capabilities for the Ktor framework. It handles Accept-Encoding headers and transparently processes compressed response content, supporting gzip, deflate, and identity encodings.

Package Information

  • Package Name: ktor-client-encoding-tvosarm64
  • Package Type: maven
  • Language: Kotlin
  • Platform: tvOS ARM64
  • Installation: Add dependency to your build.gradle.kts:
implementation("io.ktor:ktor-client-encoding-tvosarm64:2.3.13")

Core Imports

import io.ktor.client.plugins.compression.ContentEncoding
import io.ktor.client.plugins.compression.ContentEncoder
import io.ktor.client.plugins.compression.UnsupportedContentEncodingException
import io.ktor.util.Encoder
import io.ktor.utils.io.ByteReadChannel
import kotlinx.coroutines.CoroutineScope

Basic Usage

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

// Create client with content encoding
val client = HttpClient {
    ContentEncoding {
        gzip()
        deflate()
        identity()
    }
}

// Make request - compression is handled automatically
val response: HttpResponse = client.get("https://api.example.com/data")
val content: String = response.body<String>() // Automatically decompressed

Architecture

Ktor Client Encoding integrates with the Ktor HTTP client pipeline through two main interception points:

  • Request Pipeline: Automatically adds Accept-Encoding headers based on configured encoders
  • Response Pipeline: Transparently decompresses response content based on Content-Encoding headers

The plugin uses platform-specific encoder implementations:

  • JVM: Full compression support using native Java libraries
  • JS: Delegates to browser compression (Identity fallback)
  • Native/tvOS: Simplified Identity implementation for compatibility

Capabilities

Plugin Installation and Configuration

Install the ContentEncoding plugin with customizable encoder configuration and quality values.

fun HttpClientConfig<*>.ContentEncoding(
    block: ContentEncoding.Config.() -> Unit = {
        gzip()
        deflate()
        identity()
    }
): Unit

Encoder Configuration

Configure individual content encoders with optional quality values for Accept-Encoding header negotiation.

@KtorDsl
class ContentEncoding.Config {
    /**
     * Installs the gzip encoder.
     * @param quality a priority value to use in the Accept-Encoding header.
     */
    fun gzip(quality: Float? = null): Unit
    
    /**
     * Installs the deflate encoder.
     * @param quality a priority value to use in the Accept-Encoding header.
     */
    fun deflate(quality: Float? = null): Unit
    
    /**
     * Installs the identity encoder.
     * @param quality a priority value to use in the Accept-Encoding header.
     */
    fun identity(quality: Float? = null): Unit
    
    /**
     * Installs a custom encoder.
     * @param encoder a custom encoder to use.
     * @param quality a priority value to use in the Accept-Encoding header.
     */
    fun customEncoder(encoder: ContentEncoder, quality: Float? = null): Unit
}

Parameters:

  • quality: Optional priority value (0.0..1.0) for Accept-Encoding header. Higher values indicate preferred encodings.

Usage Examples:

// Default configuration (all encoders, no quality values)
ContentEncoding()

// Custom quality preferences
ContentEncoding {
    gzip(quality = 0.9f)
    deflate(quality = 0.8f)
    identity(quality = 0.1f)
}

// Selective encoders
ContentEncoding {
    gzip()
    // Only gzip encoding enabled
}

Custom Encoder Support

Implement custom content encoders for specialized compression algorithms.

interface ContentEncoder : Encoder {
    /**
     * Encoder identifier to use in http headers.
     */
    val name: String
}

interface Encoder {
    /**
     * Launch coroutine to encode source bytes.
     */
    fun CoroutineScope.encode(source: ByteReadChannel): ByteReadChannel
    
    /**
     * Launch coroutine to decode source bytes.
     */
    fun CoroutineScope.decode(source: ByteReadChannel): ByteReadChannel
}

Properties:

  • name: Encoder identifier used in HTTP headers (e.g., "gzip", "br", "custom")

Integration:

object CustomEncoder : ContentEncoder {
    override val name = "custom"
    // Implement Encoder interface methods
}

// Register custom encoder
ContentEncoding {
    customEncoder(CustomEncoder, quality = 0.7f)
}

Plugin Implementation

Core plugin class implementing the HttpClientPlugin interface.

class ContentEncoding private constructor(
    private val encoders: Map<String, ContentEncoder>,
    private val qualityValues: Map<String, Float>
) {
    @KtorDsl
    class Config {
        fun gzip(quality: Float? = null): Unit
        fun deflate(quality: Float? = null): Unit  
        fun identity(quality: Float? = null): Unit
        fun customEncoder(encoder: ContentEncoder, quality: Float? = null): Unit
    }
    
    companion object : HttpClientPlugin<Config, ContentEncoding> {
        override val key: AttributeKey<ContentEncoding>
        override fun prepare(block: Config.() -> Unit): ContentEncoding
        override fun install(plugin: ContentEncoding, scope: HttpClient): Unit
    }
}

Error Handling

Exception thrown when encountering unsupported content encodings in response headers.

class UnsupportedContentEncodingException(encoding: String) : 
    IllegalStateException("Content-Encoding: \$encoding unsupported.")

Parameters:

  • encoding: The unsupported encoding name from Content-Encoding header

When Thrown:

  • Server responds with Content-Encoding not registered in plugin configuration
  • Malformed or unrecognized encoding values in response headers

Example:

try {
    val response = client.get("https://api.example.com/compressed")
    val content = response.body<String>()
} catch (e: UnsupportedContentEncodingException) {
    println("Unsupported encoding: ${e.message}")
    // Handle unsupported encoding
}

Types

Built-in Encoder Support

The plugin provides built-in support for standard content encodings through internal encoder implementations:

// Internal encoder objects (not directly accessible)
internal object GZipEncoder : ContentEncoder, Encoder by GZip { // JVM only
    override val name: String = "gzip"
}

internal object DeflateEncoder : ContentEncoder, Encoder by Deflate { // JVM only  
    override val name: String = "deflate"
}

internal object IdentityEncoder : ContentEncoder, Encoder by Identity {
    override val name: String = "identity"
}

Encoder Types:

  • gzip: GZip compression (JVM: full compression, JS/Native: delegates to Identity)
  • deflate: Deflate compression (JVM: full compression, JS/Native: delegates to Identity)
  • identity: No compression (available on all platforms)

Platform-Specific Behavior:

  • JVM: Full compression/decompression using Java standard libraries (GZip, Deflate encoders delegate to io.ktor.util.GZip and io.ktor.util.Deflate)
  • JS: Identity encoding only (browsers handle compression automatically - GZip and Deflate encoders delegate to Identity)
  • Native/tvOS ARM64: Identity encoding only (simplified implementation for compatibility - GZip and Deflate encoders delegate to Identity)

HTTP Header Integration

The plugin automatically manages HTTP headers for content negotiation:

Request Headers:

  • Sets Accept-Encoding with configured encoders and quality values
  • Example: Accept-Encoding: gzip;q=0.9,deflate;q=0.8,identity;q=0.1

Response Processing:

  • Reads Content-Encoding header from server responses
  • Applies appropriate decompression based on encoding chain
  • Supports multiple encodings applied in sequence

Error Scenarios

Configuration Errors:

  • Invalid quality values (outside 0.0..1.0 range) throw IllegalArgumentException
  • Quality values are validated during plugin preparation

Runtime Errors:

  • UnsupportedContentEncodingException for unknown encodings
  • Graceful handling of missing Content-Encoding headers (no decompression applied)

Platform Limitations:

  • tvOS ARM64: All compression encoders (gzip, deflate) fall back to Identity encoding - no actual compression/decompression occurs
  • JavaScript: Relies on browser compression capabilities - encoders delegate to Identity
  • JVM: Full compression support with native Java libraries

Thread Safety

The ContentEncoding plugin is thread-safe and can be used concurrently across multiple requests. Internal state is immutable after configuration, and platform-specific encoders handle concurrent access appropriately.