@comapeo/core 1.0.0

package/src/fastify-controller.js

@@ -0,0 +1,84 @@
+import { promisify } from 'util'
+import StateMachine from 'start-stop-state-machine'
+
+/**
+ * @typedef {Object} StartOpts
+ *
+ * @property {string} [host]
+ * @property {number} [port]
+ */
+
+// Class to properly manage the server lifecycle of a Fastify instance
+export class FastifyController {
+  #fastify
+  #fastifyStarted
+  #serverState
+
+  /**
+   * @param {Object} opts
+   * @param {import('fastify').FastifyInstance} opts.fastify
+   */
+  constructor({ fastify }) {
+    this.#fastifyStarted = false
+
+    this.#fastify = fastify
+
+    this.#serverState = new StateMachine({
+      start: this.#startServer.bind(this),
+      stop: this.#stopServer.bind(this),
+    })
+  }
+
+  /**
+   * @param {StartOpts} [opts]
+   */
+  async #startServer({ host = '127.0.0.1', port = 0 } = {}) {
+    if (!this.#fastifyStarted) {
+      this.#fastifyStarted = true
+      await this.#fastify.listen({ host, port })
+      return
+    }
+
+    const { server } = this.#fastify
+
+    await new Promise((res, rej) => {
+      server.listen.call(server, { host, port })
+
+      server.once('listening', onListening)
+      server.once('error', onError)
+
+      function onListening() {
+        server.removeListener('error', onError)
+        res(null)
+      }
+
+      /**
+       * @param {Error} err
+       */
+      function onError(err) {
+        server.removeListener('listening', onListening)
+        rej(err)
+      }
+    })
+  }
+
+  async #stopServer() {
+    const { server } = this.#fastify
+    await promisify(server.close.bind(server))()
+  }
+
+  /**
+   * @param {StartOpts} [opts]
+   */
+  async start(opts) {
+    await this.#serverState.start(opts)
+  }
+
+  async started() {
+    return this.#serverState.started()
+  }
+
+  async stop() {
+    await this.#serverState.stop()
+  }
+}

package/src/fastify-plugins/blobs.js

@@ -0,0 +1,139 @@
+import fp from 'fastify-plugin'
+import { filetypemime } from 'magic-bytes.js'
+import { Type as T } from '@sinclair/typebox'
+
+import { SUPPORTED_BLOB_VARIANTS } from '../blob-store/index.js'
+import { HEX_REGEX_32_BYTES, Z_BASE_32_REGEX_32_BYTES } from './constants.js'
+
+/** @import { BlobId } from '../types.js' */
+
+export default fp(blobServerPlugin, {
+  fastify: '4.x',
+  name: 'mapeo-blobs',
+})
+
+/**
+ * @typedef {Object} BlobServerPluginOpts
+ *
+ * @property {(projectPublicId: string) => Promise<import('../blob-store/index.js').BlobStore>} getBlobStore
+ */
+
+const BLOB_TYPES = /** @type {BlobId['type'][]} */ (
+  Object.keys(SUPPORTED_BLOB_VARIANTS)
+)
+const BLOB_VARIANTS = [
+  ...new Set(Object.values(SUPPORTED_BLOB_VARIANTS).flat()),
+]
+
+const PARAMS_JSON_SCHEMA = T.Object({
+  projectPublicId: T.String({ pattern: Z_BASE_32_REGEX_32_BYTES }),
+  driveId: T.String({ pattern: HEX_REGEX_32_BYTES }),
+  type: T.Union(
+    BLOB_TYPES.map((type) => {
+      return T.Literal(type)
+    })
+  ),
+  variant: T.Union(
+    BLOB_VARIANTS.map((variant) => {
+      return T.Literal(variant)
+    })
+  ),
+  name: T.String(),
+})
+
+/** @type {import('fastify').FastifyPluginAsync<import('fastify').RegisterOptions & BlobServerPluginOpts>} */
+async function blobServerPlugin(fastify, options) {
+  if (!options.getBlobStore) throw new Error('Missing getBlobStore')
+
+  // We call register here so that the `prefix` option can work if desired
+  // https://fastify.dev/docs/latest/Reference/Routes#route-prefixing-and-fastify-plugin
+  fastify.register(routes, options)
+}
+
+/** @type {import('fastify').FastifyPluginAsync<Omit<BlobServerPluginOpts, 'prefix'>, import('fastify').RawServerDefault, import('@fastify/type-provider-typebox').TypeBoxTypeProvider>} */
+async function routes(fastify, options) {
+  const { getBlobStore } = options
+
+  fastify.get(
+    '/:projectPublicId/:driveId/:type/:variant/:name',
+    { schema: { params: PARAMS_JSON_SCHEMA } },
+    async (request, reply) => {
+      const { projectPublicId, ...blobId } = request.params
+
+      if (!isValidBlobId(blobId)) {
+        reply.code(400)
+        throw new Error(
+          `Unsupported variant "${blobId.variant}" for ${blobId.type}`
+        )
+      }
+      const { driveId } = blobId
+
+      let blobStore
+      try {
+        blobStore = await getBlobStore(projectPublicId)
+      } catch (e) {
+        reply.code(404)
+        throw e
+      }
+
+      let entry
+      try {
+        entry = await blobStore.entry(blobId, { wait: false })
+      } catch (e) {
+        reply.code(404)
+        throw e
+      }
+
+      if (!entry) {
+        reply.code(404)
+        throw new Error('Entry not found')
+      }
+
+      const { metadata } = entry.value
+
+      let blobStream
+      try {
+        blobStream = await blobStore.createEntryReadStream(driveId, entry)
+      } catch (e) {
+        reply.code(404)
+        throw e
+      }
+
+      // Extract the 'mimeType' property of the metadata and use it for the response header if found
+      if (
+        metadata &&
+        'mimeType' in metadata &&
+        typeof metadata.mimeType === 'string'
+      ) {
+        reply.header('Content-Type', metadata.mimeType)
+      } else {
+        // Attempt to guess the MIME type based on the blob contents
+        const blobSlice = await blobStore.getEntryBlob(driveId, entry, {
+          length: 20,
+        })
+
+        if (!blobSlice) {
+          reply.code(404)
+          throw new Error('Blob not found')
+        }
+
+        const [guessedMime] = filetypemime(blobSlice)
+
+        reply.header('Content-Type', guessedMime || 'application/octet-stream')
+      }
+
+      return reply.send(blobStream)
+    }
+  )
+}
+
+/**
+ * @param {Omit<BlobId, 'variant'> & { variant: BlobId['variant'] }} maybeBlobId
+ * @returns {maybeBlobId is BlobId}
+ */
+function isValidBlobId(maybeBlobId) {
+  const { type, variant } = maybeBlobId
+  /** @type {readonly BlobId['variant'][]} */
+  const validVariants = SUPPORTED_BLOB_VARIANTS[type]
+  return validVariants.includes(variant)
+}

package/src/fastify-plugins/constants.js

@@ -0,0 +1,5 @@
+// hex encoded 32-byte string
+export const HEX_REGEX_32_BYTES = '^[0-9a-fA-F]{64}$'
+
+// z-base-32 encoded 32-byte string (52 characters)
+export const Z_BASE_32_REGEX_32_BYTES = '^[0-9a-zA-Z]{52}$'

package/src/fastify-plugins/icons.js

@@ -0,0 +1,158 @@
+import { Type as T } from '@sinclair/typebox'
+import fp from 'fastify-plugin'
+import { docSchemas } from '@comapeo/schema'
+
+import { kGetIconBlob } from '../icon-api.js'
+import { HEX_REGEX_32_BYTES, Z_BASE_32_REGEX_32_BYTES } from './constants.js'
+import { ExhaustivenessError } from '../utils.js'
+
+export default fp(iconServerPlugin, {
+  fastify: '4.x',
+  name: 'mapeo-icons',
+})
+
+const ICON_DOC_ID_STRING = T.String({ pattern: HEX_REGEX_32_BYTES })
+const PROJECT_PUBLIC_ID_STRING = T.String({ pattern: Z_BASE_32_REGEX_32_BYTES })
+
+const VALID_SIZES = docSchemas.icon.definitions.size.enum
+const VALID_MIME_TYPES = docSchemas.icon.properties.variants.items.oneOf.map(
+  (iconType) => iconType.properties.mimeType.const
+)
+const VALID_PIXEL_DENSITIES = docSchemas.icon.properties.variants.items.oneOf
+  .map((iconType) =>
+    'pixelDensity' in iconType.properties
+      ? iconType.properties.pixelDensity.enum
+      : []
+  )
+  .flat()
+
+const PARAMS_JSON_SCHEMA = T.Object({
+  iconDocId: ICON_DOC_ID_STRING,
+  projectPublicId: PROJECT_PUBLIC_ID_STRING,
+  iconInfo: T.String({
+    pattern: `^(${VALID_SIZES.join('|')})(@(${VALID_PIXEL_DENSITIES.join(
+      '|'
+    )}+)x)?$`,
+  }),
+  mimeTypeExtension: T.Union(
+    VALID_MIME_TYPES.map((mimeType) => {
+      switch (mimeType) {
+        case 'image/png':
+          return T.Literal('png')
+        case 'image/svg+xml':
+          return T.Literal('svg')
+        default:
+          throw new ExhaustivenessError(mimeType)
+      }
+    })
+  ),
+})
+
+/**
+ * @typedef {Object} IconServerPluginOpts
+ *
+ * @property {(projectId: string) => Promise<import('../mapeo-project.js').MapeoProject>} getProject
+ **/
+
+/** @type {import('fastify').FastifyPluginAsync<import('fastify').RegisterOptions & IconServerPluginOpts>} */
+async function iconServerPlugin(fastify, options) {
+  if (!options.getProject) throw new Error('Missing getProject')
+  fastify.register(routes, options)
+}
+
+/** @type {import('fastify').FastifyPluginAsync<Omit<IconServerPluginOpts, 'prefix'>, import('fastify').RawServerDefault, import('@fastify/type-provider-typebox').TypeBoxTypeProvider>} */
+async function routes(fastify, options) {
+  const { getProject } = options
+
+  fastify.get(
+    '/:projectPublicId/:iconDocId/:iconInfo.:mimeTypeExtension',
+    { schema: { params: PARAMS_JSON_SCHEMA } },
+    async (req, res) => {
+      const { projectPublicId, iconDocId, iconInfo, mimeTypeExtension } =
+        req.params
+
+      const { size, pixelDensity } = extractSizeAndPixelDensity(iconInfo)
+
+      const project = await getProject(projectPublicId)
+
+      const mimeType =
+        mimeTypeExtension === 'png' ? 'image/png' : 'image/svg+xml'
+
+      try {
+        const icon = await project.$icons[kGetIconBlob](
+          iconDocId,
+          mimeType === 'image/svg+xml'
+            ? {
+                size,
+                mimeType,
+              }
+            : {
+                size,
+                pixelDensity,
+                mimeType,
+              }
+        )
+
+        res.header('Content-Type', mimeType)
+        return res.send(icon)
+      } catch (err) {
+        res.code(404)
+        throw err
+      }
+    }
+  )
+}
+
+// matches strings that end in `@_x` and captures `_`, where `_` is a positive integer
+const DENSITY_MATCH_REGEX = /@(\d+)x$/i
+
+/**
+ * @param {string} input
+ *
+ * @return {{
+ * pixelDensity: import('../icon-api.js').BitmapOpts['pixelDensity'],
+ * size: import('../icon-api.js').ValidSizes}}
+ */
+function extractSizeAndPixelDensity(input) {
+  const result = DENSITY_MATCH_REGEX.exec(input)
+
+  if (result) {
+    const [match, capturedDensity] = result
+    const size = input.split(match, 1)[0]
+    const pixelDensity = parseInt(capturedDensity, 10)
+
+    assertValidSize(size)
+    assertValidPixelDensity(pixelDensity)
+
+    return { size, pixelDensity }
+  }
+
+  assertValidSize(input)
+
+  return { size: input, pixelDensity: 1 }
+}
+
+/**
+ * @param {string} value
+ * @returns {asserts value is Exclude<import('@comapeo/schema').Icon['variants'][number]['size'],'size_unspecified'>}
+ */
+function assertValidSize(value) {
+  if (
+    !VALID_SIZES.includes(
+      // @ts-expect-error
+      value
+    )
+  ) {
+    throw new Error(`'${value}' is not a valid icon size`)
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @returns {asserts value is import('../icon-api.js').BitmapOpts['pixelDensity']}
+ */
+function assertValidPixelDensity(value) {
+  if (!VALID_PIXEL_DENSITIES.includes(/** @type {any} */ (value))) {
+    throw new Error(`${value} is not a valid icon pixel density`)
+  }
+}

package/src/fastify-plugins/maps/index.js

@@ -0,0 +1,173 @@
+import fp from 'fastify-plugin'
+import { Type as T } from '@sinclair/typebox'
+import { fetch } from 'undici'
+
+import {
+  NotFoundError,
+  createStyleJsonResponseHeaders,
+  getFastifyServerAddress,
+} from '../utils.js'
+import { PLUGIN_NAME as MAPEO_STATIC_MAPS } from './static-maps.js'
+import { PLUGIN_NAME as MAPEO_OFFLINE_FALLBACK } from './offline-fallback-map.js'
+
+export const PLUGIN_NAME = 'mapeo-maps'
+export const DEFAULT_MAPBOX_STYLE_URL =
+  'https://api.mapbox.com/styles/v1/mapbox/outdoors-v12'
+
+const MAP_PROVIDER_API_KEY_QUERY_PARAM_BY_HOSTNAME = new Map([
+  // Mapbox expects `access_token`: https://docs.mapbox.com/api/maps/styles/
+  ['api.mapbox.com', 'access_token'],
+  // Protomaps expects `key` (no docs link yet)
+  ['api.protomaps.com', 'key'],
+  // MapTiler expects `key`: https://docs.maptiler.com/cloud/api/maps/
+  ['api.maptiler.com', 'key'],
+  // Stadia expects `api_key`: https://docs.stadiamaps.com/themes/
+  ['tiles.stadiamaps.com', 'api_key'],
+  // ArcGIS expects `token`: https://developers.arcgis.com/documentation/mapping-apis-and-services/security/api-keys/
+  ['basemapstyles-api.arcgis.com', 'token'],
+])
+
+export const plugin = fp(mapsPlugin, {
+  fastify: '4.x',
+  name: PLUGIN_NAME,
+  decorators: { fastify: ['mapeoStaticMaps', 'mapeoFallbackMap'] },
+  dependencies: [MAPEO_STATIC_MAPS, MAPEO_OFFLINE_FALLBACK],
+})
+
+/**
+ * @typedef {object} MapsPluginOpts
+ * @property {string} [prefix]
+ * @property {string} [defaultOnlineStyleUrl]
+ */
+
+/**
+ * @typedef {object} MapsPluginContext
+ * @property {() => Promise<string>} getStyleJsonUrl
+ */
+
+/** @type {import('fastify').FastifyPluginAsync<MapsPluginOpts>} */
+async function mapsPlugin(fastify, opts) {
+  fastify.decorate('mapeoMaps', {
+    async getStyleJsonUrl() {
+      const base = await getFastifyServerAddress(fastify.server, {
+        timeout: 5000,
+      })
+
+      return new URL(`${opts.prefix || ''}/style.json`, base).href
+    },
+  })
+  fastify.register(routes, {
+    prefix: opts.prefix,
+    defaultOnlineStyleUrl: opts.defaultOnlineStyleUrl,
+  })
+}
+
+const GetStyleJsonQueryStringSchema = T.Object({
+  key: T.Optional(T.String()),
+})
+
+/** @type {import('fastify').FastifyPluginAsync<MapsPluginOpts, import('fastify').RawServerDefault, import('@fastify/type-provider-typebox').TypeBoxTypeProvider>} */
+async function routes(fastify, opts) {
+  const { defaultOnlineStyleUrl = DEFAULT_MAPBOX_STYLE_URL } = opts
+
+  fastify.get(
+    '/style.json',
+    { schema: { querystring: GetStyleJsonQueryStringSchema } },
+    async (req, rep) => {
+      const serverAddress = await getFastifyServerAddress(req.server.server)
+
+      // 1. Attempt to get "default" local static map's style.json
+      {
+        const styleId = 'default'
+
+        const results = await Promise.all([
+          fastify.mapeoStaticMaps.getStyleJsonStats(styleId),
+          fastify.mapeoStaticMaps.getResolvedStyleJson(styleId, serverAddress),
+        ]).catch(() => {
+          fastify.log.warn('Cannot read default static map')
+          return null
+        })
+
+        if (results) {
+          const [stats, styleJson] = results
+          rep.headers(createStyleJsonResponseHeaders(stats.mtime))
+          return styleJson
+        }
+      }
+
+      // 2. Attempt to get a default style.json from online source
+      {
+        const { key } = req.query
+
+        const upstreamUrlObj = new URL(defaultOnlineStyleUrl)
+        const { hostname } = upstreamUrlObj
+
+        if (key) {
+          const paramToUpsert =
+            MAP_PROVIDER_API_KEY_QUERY_PARAM_BY_HOSTNAME.get(hostname)
+
+          if (paramToUpsert) {
+            // Note that even if the search param of interest already exists in the url
+            // it is overwritten by the key provided in the request's search params
+            upstreamUrlObj.searchParams.set(paramToUpsert, key)
+          } else {
+            fastify.log.warn(
+              `Provided API key will not be applied to unrecognized provider: ${hostname}`
+            )
+          }
+        }
+
+        try {
+          const upstreamResponse = await fetch(upstreamUrlObj.href, {
+            signal: AbortSignal.timeout(30_000),
+          })
+
+          if (upstreamResponse.ok) {
+            // Set up headers to forward
+            for (const [name, value] of upstreamResponse.headers) {
+              // Only forward headers related to caching
+              // https://www.rfc-editor.org/rfc/rfc9111#name-field-definitions
+              // e.g. usage from map renderer: https://github.com/maplibre/maplibre-gl-js/blob/26a7a6c2c142ef2e26db89f5fdf2338769494902/src/util/ajax.ts#L205
+              if (
+                ['age', 'cache-control', 'expires'].includes(name.toLowerCase())
+              ) {
+                rep.header(name, value)
+              }
+            }
+            // Some upstream providers will not set the 'application/json' content-type header despite the body being JSON e.g. Protomaps
+            // TODO: Should we forward the upstream 'content-type' header?
+            // We kind of assume that a Style Spec-compatible JSON payload will always be used by a provider
+            // Technically, there could be cases where a provider doesn't use the Mapbox Style Spec and has their own format,
+            // which may be delivered as some other content type
+            rep.header('content-type', 'application/json; charset=utf-8')
+            return upstreamResponse.json()
+          } else {
+            fastify.log.warn(
+              `Upstream style.json request returned non-2xx status: ${upstreamResponse.status} ${upstreamResponse.statusText}`
+            )
+          }
+        } catch (err) {
+          fastify.log.warn('Failed to make upstream style.json request', err)
+        }
+      }
+
+      // 3. Provide offline fallback map's style.json
+      {
+        let results = null
+
+        try {
+          results = await Promise.all([
+            fastify.mapeoFallbackMap.getStyleJsonStats(),
+            fastify.mapeoFallbackMap.getResolvedStyleJson(serverAddress),
+          ])
+        } catch (err) {
+          throw new NotFoundError(`id = fallback, style.json`)
+        }
+
+        const [stats, styleJson] = results
+        rep.headers(createStyleJsonResponseHeaders(stats.mtime))
+        return styleJson
+      }
+    }
+  )
+}

package/src/fastify-plugins/maps/offline-fallback-map.js

@@ -0,0 +1,114 @@
+import path from 'path'
+import fs from 'fs/promises'
+import FastifyStatic from '@fastify/static'
+import fp from 'fastify-plugin'
+
+import {
+  NotFoundError,
+  createStyleJsonResponseHeaders,
+  getFastifyServerAddress,
+} from '../utils.js'
+
+export const PLUGIN_NAME = 'mapeo-static-maps'
+
+export const plugin = fp(offlineFallbackMapPlugin, {
+  fastify: '4.x',
+  name: PLUGIN_NAME,
+})
+
+/**
+ * @typedef {object} OfflineFallbackMapPluginOpts
+ * @property {string} [prefix]
+ * @property {string} styleJsonPath
+ * @property {string} sourcesDir
+ */
+
+/**
+ * @typedef {object} FallbackMapPluginDecorator
+ * @property {(serverAddress: string) => Promise<any>} getResolvedStyleJson
+ * @property {() => Promise<import('node:fs').Stats>} getStyleJsonStats
+ */
+
+/** @type {import('fastify').FastifyPluginAsync<OfflineFallbackMapPluginOpts>} */
+async function offlineFallbackMapPlugin(fastify, opts) {
+  const { styleJsonPath, sourcesDir } = opts
+
+  fastify.decorate(
+    'mapeoFallbackMap',
+    /** @type {FallbackMapPluginDecorator} */
+    ({
+      async getResolvedStyleJson(serverAddress) {
+        const rawStyleJson = await fs.readFile(styleJsonPath, 'utf-8')
+        const styleJson = JSON.parse(rawStyleJson)
+
+        const sources = styleJson.sources || {}
+
+        const sourcesDirFiles = await fs.readdir(sourcesDir, {
+          withFileTypes: true,
+        })
+
+        for (const file of sourcesDirFiles) {
+          if (!file.isFile()) continue
+
+          if (file.name === 'style.json') continue
+
+          const extension = path.extname(file.name).toLowerCase()
+          if (!(extension === '.json' || extension === '.geojson')) continue
+
+          const sourceName = path.basename(file.name, extension) + '-source'
+
+          sources[sourceName] = {
+            type: 'geojson',
+            data: new URL(`${opts.prefix || ''}/${file.name}`, serverAddress)
+              .href,
+          }
+        }
+
+        styleJson.sources = sources
+
+        return styleJson
+      },
+      getStyleJsonStats() {
+        return fs.stat(styleJsonPath)
+      },
+    })
+  )
+
+  fastify.register(routes, {
+    prefix: opts.prefix,
+    styleJsonPath: opts.styleJsonPath,
+    sourcesDir: opts.sourcesDir,
+  })
+}
+
+/** @type {import('fastify').FastifyPluginAsync<OfflineFallbackMapPluginOpts, import('fastify').RawServerDefault, import('@fastify/type-provider-typebox').TypeBoxTypeProvider>} */
+async function routes(fastify, opts) {
+  const { sourcesDir } = opts
+
+  fastify.register(FastifyStatic, {
+    root: sourcesDir,
+    decorateReply: false,
+  })
+
+  fastify.get('/style.json', async (req, rep) => {
+    const serverAddress = await getFastifyServerAddress(req.server.server)
+
+    let stats, styleJson
+
+    try {
+      const results = await Promise.all([
+        fastify.mapeoFallbackMap.getStyleJsonStats(),
+        fastify.mapeoFallbackMap.getResolvedStyleJson(serverAddress),
+      ])
+
+      stats = results[0]
+      styleJson = results[1]
+    } catch (err) {
+      throw new NotFoundError(`id = fallback, style.json`)
+    }
+
+    rep.headers(createStyleJsonResponseHeaders(stats.mtime))
+
+    return styleJson
+  })
+}