protomaps

README

go-http-protomaps

go-http-protomaps is an HTTP middleware package for including Protomaps.js (v0.15.0) assets in web applications.

Documentation

go-http-protomaps is an HTTP middleware package for including Protomaps.js assets in web applications. It exports two principal methods:

• protomaps.AppendAssetHandlers(*http.ServeMux, *ProtomapsOptions) which is used to append HTTP handlers to a http.ServeMux instance for serving Protomaps JavaScript files, and related assets.
• protomaps.AppendResourcesHandler(http.Handler, *ProtomapsOptions) which is used to rewrite any HTML produced by previous handler to include the necessary markup to load Protomaps JavaScript files and related assets.

Example

package main

import (
	"embed"
	"log"
	"net/http"
	"net/url"

	"github.com/sfomuseum/go-http-protomaps"
)

//go:embed index.html sfo.pmtiles
var staticFS embed.FS

func main() {

	tile_url := "/sfo.pmtiles"

	static_fs := http.FS(staticFS)
	static_handler := http.FileServer(static_fs)

	mux := http.NewServeMux()

	mux.Handle(*tile_url, static_handler)
	
	pm_opts := protomaps.DefaultProtomapsOptions()
	pm_opts.TileURL = *tile_url

	protomaps.AppendAssetHandlers(mux, pm_opts)
	
	index_handler := protomaps.AppendResourcesHandler(static_handler, pm_opts)
	mux.Handle("/", index_handler)

	err = http.ListenAndServe(":8080", mux)
}

Error handling omitted for brevity.

Tools

$> make cli
go build -mod vendor -o bin/example cmd/example/main.go

example

A simple example web application that uses the go-http-protomaps middleware and displays a map.

$> ./bin/example -h
Usage of ./bin/example:
  -protomaps-tile-url string
    	A custom file://, http:// or https:// URI pointing to a valid Protomaps tiles bundle. (default "/sfo.pmtiles")
  -server-uri string
    	A valid aaronland/go-http-server URI (default "http://localhost:8080")

The example application contains an embedded Protomaps tiles database file so the easiest way to test things is like this:

$> ./bin/example 
2021/04/28 07:45:57 Listening for requests on http://localhost:8080

And then when you open the URL http://localhost:8080 in your web browser you should see something like this:

The example application also supports loading .pmtiles databases from remote locations. For example:

$> ./bin/example -protomaps-tile-url https://static.sfomuseum.org/pmtiles/sfo.pmtiles
2021/04/28 07:48:11 Listening for requests on http://localhost:8080

If you want to load a local file you'd do this:

$> ./bin/example -protomaps-tile-url file:///usr/local/data/sfo.pmtiles
2021/04/28 07:48:53 Listening for requests on http://localhost:8080

In the case of file:// URLs the example application will create an http.Dir handler for the root folder of the URL (/usr/local/data/) and then route the filename (/sfo.pmtiles) to that handler.

AWS

S3

If you are serving your Protomaps .pmtiles databases from an S3 bucket you'll need to make that you have CORS enabled for that bucket. For example:

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "GET",
            "HEAD"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": [],
        "MaxAgeSeconds": 3000
    }
]

Be sure to allow the HEAD method. It took me a while to remember this was necessary the first time I set things up.

CloudFront

If you are serving your Protomaps .pmtiles databases from a CloudFront endpoint you'll need to make sure you do the following:

• Ensure that the Allowed HTTP Methods setting is configured to allow "GET, HEAD, OPTIONS".
• Ensure that the Cache Based on Selected Request Headers setting is configured to use a "whitelist".
• Add the following default headers to the whitelist: Access-Control-Request-Headers, Access-Control-Request-Method, Origin.
• Add the following custom headers to the whitelist: Range.

See also

• https://protomaps.com/blog/new-way-to-make-maps/
• https://github.com/protomaps/protomaps.js
• https://github.com/aaronland/go-http-leaflet

Documentation

Overview

`go-http-protomaps` is an HTTP middleware package for including Protomaps.js assets in web applications. It exports two principal methods:

* `protomaps.AppendAssetHandlers(*http.ServeMux)` which is used to append HTTP handlers to a `http.ServeMux` instance for serving Protomaps JavaScript files, and related assets. * `protomaps.AppendResourcesHandler(http.Handler, *ProtomapsOptions)` which is used to rewrite any HTML produced by previous handler to include the necessary markup to load Protomaps JavaScript files and related assets.

Example (Note the way we are embedding the HTML and .pmtiles database as an embed.FS instance)

import (
	"embed"
	"github.com/sfomuseum/go-http-protomaps"
	"log"
	"net/http"
	"net/url"
)

//go:embed index.html sfo.pmtiles
var staticFS embed.FS

func main() {

	tile_url := "/sfo.pmtiles"

	static_fs := http.FS(staticFS)
	static_handler := http.FileServer(static_fs)

	mux := http.NewServeMux()

	mux.Handle(*tile_url, static_handler)

	protomaps.AppendAssetHandlers(mux)

	pm_opts := protomaps.DefaultProtomapsOptions()
	pm_opts.TileURL = *tile_url

	index_handler := protomaps.AppendResourcesHandler(static_handler, pm_opts)
	mux.Handle("/", index_handler)

	err = http.ListenAndServe(":8080", mux)
}

Index

• func AppendAssetHandlers(mux *http.ServeMux, opts *ProtomapsOptions) error
• func AppendResourcesHandler(next http.Handler, opts *ProtomapsOptions) http.Handler
• func FileHandlerFromPath(path string, prefix string) (string, http.Handler, error)
• type ProtomapsOptions
  • func DefaultProtomapsOptions() *ProtomapsOptions

Functions

func AppendAssetHandlers

func AppendAssetHandlers(mux *http.ServeMux, opts *ProtomapsOptions) error

Append all the files in the net/http FS instance containing the embedded Protomaps assets to an *http.ServeMux instance ensuring that all URLs are prepended with prefix.

func AppendResourcesHandler

func AppendResourcesHandler(next http.Handler, opts *ProtomapsOptions) http.Handler

AppendResourcesHandlerWithPrefix will rewrite any HTML produced by previous handler to include the necessary markup to load Protomaps JavaScript files and related assets ensuring that all URIs are prepended with a prefix.

func FileHandlerFromPath

func FileHandlerFromPath(path string, prefix string) (string, http.Handler, error)

FileHandlerFromPath will take a path and create a http.FileServer handler instance for the files in its root directory. The handler is returned with a relative URI for the filename in 'path' to be assigned to a net/http ServeMux instance.

Types

type ProtomapsOptions

type ProtomapsOptions struct {
	// A list of relative JavaScript files to reference in one or more <script> tags
	JS []string
	// A list of relative CSS files to reference in one or more <link rel="stylesheet"> tags
	CSS []string
	// A URL for a specific PMTiles database to include as a 'data-protomaps-tile-url' attribute on the <body> tag.
	TileURL string
	// A leaflet.LeafletOptions struct
	LeafletOptions *leaflet.LeafletOptions
	// AppendJavaScriptAtEOF is a boolean flag to append JavaScript markup at the end of an HTML document
	// rather than in the <head> HTML element. Default is false
	AppendJavaScriptAtEOF bool
	// Rollup (minify and bundle) JavaScript and CSS assets.
	RollupAssets bool
	Prefix       string
	Logger       *log.Logger
	// By default the go-http-protomaps package will also include and reference Leaflet.js resources using the aaronland/go-http-leaflet package. If you want or need to disable this behaviour set this variable to false.
	AppendLeafletResources bool
	// By default the go-http-protomaps package will also include and reference Leaflet.js assets using the aaronland/go-http-leaflet package. If you want or need to disable this behaviour set this variable to false.
	AppendLeafletAssets bool
}

ProtomapsOptions provides a list of JavaScript and CSS link to include with HTML output as well as a URL referencing a specific Protomaps PMTiles database to include a data attribute.

func DefaultProtomapsOptions

func DefaultProtomapsOptions() *ProtomapsOptions

Return a *ProtomapsOptions struct with default paths and URIs.