feat: add env vars to control exclusion, inclusion and aliases

Author: albanm

README.md

@@ -0,0 +1,57 @@
+# @data-fair/tileserver
+
+Vector tile server for the data-fair stack. Wraps [tileserver-gl-light](https://github.com/maptiler/tileserver-gl) and pulls tilesets and styles from a [data-fair/registry](https://github.com/data-fair/registry) instance at boot.
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `REGISTRY_URL` | yes | | Base URL of the data-fair registry |
+| `REGISTRY_SECRET` | yes | | Secret key for registry authentication |
+| `DATA_DIR` | no | `/data` | Root directory for cache and config |
+| `FONTS_DIR` | no | `/app/fonts` | Directory containing font files |
+| `PORT` | no | `8080` | HTTP server port |
+| `LOG_LEVEL` | no | `info` | One of `trace`, `debug`, `info`, `warn`, `error` |
+| `OBSERVER_ACTIVE` | no | `true` | Enable Prometheus metrics |
+| `OBSERVER_PORT` | no | `9090` | Prometheus metrics port |
+| `TILESET_INCLUDE` | no | | Comma-separated list of tileset IDs to include (if set, all others are excluded) |
+| `TILESET_EXCLUDE` | no | | Comma-separated list of tileset IDs to exclude |
+| `TILESET_ALIASES` | no | | Comma-separated `source:key` pairs to remap tileset serving keys |
+| `STYLE_INCLUDE` | no | | Comma-separated list of style IDs to include (if set, all others are excluded) |
+| `STYLE_EXCLUDE` | no | | Comma-separated list of style IDs to exclude |
+| `STYLE_ALIASES` | no | | Comma-separated `source:key` pairs to remap style serving names |
+
+### Filtering and aliasing
+
+**Include/Exclude** control which artefacts are downloaded from the registry. If `*_INCLUDE` is set, only listed IDs are kept. `*_EXCLUDE` removes listed IDs. When both are set, include is applied first, then exclude.
+
+**Aliases** remap the serving key of an artefact without changing the downloaded file. The format is `source:key` where `source` is the artefact ID in the registry and `key` is the desired serving key.
+
+Example: serve `france.mbtiles` under the `world` key instead of downloading `world.mbtiles`:
+
+```bash
+TILESET_EXCLUDE=world
+TILESET_ALIASES=france:world
+```
+
+Example: use a timestamped tileset as a generic data layer:
+
+```bash
+TILESET_ALIASES=contours-2026:contours
+```
+
+## Development
+
+```bash
+# start dependencies (registry mock via docker)
+npm run dev-deps
+
+# start the dev server
+npm run dev
+
+# run tests
+npm test
+
+# lint and type-check
+npm run quality
+```

src/build-config.ts

@@ -24,6 +24,13 @@ export interface TileserverConfig {
   data: Record<string, { mbtiles: string }>
 }
 
+const filterArtefacts = (artefacts: Artefact[], include: string[], exclude: string[]): Artefact[] => {
+  let filtered = artefacts
+  if (include.length) filtered = filtered.filter(a => include.includes(a._id))
+  if (exclude.length) filtered = filtered.filter(a => !exclude.includes(a._id))
+  return filtered
+}
+
 const stylePackageName = (a: Artefact): string => {
   const name = a.name.replace(/^@[^/]+\//, '')
   return name.replace(/[^a-z0-9_-]/gi, '-')
@@ -50,9 +57,14 @@ export const buildTileserverConfig = async (): Promise<TileserverConfig> => {
   const styles = await listArtefacts({ category: 'maplibre-style', format: 'file' })
   log.info(`found ${styles.length} styles`)
 
+  const filteredTilesets = filterArtefacts(tilesets, config.tilesetInclude, config.tilesetExclude)
+  if (filteredTilesets.length !== tilesets.length) {
+    log.info(`filtered to ${filteredTilesets.length} tilesets`)
+  }
+
   const data: TileserverConfig['data'] = {}
   const tilesetIds = new Set<string>()
-  for (const t of tilesets) {
+  for (const t of filteredTilesets) {
     log.info(`ensuring tileset ${t._id}...`)
     const { downloaded } = await ensureArtefactFile({
       registryUrl: config.registryUrl,
@@ -62,12 +74,18 @@ export const buildTileserverConfig = async (): Promise<TileserverConfig> => {
       fileName: `${t._id}.mbtiles`
     })
     if (downloaded) log.info(`tileset ${t._id} downloaded`)
-    data[t._id] = { mbtiles: `${t._id}.mbtiles` }
-    tilesetIds.add(t._id)
+    const dataKey = config.tilesetAliases[t._id] ?? t._id
+    data[dataKey] = { mbtiles: `${t._id}.mbtiles` }
+    tilesetIds.add(dataKey)
+  }
+
+  const filteredStyles = filterArtefacts(styles, config.styleInclude, config.styleExclude)
+  if (filteredStyles.length !== styles.length) {
+    log.info(`filtered to ${filteredStyles.length} styles`)
   }
 
   const stylesCfg: TileserverConfig['styles'] = {}
-  for (const s of styles) {
+  for (const s of filteredStyles) {
     log.info(`ensuring style ${s._id}...`)
     const { path: tarballPath, downloaded } = await ensureArtefactFile({
       registryUrl: config.registryUrl,
@@ -83,7 +101,7 @@ export const buildTileserverConfig = async (): Promise<TileserverConfig> => {
       await mkdir(styleDir, { recursive: true })
       await extractTarball(createReadStream(tarballPath), styleDir)
     }
-    const styleName = stylePackageName(s)
+    const styleName = config.styleAliases[s._id] ?? stylePackageName(s)
     await normalizeStyle({ styleDir, styleName, tilesetIds })
     const rel = relative(dirs.styles, join(styleDir, 'style.json'))
     stylesCfg[styleName] = { style: rel }

src/config.ts

@@ -8,7 +8,29 @@ const EnvSchema = z.object({
   PORT: z.coerce.number().int().positive().default(8080),
   LOG_LEVEL: z.enum(['trace', 'debug', 'info', 'warn', 'error']).default('info'),
   OBSERVER_ACTIVE: z.enum(['true', 'false']).default('true').transform(v => v === 'true'),
-  OBSERVER_PORT: z.coerce.number().int().positive().default(9090)
+  OBSERVER_PORT: z.coerce.number().int().positive().default(9090),
+  TILESET_INCLUDE: z.string().default('').transform(v => v ? v.split(',').map(s => s.trim()).filter(Boolean) : []),
+  TILESET_EXCLUDE: z.string().default('').transform(v => v ? v.split(',').map(s => s.trim()).filter(Boolean) : []),
+  TILESET_ALIASES: z.string().default('').transform(v => {
+    if (!v) return {} as Record<string, string>
+    const map: Record<string, string> = {}
+    for (const pair of v.split(',')) {
+      const [source, alias] = pair.split(':').map(s => s.trim())
+      if (source && alias) map[source] = alias
+    }
+    return map
+  }),
+  STYLE_INCLUDE: z.string().default('').transform(v => v ? v.split(',').map(s => s.trim()).filter(Boolean) : []),
+  STYLE_EXCLUDE: z.string().default('').transform(v => v ? v.split(',').map(s => s.trim()).filter(Boolean) : []),
+  STYLE_ALIASES: z.string().default('').transform(v => {
+    if (!v) return {} as Record<string, string>
+    const map: Record<string, string> = {}
+    for (const pair of v.split(',')) {
+      const [source, alias] = pair.split(':').map(s => s.trim())
+      if (source && alias) map[source] = alias
+    }
+    return map
+  })
 })
 
 const parsed = EnvSchema.safeParse(process.env)
@@ -32,7 +54,13 @@ const config = {
   observer: {
     active: env.OBSERVER_ACTIVE,
     port: env.OBSERVER_PORT
-  }
+  },
+  tilesetInclude: env.TILESET_INCLUDE,
+  tilesetExclude: env.TILESET_EXCLUDE,
+  tilesetAliases: env.TILESET_ALIASES,
+  styleInclude: env.STYLE_INCLUDE,
+  styleExclude: env.STYLE_EXCLUDE,
+  styleAliases: env.STYLE_ALIASES
 } as const
 
 export default config