Feat: Icon HTTP Server

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}$'

src/fastify-plugins/icons.js

@@ -0,0 +1,153 @@
+import { Type as T } from '@sinclair/typebox'
+import fp from 'fastify-plugin'
+import { docSchemas } from '@mapeo/schema'
+
+import { kGetIconBlob } from '../icon-api.js'
+import { HEX_REGEX_32_BYTES, Z_BASE_32_REGEX_32_BYTES } from './constants.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.properties.variants.items.properties.size.enum
+const VALID_MIME_TYPES =
+  docSchemas.icon.properties.variants.items.properties.mimeType.enum
+const VALID_PIXEL_DENSITIES =
+  docSchemas.icon.properties.variants.items.properties.pixelDensity.enum
+
+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')
+      }
+    })
+  ),
+})
+
+/**
+ * @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 {Pick<import('@mapeo/schema').Icon['variants'][number], 'size' | 'pixelDensity'>}
+ */
+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 import('@mapeo/schema').Icon['variants'][number]['size']}
+ */
+function assertValidSize(value) {
+  if (
+    !VALID_SIZES.includes(
+      // @ts-expect-error
+      value
+    )
+  ) {
+    throw new Error(`'${value}' is not a valid icon size`)
+  }
+}
+
+/**
+ * @param {number} value
+ * @returns {asserts value is import('@mapeo/schema').Icon['variants'][number]['pixelDensity']}
+ */
+function assertValidPixelDensity(value) {
+  if (
+    !VALID_PIXEL_DENSITIES.includes(
+      // @ts-expect-error
+      value
+    )
+  ) {
+    throw new Error(`${value} is not a valid icon pixel density`)
+  }
+}

src/mapeo-project.js

@@ -32,6 +32,7 @@ import {
 import { Capabilities } from './capabilities.js'
 import { getDeviceId, projectKeyToId, valueOf } from './utils.js'
 import { MemberApi } from './member-api.js'
+import { IconApi } from './icon-api.js'
 import { SyncApi, kSyncReplicate } from './sync/sync-api.js'
 import Hypercore from 'hypercore'
 
@@ -56,6 +57,7 @@ export class MapeoProject {
   #capabilities
   #ownershipWriteDone
   #memberApi
+  #iconApi
   #syncApi
 
   /**
@@ -245,6 +247,16 @@ export class MapeoProject {
       },
     })
 
+    this.#iconApi = new IconApi({
+      iconDataStore: this.#dataStores.config,
+      iconDataType: this.#dataTypes.icon,
+      projectId: this.#projectId,
+      // TODO: Update after merging https://github.com/digidem/mapeo-core-next/pull/365
+      getMediaBaseUrl: async () => {
+        throw new Error('Not yet implemented')
+      },
+    })
+
     this.#syncApi = new SyncApi({
       coreManager: this.#coreManager,
       capabilities: this.#capabilities,
@@ -468,6 +480,13 @@ export class MapeoProject {
       schemaName: 'deviceInfo',
     })
   }
+
+  /**
+   * @returns {import('./icon-api.js').IconApi}
+   */
+  get $icons() {
+    return this.#iconApi
+  }
 }
 
 /**

tests/fastify-plugins/icons.js

@@ -0,0 +1,141 @@
+// @ts-check
+import { test } from 'brittle'
+import { randomBytes } from 'crypto'
+import fastify from 'fastify'
+
+import IconServerPlugin from '../../src/fastify-plugins/icons.js'
+import { projectKeyToPublicId } from '../../src/utils.js'
+
+test('Plugin throws error if missing getProject option', async (t) => {
+  const server = fastify()
+  await t.exception(() => server.register(IconServerPlugin))
+})
+
+test('Plugin handles prefix option properly', async (t) => {
+  const prefix = 'icons'
+
+  const server = fastify()
+
+  server.register(IconServerPlugin, {
+    prefix,
+    getProject: async () => {
+      throw new Error('Not implemented')
+    },
+  })
+
+  const response = await server.inject({
+    method: 'GET',
+    url: `${prefix}/${buildIconUrl({
+      projectPublicId: projectKeyToPublicId(randomBytes(32)),
+      iconId: randomBytes(32).toString('hex'),
+      size: 'small',
+      extension: 'png',
+    })}`,
+  })
+
+  t.not(response.statusCode, 404, 'returns non-404 status code')
+})
+
+test('url param validation', async (t) => {
+  const server = fastify()
+
+  server.register(IconServerPlugin, {
+    getProject: async () => {
+      throw new Error('Not implemented')
+    },
+  })
+
+  const projectPublicId = projectKeyToPublicId(randomBytes(32))
+  const iconId = randomBytes(32).toString('hex')
+
+  /** @type {Array<[string, Parameters<typeof buildIconUrl>[0]]>} */
+  const fixtures = [
+    [
+      'invalid project public id',
+      {
+        projectPublicId: randomBytes(32).toString('hex'),
+        iconId,
+        size: 'small',
+        extension: 'png',
+      },
+    ],
+    [
+      'invalid icon id',
+      {
+        projectPublicId,
+        iconId: randomBytes(16).toString('hex'),
+        size: 'small',
+        extension: 'png',
+      },
+    ],
+    [
+      'invalid pixel density',
+      {
+        projectPublicId,
+        iconId,
+        size: 'small',
+        extension: 'png',
+        pixelDensity: 10,
+      },
+    ],
+    [
+      'invalid size',
+      {
+        projectPublicId,
+        iconId,
+        size: 'foo',
+        extension: 'svg',
+      },
+    ],
+    [
+      'invalid extension',
+      {
+        projectPublicId,
+        iconId,
+        size: 'small',
+        extension: 'foo',
+      },
+    ],
+  ]
+
+  await Promise.all(
+    fixtures.map(async ([name, input]) => {
+      const response = await server.inject({
+        method: 'GET',
+        url: buildIconUrl(input),
+      })
+
+      t.comment(name)
+
+      t.is(response.statusCode, 400, 'returns expected status code')
+      t.is(
+        response.json().code,
+        'FST_ERR_VALIDATION',
+        'error is validation error'
+      )
+    })
+  )
+})
+
+/**
+ *
+ * @param {object} opts
+ * @param {string} opts.projectPublicId
+ * @param {string} opts.iconId
+ * @param {string} opts.size
+ * @param {number} [opts.pixelDensity]
+ * @param {string} opts.extension
+ *
+ * @returns {string}
+ */
+function buildIconUrl({
+  projectPublicId,
+  iconId,
+  size,
+  pixelDensity,
+  extension,
+}) {
+  const densitySuffix =
+    typeof pixelDensity === 'number' ? `@${pixelDensity}x` : ''
+  return `${projectPublicId}/${iconId}/${size}${densitySuffix}.${extension}`
+}