Ktor OCR API workshop

Latest stable Based on Image release 0.3.0

Runnable example

Problem

This Ktor 3 workshop accepts a streamed multipart image, parses Tesseract language codes, calls an injectable OcrEngine, and maps validation and native-runtime failures to stable JSON responses. Its tests run without a host Tesseract installation.

When to use it

Use it when adding OCR to a Ktor service, learning how to isolate native dependencies behind an interface, or comparing Ktor wiring with the Spring Boot OCR workshop.

Coordinates

The example is not published. Select one bluetape4k-dependencies version for the application and consume bluetape4k-images-ocr; do not manage an independent OCR-module version.

Core concepts

Multipart input is streamed and limited by maxInputBytes before decoding.
eng+kor, eng,kor, and whitespace-separated values become a language list.
KtorOcrService depends on OcrEngine; production uses TesseractOcrEngine, tests inject a fake.
Invalid requests become 400 bad_request; OcrException becomes 503 ocr_unavailable.

Quick start

JDK 21+ is sufficient for tests. Real OCR also requires Tesseract and the requested traineddata packages.

brew install tesseract tesseract-lang
export EXAMPLE_OCR_TESSDATA_PATH=/opt/homebrew/share/tessdata
./gradlew :ktor-ocr-api:run

curl -F "file=@sample-ko.png;type=image/png" \
  "http://localhost:8080/api/ocr?languages=eng+kor"

The response contains text, normalized languages, and characterCount.

API by task

Task	Release API
Configure route/runtime	`KtorOcrApiConfig`
Install endpoint	`configureKtorOcrApi(config, ocrEngine)`
Decode and recognize	`immutableImageOf(bytes).suspendExtractText(...)`
Health check	`GET /ready`
OCR request	`POST /api/ocr?languages=eng+kor`

Recommended patterns

Keep host-specific tessdata configuration outside the request, inject the OCR engine, cap bytes before image decoding, and map native availability separately from client validation. This keeps normal CI independent of Tesseract while preserving the production contract.

Integrations

The workshop uses bluetape4k-images-ocr and core image decoding. Compare spring-boot-ocr-api to choose framework wiring without changing the OCR domain boundary.

Configuration

Defaults: route /api/ocr, multipart field file, 10 MiB maximum, language eng, port 8080. PORT changes the port; EXAMPLE_OCR_TESSDATA_PATH supplies the host traineddata directory.

Failure modes

400 bad_request: missing/wrong multipart field, empty upload, unsupported media type, invalid language list, or input over 10 MiB.
503 ocr_unavailable: Tesseract, a traineddata package, or the native bridge is unavailable.
Empty/poor recognition: verify tesseract --list-langs, input resolution, contrast, orientation, and the requested language set.

Operations

Treat OCR as a bounded native service call. Add authentication, rate limiting, request queues, timeouts, and concurrency limits in the owning application. Log language and duration, not uploaded document contents.

Testing

./gradlew :ktor-ocr-api:test

Ktor testApplication verifies language parsing and tessdata propagation, wrong fields, unsupported content types, and the 503 native-failure mapping using a fake engine.

Workshops and learning path

Learn multipart route conventions in ktor-image-api.
Run this workshop’s fake-engine tests before installing native OCR.
Install Tesseract, verify languages, then send a real text-heavy image.
Read the OCR module manual and compare the Spring Boot workshop.

Limitations

The workshop does not include authentication, persistence, batch OCR, preprocessing policy, queues, or distributed admission control. OCR quality and supported languages depend on the host installation.

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.