styled-map-package-api 5.0.0-pre.3 → 5.0.0-pre.4

package/lib/reader.js

@@ -0,0 +1,360 @@
+import { ZipReader } from '@gmaclennan/zip-reader'
+
+import { ENOENT } from './utils/errors.js'
+import { noop } from './utils/misc.js'
+import { validateStyle } from './utils/style.js'
+import {
+  getContentType,
+  getResourceType,
+  STYLE_FILE,
+  URI_BASE,
+  VERSION_FILE,
+} from './utils/templates.js'
+
+/**
+ * Simple deferred promise helper (Node 20 lacks Promise.withResolvers).
+ * @template T
+ * @returns {{ promise: Promise<T>, resolve: (value: T) => void, reject: (reason: unknown) => void }}
+ */
+function defer() {
+  /** @type {(value: any) => void} */
+  let resolve
+  /** @type {(reason: unknown) => void} */
+  let reject
+  const promise = new Promise((res, rej) => {
+    resolve = res
+    reject = rej
+  })
+  // @ts-ignore — resolve/reject are assigned synchronously inside the Promise constructor
+  return { promise, resolve, reject }
+}
+
+/**
+ * Manages zip entry iteration and allows looking up entries by name before all
+ * entries have been read. When a requested entry hasn't been seen yet, a
+ * deferred promise is created that resolves as soon as the entry is encountered
+ * during iteration. This avoids waiting for the entire ZIP central directory to
+ * be processed before serving early entries like VERSION and style.json.
+ */
+class Entries {
+  /** @type {Map<string, import('@gmaclennan/zip-reader').ZipEntry>} */
+  #entries = new Map()
+  /** @type {Map<string, ReturnType<typeof defer<import('@gmaclennan/zip-reader').ZipEntry | undefined>>>} */
+  #deferredEntries = new Map()
+  #readyPromise
+  #ready = false
+  #closing = false
+  /** @type {unknown} */
+  #error
+
+  /**
+   * @param {Promise<import('@gmaclennan/zip-reader').ZipReader>} zipPromise
+   * @param {{ maxEntries: number }} options
+   */
+  constructor(zipPromise, { maxEntries }) {
+    this.#readyPromise = (async () => {
+      try {
+        if (this.#closing) return
+        const zip = await zipPromise
+        if (this.#closing) return
+        let count = 0
+        for await (const entry of zip) {
+          if (this.#closing) return
+          if (++count > maxEntries) {
+            throw new Error(
+              `SMP archive exceeds maximum entry count of ${maxEntries}`,
+            )
+          }
+          const normalizedName = entry.name.normalize('NFC')
+          this.#entries.set(normalizedName, entry)
+          this.#deferredEntries.get(normalizedName)?.resolve(entry)
+          this.#deferredEntries.delete(normalizedName)
+        }
+      } catch (error) {
+        this.#error = error
+        for (const deferred of this.#deferredEntries.values()) {
+          deferred.reject(error)
+        }
+        this.#deferredEntries.clear()
+        throw error
+      } finally {
+        this.#ready = true
+        // Resolve remaining deferreds with undefined (entry not found)
+        for (const deferred of this.#deferredEntries.values()) {
+          deferred.resolve(undefined)
+        }
+        this.#deferredEntries.clear()
+      }
+    })()
+    this.#readyPromise.catch(noop)
+  }
+
+  async ready() {
+    await this.#readyPromise
+  }
+
+  /** @param {string} path */
+  async get(path) {
+    path = path.normalize('NFC')
+    if (this.#entries.has(path)) {
+      return this.#entries.get(path)
+    }
+    if (this.#ready || this.#closing) {
+      if (this.#error) throw this.#error
+      return undefined
+    }
+    const existingDeferred = this.#deferredEntries.get(path)
+    if (existingDeferred) {
+      return existingDeferred.promise
+    }
+    const deferred = defer()
+    this.#deferredEntries.set(path, deferred)
+    return deferred.promise
+  }
+
+  async close() {
+    this.#closing = true
+    await this.#readyPromise
+  }
+}
+
+/**
+ * Read a web ReadableStream into a string.
+ * Browser-compatible replacement for node:stream/consumers `text()`.
+ * @param {ReadableStream<Uint8Array>} readable
+ * @returns {Promise<string>}
+ */
+async function streamToText(readable) {
+  const chunks = /** @type {Uint8Array[]} */ ([])
+  const reader = readable.getReader()
+  try {
+    while (true) {
+      const { done, value } = await reader.read()
+      if (done) break
+      chunks.push(value instanceof Uint8Array ? value : new Uint8Array(value))
+    }
+  } finally {
+    reader.releaseLock()
+  }
+  const totalLen = chunks.reduce((s, c) => s + c.byteLength, 0)
+  const buf = new Uint8Array(totalLen)
+  let off = 0
+  for (const chunk of chunks) {
+    buf.set(chunk, off)
+    off += chunk.byteLength
+  }
+  return new TextDecoder().decode(buf)
+}
+
+/**
+ * Read a web ReadableStream into a parsed JSON value.
+ * Browser-compatible replacement for node:stream/consumers `json()`.
+ * @param {ReadableStream<Uint8Array>} readable
+ * @returns {Promise<unknown>}
+ */
+async function streamToJson(readable) {
+  return JSON.parse(await streamToText(readable))
+}
+
+/**
+ * @typedef {object} Resource
+ * @property {string} resourceType
+ * @property {string} contentType
+ * @property {number} contentLength
+ * @property {ReadableStream<Uint8Array>} stream
+ * @property {'gzip'} [contentEncoding]
+ */
+
+/**
+ * @typedef {object} ReaderOptions
+ * @property {number} [maxEntries=500_000] Maximum number of ZIP entries to
+ *   process. Exceeding this limit throws an error during `opened()`. Default is
+ *   500,000 (~a global z9 tileset).
+ * @property {number} [maxResourceSize=20 * 1024 * 1024] Maximum uncompressed
+ *   size in bytes for a single resource returned by `getResource()`. Default is
+ *   20 MiB.
+ */
+
+/**
+ * A low-level reader for styled map packages. Returns resources in the package
+ * as readable streams, for serving over HTTP for example.
+ */
+export class Reader {
+  #entries
+  /** @type {undefined | Promise<void>} */
+  #closePromise
+  /** @type {import('@gmaclennan/zip-reader/file-source').FileSource | null} */
+  #fileSource = null
+  #maxResourceSize
+
+  /**
+   * @param {string | import('@gmaclennan/zip-reader').ZipReader} filepathOrZip Path to styled map package (`.styledmap`) file, or a ZipReader instance
+   * @param {ReaderOptions} [options]
+   */
+  constructor(filepathOrZip, options = {}) {
+    const { maxEntries = 500_000, maxResourceSize = 20 * 1024 * 1024 } = options
+    this.#maxResourceSize = maxResourceSize
+    /** @type {Promise<import('@gmaclennan/zip-reader').ZipReader>} */
+    let zipPromise
+    if (typeof filepathOrZip === 'string') {
+      // Dynamic import so FileSource (which uses node:fs) is never loaded
+      // in browser environments where only ZipReader instances are passed.
+      const sourcePromise = import('@gmaclennan/zip-reader/file-source').then(
+        ({ FileSource }) => FileSource.open(filepathOrZip),
+      )
+      sourcePromise.catch(noop)
+      zipPromise = sourcePromise.then((source) => {
+        this.#fileSource = source
+        return ZipReader.from(source, { skipUniqueEntryCheck: true })
+      })
+    } else {
+      zipPromise = Promise.resolve(filepathOrZip)
+    }
+    zipPromise.catch(noop)
+    this.#entries = new Entries(zipPromise, { maxEntries })
+    // Close the internally-opened file source on failure to avoid FD leaks.
+    // Uses this.close() so that #closePromise is set, ensuring any subsequent
+    // reader.close() call awaits the same cleanup rather than racing with it.
+    this.#entries.ready().catch(() => this.close())
+  }
+
+  /**
+   * Resolves when the styled map package has been opened and the entries have
+   * been read. Throws any error that occurred during opening.
+   */
+  async opened() {
+    await this.#entries.ready()
+  }
+
+  /**
+   * Get the format version from the VERSION file in the styled map package.
+   * Returns "1.0" if no VERSION file exists (older SMP files did not have a
+   * VERSION file, so we assume version 1.0).
+   *
+   * @returns {Promise<string>}
+   */
+  async getVersion() {
+    const versionEntry = await this.#entries.get(VERSION_FILE)
+    if (!versionEntry) return '1.0'
+    return (await streamToText(versionEntry.readable())).trim()
+  }
+
+  /**
+   * Get the style JSON from the styled map package. The URLs in the style JSON
+   * will be transformed to use the provided base URL.
+   *
+   * @param {string | null} [baseUrl] Base URL where you plan to serve the resources in this styled map package, e.g. `http://localhost:3000/maps/styleA`
+   * @returns {Promise<import('./types.js').SMPStyle>}
+   */
+  async getStyle(baseUrl = null) {
+    const styleEntry = await this.#entries.get(STYLE_FILE)
+    if (!styleEntry) throw new ENOENT(STYLE_FILE)
+    const style = await streamToJson(styleEntry.readable())
+    if (!validateStyle(style)) {
+      throw new AggregateError(validateStyle.errors, 'Invalid style')
+    }
+    if (typeof style.glyphs === 'string') {
+      style.glyphs = getUrl(style.glyphs, baseUrl)
+    }
+    if (typeof style.sprite === 'string') {
+      style.sprite = getUrl(style.sprite, baseUrl)
+    } else if (Array.isArray(style.sprite)) {
+      style.sprite = style.sprite.map(({ id, url }) => {
+        return { id, url: getUrl(url, baseUrl) }
+      })
+    }
+    for (const source of Object.values(style.sources)) {
+      if ('tiles' in source && source.tiles) {
+        source.tiles = source.tiles.map((tile) => getUrl(tile, baseUrl))
+      }
+      if (
+        'data' in source &&
+        typeof source.data === 'string' &&
+        source.data.startsWith(URI_BASE)
+      ) {
+        source.data = getUrl(source.data, baseUrl)
+      }
+    }
+    // Hard to get this type-safe without a validation function. Instead we
+    // trust the Writer and the tests for now.
+    return /** @type {import('./types.js').SMPStyle} */ (style)
+  }
+
+  /**
+   * Get a resource from the styled map package. The path should be relative to
+   * the root of the package.
+   *
+   * @param {string} path
+   * @returns {Promise<Resource>}
+   */
+  async getResource(path) {
+    if (path[0] === '/') path = path.slice(1)
+    if (path === STYLE_FILE) {
+      const styleJSON = JSON.stringify(await this.getStyle())
+      const bytes = new TextEncoder().encode(styleJSON)
+      return {
+        contentType: 'application/json; charset=utf-8',
+        contentLength: bytes.byteLength,
+        resourceType: 'style',
+        stream: new ReadableStream({
+          start(controller) {
+            controller.enqueue(bytes)
+            controller.close()
+          },
+        }),
+      }
+    }
+    const entry = await this.#entries.get(path)
+    if (!entry) throw new ENOENT(path)
+    if (entry.uncompressedSize > this.#maxResourceSize) {
+      throw new Error(
+        `Resource ${path} exceeds maximum size of ${this.#maxResourceSize} bytes (${entry.uncompressedSize} bytes)`,
+      )
+    }
+    const resourceType = getResourceType(path)
+    const contentType = getContentType(path)
+    const stream = entry.readable()
+    /** @type {Resource} */
+    const resource = {
+      resourceType,
+      contentType,
+      contentLength: entry.uncompressedSize,
+      stream,
+    }
+    if (path.endsWith('.gz')) {
+      resource.contentEncoding = 'gzip'
+    }
+    return resource
+  }
+
+  /**
+   * Close the styled map package file (should be called after reading the file to avoid memory leaks)
+   */
+  async close() {
+    if (this.#closePromise) return this.#closePromise
+    this.#closePromise = (async () => {
+      // Wait for entry iteration to stop before closing the file source,
+      // otherwise close() can race with the for-await loop still reading entries.
+      await this.#entries.close().catch(noop)
+      if (this.#fileSource) {
+        await this.#fileSource.close().catch(noop)
+      }
+    })()
+    return this.#closePromise
+  }
+}
+
+/**
+ * @param {string} smpUri
+ * @param {string | null} baseUrl
+ */
+function getUrl(smpUri, baseUrl) {
+  if (!smpUri.startsWith(URI_BASE)) {
+    throw new Error(`Invalid SMP URI: ${smpUri}`)
+  }
+  if (typeof baseUrl !== 'string') return smpUri
+  if (!baseUrl.endsWith('/')) {
+    baseUrl += '/'
+  }
+  return smpUri.replace(URI_BASE, baseUrl)
+}

package/lib/server.js

@@ -0,0 +1,222 @@
+import { IttyRouter } from 'itty-router/IttyRouter'
+import { StatusError } from 'itty-router/StatusError'
+import { createResponse } from 'itty-router/createResponse'
+
+import { isFileNotThereError } from './utils/errors.js'
+import { URI_BASE, templateToRegex } from './utils/templates.js'
+
+/** @import { Resource, Reader } from './reader.js' */
+/** @import {IRequestStrict, RequestLike} from 'itty-router' */
+
+/** @typedef {Pick<Reader, keyof Reader>} ReaderLike */
+/** @typedef {typeof IttyRouter<IRequestStrict, [ReaderLike], Response>} RouterType */
+
+/**
+ * @param {Resource} resource
+ * @param {ResponseInit} [options]
+ * @returns {Response} reply
+ */
+function resourceResponse(resource, options = {}) {
+  const response = new Response(resource.stream, options)
+  response.headers.set('Content-Type', resource.contentType)
+  response.headers.set('Content-Length', resource.contentLength.toString())
+  if (resource.contentEncoding) {
+    response.headers.set('Content-Encoding', resource.contentEncoding)
+  }
+  return response
+}
+
+const jsonRaw = createResponse('application/json; charset=utf-8')
+const encoder = new TextEncoder()
+
+/** @param {unknown} obj */
+function json(obj) {
+  const data = encoder.encode(JSON.stringify(obj))
+  return jsonRaw(data, {
+    headers: { 'Content-Length': data.length.toString() },
+  })
+}
+
+/**
+ * Create a server for serving styled map packages (SMP) over http. The server
+ * is a `fetch` handler that must be provided a WHATWG `Request` and a SMP
+ * `Reader` instance. Use `@whatwg-node/server` to use with Node.js HTTP server.
+ *
+ * To handle errors, catch errors from `fetch` and return appropriate HTTP responses.
+ * You can use `itty-router/error` for this.
+ *
+ * @example
+ * ```js
+ * import { createServer } from 'node:http'
+ * import { error } from 'itty-router/error'
+ * import { createServerAdapter } from '@whatwg-node/server'
+ * import { createServer as createSMPServer } from 'styled-map-package-api/server'
+ * import { Reader } from 'styled-map-package-api/reader'
+ *
+ * const reader = new Reader('path/to/your-style.smp')
+ * const smpServer = createSMPServer()
+ * const httpServer = createServer(createServerAdapter((request) => {
+ *   return smpServer.fetch(request, reader).catch(error)
+ * }))
+ * ```
+ *
+ * @param {object} [options]
+ * @param {string} [options.base='/'] Base path for the server routes
+ * @param {(tileId: { x: number, y: number, z: number }, sourceInfo: { sourceId: string, source: import('./types.js').SMPSource }) => Response | Promise<Response>} [options.fallbackTile] Called when a tile is missing from the SMP
+ * @param {(fontstack: string, range: string) => Response | Promise<Response>} [options.fallbackGlyph] Called when a glyph is missing from the SMP
+ * @returns {{ fetch: (request: RequestLike, reader: ReaderLike) => Promise<Response> }} server instance
+ */
+export function createServer({ base = '/', fallbackTile, fallbackGlyph } = {}) {
+  base = base.endsWith('/') ? base : base + '/'
+
+  /** @type {WeakMap<ReaderLike, Promise<import('./types.js').SMPStyle>>} */
+  const styleCache = new WeakMap()
+
+  /** @type {WeakMap<ReaderLike, TileMatcher[]>} */
+  const tileMatcherCache = new WeakMap()
+
+  /** @type {WeakMap<ReaderLike, RegExp | null>} */
+  const glyphRegexCache = new WeakMap()
+
+  /**
+   * Get the raw style for a reader, caching the promise per reader.
+   * @param {ReaderLike} reader
+   */
+  function getCachedStyle(reader) {
+    let promise = styleCache.get(reader)
+    if (!promise) {
+      promise = reader.getStyle()
+      styleCache.set(reader, promise)
+    }
+    return promise
+  }
+
+  const router = IttyRouter({
+    base,
+  })
+    .get('/style.json', async (request, reader) => {
+      const baseUrl = new URL('.', request.url)
+      const style = await reader.getStyle(baseUrl.href)
+      return json(style)
+    })
+    .get(':path+', async (request, reader) => {
+      const path = decodeURIComponent(request.params.path)
+      try {
+        const resource = await reader.getResource(path)
+        return resourceResponse(resource)
+      } catch (err) {
+        if (!isFileNotThereError(err)) throw err
+
+        if (fallbackTile) {
+          let matchers = tileMatcherCache.get(reader)
+          if (!matchers) {
+            const style = await getCachedStyle(reader)
+            matchers = buildTileMatchers(style.sources)
+            tileMatcherCache.set(reader, matchers)
+          }
+          for (const { regex, sourceId, source } of matchers) {
+            const match = path.match(regex)
+            if (match?.groups) {
+              return fallbackTile(
+                {
+                  x: Number(match.groups.x),
+                  y: Number(match.groups.y),
+                  z: Number(match.groups.z),
+                },
+                { sourceId, source },
+              )
+            }
+          }
+        }
+
+        if (fallbackGlyph) {
+          let glyphRegex = glyphRegexCache.get(reader)
+          if (glyphRegex === undefined) {
+            const style = await getCachedStyle(reader)
+            glyphRegex = buildGlyphRegex(style.glyphs)
+            glyphRegexCache.set(reader, glyphRegex)
+          }
+          if (glyphRegex) {
+            const match = path.match(glyphRegex)
+            if (match?.groups) {
+              return fallbackGlyph(match.groups.fontstack, match.groups.range)
+            }
+          }
+        }
+
+        throw new StatusError(404, 'Not Found')
+      }
+    })
+  return {
+    fetch: (request, reader) => {
+      return router.fetch(request, reader).catch((err) => {
+        if (isFileNotThereError(err)) {
+          throw new StatusError(404, 'Not Found')
+        } else {
+          throw err
+        }
+      })
+    },
+  }
+}
+
+/**
+ * @typedef {{ regex: RegExp, sourceId: string, source: import('./types.js').SMPSource }} TileMatcher
+ */
+
+const TILE_PLACEHOLDERS = { z: '\\d+', x: '\\d+', y: '\\d+' }
+
+/** Check that a tile URL template has {z}, {x}, {y} and no adjacent placeholders.
+ * @param {string} template */
+function isValidTileTemplate(template) {
+  return (
+    template.includes('{z}') &&
+    template.includes('{x}') &&
+    template.includes('{y}') &&
+    !template.includes('}{')
+  )
+}
+
+/**
+ * Build precompiled regex matchers for all tile sources.
+ *
+ * @param {{ [_: string]: import('./types.js').SMPSource }} sources
+ * @returns {TileMatcher[]}
+ */
+function buildTileMatchers(sources) {
+  /** @type {TileMatcher[]} */
+  const matchers = []
+  for (const [sourceId, source] of Object.entries(sources)) {
+    if (!('tiles' in source) || !source.tiles) continue
+    for (const tileUrl of source.tiles) {
+      if (!tileUrl.startsWith(URI_BASE)) continue
+      const templatePath = tileUrl.slice(URI_BASE.length)
+      if (!isValidTileTemplate(templatePath)) continue
+      const regex = templateToRegex(templatePath, TILE_PLACEHOLDERS)
+      matchers.push({ regex, sourceId, source })
+    }
+  }
+  return matchers
+}
+
+const GLYPH_PLACEHOLDERS = { fontstack: '.+', range: '[^/]+' }
+
+/**
+ * Build a regex to parse fontstack and range from a glyph resource path,
+ * based on the style's glyphs URI template.
+ *
+ * @param {string | undefined} glyphsUri
+ * @returns {RegExp | null}
+ */
+function buildGlyphRegex(glyphsUri) {
+  if (!glyphsUri || !glyphsUri.startsWith(URI_BASE)) return null
+  const template = glyphsUri.slice(URI_BASE.length)
+  if (
+    !template.includes('{fontstack}') ||
+    !template.includes('{range}') ||
+    template.includes('}{')
+  ) {
+    return null
+  }
+  return templateToRegex(template, GLYPH_PLACEHOLDERS)
+}