Add function to render HTML directly into ByteBuffer

[Cyberbeni]

I am creating a HTMX SSE based website where I want to send the same event to all the clients, so I want to just render that event into a ByteBuffer once and then pass a copy of that buffer to all the ResponseBodyWriter instances. Currently I'm rendering into a string and then writing that into the buffer which works fine, just copies the data more than necessary.

[Cyberbeni]

This is what I ended on:

import Elementary
import NIO

extension ByteBuffer {
	mutating func writeHTML(_ html: consuming any HTML, chunkSize: Int = 1024) async throws {
		try await html.render(into: &self, chunkSize: chunkSize)
	}
}

private extension HTML {
	consuming func render(into buffer: UnsafeMutablePointer<ByteBuffer>, chunkSize: Int) async throws {
		try await render(into: ByteBufferWriter(buffer: buffer), chunkSize: chunkSize)
	}
}

private class ByteBufferWriter: HTMLStreamWriter {
	private let buffer: UnsafeMutablePointer<ByteBuffer>

	init(buffer: UnsafeMutablePointer<ByteBuffer>) {
		self.buffer = buffer
	}

	func write(_ bytes: ArraySlice<UInt8>) async throws {
		buffer.pointee.writeBytes(bytes)
	}
}

[sliemeobn]

Hi, thanks for getting in touch!

At the moment Elementary is dependency-free, and to me adding a dependency (even NIO) has a very high bar.
I understand where you are coming from though, there should a be a lean way to get this done.

At the very least, I am pretty sure it will be possible to do something like your snippet above, but without unsafe pointers. (We could add an implementation of this to the hummingbird/vapor integration packages maybe?)

The real "fix" should come with the introduction of RawSpans to Swift - then we should be able to add a zero-allocation, zero-generics render implementation.

[Cyberbeni]

Ah, my previous code relied on undefined behaviour (https://github.com/swiftlang/swift/blob/974767eb830620a32abaa98aa3402d0caab0d7ad/stdlib/public/core/UnsafePointer.swift#L649-L657), fixed it in case someone wants to copy paste it.

[Cyberbeni]

I had some time to think about this. Is this the RawSpan based API you were thinking about?

consuming func render(into writer: (RawSpan) -> Void)

Both of the current render(into:) functions mark their input as escaping (or non-borrowing) but they don't actually escape the writer, they're just used in a way that the compiler can't guarantee that they are not escaped. That should be avoided with the new API.

(Buffering the writes just adds unnecessary memcopies, assuming our writer has sensible strategy for allocating extra storage. For example ByteBuffer always allocates desiredCapacity.nextPowerOf2ClampedToMax() amount of bytes, so with a good initial capacity(like 512B for an HTMX-SSE message, 4kB for a basic full page, 64kB for a more complex page), we can avoid the extra reallocs at small size.)

[sliemeobn]

I am not sure yet how exactly, but I figured it would be best if we get an OutputSpan as param and write directly into the consumers buffer (eg: the ByteBuffer that we then pass down the NIO pipeline).

the only thing we'd need to "learn" is to chunk it up based on the OutputSpan's size and somehow keep asking for an OutputSpan until we are done. but I haven't really seriously thought about it.

[Cyberbeni]

Did some benchmarks with HummingbirdElementary and it seems like switching AsyncHTMLRenderer to one that uses ByteBuffer instead of [UInt8] internally, makes it slower 🤔 (This would allow us to skip self.allocator.buffer(bytes: bytes) and just pass the existing ByteBuffer then clear it)

There is a typo in the default value here: https://github.com/hummingbird-community/hummingbird-elementary/blob/e41590e49cdb60dcf62004fc15729a10c069249c/Sources/HummingbirdElementary/HTMLResponseBodyWriter.swift#L19

And I think this should be chunkSize instead of buffer.capacity: https://github.com/sliemeobn/elementary/blob/a9029bc81a7f02464a500581e702f21d261c1b9a/Sources/Elementary/Rendering/HtmlAsyncRenderer.swift#L18

[sliemeobn]

just FYI, I intend to add an experimental new "fast render" path following the AsyncWriter shape as suggested here:
https://github.com/apple/swift-async-algorithms/blob/3da39bbc4e687d4192af7c9cf4eab805745a0b9c/Sources/AsyncStreaming/NNNN-async-streaming.md

basically, have a write protocol that offers a write function with buffer callback (some output span maybe?)
then we could allocate a single ByteBuffer and use it to shuttle the chunks of HTML down the pipe, because elementary can write into unowned storage... I'll keep you posted.