engine

Documentation

Index

• Constants
• Variables
• func RenderProblem(kind ProblemKind, w http.ResponseWriter, details ...string)
• func RenderProblemAndLog(kind ProblemKind, w http.ResponseWriter, err error, details ...string)
• func SafeWrite(write func([]byte) (int, error), body []byte)
• type Breadcrumb
• type ContentNegotiation
  • func (cn *ContentNegotiation) NegotiateFormat(req *http.Request) string
  • func (cn *ContentNegotiation) NegotiateLanguage(w http.ResponseWriter, req *http.Request) language.Tag
• type Engine
  • func NewEngine(configFile string, enableTrailingSlash bool, enableCORS bool) (*Engine, error)
  • func NewEngineWithConfig(config *config.Config, enableTrailingSlash bool, enableCORS bool) *Engine
  • func (e *Engine) ParseTemplate(key TemplateKey)
  • func (e *Engine) RegisterShutdownHook(fn func())
  • func (e *Engine) RenderAndServePage(w http.ResponseWriter, r *http.Request, key TemplateKey, params any, ...)
  • func (e *Engine) RenderTemplates(urlPath string, breadcrumbs []Breadcrumb, keys ...TemplateKey)
  • func (e *Engine) RenderTemplatesWithParams(urlPath string, params any, breadcrumbs []Breadcrumb, keys ...TemplateKey)
  • func (e *Engine) ReverseProxy(w http.ResponseWriter, r *http.Request, target *url.URL, prefer204 bool, ...)
  • func (e *Engine) ReverseProxyAndValidate(w http.ResponseWriter, r *http.Request, target *url.URL, prefer204 bool, ...)
  • func (e *Engine) Serve(w http.ResponseWriter, r *http.Request, validateRequest bool, ...)
  • func (e *Engine) ServePage(w http.ResponseWriter, r *http.Request, templateKey TemplateKey)
  • func (e *Engine) Start(address string, debugPort int, shutdownDelay int) error
• type OpenAPI
  • func (o *OpenAPI) ValidateRequest(r *http.Request) error
  • func (o *OpenAPI) ValidateResponse(contentType string, body []byte, r *http.Request) error
• type ProblemKind
• type TemplateData
  • func (td *TemplateData) AvailableFormats() map[string]string
  • func (td *TemplateData) QueryString(format string) string
• type TemplateKey
  • func ExpandTemplateKey(key TemplateKey, language language.Tag) TemplateKey
  • func NewTemplateKey(path string) TemplateKey
  • func NewTemplateKeyWithLanguage(path string, language language.Tag) TemplateKey
  • func NewTemplateKeyWithName(path string, instanceName string) TemplateKey
  • func NewTemplateKeyWithNameAndLanguage(path string, instanceName string, language language.Tag) TemplateKey
• type Templates

Constants

const (
	FormatParam = "f"

	MediaTypeJSON    = "application/json"
	MediaTypeXML     = "application/xml"
	MediaTypeHTML    = "text/html"
	MediaTypeOpenAPI = "application/vnd.oai.openapi+json;version=3.0"
	MediaTypeGeoJSON = "application/geo+json"
	MediaTypeJSONFG  = "application/vnd.ogc.fg+json" // https://docs.ogc.org/per/21-017r1.html#toc17

	FormatHTML    = "html"
	FormatXML     = "xml"
	FormatJSON    = "json"
	FormatGeoJSON = "geojson" // ?=json should also work for geojson
	FormatJSONFG  = "jsonfg"
	FormatGzip    = "gzip"
)

const (
	HeaderLink            = "Link"
	HeaderAccept          = "Accept"
	HeaderAcceptLanguage  = "Accept-Language"
	HeaderContentType     = "Content-Type"
	HeaderContentLength   = "Content-Length"
	HeaderContentCrs      = "Content-Crs"
	HeaderContentEncoding = "Content-Encoding"
	HeaderBaseURL         = "X-BaseUrl"
	HeaderRequestedWith   = "X-Requested-With"
	HeaderAPIVersion      = "API-Version"
)

const (
	HTMLRegex = `<[/]?([a-zA-Z]+).*?>`
)

Variables

var (
	MediaTypeJSONFamily    = []string{MediaTypeGeoJSON, MediaTypeJSONFG}
	OutputFormatDefault    = map[string]string{FormatJSON: "JSON"}
	OutputFormatFeatures   = map[string]string{FormatJSON: "GeoJSON", FormatJSONFG: "JSON-FG"}
	CompressibleMediaTypes = []string{
		MediaTypeJSON,
		MediaTypeGeoJSON,
		MediaTypeJSONFG,
		MediaTypeOpenAPI,
		MediaTypeHTML,

		"text/css",
		"text/plain",
		"text/javascript",
		"application/javascript",
		"image/svg+xml",
	}
)

var (
	ProblemBadRequest    = ProblemKind(http.StatusBadRequest)
	ProblemNotFound      = ProblemKind(http.StatusNotFound)
	ProblemNotAcceptable = ProblemKind(http.StatusNotAcceptable)
	ProblemServerError   = ProblemKind(http.StatusInternalServerError)
	ProblemBadGateway    = ProblemKind(http.StatusBadGateway)
)

The following problems should be added to openapi/problems.go.json

var (
	GlobalTemplateFuncs texttemplate.FuncMap
)

var Now = time.Now // allow mocking

Functions

func RenderProblem

func RenderProblem(kind ProblemKind, w http.ResponseWriter, details ...string)

RenderProblem writes RFC 7807 (https://tools.ietf.org/html/rfc7807) problem to client. Only the listed problem kinds are supported since they should be advertised in the OpenAPI spec. Optionally a caller may add a details (single string) about the problem. Warning: Be sure to not include sensitive information in the details string!

func RenderProblemAndLog

func RenderProblemAndLog(kind ProblemKind, w http.ResponseWriter, err error, details ...string)

RenderProblemAndLog writes RFC 7807 (https://tools.ietf.org/html/rfc7807) problem to client + logs message to stdout.

func SafeWrite

func SafeWrite(write func([]byte) (int, error), body []byte)

SafeWrite executes the given http.ResponseWriter.Write while logging errors

Types

type Breadcrumb

type Breadcrumb struct {
	Name string
	Path string
}

type ContentNegotiation

type ContentNegotiation struct {
	// contains filtered or unexported fields
}

func (*ContentNegotiation) NegotiateFormat

func (cn *ContentNegotiation) NegotiateFormat(req *http.Request) string

NegotiateFormat performs content negotiation, not idempotent (since it removes the ?f= param)

func (*ContentNegotiation) NegotiateLanguage

func (cn *ContentNegotiation) NegotiateLanguage(w http.ResponseWriter, req *http.Request) language.Tag

NegotiateLanguage performs language negotiation, not idempotent (since it removes the ?lang= param)

type Engine

type Engine struct {
	Config    *config.Config
	OpenAPI   *OpenAPI
	Templates *Templates
	CN        *ContentNegotiation
	Router    *chi.Mux
	// contains filtered or unexported fields
}

Engine encapsulates shared non-OGC API specific logic

func NewEngine

func NewEngine(configFile string, enableTrailingSlash bool, enableCORS bool) (*Engine, error)

NewEngine builds a new Engine

func NewEngineWithConfig

func NewEngineWithConfig(config *config.Config, enableTrailingSlash bool, enableCORS bool) *Engine

NewEngineWithConfig builds a new Engine

func (*Engine) ParseTemplate

func (e *Engine) ParseTemplate(key TemplateKey)

ParseTemplate parses both HTML and non-HTML templates depending on the format given in the TemplateKey and stores it in the engine for future rendering using RenderAndServePage.

func (*Engine) RegisterShutdownHook

func (e *Engine) RegisterShutdownHook(fn func())

RegisterShutdownHook register a func to execute during graceful shutdown, e.g. to clean up resources.

func (*Engine) RenderAndServePage

func (e *Engine) RenderAndServePage(w http.ResponseWriter, r *http.Request, key TemplateKey,
	params any, breadcrumbs []Breadcrumb)

RenderAndServePage renders an already parsed HTML or non-HTML template on-the-fly depending on the format in the given TemplateKey. The result isn't store in engine, it's served directly to the client.

NOTE: only used this for dynamic pages that can't be pre-rendered and cached (e.g. with data from a datastore), otherwise use ServePage for pre-rendered pages.

func (*Engine) RenderTemplates

func (e *Engine) RenderTemplates(urlPath string, breadcrumbs []Breadcrumb, keys ...TemplateKey)

RenderTemplates renders both HTML and non-HTML templates depending on the format given in the TemplateKey. This method also performs OpenAPI validation of the rendered template, therefore we also need the URL path. The rendered templates are stored in the engine for future serving using ServePage.

func (*Engine) RenderTemplatesWithParams

func (e *Engine) RenderTemplatesWithParams(urlPath string, params any, breadcrumbs []Breadcrumb, keys ...TemplateKey)

RenderTemplatesWithParams renders both HTMl and non-HTML templates depending on the format given in the TemplateKey.

func (*Engine) ReverseProxy

func (e *Engine) ReverseProxy(w http.ResponseWriter, r *http.Request, target *url.URL,
	prefer204 bool, contentTypeOverwrite string)

ReverseProxy forwards given HTTP request to given target server, and optionally tweaks response

func (*Engine) ReverseProxyAndValidate

func (e *Engine) ReverseProxyAndValidate(w http.ResponseWriter, r *http.Request, target *url.URL,
	prefer204 bool, contentTypeOverwrite string, validateResponse bool)

ReverseProxyAndValidate forwards given HTTP request to given target server, and optionally tweaks and validates response

func (*Engine) Serve

func (e *Engine) Serve(w http.ResponseWriter, r *http.Request,
	validateRequest bool, validateResponse bool, contentType string, output []byte)

Serve serves the given response (arbitrary bytes) while also validating against the OpenAPI spec

func (*Engine) ServePage

func (e *Engine) ServePage(w http.ResponseWriter, r *http.Request, templateKey TemplateKey)

ServePage serves a pre-rendered template while also validating against the OpenAPI spec

func (*Engine) Start

func (e *Engine) Start(address string, debugPort int, shutdownDelay int) error

Start the engine by initializing all components and starting the server

type OpenAPI

type OpenAPI struct {
	SpecJSON []byte
	// contains filtered or unexported fields
}

func (*OpenAPI) ValidateRequest

func (o *OpenAPI) ValidateRequest(r *http.Request) error

func (*OpenAPI) ValidateResponse

func (o *OpenAPI) ValidateResponse(contentType string, body []byte, r *http.Request) error

type ProblemKind

type ProblemKind int

type TemplateData

type TemplateData struct {
	// Config set during startup based on the given config file
	Config *config.Config

	// Params optional parameters not part of Gomagpie's config file. You can use
	// this to provide extra data to a template at rendering time.
	Params any

	// Breadcrumb path to the page, in key-value pairs of name->path
	Breadcrumbs []Breadcrumb
	// contains filtered or unexported fields
}

TemplateData the data/variables passed as an argument into the template.

func (*TemplateData) AvailableFormats

func (td *TemplateData) AvailableFormats() map[string]string

AvailableFormats returns the output formats available for the current page

func (*TemplateData) QueryString

func (td *TemplateData) QueryString(format string) string

QueryString returns ?=foo=a&bar=b style query string of the current page

type TemplateKey

type TemplateKey struct {
	// Name of the template, the filename including extension
	Name string

	// Directory in which the template resides
	Directory string

	// Format the file format based on the filename extension, 'html' or 'json'
	Format string

	// Language of the contents of the template
	Language language.Tag

	// Optional. Only required when you want to render the same template multiple times (with different content).
	// By specifying an 'instance name' you can refer to a certain instance of a rendered template later on.
	InstanceName string
}

TemplateKey unique key to register and lookup Go templates

func ExpandTemplateKey

func ExpandTemplateKey(key TemplateKey, language language.Tag) TemplateKey

func NewTemplateKey

func NewTemplateKey(path string) TemplateKey

NewTemplateKey build TemplateKeys

func NewTemplateKeyWithLanguage

func NewTemplateKeyWithLanguage(path string, language language.Tag) TemplateKey

func NewTemplateKeyWithName

func NewTemplateKeyWithName(path string, instanceName string) TemplateKey

NewTemplateKeyWithName build TemplateKey with InstanceName (see docs in struct)

func NewTemplateKeyWithNameAndLanguage

func NewTemplateKeyWithNameAndLanguage(path string, instanceName string, language language.Tag) TemplateKey

type Templates

type Templates struct {
	// ParsedTemplates templates loaded from disk and parsed to an in-memory Go representation.
	ParsedTemplates map[TemplateKey]any

	// RenderedTemplates templates parsed + rendered to their actual output format like JSON, HTMl, etc.
	// We prefer pre-rendered templates whenever possible. These are stored in this map.
	RenderedTemplates map[TemplateKey][]byte
	// contains filtered or unexported fields
}