Layer Patterns

Layers in tilegroxy can be matched to incoming requests in one of two ways. The default method is to match the incoming layer name (from the URL) with the layer’s configured id. A layer can instead define a pattern.

Incoming tile requests look like /tiles/{layerName}/{z}/{x}/{y}. Tilegroxy checks each configured layer in the order they appear in the configuration and uses the first one that matches layerName:

Because the first match wins, put specific layers above broad patterns that could also match their names. A request that matches nothing is rejected as an unknown layer.

A pattern layer still needs a unique id as it’s used for the layer’s identity elsewhere.

The ref provider resolves its layer the same way as an incoming request, so a ref can point at a name that fits a pattern.

A placeholder is a name wrapped in curly braces. Everything outside the braces is literal text that must appear in the layer name exactly.

Given a request for my_first_v2, name is first and version is v2.

Placeholders must be "non-subsequent", meaning two placeholders can’t sit directly next to each other. There must be some literal text between them, because that text is how tilegroxy knows where one value ends and the next begins. A pattern such as a_{x}{y} fails at startup. The same placeholder name also can’t be used twice in one pattern.

Matching is simple. Each value runs until the first occurrence of the literal text that follows it. With the pattern above, my_a_b_v2 matches with name as a and version as b_v2. Keep this in mind when a value could contain your separator, and use paramValidator to reject names that would split in an unexpected way. Without a validator a placeholder can also match an empty string.

paramValidator maps a placeholder name to a regular expression that its value must match. Expressions are anchored automatically, so they must match the whole value rather than just part of it. Use the key * to apply an expression to every placeholder. A name with any value failing its expression doesn’t match the layer at all, so the request moves on to later layers and is rejected if nothing else matches.

paramValidator only applies to layers that have a pattern.

In some cases you might want to have different values in your URLs compared to what is needed for your upstream provider. In those cases you can use paramMap to perform simple replacements from one value to another.

An entry with default: true applies to every value the other entries don’t list. A default can optionally include the to option, if it’s omitted then the default is a straight passthrough.

Startup fails if a key isn’t a placeholder in the pattern, a from value is listed twice, a placeholder has more than one default, or a default has a from. Providers, including custom ones, and analytics see the mapped value. Tiles are still cached under the layer name from the request (before mappings).

Providers reference a placeholder value as {layer.NAME}, where NAME is the placeholder name from the pattern. The following providers support it:

Startup fails if a {layer.NAME} anywhere in the provider configuration names a placeholder that isn’t in the pattern, such as a typo. Names are case sensitive, so {layer.region} doesn’t match a pattern of {Region}.

Placeholder values are also available to analytics as the layerparams field and to custom providers through LayerParams.

A pattern layer has no single name, so features that need one use the examples list instead. This is currently used in a couple ways:

Tiles are cached under the layer name from the request, not the id. Every distinct set of placeholder values gets its own cache entries, which is usually what you want since they produce different tiles. It also means a pattern that accepts many values can fill a cache with many variations.

The disk, S3, and memcached caches replace any character other than letters, digits, -, and . with _ before using the name in a key. This keeps a request from escaping the cache directory or adding path segments to an object key. The tradeoff is that names differing only in those characters share entries: a b and a/b both become a_b. A tight paramValidator avoids this.

Placeholder values come straight from the request, so they are User input and should be treated as hostile. Escaping in Proxy and CGI and prepared statements in PostGIS protect against the most direct injection, but they don’t stop a User from asking your upstream for something you didn’t intend to serve.

A warning is logged at startup and on every reload for each pattern layer with a placeholder that has no paramValidator expression (including *) and isn’t in paramMap. A paramMap whose default passes values through unchanged doesn’t count, since it accepts anything.

See Security for more.

The NOAA post-storm example serves NOAA’s post-storm aerial imagery. NOAA publishes each flight as a separate tile set with a date and letter in the URL, such as 20230902a. Rather than one layer per flight, a single pattern layer covers them all:

A request for /tiles/noaa_poststorm_20230902a/16/18020/27142 matches the pattern with version set to 20230902a. That value is exactly eight digits and an a, so it passes the validator. The proxy then requests https://stormscdn.ngs.noaa.gov/20230902a-rgb/16/18020/27142. Flights only cover a small area, so the fallback returns a transparent tile wherever NOAA has none.

A request for noaa_poststorm_latest fails the validator and is rejected. So is noaa_poststorm_imagery_in_parts, since the id isn’t matched once a pattern is set.

The examples let tilegroxy test and TileJSON work with two real flights.

Other layers in the same file reuse the pattern layer to combine all flights for a storm into one layer:

noaa_2023_lee uses ref providers that name concrete flights. noaa_2023_idalia does the same with less repetition using blend’s layer option. Here {v} belongs to blend, not to a layer pattern, so it uses the bare placeholder name rather than {layer.v}.

Each referenced flight is cached separately under its own name, so a request for noaa_2023_idalia also warms the cache for the individual flights.