Add an optional argument to HttpServerResponse.sendFile() to control whether the response is ended

[oxsdd]

Add an optional argument to HttpServerResponse.sendFile() that indicates whether the response should be ended.

Currently, sendFile always ends the response. This prevents sending data from more than one file.

This would be similar in nature to Pipe.endOnComplete().

This option would be also be available on the sendFile(filename, offset) and sendFile(filename, offset, length) variants as well, so partial files could also be sent.

Use case: We have an S3 storage service where multipart objects are stored in multiple files. We can send single part S3 objects with sendFile. But, when sending multipart objects (ranges), we must compose Pipe futures with endOnComplete(false), which does not take advantage of the zero-copy IO features of Linux.

I would not be able to contribute, but would be able to test the feature.

Thanks!

[vietj]

@oxsdd go ahead, I think also then the content-length should not be set on the response and instead it should be chunked ?

[oxsdd]

I was not sure if I would be able to contribute thinking that it is core internal code but if you would like me to I will make an attempt. Note that I am a first time contributor so I may need some assistance along the way.

I was not considering chunked encoding, since my use case does not need it. Instead I am looking for a means of pumping data from multiple files to the response that utilizes zero-copy. Currently the only option seems to be a composition of Pipe.endOnComplete(false) that call HttpServerResponse::write(Buffer) which is not zero-copy. Since the application can compute the content length from the files, it's not clear to me that chunked encoding support would be required?

Looking at Http1xServerResponse I am now thinking that instead of changing sendFile, that it might be better to add new methods to HttpServerResponse like the following, which have similar behavior to HttpServerResponse::write(Buffer):

Future<Void> writeFile(String path);
Future<Void> writeFile(string path, long offset);
Future<Void> writeFile(String path, long offset, long length);

The implementation in Http1xServerResponse would:

• Ensure the response was not already written, and throw an exception if it is.
• Ensure the response is not chunked, and throw an exception if it is.
• Ensure that Content-Length is set, and throw an exception if it is not.
• Open the RandomAccessFile
• If headers have not been written, prepare them (call prepareHeaders(-1)) and write them to the connection.
• Call ConnectionBase::sendFile(RandomAccessFile raf, long offset, long length) to send the file.
• Anything else at this point, since we are not ending the request?

It's not clear to me how to support chunking, so it is not allowed. That is handled by lower level code in ConnectionBase. I could dig deeper into ConnectionBase etc if chunked support is required. But I do not need it.

Usage with the new API would look something like this:

response.putHeader("content-length", "123456")
    .writeFile("file1.dat", 1234)
    .compose(v -> response.writeFile("file2.dat"))
    .compose(v -> response.writeFile("file3.dat", 0, 5678)
    .compose(v -> response.end());

instead of the current using Pipe:

response.putHeader("content-length", "123456");
vertx.fileSystem().open("file1", new OpenOptions()).map(file1 -> file1.setReadPos(1234))
    .compose(file1 -> file1.pipe().endOnComplete(false).to(response).eventually(v -> file1.close()))
    .compose(v -> vertx.fileSystem().open("file2", new OpenOptions()))
    .compose(file2 -> file2.pipe().endOnComplete(false).to(response).eventually(v -> file2.close()))
    .compose(v -> vertx.fileSystem().open("file3", new OpenOptions()).map(file3 -> file3.setReadLength(5678)))
    .compose(file3 -> file3.pipe().endOnComplete(false).to(response).eventually(v -> file3.close()))
    .compose(v -> response.end());

[jnbdz]

Picking this up. Looking at current master, sendFile is terminal on every transport (writes Content-Length, the file region, then the last content), so multi-file bodies still need Pipe#endOnComplete(false) and lose zero-copy on HTTP/1.

I'd propose the shape suggested by @oxsdd above rather than a flag on sendFile, since the semantics are really those of write:

Future<Void> writeFile(String filename);
Future<Void> writeFile(String filename, long offset);
Future<Void> writeFile(String filename, long offset, long length);
// same three for RandomAccessFile and FileChannel, mirroring sendFile

• behaves like write(Buffer): does not end the response, can be mixed with write calls and followed by end();
• the response must either be chunked or have a Content-Length set, exactly like write (same IllegalStateException otherwise) — no header is set on the user's behalf, in particular no Content-Length / Content-Type guessing, which is what makes sendFile terminal;
• HTTP/1: head written on the first write if needed, then the file region through the connection — HttpObjectEncoder frames a FileRegion as a chunk in chunked mode (encodedChunkedFileRegionContent), so both chunked and content-length responses keep zero-copy; the file is closed once written for the String variant and left open for the RandomAccessFile / FileChannel variants, like sendFile;
• HTTP/2 and HTTP/3: same as today's sendFile internals minus the end, i.e. the file region when the connection supports it, otherwise an AsyncFile piped with endOnComplete(false).

If you'd rather have sendFile(..., boolean end) overloads instead, or want to restrict writeFile to chunked responses only, tell me and I'll do that. Otherwise I'll go with the above and add tests for HTTP/1 (chunked and content-length), HTTP/2 and HTTP/3.

[oxsdd]

FYI the application where this was needed for my purposes has been retired, so this issue fell of the radar. Feel free to close as appropriate if it does not fulfill a general need. Thanks.