RFC: HTML streaming in Podium #507

digitalsadhu · 2024-09-25T01:14:09Z

This PR is a first attempt at an API for HTML streaming. This is made possible by the early hints work which makes it possible to get assets from podlets before the rest of the podlet content.

podium-streaming.mov

The whole approach is non breaking with the caveat that in order to use the streaming feature, all podlets would need to be updated to the latest version of the podlet module (no code changes)

Other comments thoughts inline..

digitalsadhu · 2024-09-25T01:16:05Z

lib/layout.js

+                    this.#view(incoming, responseStream, ...args);
+                    // return the stream for the developer to work with
+                    return responseStream;
+                };


I went with a new function on res here. res.podiumStream which can be passed additional arguments for html template and returns a stream object to work with after setting up streaming internally. Worth noting that there will need to be a slightly different implementation for Fastify than Express here which is a good argument for implementing this as a function along side res.podiumSend I think.

with this approach, we can stay non breaking and any page that wants to implement streaming just needs to ensure that all podlets on the page are updated to a a version of @podium/podlet that supports early hints.

existing templates continue to work as before since we just inject a token and use it to split the template into 2 pieces. We then immediately send the first (header) and hand control to the developer to do streaming. Once the developer is finished and hands control back, we send the footer and terminate the stream.

Worth noting that there will need to be a slightly different implementation for Fastify than Express

The difference are under the hood or also in the public API surface?

The only difference would be in how we pipe the streams in the fastify plugin, api surface should be the same for the end user

digitalsadhu · 2024-09-25T01:21:23Z

lib/response-stream.js

+    end() {
+        setTimeout(() => this.push(null), 0);
+    }
+}


This Readable stream class probably belongs in the Podium utils package. It provides a .send() method to push chunks of html onto the response, a .done() method to be used by the developer to signal when they are finished pushing content, as well as a .end() method to indicate that the app has no more html to push and closes the stream.

Essentially, html template uses .send() to push the document head, then the application developer uses .send() to push the content and calls .done() when they are finished at which point HTML template takes over again and uses .send() to push the final bits of the template and ends the stream with .end()

digitalsadhu · 2024-09-25T01:23:01Z

lib/template.js

+        body.send(documentTrailers);
+        body.end();
+    });
+};


Not much difference here between this and the original built in html template. We check if body is a response stream instead of a string and if it is, we set up streaming, otherwise we do the same as before and just spit out a template

digitalsadhu · 2024-09-25T01:23:39Z

example/streaming/server.js

+    const contentFetch = content.fetch(incoming);
+    const footerFetch = footer.fetch(incoming);
+
+    incoming.hints.on('complete', async ({ js, css }) => {


once we have hints in from the podlets, we can set up streaming

digitalsadhu · 2024-09-25T01:23:54Z

example/streaming/server.js

+    incoming.hints.on('complete', async ({ js, css }) => {
+        // set the assets on httpincoming so that they are available in the document template
+        incoming.js = [...incoming.js, ...js];
+        incoming.css = [...incoming.css, ...css];


this is pretty awkward but works for now at least

digitalsadhu · 2024-09-25T01:25:12Z

example/streaming/server.js

+                    </div>
+                </div>
+            </template>
+        `);


In this case we are sending a DSD template with slots and placeholder skeleton html so that we can replace these by streaming in podlet content later.

digitalsadhu · 2024-09-25T01:25:39Z

example/streaming/server.js

+
+        // close out the dom and the stream
+        await Promise.all([headerFetch, menuFetch, contentFetch, footerFetch]);
+        stream.done();


Indicate that we are finished streaming content so that the html template can finish things off

digitalsadhu · 2024-09-25T01:26:11Z

example/streaming/server.js

+        // stream in podlet content when available...
+        headerFetch.then((content) => {
+            stream.send(`<div slot="header">${content}</div>`);
+        });


we decorate the podlet content in divs with slot attributes to indicate where they should be placed into the document.

wkillerud

This looks very cool 🎉

wkillerud · 2024-09-25T12:38:59Z

lib/layout.js

+
+                    // call our document template, injecting a token we can use to split the template
+                    // into header and footer
+                    const splitToken = `<!--split-token-->`;


I'm having a tough time visualizing how this split would affect loading. Is this only here to handle the server-simple case of shipping off <head> and <body> in two chunks?

We split the template on the position that would normally have the body injected by the developers so that we are left with 2 pieces that we are able to deliver. The first bit goes immediately, then we allow the user to stream whatever they want, and then we deliver the second bit at the end. In practice this looks like...

We deliver this right away..

<html> <head> ... </head> <body>

Then the developer does there thing and streams the content they want in the body... podlets etc

<main> ... podlets etc... </main>

Then we deliver the second split part of the template which is the document end...

... some scripts etc... </body> </html>

The nice thing about using the split technique is that all existing templates should just work as they are so its nice and backwards compatible

I guess my main concern about shipping a "finished" <head> is that podlets' early hints might give us styles and scripts that should be up there. I suppose that's a design constraint with streaming you have to deal with as an app developer, that your stuff can come in at any time?

we wait for all assets before shipping the head by using incoming.hints.on('complete')

digitalsadhu · 2024-09-26T01:30:58Z

Looked into browser and server support and the need for fallbacks etc. As I understand it, we are good because:

HTTP 1.1 onwards supports streams (HTTP 2 is more efficient)
If a browser or server didn't support streaming, content would just be buffered and displayed at once
Early hints work between podlet and layout regardless because we control the client (Undici) which supports early hints
Early hints won't work between the layout and the browser for older browsers or servers not using HTTP 2
Again, we dont need a fallback for early hints between layout and browser, all it will mean is a perf degradation.

trygve-lie · 2024-09-26T06:57:45Z

This is great stuff!

On the general side; are the loading sequential or are they out of order? In the video they look sequential. Getting it rendered out of order is a bit different problem I think.

digitalsadhu · 2024-09-26T07:01:45Z

This is great stuff!

On the general side; are the loading sequential or are they out of order? In the video they look sequential. Getting it rendered out of order is a bit different problem I think.

You have full control, in my demo I just did sequential setTimeouts to show the delay. You can have it all come in when it comes in or you can use Promise.all to wait for all podlets and send them out at once or you could do the header first and the rest after or however you like.

feat: html streaming

80b02c6

digitalsadhu commented Sep 25, 2024

View reviewed changes

digitalsadhu changed the title ~~feat: html streaming~~ RFC: HTML streaming in Podium Sep 25, 2024

digitalsadhu added 6 commits September 25, 2024 16:50

refactor: remove the need to rewrite html templates

2c2b292

chore: remove console logs and add comments

fa708b2

chore: add simple server example

5b91cb7

test: fix test snapshot

4618d55

test: set snapshot back again

5a575a8

chore: ignore type errors

858a50f

digitalsadhu requested review from trygve-lie, leftieFriele, wkillerud, tor0405 and flatoy September 25, 2024 08:02

wkillerud reviewed Sep 25, 2024

View reviewed changes

digitalsadhu added 2 commits September 26, 2024 18:30

docs: update docs and add tests

ada6812

chore: update @podium/test-utils

b75d0d4

Base automatically changed from next to main November 6, 2024 04:14

digitalsadhu added 2 commits November 11, 2024 14:26

Merge branch 'main' into prototype_html_streaming

ef3bcf9

refactor: drop early hints, use link header assets

651eee0

refactor(examples): rework examples to match latest podium

7a9a164

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

RFC: HTML streaming in Podium #507

RFC: HTML streaming in Podium #507

digitalsadhu commented Sep 25, 2024 •

edited

Loading

digitalsadhu Sep 25, 2024 •

edited

Loading

digitalsadhu Sep 25, 2024

digitalsadhu Sep 25, 2024

trygve-lie Sep 26, 2024

digitalsadhu Sep 26, 2024

digitalsadhu Sep 25, 2024

digitalsadhu Sep 25, 2024

digitalsadhu Sep 25, 2024

digitalsadhu Sep 25, 2024

digitalsadhu Sep 25, 2024

digitalsadhu Sep 25, 2024

digitalsadhu Sep 25, 2024

wkillerud left a comment

wkillerud Sep 25, 2024

digitalsadhu Sep 26, 2024 •

edited

Loading

digitalsadhu Sep 26, 2024

wkillerud Sep 26, 2024

digitalsadhu Sep 26, 2024

digitalsadhu commented Sep 26, 2024

trygve-lie commented Sep 26, 2024

digitalsadhu commented Sep 26, 2024

RFC: HTML streaming in Podium #507

Are you sure you want to change the base?

RFC: HTML streaming in Podium #507

Conversation

digitalsadhu commented Sep 25, 2024 • edited Loading

digitalsadhu Sep 25, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

wkillerud left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

digitalsadhu Sep 26, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

digitalsadhu commented Sep 26, 2024

trygve-lie commented Sep 26, 2024

digitalsadhu commented Sep 26, 2024

digitalsadhu commented Sep 25, 2024 •

edited

Loading

digitalsadhu Sep 25, 2024 •

edited

Loading

digitalsadhu Sep 26, 2024 •

edited

Loading