CtrlK
BlogDocsLog inGet started
Tessl Logo

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

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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.

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