Skip to content
Hokusai2.2.2
ivantokar.com

Hokusai Hummingbird

Hokusai Hummingbird (2.1.0) is a thin layer: streaming, cancellation and limits are Hokusai’s own (writeByteBuffers in HokusaiNIO, built on the core writeChunks); no Hummingbird type reaches the native layer. Requirements: Swift 6.0+, Hummingbird 2.x, Hokusai 2, libvips 8.16+ and Cairo with PDF support (installation).

dependencies: [
.package(url: "https://github.com/hummingbird-project/hummingbird.git", from: "2.0.0"),
.package(url: "https://github.com/ivantokar/hokusai-hummingbird.git", from: "2.0.0")
]

Add HokusaiHummingbird to the target that defines your routes.

Hokusai’s settings freeze at first use, so configure before the first request; initialize() turns a native problem into a startup failure.

try Hokusai.configure(.init(maxConcurrentEvaluations: .fixed(4), maxQueuedEvaluations: 64))
try Hokusai.initialize()
func buildRouter() -> Router<BasicRequestContext> {
let router = Router()
router.add(middleware: HokusaiErrorMiddleware())
// POST /resize --data-binary @photo.jpg
router.post("resize") { request, _ -> Response in
let image = try await request.hokusaiImage(maximumSize: 5 * 1024 * 1024) // 413 above 5 MiB
return try await image
.resize(width: 800, height: 600, fit: .cover)
.webp(quality: 82) // choose the encoder on the pipeline
.response() // Content-Type: image/webp, streamed
}
// An A4 PDF of the upload
router.post("report") { request, _ -> Response in
let image = try await request.hokusaiImage()
return try await image
.resize(width: 1240, height: 1754, fit: .contain)
.pdf(pageSize: .a4(), margins: .all(36), background: .white)
.response(status: .created, headers: [.cacheControl: "no-store"])
}
return router
}
@main
struct Entry {
static func main() async throws {
// Hokusai's process-level settings are frozen at first use, so set them before the first request.
try Hokusai.configure(.init(maxConcurrentEvaluations: .fixed(4), maxQueuedEvaluations: 64))
try Hokusai.initialize()
let app = Application(router: buildRouter(), configuration: .init(address: .hostname("127.0.0.1", port: 8080)))
try await app.runService()
}
}

The code above is compiled in CI against hokusai-hummingbird 2.1.0 (examples/integrations/hummingbird-app). Try it:

Terminal window
curl -X POST http://localhost:8080/resize --data-binary "@photo.jpg" -o output.webp
  • Upload limits. hokusaiImage reads the body as it arrives and never past its limit: a declared Content-Length over maximumSize (20 MiB by default) is rejected before a byte is read, and a body without one is rejected as soon as it grows past it, both with 413. Pass options: InputOptions(limits: …) for Hokusai’s own decode limits. A small upload stays in memory; one larger than memoryLimit (1 MiB by default) moves to a private temporary file (Hokusai(spooling:)), so the encoded upload takes at most memoryLimit plus one chunk of memory however large maximumSize is. Decoding is bounded separately by InputLimits.maxPixels.
  • Streamed responses. response() writes through Hokusai.writeByteBuffers: each buffer goes to Hummingbird’s ResponseBodyWriter as it is encoded, so a slow client slows encoding down; at most four 64 KiB buffers of encoded output are held. The body is chunked, with no Content-Length. Content-Type comes from the encoder the pipeline carries (a pipeline without one is a 500). status:, headers: and chunkSize: are parameters. TIFF is encoded in memory first, then streamed.
  • Failures before the first byte are 4xx. The source header is read before the response is committed, so a missing or unreadable image is a clean error and not a broken 200. A failure after the first byte can only end the stream early, which is how HTTP works; a client disconnect cancels the evaluation.
  • Errors. HokusaiErrorMiddleware turns a HokusaiError thrown by a route into an HTTP error; hokusaiImage and response already do this for what they run. Mapping: invalidInput / invalidOption 400, decode 422, resource 413 for bytes, 422 for pixels or channels, 503 when the evaluation queue is full, unsupported 501, and io / transform / encode / runtime 500. error.httpStatus and error.httpError are public if you want a different policy.