Skip to content

Escape Text and Textf at render time - #357

Merged
maragubot merged 7 commits into
mainfrom
lazy-text-escaping
Sep 24, 2026
Merged

maragubot merged 7 commits into
mainfrom
lazy-text-escaping

Conversation

@maragubot

@maragubot maragubot commented Sep 15, 2026 •

Copy link
Copy Markdown
Collaborator
  • Text and Textf return a text node that escapes as it renders through writeEscaped, the same path attribute values take since Avoid another allocation #352, instead of escaping into a new string at construction and rendering that as raw. Rendered bytes are unchanged.
  • escapeString had no callers left and is removed. The internal test and fuzz target now pin writeEscaped against text/template.HTMLEscapeString on the same inputs as before, through both a strings.Builder and a writer that only has Write, so both branches are held to the reference.
  • Refreshes the README benchmark highlights table from a run on this branch: the realistic full page drops from 3044 to 2858 allocations and from 129686 to 126580 bytes per render, Text and Textf keep their allocations since the highlight uses short clean text, and the other rows are updated so the whole table comes from one run.
  • text satisfies fmt.Stringer with the escaped string, as raw did for Text before, with a test for it; a second opinion caught that the first version had dropped it.

The trade is the one #352 made for attributes. A page built and rendered once per request saves one allocation and the copy for every text node that needs escaping. A tree built once and rendered many times escapes on every render instead of once. A side effect in the first case's favour: Text inside an If(false, ...) is still constructed, since Go evaluates the argument, but no longer escapes a string nobody renders.

Eager (main, with the BenchmarkText table from #356) versus this branch, Apple M4, Go 1.27.1, interleaved, n=10. construct and render is the per-request path:

writer / text sec/op allocs/op
discarded / short text, no escaping ~ 1 → 1
discarded / long text, no escaping +5% 1 → 1
discarded / short text, little escaping -48% 2 → 1
discarded / long text, little escaping -55% 3 → 1
discarded / short text, much escaping -36% 2 → 1
discarded / long text, much escaping -36% 3 → 1
buffered / short text, little escaping -38% 2 → 1
buffered / long text, little escaping -42% 3 → 1
buffered / short text, much escaping -4% 2 → 1
buffered / long text, much escaping +8% 3 → 1
write-only, both kinds / all six ~ unchanged

render pre-built rows go from about 2 ns, one write of a ready string, to the full escaping cost on every render: 7.5 ns for short clean text, 128 ns for long text with little escaping, 239 ns for long text with much, on io.Discard. Writers without WriteString also gain one or two allocations per render on escaping rows.

BenchmarkRealisticPage, which is what a request looks like:

variant sec/op allocs/op
construct and render / discarded -2.3% 3044 → 2858
construct and render / buffered -3.8% 3044 → 2858
render pre-built tree / discarded +2.1% 18 → 18
render pre-built tree / buffered -0.9% 18 → 18

See #352, #356.

`Text` and `Textf` return a `text` node that escapes as it renders through `writeEscaped`,
like attribute values do, instead of escaping into a new string at construction. A page built
and rendered once per request saves one allocation per text node that needs escaping; a tree
rendered many times escapes on every render instead of once.

`escapeString` had no callers left, so it is gone, and the internal test and fuzz target now
pin `writeEscaped` against `text/template` through both an `io.StringWriter` and a writer
that only has `Write`.

See #352, #356
Comment thread gomponents.go Resolved
@markuswustenberg

Copy link
Copy Markdown
Member

@Hendrikto this is essentially the same as #352, what do you think?

@maragubot

Copy link
Copy Markdown
Collaborator Author

One note on the trade-off. The only case this makes slower is a tree built once and rendered many times, which now escapes its text on every render instead of once. That is the case #323 is about: a node rendered once into a string and written from then on would pay the escaping once and skip the tree walk too, so it would end up ahead of where eager escaping is today. Whatever shape that lands in, it is the natural companion to this change.

Base automatically changed from text-writer-benchmarks to main September 16, 2026 11:46
@codecov

codecov Bot commented Sep 16, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (ee8dbbd) to head (0009760).

Additional details and impacted files
@@            Coverage Diff            @@
##              main      #357   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            6         6           
  Lines          681       685    +4     
=========================================
+ Hits           681       685    +4     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@Hendrikto

Copy link
Copy Markdown
Contributor

Hi @markuswustenberg,

We discussed this before, e.g. in #314, and back then, I came to the conclusion that the trade-off is likely not worth it. However, now with everything that changed in the meantime, the verdict may change. I will have a closer look.

Off the top of my head, there are definitely advantages to this approach. We could even make g.Text a type in a potential v2, similar to g.Raw, so we could have g.Text constants, take g.Text parameters, etc.

Today I am pretty busy, but I will evaluate this branch when I find the time.

@markuswustenberg

Copy link
Copy Markdown
Member

Take your time, as always. :-)

@markuswustenberg

Copy link
Copy Markdown
Member

Note to self: update readme benchmark when/if this merges.

@Hendrikto

Hendrikto commented Sep 21, 2026 •

Copy link
Copy Markdown
Contributor

I had a closer look, and it is really non-obvious whether this change makes sense. I get why you consulted me 😄

Results

First of all, here are my benchmark results:

benchmark results

These results were obtained as follows:

❯ git rev-parse HEAD
ee8dbbd1270b1317d815f1711a27c448d84f34c1 # markus/main
❯ go test . -bench=Text -benchmem -count=10 > main-Text.txt
❯ git switch lazy-text-escaping 
Switched to branch 'lazy-text-escaping'
Your branch is up to date with 'hendrik/lazy-text-escaping'.
❯ git rev-parse HEAD            
6b002b32a2f6160d827271c7c9627cbc7eaf7f93 # markus/lazy-text-escaping rebased on markus/main (ee8dbbd1270b1317d815f1711a27c448d84f34c1)
❯ go test . -bench=Text -benchmem -count=10 > lazy_escaping-Text.txt
❯ go run golang.org/x/perf/cmd/benchstat@latest main-Text.txt lazy_escaping-Text.txt > benchstat-Text.txt
❯ grep -vP '~ \(p=' benchstat-Text.txt > diff-Text.txt

Then I resorted the results such that all "construct and render" tests are grouped.

goos: linux
goarch: amd64
pkg: maragu.dev/gomponents
cpu: AMD Ryzen 9 9950X3D 16-Core Processor          
                                                                             │ main-Text.txt │         lazy_escaping-Text.txt          │
                                                                             │    sec/op     │    sec/op      vs base                  │
Text/construct_and_render/discarded/short_text,_no_escaping-32                   15.32n ± 0%     14.48n ± 0%     -5.45% (p=0.000 n=10)
Text/construct_and_render/discarded/long_text,_no_escaping-32                    87.79n ± 1%     85.43n ± 1%     -2.68% (p=0.000 n=10)
Text/construct_and_render/discarded/short_text,_little_escaping-32               37.17n ± 1%     19.68n ± 1%    -47.07% (p=0.000 n=10)
Text/construct_and_render/discarded/long_text,_little_escaping-32                217.1n ± 0%     116.6n ± 1%    -46.29% (p=0.000 n=10)
Text/construct_and_render/discarded/short_text,_much_escaping-32                 40.21n ± 1%     23.98n ± 1%    -40.36% (p=0.000 n=10)
Text/construct_and_render/discarded/long_text,_much_escaping-32                  299.8n ± 0%     194.4n ± 1%    -35.13% (p=0.000 n=10)
Text/construct_and_render/buffered/short_text,_no_escaping-32                    16.97n ± 1%     15.98n ± 1%     -5.83% (p=0.000 n=10)
Text/construct_and_render/buffered/long_text,_no_escaping-32                     91.48n ± 1%     88.05n ± 1%     -3.75% (p=0.000 n=10)
Text/construct_and_render/buffered/short_text,_little_escaping-32                38.76n ± 1%     24.46n ± 1%    -36.87% (p=0.000 n=10)
Text/construct_and_render/buffered/long_text,_little_escaping-32                 222.6n ± 0%     164.5n ± 1%    -26.11% (p=0.000 n=10)
Text/construct_and_render/buffered/short_text,_much_escaping-32                  41.81n ± 1%     37.04n ± 1%    -11.41% (p=0.000 n=10)
Text/construct_and_render/buffered/long_text,_much_escaping-32                   305.9n ± 0%     395.9n ± 2%    +29.40% (p=0.000 n=10)
Text/construct_and_render/write-only/short_text,_no_escaping-32                  25.89n ± 1%     24.38n ± 1%     -5.85% (p=0.000 n=10)
Text/construct_and_render/write-only/long_text,_no_escaping-32                   123.0n ± 3%     117.0n ± 1%     -4.84% (p=0.000 n=10)
Text/construct_and_render/write-only/short_text,_little_escaping-32              49.09n ± 1%     48.08n ± 1%     -2.07% (p=0.000 n=10)
Text/construct_and_render/write-only/long_text,_little_escaping-32               244.6n ± 0%     241.8n ± 0%     -1.10% (p=0.000 n=10)
Text/construct_and_render/write-only/short_text,_much_escaping-32                50.15n ± 1%     49.05n ± 1%     -2.18% (p=0.000 n=10)
Text/construct_and_render/write-only/long_text,_much_escaping-32                 341.9n ± 1%     336.4n ± 0%     -1.59% (p=0.000 n=10)
Text/construct_and_render/write-only_buffered/short_text,_no_escaping-32         27.88n ± 1%     26.03n ± 1%     -6.64% (p=0.000 n=10)
Text/construct_and_render/write-only_buffered/long_text,_no_escaping-32          126.2n ± 2%     122.3n ± 2%     -3.13% (p=0.000 n=10)
Text/construct_and_render/write-only_buffered/short_text,_little_escaping-32     51.57n ± 1%     49.66n ± 1%     -3.69% (p=0.000 n=10)
Text/construct_and_render/write-only_buffered/long_text,_little_escaping-32      252.6n ± 2%     247.9n ± 0%     -1.84% (p=0.000 n=10)
Text/construct_and_render/write-only_buffered/short_text,_much_escaping-32       51.66n ± 1%     50.25n ± 1%     -2.74% (p=0.000 n=10)
Text/construct_and_render/write-only_buffered/long_text,_much_escaping-32        350.4n ± 0%     345.2n ± 1%     -1.46% (p=0.000 n=10)
Text/render_pre-built/discarded/short_text,_no_escaping-32                       1.993n ± 0%     5.951n ± 4%   +198.60% (p=0.000 n=10)
Text/render_pre-built/discarded/long_text,_no_escaping-32                        1.997n ± 0%    70.545n ± 3%  +3432.55% (p=0.000 n=10)
Text/render_pre-built/discarded/short_text,_little_escaping-32                   2.001n ± 0%    10.930n ± 1%   +446.36% (p=0.000 n=10)
Text/render_pre-built/discarded/long_text,_little_escaping-32                    1.996n ± 0%   103.050n ± 2%  +5064.12% (p=0.000 n=10)
Text/render_pre-built/discarded/short_text,_much_escaping-32                     1.997n ± 0%    14.715n ± 2%   +636.86% (p=0.000 n=10)
Text/render_pre-built/discarded/long_text,_much_escaping-32                      1.997n ± 0%   184.100n ± 1%  +9118.83% (p=0.000 n=10)
Text/render_pre-built/buffered/short_text,_no_escaping-32                        3.451n ± 2%     7.233n ± 1%   +109.59% (p=0.000 n=10)
Text/render_pre-built/buffered/long_text,_no_escaping-32                         5.241n ± 0%    71.990n ± 2%  +1273.59% (p=0.000 n=10)
Text/render_pre-built/buffered/short_text,_little_escaping-32                    3.641n ± 1%    15.295n ± 1%   +320.02% (p=0.000 n=10)
Text/render_pre-built/buffered/long_text,_little_escaping-32                     6.328n ± 1%   153.650n ± 2%  +2328.10% (p=0.000 n=10)
Text/render_pre-built/buffered/short_text,_much_escaping-32                      3.466n ± 2%    27.635n ± 0%   +697.32% (p=0.000 n=10)
Text/render_pre-built/buffered/long_text,_much_escaping-32                       7.131n ± 0%   384.800n ± 1%  +5296.54% (p=0.000 n=10)
Text/render_pre-built/write-only/short_text,_no_escaping-32                      12.01n ± 0%     15.81n ± 1%    +31.64% (p=0.000 n=10)
Text/render_pre-built/write-only/long_text,_no_escaping-32                       26.71n ± 1%    105.65n ± 1%   +295.54% (p=0.000 n=10)
Text/render_pre-built/write-only/short_text,_little_escaping-32                  13.47n ± 0%     39.36n ± 1%   +192.28% (p=0.000 n=10)
Text/render_pre-built/write-only/long_text,_little_escaping-32                   31.51n ± 0%    231.30n ± 0%   +634.17% (p=0.000 n=10)
Text/render_pre-built/write-only/short_text,_much_escaping-32                    12.12n ± 0%     40.58n ± 0%   +234.82% (p=0.000 n=10)
Text/render_pre-built/write-only/long_text,_much_escaping-32                     47.83n ± 1%    325.85n ± 0%   +581.27% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/short_text,_no_escaping-32             13.70n ± 1%     17.46n ± 1%    +27.53% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/long_text,_no_escaping-32              31.26n ± 2%    110.20n ± 1%   +252.53% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/short_text,_little_escaping-32         14.79n ± 1%     40.72n ± 1%   +175.19% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/long_text,_little_escaping-32          38.09n ± 3%    238.20n ± 0%   +525.28% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/short_text,_much_escaping-32           13.54n ± 2%     41.81n ± 1%   +208.90% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/long_text,_much_escaping-32            54.62n ± 2%    335.05n ± 2%   +513.42% (p=0.000 n=10)
Textf/formatted_text_element-32                                                  47.84n ± 1%     46.11n ± 1%     -3.60% (p=0.000 n=10)
geomean                                                                          26.49n          63.15n        +138.42%

                                                                             │ main-Text.txt  │         lazy_escaping-Text.txt          │
                                                                             │      B/op      │     B/op      vs base                   │
Text/construct_and_render/discarded/short_text,_little_escaping-32               40.00 ± 0%       16.00 ± 0%   -60.00% (p=0.000 n=10)
Text/construct_and_render/discarded/long_text,_little_escaping-32               656.00 ± 0%       16.00 ± 0%   -97.56% (p=0.000 n=10)
Text/construct_and_render/discarded/short_text,_much_escaping-32                 48.00 ± 0%       16.00 ± 0%   -66.67% (p=0.000 n=10)
Text/construct_and_render/discarded/long_text,_much_escaping-32                1040.00 ± 0%       16.00 ± 0%   -98.46% (p=0.000 n=10)
Text/construct_and_render/buffered/short_text,_little_escaping-32                40.00 ± 0%       16.00 ± 0%   -60.00% (p=0.000 n=10)
Text/construct_and_render/buffered/long_text,_little_escaping-32                656.00 ± 0%       16.00 ± 0%   -97.56% (p=0.000 n=10)
Text/construct_and_render/buffered/short_text,_much_escaping-32                  48.00 ± 0%       16.00 ± 0%   -66.67% (p=0.000 n=10)
Text/construct_and_render/buffered/long_text,_much_escaping-32                 1040.00 ± 0%       16.00 ± 0%   -98.46% (p=0.000 n=10)
Text/render_pre-built/write-only/short_text,_little_escaping-32                  24.00 ± 0%       48.00 ± 0%  +100.00% (p=0.000 n=10)
Text/render_pre-built/write-only/long_text,_little_escaping-32                   320.0 ± 0%       960.0 ± 0%  +200.00% (p=0.000 n=10)
Text/render_pre-built/write-only/short_text,_much_escaping-32                    32.00 ± 0%       64.00 ± 0%  +100.00% (p=0.000 n=10)
Text/render_pre-built/write-only/long_text,_much_escaping-32                     512.0 ± 0%      1536.0 ± 0%  +200.00% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/short_text,_little_escaping-32         24.00 ± 0%       48.00 ± 0%  +100.00% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/long_text,_little_escaping-32          320.0 ± 0%       960.0 ± 0%  +200.00% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/short_text,_much_escaping-32           32.00 ± 0%       64.00 ± 0%  +100.00% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/long_text,_much_escaping-32            512.0 ± 0%      1536.0 ± 0%  +200.00% (p=0.000 n=10)
geomean                                                                                     ²                  -22.74%                ²
² summaries must be >0 to compute geomean

                                                                             │ main-Text.txt │        lazy_escaping-Text.txt         │
                                                                             │   allocs/op   │ allocs/op   vs base                   │
Text/construct_and_render/discarded/short_text,_little_escaping-32              2.000 ± 0%     1.000 ± 0%   -50.00% (p=0.000 n=10)
Text/construct_and_render/discarded/long_text,_little_escaping-32               3.000 ± 0%     1.000 ± 0%   -66.67% (p=0.000 n=10)
Text/construct_and_render/discarded/short_text,_much_escaping-32                2.000 ± 0%     1.000 ± 0%   -50.00% (p=0.000 n=10)
Text/construct_and_render/discarded/long_text,_much_escaping-32                 3.000 ± 0%     1.000 ± 0%   -66.67% (p=0.000 n=10)
Text/construct_and_render/buffered/short_text,_little_escaping-32               2.000 ± 0%     1.000 ± 0%   -50.00% (p=0.000 n=10)
Text/construct_and_render/buffered/long_text,_little_escaping-32                3.000 ± 0%     1.000 ± 0%   -66.67% (p=0.000 n=10)
Text/construct_and_render/buffered/short_text,_much_escaping-32                 2.000 ± 0%     1.000 ± 0%   -50.00% (p=0.000 n=10)
Text/construct_and_render/buffered/long_text,_much_escaping-32                  3.000 ± 0%     1.000 ± 0%   -66.67% (p=0.000 n=10)
Text/render_pre-built/write-only/short_text,_little_escaping-32                 1.000 ± 0%     2.000 ± 0%  +100.00% (p=0.000 n=10)
Text/render_pre-built/write-only/long_text,_little_escaping-32                  1.000 ± 0%     3.000 ± 0%  +200.00% (p=0.000 n=10)
Text/render_pre-built/write-only/short_text,_much_escaping-32                   1.000 ± 0%     2.000 ± 0%  +100.00% (p=0.000 n=10)
Text/render_pre-built/write-only/long_text,_much_escaping-32                    1.000 ± 0%     3.000 ± 0%  +200.00% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/short_text,_little_escaping-32        1.000 ± 0%     2.000 ± 0%  +100.00% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/long_text,_little_escaping-32         1.000 ± 0%     3.000 ± 0%  +200.00% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/short_text,_much_escaping-32          1.000 ± 0%     2.000 ± 0%  +100.00% (p=0.000 n=10)
Text/render_pre-built/write-only_buffered/long_text,_much_escaping-32           1.000 ± 0%     3.000 ± 0%  +200.00% (p=0.000 n=10)
geomean                                                                                    ²                 +0.00%                ²
² summaries must be >0 to compute geomean

In summary, we get

construct and render render pre-built
sec/op -1.10% — -47.07% +27.53% — +9118.83%
B/op -60.00% — -98.46% +100.00% — +200.00%
allocs/op -50.00% — -66.67% +100.00% — +200.00%

All results are extremely statistically significant, and the only exception to the pattern is +29.40% sec/op for Text/construct_and_render/buffered/long_text,_much_escaping.

Considerations

In essence, this PR is hugely beneficial when constructing and rendering nodes, and enormously detrimental when rendering pre-built nodes. The question then becomes mainly how to weight those two use cases.

On one hand, you could argue that "construct and render" is the default, and probably the most common case, so we should optimize for that. On the other hand, this is also the "performance is no concern" option. Constructing and rendering is likely what most people start out with, and is almost always good enough. When performance does become an issue, this is exactly when one would switch to "rendering pre-built" option.

Does it make sense to optimize the case when performance is no concern and pessimize the performance-optimized use case?

On the other hand, optimizing the default construct and render path even further would also decrease the probability of ever having to think about performance and switch away from the default case. From my and @markuswustenberg's experience, construct and render is used almost exclusively.

For the rest of my reasoning, see this comment.

Recommendation

As @markuswustenberg said that he wants to optimize for the construct and render path, I recommend this PR be merged, as it is definitely a huge improvement to that path, as confirmed by benchmarks across different machines and architectures.

As that comes at the cost of decreased performance for the pre-built case, we might want to offer a fully static alternative, as discussed in #363. That would get us the best of both worlds: a performance-optimized default case, as well as a fully optimized static case for when even the optimized default becomes an issue.

@markuswustenberg

Copy link
Copy Markdown
Member

@Hendrikto thank you for your comment! I think it makes sense to take the absolute numbers into consideration as well. The pre-built docs still render in nanoseconds, but percentage-wise, it's a big difference, because the initial number is tiny. And yeah, memory allocation would be per-render, but fewer allocations in the default case.

I agree that construct and render is probably the default, and I'd like to optimize for that. (In fact, I don't think I've ever done anything else in my apps.) I wouldn't call it "performance is no concern" though. For static content, I'm working on something like #363.

But maybe there needs to be a better story for the case where someone would like to optimize by pre-building a component. Hmm. I'll think about it some more.

@Hendrikto

Copy link
Copy Markdown
Contributor

I agree that construct and render is probably the default, and I'd like to optimize for that.

In that case, that makes the analysis much simpler: If you want to optimize for the construct and render case, this PR is definitely an improvement. I did confirm with my own benchmarks on a different architecture.

I wouldn't call it "performance is no concern" though.

Maybe I could have phrased this more clearly. What I meant is

I don't think I've ever done anything else in my apps.

So construct and render is the default, and you would never reach for anything else, unless performance becomes a concern. So maybe I should have called it the "you did not have to think about performance yet" case.

For static content, I'm working on something like #363.

Something like that would have been my suggestion as well. I also use the construct and render path almost exclusively. If you have anything dynamic, you are almost forced to, unless you want to make really fine-grained components and cache just the static parts.

If we have an optimized default construct and render path, and a fully static path, I guess the middle ground of pre-building nodes becomes mostly irrelevant. You would either use construct and render of fully static.

That way, we make the default more performant, such that we have to think about performance even less, and if/when we do, we can switch to an even more optimized alternative.

@markuswustenberg

Copy link
Copy Markdown
Member

In that case, that makes the analysis much simpler: If you want to optimize for the construct and render case, this PR is definitely an improvement. I did confirm with my own benchmarks on a different architecture.

Excellent, thank you.

Something like that would have been my suggestion as well. I also use the construct and render path almost exclusively. If you have anything dynamic, you are almost forced to, unless you want to make really fine-grained components and cache just the static parts.

Yeah, true, and I think this is what most people do (and what all the examples etc. do). I think the design lends itself to that.

If we have an optimized default construct and render path, and a fully static path, I guess the middle ground of pre-building nodes becomes mostly irrelevant. You would either use construct and render of fully static.

That way, we make the default more performant, such that we have to think about performance even less, and if/when we do, we can switch to an even more optimized alternative.

Yeah, exactly.

Okay, that settles it, I'll merge this. Thank you again for your input, much appreciated!

@maragubot
maragubot merged commit 90943aa into main Sep 24, 2026
17 checks passed
@maragubot
maragubot deleted the lazy-text-escaping branch September 24, 2026 11:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants