-
Notifications
You must be signed in to change notification settings - Fork 1
/
renderer.go
273 lines (238 loc) · 7.71 KB
/
renderer.go
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
// Copyright 2023 The Authors (see AUTHORS file)
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// Package render exposes high-performance HTML and JSON rendering
// functionality. Most use cases can use the [Renderer] without modification.
// More advanced use cases can customize template functions and error handling.
//
// The renderer accepts a filesystem ([fs.FS]). In most cases, this will be a
// filesystem on disk. However, it accepts the FS interface for testing and
// [embed] purposes. Because embed does not perform hot reloading, you may want
// to use a different fs for development versus production:
//
// //go:embed assets assets/**/*
// var _assetsFS embed.FS
//
// func AssetsFS() fs.FS {
// // In dev, just read directly from disk
// if v, _ := strconv.ParseBool(os.Getenv("DEV_MODE")); v {
// return os.DirFS("./assets")
// }
//
// // Otherwise use the embedded fs
// return _assetsFS
// }
//
// The the renderer includes some prebuilt functions, including static asset
// parsing for CSS and Javascript files. The renderer assumes these files exist
// in a `static/css` and `static/js` directory at the root of the provided
// filesystem.
//
// assets/
// \_ static/
// \_ css/
// \_ js/
//
// To render the include tags in a template:
//
// {{ define "home" }}
// {{ cssIncludeTag "css/*.css" }}
// {{ jsIncludeTag "js/index.js" }}
// {{ end }}
package renderer
import (
"bytes"
"context"
"fmt"
"html/template"
"io"
"io/fs"
"strings"
"sync"
)
// Renderer is responsible for rendering various content and templates like HTML
// and JSON responses. This implementation caches templates and uses a pool of
// buffers.
type Renderer struct {
// rendererPool is a pool of *bytes.Buffer, used as a rendering buffer to
// prevent partial responses being sent to clients.
rendererPool *sync.Pool
// templates is the actual collection of templates. templatesLock is a mutex
// to prevent concurrent modification of the templates field.
templates *template.Template
templatesLock sync.RWMutex
// fs is the underlying filesystem to read.
fs fs.FS
// debug indicates templates should be reloaded on each invocation and real
// error responses should be rendered. Do not enable in production.
debug bool
// onError is a function that is called when irrecoverable errors are
// encountered. This is guaranteed to be non-nil when calling [New].
onError func(err error)
// templateFuncs is the compiled list of template functions.
templateFuncs template.FuncMap
}
// TestingFatalf is an interface that is satisfied by [testing.TB]. It exists to
// avoid depending on the testing package at runtime.
type TestingFatalf interface {
Fatalf(format string, args ...any)
}
// Option is an interface for options to creating a renderer.
type Option func(*Renderer) *Renderer
// WithDebug configures debugging on the renderer.
func WithDebug(v bool) Option {
return func(r *Renderer) *Renderer {
r.debug = v
return r
}
}
// WithOnError overwrites the onError handler with the given function. This
// handler is invoked when an irrecoverable error occurs while rendering, but
// information cannot be sent back to the client. For example, if HTTP rendering
// fails after a partial response has been sent.
func WithOnError(fn func(err error)) Option {
return func(r *Renderer) *Renderer {
r.onError = fn
return r
}
}
// WithTemplateFuncs registers additional template functions. The renderer
// includes many helpful functions, but some applications may wish to
// inject/define their own template helpers. Functions in this map take
// precedence over the built-in list. If called with multiple func maps or
// called multiple times with conflicting keys, the last key takes precedence.
// To delete an entry, supply a key with a nil value.
func WithTemplateFuncs(fns ...template.FuncMap) Option {
return func(r *Renderer) *Renderer {
if r.templateFuncs == nil {
r.templateFuncs = make(map[string]any)
}
for _, fn := range fns {
for k, v := range fn {
if v == nil {
delete(r.templateFuncs, k)
} else {
r.templateFuncs[k] = v
}
}
}
return r
}
}
// New creates a new renderer with the given details.
func New(ctx context.Context, fsys fs.FS, opts ...Option) (*Renderer, error) {
r := &Renderer{
rendererPool: &sync.Pool{
New: func() interface{} {
return bytes.NewBuffer(make([]byte, 0, 1024))
},
},
fs: fsys,
}
for _, opt := range opts {
if opt != nil {
r = opt(r)
}
}
// Ensure there's an error handler so we don't have to nil-check each time.
if r.onError == nil {
r.onError = func(err error) {}
}
// Wrap the error function to recover from panics.
origOnError := r.onError
r.onError = func(err error) {
defer func() {
if r := recover(); r != nil {
// do nothing
_ = r
}
}()
origOnError(err)
}
// Compile template functions.
fns := builtinFuncs()
fns["cssIncludeTag"] = assetIncludeTag(r.fs, cssIncludeTmpl, &cssIncludeTagCache, r.debug)
fns["jsIncludeTag"] = assetIncludeTag(r.fs, jsIncludeTmpl, &jsIncludeTagCache, r.debug)
for k, v := range r.templateFuncs {
fns[k] = v
}
r.templateFuncs = fns
// Load initial templates
if err := r.loadTemplates(); err != nil {
return nil, err
}
return r, nil
}
// NewTesting is a helper function to create a renderer suitable for injection
// in tests. It calls t.Fatal if setup fails.
func NewTesting(ctx context.Context, tb TestingFatalf, fsys fs.FS, opts ...Option) *Renderer {
opts = append([]Option{
WithDebug(true),
WithOnError(func(err error) {
tb.Fatalf("failed to render template: %s", err)
}),
}, opts...)
h, err := New(ctx, fsys, opts...)
if err != nil {
tb.Fatalf("failed to create renderer: %s", err)
}
return h
}
// executeTemplate executes a single HTML template with the provided data.
func (r *Renderer) executeTemplate(w io.Writer, name string, data interface{}) error {
r.templatesLock.RLock()
defer r.templatesLock.RUnlock()
if r.templates == nil {
return fmt.Errorf("no html templates are defined")
}
return r.templates.ExecuteTemplate(w, name, data) //nolint:wrapcheck // There's no additional context we can add
}
// loadTemplates loads or reloads all templates.
func (r *Renderer) loadTemplates() error {
r.templatesLock.Lock()
defer r.templatesLock.Unlock()
if r.fs == nil {
return nil
}
htmltmpl := template.New("").
Option("missingkey=zero").
Funcs(r.templateFuncs)
if err := loadTemplates(r.fs, htmltmpl); err != nil {
return fmt.Errorf("failed to load templates: %w", err)
}
r.templates = htmltmpl
return nil
}
func loadTemplates(fsys fs.FS, tmpl *template.Template) error {
// You might be thinking to yourself, wait, why don't you just use
// template.ParseFS(fsys, "**/*.html"). Well, still as of Go 1.16, glob
// doesn't support shopt globbing, so you still have to walk the entire
// filepath.
if err := fs.WalkDir(fsys, ".", func(pth string, info fs.DirEntry, err error) error {
if err != nil {
return err
}
if info.IsDir() {
return nil
}
if strings.HasSuffix(info.Name(), ".html") {
if _, err := tmpl.ParseFS(fsys, pth); err != nil {
return fmt.Errorf("failed to parse %s: %w", pth, err)
}
}
return nil
}); err != nil {
return fmt.Errorf("failed to walk filesystem for templates: %w", err)
}
return nil
}