render.go

package render

import (
	"bytes"
	"encoding/json"
	"fmt"
	"html/template"
	"io"
	"log"
	"net/http"
	"os"
	"path/filepath"
	"strings"
	"sync"

	"github.com/fsnotify/fsnotify"
)

const (
	// ContentBinary header value for binary data.
	ContentBinary = "application/octet-stream"
	// ContentHTML header value for HTML data.
	ContentHTML = "text/html"
	// ContentJSON header value for JSON data.
	ContentJSON = "application/json"
	// ContentJSONP header value for JSONP data.
	ContentJSONP = "application/javascript"
	// ContentLength header constant.
	ContentLength = "Content-Length"
	// ContentText header value for Text data.
	ContentText = "text/plain"
	// ContentType header constant.
	ContentType = "Content-Type"
	// ContentXHTML header value for XHTML data.
	ContentXHTML = "application/xhtml+xml"
	// ContentXML header value for XML data.
	ContentXML = "text/xml"
	// Default character encoding.
	defaultCharset = "UTF-8"
	// Buffer pool size.
	bufferPoolSize = 32
	// Buffer pool capacity.
	bufferPoolCapacity = 1 << 19
)

// helperFuncs had to be moved out. See helpers.go|helpers_pre16.go files.

// Delims represents a set of Left and Right delimiters for HTML template rendering.
type Delims struct {
	// Left delimiter, defaults to {{.
	Left string
	// Right delimiter, defaults to }}.
	Right string
}

// Options is a struct for specifying configuration options for the render.Render object.
type Options struct {
	// Directory to load templates. Default is "templates".
	Directory string
	// FileSystem to access files
	FileSystem FileSystem
	// Asset function to use in place of directory. Defaults to nil.
	Asset func(name string) ([]byte, error)
	// AssetNames function to use in place of directory. Defaults to nil.
	AssetNames func() []string
	// Layout template name. Will not render a layout if blank (""). Defaults to blank ("").
	Layout string
	// Extensions to parse template files from. Defaults to [".tmpl"].
	Extensions []string
	// Funcs is a slice of FuncMaps to apply to the template upon compilation.
	// This is useful for helper functions. Defaults to empty map.
	Funcs []template.FuncMap
	// Delims sets the action delimiters to the specified strings in the Delims struct.
	Delims Delims
	// Appends the given character set to the Content-Type header. Default is "UTF-8".
	Charset string
	// If DisableCharset is set to true, it will not append the above Charset value to the Content-Type header.
	// Default is false.
	DisableCharset bool
	// Outputs human readable JSON.
	IndentJSON bool
	// Outputs human readable XML. Default is false.
	IndentXML bool
	// Prefixes the JSON output with the given bytes. Default is false.
	PrefixJSON []byte
	// Prefixes the XML output with the given bytes.
	PrefixXML []byte
	// Allows changing the binary content type.
	BinaryContentType string
	// Allows changing the HTML content type.
	HTMLContentType string
	// Allows changing the JSON content type.
	JSONContentType string
	// Allows changing the JSONP content type.
	JSONPContentType string
	// Allows changing the Text content type.
	TextContentType string
	// Allows changing the XML content type.
	XMLContentType string
	// If IsDevelopment is set to true, this will recompile the templates on every request. Default is false.
	IsDevelopment bool
	// If UseMutexLock is set to true, the standard `sync.RWMutex` lock will be used instead of the lock free
	// implementation. Default is false. Note that when `IsDevelopment` is true, the standard `sync.RWMutex`
	// lock is always used. Lock free is only a production feature.
	UseMutexLock bool
	// Unescape HTML characters "&<>" to their original values. Default is false.
	UnEscapeHTML bool
	// Sets the `Option` value for HTML templates. Defaults to blank ("").
	HTMLTemplateOption string
	// Streams JSON responses instead of marshalling prior to sending. Default is false.
	StreamingJSON bool
	// Require that all partials executed in the layout are implemented in all templates using the layout.
	// Default is false.
	RequirePartials bool
	// Deprecated: Use the above `RequirePartials` instead of this. As of Go 1.6, blocks are built in. Default is false.
	RequireBlocks bool
	// Disables automatic rendering of http.StatusInternalServerError when an error occurs. Default is false.
	DisableHTTPErrorRendering bool
	// Enables using partials without the current filename suffix which allows use of the same template in
	// multiple files. e.g {{ partial "carousel" }} inside the home template will match carousel-home or carousel.
	// ***NOTE*** - This option should be named RenderPartialsWithoutSuffix as that is what it does.
	// "Prefix" is a typo. Maintaining the existing name for backwards compatibility.
	RenderPartialsWithoutPrefix bool
	// BufferPool to use when rendering HTML templates. If none is supplied
	// defaults to SizedBufferPool of size 32 with 512KiB buffers.
	BufferPool GenericBufferPool
	// Custom JSON Encoder. Defaults to encoding/json.NewEncoder.
	JSONEncoder func(w io.Writer) JSONEncoder
}

// HTMLOptions is a struct for overriding some rendering Options for specific HTML call.
type HTMLOptions struct {
	// Layout template name. Overrides Options.Layout.
	Layout string
	// Funcs added to Options.Funcs.
	Funcs template.FuncMap
}

// Render is a service that provides functions for easily writing JSON, XML,
// binary data, and HTML templates out to a HTTP Response.
type Render struct {
	lock rwLock

	// Customize Secure with an Options struct.
	opt             Options
	templates       *template.Template
	compiledCharset string
	hasWatcher      bool
}

// New constructs a new Render instance with the supplied options.
func New(options ...Options) *Render {
	var o Options
	if len(options) > 0 {
		o = options[0]
	}

	r := Render{opt: o}

	r.prepareOptions()
	r.CompileTemplates()

	return &r
}

func (r *Render) prepareOptions() {
	// Fill in the defaults if need be.
	if len(r.opt.Charset) == 0 {
		r.opt.Charset = defaultCharset
	}

	if !r.opt.DisableCharset {
		r.compiledCharset = "; charset=" + r.opt.Charset
	}

	if len(r.opt.Directory) == 0 {
		r.opt.Directory = "templates"
	}

	if r.opt.FileSystem == nil {
		r.opt.FileSystem = &LocalFileSystem{}
	}

	if len(r.opt.Extensions) == 0 {
		r.opt.Extensions = []string{".tmpl"}
	}

	if len(r.opt.BinaryContentType) == 0 {
		r.opt.BinaryContentType = ContentBinary
	}

	if len(r.opt.HTMLContentType) == 0 {
		r.opt.HTMLContentType = ContentHTML
	}

	if len(r.opt.JSONContentType) == 0 {
		r.opt.JSONContentType = ContentJSON
	}

	if len(r.opt.JSONPContentType) == 0 {
		r.opt.JSONPContentType = ContentJSONP
	}

	if len(r.opt.TextContentType) == 0 {
		r.opt.TextContentType = ContentText
	}

	if len(r.opt.XMLContentType) == 0 {
		r.opt.XMLContentType = ContentXML
	}

	if r.opt.BufferPool == nil {
		r.opt.BufferPool = NewSizedBufferPool(bufferPoolSize, bufferPoolCapacity)
	}

	if r.opt.IsDevelopment || r.opt.UseMutexLock {
		r.lock = &sync.RWMutex{}
	} else {
		r.lock = &emptyLock{}
	}

	if r.opt.JSONEncoder == nil {
		r.opt.JSONEncoder = func(w io.Writer) JSONEncoder {
			return json.NewEncoder(w)
		}
	}
}

func (r *Render) CompileTemplates() {
	if r.opt.Asset == nil || r.opt.AssetNames == nil {
		r.compileTemplatesFromDir()

		return
	}

	r.compileTemplatesFromAsset()
}

func (r *Render) compileTemplatesFromDir() {
	dir := r.opt.Directory
	tmpTemplates := template.New(dir)

	if len(r.opt.HTMLTemplateOption) > 0 {
		tmpTemplates.Option(r.opt.HTMLTemplateOption)
	}

	tmpTemplates.Delims(r.opt.Delims.Left, r.opt.Delims.Right)

	var watcher *fsnotify.Watcher

	if r.opt.IsDevelopment {
		var err error

		watcher, err = fsnotify.NewWatcher()
		if err != nil {
			log.Printf("Unable to create new watcher for template files. "+
				"Templates will be recompiled on every render. Error: %v\n", err)
		}
	}

	// Walk the supplied directory and compile any files that match our extension list.
	_ = r.opt.FileSystem.Walk(dir, func(path string, info os.FileInfo, _ error) error {
		// Fix same-extension-dirs bug: some dir might be named to: "users.tmpl", "local.html".
		// These dirs should be excluded as they are not valid golang templates, but files under
		// them should be treat as normal.
		// If is a dir, return immediately (dir is not a valid golang template).
		if info != nil && watcher != nil {
			_ = watcher.Add(path)
		}

		if info == nil || info.IsDir() {
			return nil
		}

		rel, err := filepath.Rel(dir, path)
		if err != nil {
			return err
		}

		ext := ""
		if strings.Contains(rel, ".") {
			ext = filepath.Ext(rel)
		}

		for _, extension := range r.opt.Extensions {
			if ext == extension {
				buf, err := r.opt.FileSystem.ReadFile(path)
				if err != nil {
					panic(err)
				}

				name := (rel[0 : len(rel)-len(ext)])
				tmpl := tmpTemplates.New(filepath.ToSlash(name))

				// Add our funcmaps.
				for _, funcs := range r.opt.Funcs {
					tmpl.Funcs(funcs)
				}

				// Break out if this parsing fails. We don't want any silent server starts.
				template.Must(tmpl.Funcs(helperFuncs()).Parse(string(buf)))

				break
			}
		}

		return nil
	})

	r.lock.Lock()
	defer r.lock.Unlock()
	r.templates = tmpTemplates

	if r.hasWatcher = watcher != nil; r.hasWatcher {
		go func() {
			select {
			case _, ok := <-watcher.Events:
				if !ok {
					return
				}
			case _, ok := <-watcher.Errors:
				if !ok {
					return
				}
			}
			watcher.Close()
			r.CompileTemplates()
		}()
	}
}

func (r *Render) compileTemplatesFromAsset() {
	dir := r.opt.Directory
	tmpTemplates := template.New(dir)

	if len(r.opt.HTMLTemplateOption) > 0 {
		tmpTemplates.Option(r.opt.HTMLTemplateOption)
	}

	tmpTemplates.Delims(r.opt.Delims.Left, r.opt.Delims.Right)

	for _, path := range r.opt.AssetNames() {
		if !strings.HasPrefix(path, dir) {
			continue
		}

		rel, err := filepath.Rel(dir, path)
		if err != nil {
			panic(err)
		}

		ext := ""
		if strings.Contains(rel, ".") {
			ext = "." + strings.Join(strings.Split(rel, ".")[1:], ".")
		}

		for _, extension := range r.opt.Extensions {
			if ext == extension {
				buf, err := r.opt.Asset(path)
				if err != nil {
					panic(err)
				}

				name := (rel[0 : len(rel)-len(ext)])
				tmpl := tmpTemplates.New(filepath.ToSlash(name))

				// Add our funcmaps.
				for _, funcs := range r.opt.Funcs {
					tmpl.Funcs(funcs)
				}

				// Break out if this parsing fails. We don't want any silent server starts.
				template.Must(tmpl.Funcs(helperFuncs()).Parse(string(buf)))

				break
			}
		}
	}

	r.lock.Lock()
	defer r.lock.Unlock()
	r.templates = tmpTemplates
}

// TemplateLookup is a wrapper around template.Lookup and returns
// the template with the given name that is associated with t, or nil
// if there is no such template.
func (r *Render) TemplateLookup(t string) *template.Template {
	r.lock.RLock()
	defer r.lock.RUnlock()

	return r.templates.Lookup(t)
}

func (r *Render) execute(templates *template.Template, name string, binding interface{}) (*bytes.Buffer, error) {
	buf := new(bytes.Buffer)

	return buf, templates.ExecuteTemplate(buf, name, binding)
}

func (r *Render) layoutFuncs(templates *template.Template, name string, binding interface{}) template.FuncMap {
	return template.FuncMap{
		"yield": func() (template.HTML, error) {
			buf, err := r.execute(templates, name, binding)

			// Return safe HTML here since we are rendering our own template.
			return template.HTML(buf.String()), err
		},
		"current": func() (string, error) {
			return name, nil
		},
		"block": func(partialName string) (template.HTML, error) {
			log.Println("Render's `block` implementation is now depericated. Use `partial` as a drop in replacement.")
			fullPartialName := fmt.Sprintf("%s-%s", partialName, name)
			if templates.Lookup(fullPartialName) == nil && r.opt.RenderPartialsWithoutPrefix {
				fullPartialName = partialName
			}
			if r.opt.RequireBlocks || templates.Lookup(fullPartialName) != nil {
				buf, err := r.execute(templates, fullPartialName, binding)
				// Return safe HTML here since we are rendering our own template.
				return template.HTML(buf.String()), err
			}

			return "", nil
		},
		"partial": func(partialName string) (template.HTML, error) {
			fullPartialName := fmt.Sprintf("%s-%s", partialName, name)
			if templates.Lookup(fullPartialName) == nil && r.opt.RenderPartialsWithoutPrefix {
				fullPartialName = partialName
			}
			if r.opt.RequirePartials || templates.Lookup(fullPartialName) != nil {
				buf, err := r.execute(templates, fullPartialName, binding)
				// Return safe HTML here since we are rendering our own template.
				return template.HTML(buf.String()), err
			}

			return "", nil
		},
	}
}

func (r *Render) prepareHTMLOptions(htmlOpt []HTMLOptions) HTMLOptions {
	layout := r.opt.Layout
	funcs := template.FuncMap{}

	for _, tmp := range r.opt.Funcs {
		for k, v := range tmp {
			funcs[k] = v
		}
	}

	if len(htmlOpt) > 0 {
		opt := htmlOpt[0]
		if len(opt.Layout) > 0 {
			layout = opt.Layout
		}

		for k, v := range opt.Funcs {
			funcs[k] = v
		}
	}

	return HTMLOptions{
		Layout: layout,
		Funcs:  funcs,
	}
}

// Render is the generic function called by XML, JSON, Data, HTML, and can be called by custom implementations.
func (r *Render) Render(w io.Writer, e Engine, data interface{}) error {
	err := e.Render(w, data)
	if hw, ok := w.(http.ResponseWriter); err != nil && !r.opt.DisableHTTPErrorRendering && ok {
		http.Error(hw, err.Error(), http.StatusInternalServerError)
	}

	return err
}

// Data writes out the raw bytes as binary data.
func (r *Render) Data(w io.Writer, status int, v []byte) error {
	head := Head{
		ContentType: r.opt.BinaryContentType,
		Status:      status,
	}

	d := Data{
		Head: head,
	}

	return r.Render(w, d, v)
}

// HTML builds up the response from the specified template and bindings.
func (r *Render) HTML(w io.Writer, status int, name string, binding interface{}, htmlOpt ...HTMLOptions) error {
	// If we are in development mode, recompile the templates on every HTML request.
	r.lock.RLock() // rlock here because we're reading the hasWatcher
	if r.opt.IsDevelopment && !r.hasWatcher {
		r.lock.RUnlock() // runlock here because CompileTemplates will lock
		r.CompileTemplates()
		r.lock.RLock()
	}

	templates := r.templates
	r.lock.RUnlock()

	opt := r.prepareHTMLOptions(htmlOpt)
	if tpl := templates.Lookup(name); tpl != nil {
		if len(opt.Layout) > 0 {
			tpl.Funcs(r.layoutFuncs(templates, name, binding))
			name = opt.Layout
		}

		if len(opt.Funcs) > 0 {
			tpl.Funcs(opt.Funcs)
		}
	}

	head := Head{
		ContentType: r.opt.HTMLContentType + r.compiledCharset,
		Status:      status,
	}

	h := HTML{
		Head:      head,
		Name:      name,
		Templates: templates,
		bp:        r.opt.BufferPool,
	}

	return r.Render(w, h, binding)
}

// JSON marshals the given interface object and writes the JSON response.
func (r *Render) JSON(w io.Writer, status int, v interface{}) error {
	head := Head{
		ContentType: r.opt.JSONContentType + r.compiledCharset,
		Status:      status,
	}

	j := JSON{
		Head:          head,
		Indent:        r.opt.IndentJSON,
		Prefix:        r.opt.PrefixJSON,
		UnEscapeHTML:  r.opt.UnEscapeHTML,
		StreamingJSON: r.opt.StreamingJSON,
		Encoder:       r.opt.JSONEncoder,
	}

	return r.Render(w, j, v)
}

// JSONP marshals the given interface object and writes the JSON response.
func (r *Render) JSONP(w io.Writer, status int, callback string, v interface{}) error {
	head := Head{
		ContentType: r.opt.JSONPContentType + r.compiledCharset,
		Status:      status,
	}

	j := JSONP{
		Head:     head,
		Indent:   r.opt.IndentJSON,
		Callback: callback,
	}

	return r.Render(w, j, v)
}

// Text writes out a string as plain text.
func (r *Render) Text(w io.Writer, status int, v string) error {
	head := Head{
		ContentType: r.opt.TextContentType + r.compiledCharset,
		Status:      status,
	}

	t := Text{
		Head: head,
	}

	return r.Render(w, t, v)
}

// XML marshals the given interface object and writes the XML response.
func (r *Render) XML(w io.Writer, status int, v interface{}) error {
	head := Head{
		ContentType: r.opt.XMLContentType + r.compiledCharset,
		Status:      status,
	}

	x := XML{
		Head:   head,
		Indent: r.opt.IndentXML,
		Prefix: r.opt.PrefixXML,
	}

	return r.Render(w, x, v)
}