Ktor image routes

Library module

Problem

This module provides small Ktor route adapters for CAPTCHA issue/verification and multipart thumbnail generation. It standardizes validation and HTTP responses while leaving authentication, JSON installation, persistence, and rate limiting with the application.

When to use it

Use it for a compact Ktor service that needs the release CAPTCHA contract or a single-image thumbnail endpoint. Compose a custom route when uploads must stream to object storage, use libvips, or participate in a larger domain workflow.

Coordinates

Maven coordinate: io.github.bluetape4k.image:bluetape4k-images-ktor

dependencies {
    implementation(platform("io.github.bluetape4k:bluetape4k-dependencies:<version>"))
    implementation("io.github.bluetape4k.image:bluetape4k-images-ktor")
}

Core concepts

bluetape4kCaptchaRoutes registers GET issue and POST verify endpoints backed by CaptchaVerificationService. bluetape4kImageThumbnailRoutes reads one streamed multipart part, decodes through Scrimage, resizes by maximum side, and returns encoded bytes.

Quick start

install(ContentNegotiation) { json() }

routing {
    bluetape4kCaptchaRoutes()
    bluetape4kImageThumbnailRoutes(
        ImageThumbnailKtorRoutesConfig(maxInputBytes = 5L * 1024 * 1024),
    )
}

API by task

• GET /captcha?length=6: returns id, base64 PNG, content type, and expiry.
• POST /captcha/{id}/verify: consumes the challenge and maps success/wrong/expired/missing to 200/400/410/404.
• POST /images/thumbnail?maxSide=320: reads multipart field file and returns PNG by default.
• Replace generators, verification stores, id factories, writers, route paths, and response content types through config objects.

Recommended patterns

Install JSON serialization before CAPTCHA routes. Provide a distributed one-shot store and an unpredictable id factory in clustered services. Apply auth, CSRF policy, upload content validation, quotas, and rate limits at the application boundary.

Integrations

The routes reuse bluetape4k-ktor-core request/error helpers, bluetape4k-images, and bluetape4k-images-captcha. They do not integrate Spring storage, S3, CDN, OCR, or libvips.

Configuration

CAPTCHA defaults to /captcha. Thumbnail defaults to /images/thumbnail, field file, 10 MiB maximum input, 320 default maximum side, 2,048 hard maximum side, and PNG output. Every multipart part is released after inspection.

Failure modes

Invalid parameters, missing/wrong multipart fields, empty uploads, and oversize uploads return the shared 400 error payload. Malformed image I/O is also mapped to 400. CAPTCHA verification uses distinct status codes; unexpected runtime failures remain server errors.

Operations

Scrimage decode/encode runs on Dispatchers.IO, but the upload is buffered into a bounded byte array. Observe request size, decode latency, status counts, and CAPTCHA issue/verify ratios without logging answers or image contents.

Testing

Use Ktor test application coverage in CaptchaKtorRoutesTest and ImageThumbnailKtorRoutesTest. Add application tests for installed JSON, authentication, distributed-store behavior, body limits, and malformed payloads.

Workshops and learning path

Start with the route tests, run the examples/ktor-image-api and examples/ktor-ocr-api applications, then replace default in-memory/security boundaries before production.

Limitations

The thumbnail endpoint is not a streaming transform: it buffers at most maxInputBytes + 1 and uses Scrimage. It creates one thumbnail, stores nothing, and performs no MIME sniffing beyond image decode. CAPTCHA routes do not install JSON or abuse controls.

Release diagrams

These diagrams are loaded directly from README assets published with the 0.3.0 release and pinned to its immutable commit. They describe this manual’s released structure and runtime flows, not later Snapshot changes. Select a preview to open the SVG at the same release commit.

Images Ktor Architecture diagram

Release README: images-ktor/README.md

Sources

• CAPTCHA routes
• Thumbnail route and limits
• Release build