server

README

Server

The server package is responsible for handling webserver requests for map tiles and various JSON endpoints describing the configured server. Example config:

[webserver]
port = ":9090"              # set something different than default ":8080"
ssl_cert = "fullchain.pem"  # ssl cert for serving by https
ssl_key = "privkey.pem"     # ssl key for serving by https


[webserver.headers]
Access-Control-Allow-Origin = "*"

Config properties

• port (string): [Optional] Port and bind string. For example ":9090" or "127.0.0.1:9090". Defaults to ":8080"
• hostname (string): [Optional] The hostname to use in the various JSON endpoints. This is useful if tegola is behind a proxy and can't read the API consumer's request host directly.
• uri_prefix (string): [Optional] A prefix to add to all API routes. This is useful when tegola is behind a proxy (i.e. example.com/tegola). The prexfix will be added to all URLs included in the capabilities endpoint responses.
• ssl_cert (string): [Optional, unless ssl_key provided] Path to a certificate file for serving through HTTPS
• ssl_key (string): [Optional, unless ssl_cert provided] Path to a private key file for serving through HTTPS

Local development of the embedded viewer

Tegola's built in viewer code is stored in the ui/ directory. To build the ui npm must be installed. Once npm is installed the following command can be run from the repository root to generate a .go file for inclusion in the tegola binary:

go generate ./server

Disabling the viewer

The viewer can be excluded during building by using the build flag noViewer. For example, building tegola from the cmd/tegola directory:

go build -tags "noViewer"

Documentation

Overview

Package server implements the http frontend

Index

• Constants
• Variables
• func GZipHandler(next http.Handler) http.Handler
• func HeadersHandler(next http.Handler) http.Handler
• func NewRouter(a *atlas.Atlas) *httptreemux.TreeMux
• func Start(a *atlas.Atlas, port string) *http.Server
• func TileCacheHandler(a *atlas.Atlas, next http.Handler) http.Handler
• type Capabilities
• type CapabilitiesLayer
• type CapabilitiesMap
• type ErrMalformedTileTemplateURL
  • func (e ErrMalformedTileTemplateURL) Error() string
• type HandleCapabilities
  • func (req HandleCapabilities) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type HandleMapCapabilities
  • func (req HandleMapCapabilities) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type HandleMapLayerZXY
  • func (req HandleMapLayerZXY) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type HandleMapStyle
  • func (req HandleMapStyle) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type TileURLTemplate
  • func (t *TileURLTemplate) MarshalJSON() ([]byte, error)
  • func (t TileURLTemplate) Path() string
  • func (t TileURLTemplate) String() string
  • func (t *TileURLTemplate) UnmarshalJSON(data []byte) error

Constants

const (
	// MaxTileSize is 500k. Currently, just throws a warning when tile
	// is larger than MaxTileSize
	MaxTileSize = 500000

	// QueryKeyDebug is a common query string key used throughout the pacakge
	// the value should always be a boolean
	QueryKeyDebug = "debug"
)

const (
	TileURLMapsToken  = "maps"
	TileURLZToken     = "{z}"
	TileURLXToken     = "{x}"
	TileURLYToken     = "{y}"
	TileURLFileFormat = "pbf"
)

const (
	HeaderXForwardedProto = "X-Forwarded-Proto"
)

Variables

var (
	// Version is the version of the software, this should be set by the main program, before starting up.
	// It is used by various Middleware to determine the version.
	Version string = "version not set"

	// HostName is the name of the host to use for construction of URLS.
	// configurable via the tegola config.toml file (set in main.go)
	HostName *url.URL

	// Port is the port the server is listening on, used for construction of URLS.
	// configurable via the tegola config.toml file (set in main.go)
	Port string

	// SSLCert is a filepath to an SSL cert, this will be used to enable https
	SSLCert string

	// SSLKey is a filepath to an SSL key, this will be used to enable https
	SSLKey string

	// Headers is the map of user defined response headers.
	// configurable via the tegola config.toml file (set in main.go)
	Headers = map[string]string{}

	// URIPrefix sets a prefix on all server endpoints. This is often used
	// when the server sits behind a reverse proxy with a prefix (i.e. /tegola)
	URIPrefix = "/"

	// ProxyProtocol is a custom protocol that will be used to generate the URLs
	// included in the capabilities endpoint responses. This is useful when he
	// server sits behind a reverse proxy
	// (See https://github.com/go-spatial/tegola/pull/967)
	ProxyProtocol string

	// DefaultCORSHeaders define the default CORS response headers added to all requests
	DefaultCORSHeaders = map[string]string{
		"Access-Control-Allow-Origin":  "*",
		"Access-Control-Allow-Methods": "GET, OPTIONS",
	}
)

var URLRoot = func(r *http.Request) *url.URL {
	return &url.URL{
		Scheme: scheme(r),
		Host:   hostName(r).Host,
	}
}

URLRoot builds a string containing the scheme, host and port based on a combination of user defined values, headers and request parameters. The function is public so it can be overridden for other implementations.

Functions

func GZipHandler

func GZipHandler(next http.Handler) http.Handler

GZipHandler is responsible for determining if the incoming request should be served gzipped data. All response data is assumed to be compressed prior to being passed to this handler.

If the incoming request has the "Accept-Encoding" header set with the values of "gzip" or "*" the response header "Content-Encoding: gzip" is set and the compressed data is returned.

If no "Accept-Encoding" header is present or "Accept-Encoding" has a value of "gzip;q=0" or "*;q=0" the response is decompressed prior to being sent to the client.

func HeadersHandler

func HeadersHandler(next http.Handler) http.Handler

HeadersHandler is middleware for adding user defined response headers

func NewRouter

func NewRouter(a *atlas.Atlas) *httptreemux.TreeMux

NewRouter set's up our routes.

func Start

func Start(a *atlas.Atlas, port string) *http.Server

Start starts the tile server binding to the provided port

func TileCacheHandler

func TileCacheHandler(a *atlas.Atlas, next http.Handler) http.Handler

TileCacheHandler implements a request cache for tiles on requests when the URLs have a /:z/:x/:y scheme suffix (i.e. /osm/1/3/4.pbf)

Types

type Capabilities

type Capabilities struct {
	Version string            `json:"version"`
	Maps    []CapabilitiesMap `json:"maps"`
}

type CapabilitiesLayer

type CapabilitiesLayer struct {
	Name    string            `json:"name"`
	Tiles   []TileURLTemplate `json:"tiles"`
	MinZoom uint              `json:"minzoom"`
	MaxZoom uint              `json:"maxzoom"`
}

type CapabilitiesMap

type CapabilitiesMap struct {
	Name         string              `json:"name"`
	Attribution  string              `json:"attribution"`
	Bounds       *geom.Extent        `json:"bounds"`
	Center       [3]float64          `json:"center"`
	Tiles        []TileURLTemplate   `json:"tiles"`
	Capabilities string              `json:"capabilities"`
	Layers       []CapabilitiesLayer `json:"layers"`
}

type ErrMalformedTileTemplateURL

type ErrMalformedTileTemplateURL struct {
	Got string
}

func (ErrMalformedTileTemplateURL) Error

func (e ErrMalformedTileTemplateURL) Error() string

type HandleCapabilities

type HandleCapabilities struct{}

func (HandleCapabilities) ServeHTTP

func (req HandleCapabilities) ServeHTTP(w http.ResponseWriter, r *http.Request)

type HandleMapCapabilities

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

func (HandleMapCapabilities) ServeHTTP

func (req HandleMapCapabilities) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP returns details about a map according to the tileJSON spec (https://github.com/mapbox/tilejson-spec/tree/master/2.1.0)

URI scheme: /capabilities/:map_name.json map_name - map name in the config file

type HandleMapLayerZXY

type HandleMapLayerZXY struct {

	// the Atlas to use, nil (default) is the default atlas
	Atlas *atlas.Atlas
	// contains filtered or unexported fields
}

func (HandleMapLayerZXY) ServeHTTP

func (req HandleMapLayerZXY) ServeHTTP(w http.ResponseWriter, r *http.Request)

URI scheme: /maps/:map_name/:layer_name/:z/:x/:y?param=value map_name - map name in the config file layer_name - name of the single map layer to render z, x, y - tile coordinates as described in the Slippy Map Tilenames specification

z - zoom level
x - row
y - column

param - configurable query parameters and their values

type HandleMapStyle

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

func (HandleMapStyle) ServeHTTP

func (req HandleMapStyle) ServeHTTP(w http.ResponseWriter, r *http.Request)

returns details about a map according to the tileJSON spec (https://github.com/mapbox/tilejson-spec/tree/master/2.1.0)

URI scheme: /capabilities/:map_name.json

map_name - map name in the config file

type TileURLTemplate

type TileURLTemplate struct {
	Scheme     string
	Host       string
	PathPrefix string
	Query      url.Values
	MapName    string
	LayerName  string
}

TileURLTemplate is responsible for forming up tile URLs which contain the uri template variables {z}, {x} and {y}.pbf as the suffix of the path.

func (*TileURLTemplate) MarshalJSON

func (t *TileURLTemplate) MarshalJSON() ([]byte, error)

func (TileURLTemplate) Path

func (t TileURLTemplate) Path() string

Path will build the path part of the URI, including the template variables {z}, {x} and {y}.pbf. The path will start with a forward slash ("/").

func (TileURLTemplate) String

func (t TileURLTemplate) String() string

func (*TileURLTemplate) UnmarshalJSON

func (t *TileURLTemplate) UnmarshalJSON(data []byte) error