WritePendingException consistently encountered on large responses

[bjhham]

Jetty version(s)
12.1.0

Jetty Environment
Core

Java version/vendor
Coretto 21

OS type/version
MacOS

Description
Without some custom back-off mechanism, ChannelResponse.write() always runs into WritePendingException on any sufficiently large response. I'd expect the channel response either to block or have some queuing.

How to reproduce?
Here's a reproducer:

package com.example;

import org.eclipse.jetty.server.Handler;
import org.eclipse.jetty.server.Request;
import org.eclipse.jetty.server.Response;
import org.eclipse.jetty.server.Server;
import org.eclipse.jetty.util.Callback;

import java.nio.ByteBuffer;
import java.security.SecureRandom;
import java.util.Random;

public class BigResponseServer {

    private static final int PORT = 8080;
    private static final long RESPONSE_SIZE = 1024L * 1024L * 1024L; // 1 GB in bytes
    private static final int BUFFER_SIZE = 8192;

    public static void main(String[] args) throws Exception {
        Server server = new Server(PORT);
        server.setHandler(new BigResponseHandler());

        System.out.println("Starting server on port " + PORT);
        server.start();
        server.join();
    }

    static class BigResponseHandler extends Handler.Abstract {
        private final Random random = new SecureRandom();

        @Override
        public boolean handle(Request request, Response response, Callback callback) {
            response.setStatus(200);
            response.getHeaders().add("Content-Type", "application/octet-stream");
            response.getHeaders().add("Content-Length", RESPONSE_SIZE);

            Callback failCallback = Callback.from(() -> {}, Throwable::printStackTrace);
            long bytesToSend = RESPONSE_SIZE;
            while (bytesToSend > 0) {
                bytesToSend -= BUFFER_SIZE;
                ByteBuffer buffer = ByteBuffer.allocate(BUFFER_SIZE);
                random.nextBytes(buffer.array());

                // this will always fail with WritePendingException
                boolean done = bytesToSend <= 0;
                response.write(done, buffer, done ? callback : failCallback);
            }
            return true;
        }
    }
}

[sbordet]

This is by design, and it's common in all non-blocking APIs.

Since Response is-a Content.Sink, the solution is detailed in this section of the documentation.

[bjhham]

Thanks, this makes more sense now!

[sbordet]

I have expanded the documentation with your example in #13558.