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).
Install
Section titled “Install”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.
Configure at startup
Section titled “Configure at startup”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()Routes
Section titled “Routes”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}
@mainstruct 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:
curl -X POST http://localhost:8080/resize --data-binary "@photo.jpg" -o output.webpBehavior to rely on
Section titled “Behavior to rely on”- Upload limits.
hokusaiImagereads the body as it arrives and never past its limit: a declaredContent-LengthovermaximumSize(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 with413. Passoptions: InputOptions(limits: …)for Hokusai’s own decode limits. A small upload stays in memory; one larger thanmemoryLimit(1 MiB by default) moves to a private temporary file (Hokusai(spooling:)), so the encoded upload takes at mostmemoryLimitplus one chunk of memory however largemaximumSizeis. Decoding is bounded separately byInputLimits.maxPixels. - Streamed responses.
response()writes throughHokusai.writeByteBuffers: each buffer goes to Hummingbird’sResponseBodyWriteras 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 noContent-Length.Content-Typecomes from the encoder the pipeline carries (a pipeline without one is a500).status:,headers:andchunkSize: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 broken200. A failure after the first byte can only end the stream early, which is how HTTP works; a client disconnect cancels the evaluation. - Errors.
HokusaiErrorMiddlewareturns aHokusaiErrorthrown by a route into an HTTP error;hokusaiImageandresponsealready do this for what they run. Mapping:invalidInput/invalidOption400,decode422,resource413 for bytes, 422 for pixels or channels, 503 when the evaluation queue is full,unsupported501, andio/transform/encode/runtime500.error.httpStatusanderror.httpErrorare public if you want a different policy.