@comapeo/map-server 1.0.0-pre.0

package/src/lib/errors.ts

@@ -0,0 +1,187 @@
+import { json, type ErrorFormatter } from 'itty-router'
+
+interface ErrorDefinition {
+	message: string
+	status: number
+	code: string
+}
+
+type StatusErrorObject = {
+	message?: string
+	[key: string]: any
+}
+
+export class StatusError extends Error {
+	status: number;
+	[key: string]: any
+
+	constructor(status = 500, body?: StatusErrorObject | string) {
+		super(typeof body === 'object' ? body.message : body)
+		if (typeof body === 'object') Object.assign(this, body)
+		this.status = status
+	}
+}
+
+const errorsList = [
+	// Download errors (receiver-side)
+	{
+		code: 'DOWNLOAD_NOT_FOUND',
+		message: 'Download not found',
+		status: 404,
+	},
+	{
+		code: 'DOWNLOAD_ERROR',
+		message: 'Download failed',
+		status: 500,
+	},
+	{
+		code: 'DOWNLOAD_SHARE_CANCELED',
+		message: 'Download canceled by sender',
+		status: 409,
+	},
+	{
+		code: 'DOWNLOAD_SHARE_DECLINED',
+		message: 'Cannot download: share was declined',
+		status: 409,
+	},
+	{
+		code: 'DOWNLOAD_SHARE_NOT_PENDING',
+		message: 'Cannot download: share is not pending',
+		status: 409,
+	},
+	{
+		code: 'ABORT_NOT_DOWNLOADING',
+		message: 'Cannot abort: download is not in progress',
+		status: 409,
+	},
+	{
+		code: 'INVALID_SENDER_DEVICE_ID',
+		message: 'Invalid sender device ID',
+		status: 400,
+	},
+
+	// Map share errors (sender-side)
+	{
+		code: 'MAP_SHARE_NOT_FOUND',
+		message: 'Map share not found',
+		status: 404,
+	},
+	{
+		code: 'CANCEL_SHARE_NOT_CANCELABLE',
+		message: 'Cannot cancel: share is not pending or downloading',
+		status: 409,
+	},
+	{
+		code: 'DECLINE_SHARE_NOT_PENDING',
+		message: 'Cannot decline: share is not pending',
+		status: 409,
+	},
+	{
+		code: 'DECLINE_CANNOT_CONNECT',
+		message: 'Cannot decline: unable to connect to sender',
+		status: 502,
+	},
+
+	// Map errors
+	{
+		code: 'MAP_NOT_FOUND',
+		message: 'Map not found',
+		status: 404,
+	},
+	{
+		code: 'RESOURCE_NOT_FOUND',
+		message: 'Resource not found',
+		status: 404,
+	},
+	{
+		code: 'INVALID_MAP_FILE',
+		message: 'Invalid map file',
+		status: 400,
+	},
+
+	// Generic errors
+	{
+		code: 'FORBIDDEN',
+		message: 'Forbidden',
+		status: 403,
+	},
+	{
+		code: 'INVALID_REQUEST',
+		message: 'Invalid request',
+		status: 400,
+	},
+] as const satisfies Array<ErrorDefinition>
+
+export const errors = {} as Record<
+	(typeof errorsList)[number]['code'],
+	new (body?: { [key: string]: any } | string) => StatusError
+>
+for (const { code, message, status } of errorsList) {
+	errors[code] = class extends StatusError {
+		constructor(body?: { [key: string]: any } | string) {
+			body = typeof body === 'string' ? { message: body } : body
+			super(status, { code, message, ...body })
+		}
+	}
+}
+
+export class ExhaustivenessError extends Error {
+	constructor(value: never) {
+		super(`Exhaustiveness check failed. ${value} should be impossible`)
+		this.name = 'ExhaustivenessError'
+	}
+}
+
+export function jsonError(err: unknown): { message: string; code: string } {
+	if (err === null) {
+		return { message: 'Unknown error', code: 'UNKNOWN_ERROR' }
+	} else if (typeof err !== 'object') {
+		return { message: String(err), code: 'UNKNOWN_ERROR' }
+	} else {
+		return {
+			message:
+				'message' in err
+					? String((err as any).message)
+					: String((err as any).error),
+			code: (err as any).code || 'UNKNOWN_ERROR',
+		}
+	}
+}
+
+const getMessage = (code: number): string =>
+	({
+		400: 'Bad Request',
+		401: 'Unauthorized',
+		403: 'Forbidden',
+		404: 'Not Found',
+		500: 'Internal Server Error',
+	})[code] || 'Unknown Error'
+
+const getCode = (status: number): string =>
+	({
+		400: 'BAD_REQUEST',
+		401: 'UNAUTHORIZED',
+		403: 'FORBIDDEN',
+		404: 'NOT_FOUND',
+		500: 'INTERNAL_SERVER_ERROR',
+	})[status] || 'UNKNOWN_ERROR'
+
+export const error: ErrorFormatter = (a = 500, b?) => {
+	// handle passing an Error | StatusError directly in
+	if (a instanceof Error) {
+		const { message, code, ...err } = a
+		a = a.status || 500
+		b = {
+			message: message || getMessage(a),
+			code: code || getCode(a),
+			...err,
+		}
+	}
+
+	b = {
+		status: a,
+		...(typeof b === 'object' ? b : { message: b || getMessage(a) }),
+	}
+
+	return json(b, { status: a })
+}

package/src/lib/event-stream-response.ts

@@ -0,0 +1,57 @@
+import type { TypedEventTarget } from 'typed-event-target'
+
+import { noop } from './utils.js'
+
+const encoder = new TextEncoder()
+
+type EventTargetStateUpdater = TypedEventTarget<
+	Readonly<Event & { type: 'update' }>
+> & {
+	state: any
+}
+
+/**
+ * Create a Server-Sent Events stream for an EventTarget with a `state` property
+ * that emits 'update' events with state updates.
+ *
+ * You must pass an AbortSignal that will cancel the stream if the client disconnects.
+ */
+export function createEventStreamResponse(
+	eventTarget: EventTargetStateUpdater,
+	{ signal }: { signal: AbortSignal },
+): Response {
+	let listener: (event: Event & { type: 'update' }) => void | undefined
+
+	const stream = new ReadableStream({
+		start(controller) {
+			controller.enqueue(
+				encoder.encode(`data: ${JSON.stringify(eventTarget.state)}\n\n`),
+			)
+			listener = (event) => {
+				// eslint-disable-next-line @typescript-eslint/no-unused-vars
+				const { type, ...update } = event
+				controller.enqueue(
+					encoder.encode(`data: ${JSON.stringify(update)}\n\n`),
+				)
+			}
+			eventTarget.addEventListener('update', listener)
+		},
+		cancel() {
+			signal.removeEventListener('abort', onAbort)
+			if (listener) {
+				eventTarget.removeEventListener('update', listener)
+			}
+		},
+	})
+	const onAbort = () => {
+		stream.cancel().catch(noop)
+	}
+	signal.addEventListener('abort', onAbort, { once: true })
+	return new Response(stream, {
+		headers: {
+			'Content-Type': 'text/event-stream',
+			'Cache-Control': 'no-cache',
+			Connection: 'keep-alive',
+		},
+	})
+}

package/src/lib/event-target.ts

@@ -0,0 +1,11 @@
+import { type TypedEventTarget as TypedEventTargetOrig } from 'typed-event-target'
+
+/**
+ * A strongly typed EventTarget - no runtime overhead
+ */
+export const TypedEventTarget = EventTarget as {
+	new <
+		PossibleEvents extends Readonly<Event>,
+	>(): TypedEventTargetOrig<PossibleEvents>
+	prototype: EventTarget
+}

package/src/lib/fetch-api.ts

@@ -0,0 +1,18 @@
+import type { ServerAdapterOptions } from '@whatwg-node/server'
+
+// @whatwg-node/server ponyfills the fetch API by default, which has bugs in the
+// ReadableStream implementation that was causing issues with stream error
+// propagation. To avoid these issues, we explicitly provide the native fetch
+// API implementation from Node.js.
+export const fetchAPI: ServerAdapterOptions<any>['fetchAPI'] = {
+	ReadableStream: globalThis.ReadableStream,
+	WritableStream: globalThis.WritableStream,
+	TransformStream: globalThis.TransformStream,
+	Response: globalThis.Response,
+	Request: globalThis.Request,
+	Headers: globalThis.Headers,
+	FormData: globalThis.FormData,
+	File: globalThis.File,
+	Blob: globalThis.Blob,
+	fetch: globalThis.fetch,
+}

package/src/lib/map-share.ts

@@ -0,0 +1,185 @@
+import { TypedEventTarget } from '../lib/event-target.js'
+import {
+	MapShareState,
+	type MapShareStateUpdate,
+	type DownloadStateUpdate,
+	type MapInfo,
+} from '../types.js'
+import { errors } from './errors.js'
+import { StateUpdateEvent } from './state-update-event.js'
+import { addTrailingSlash, generateId, getErrorCode } from './utils.js'
+
+export type MapShareOptions = MapInfo & {
+	/**
+	 * Base URLs to construct the download URLs for the map share. Multiple URLs
+	 * are supported because the server might have multiple network interfaces
+	 * with different IP addresses
+	 */
+	baseUrls: string[]
+	/** The device ID of the receiver */
+	receiverDeviceId: string
+}
+
+/**
+ * Maintains the state of a map share and handles downloading from the sharer side
+ */
+export class MapShare extends TypedEventTarget<
+	InstanceType<typeof StateUpdateEvent>
+> {
+	#state: MapShareState
+	#download: DownloadResponse | undefined
+	constructor({ baseUrls, receiverDeviceId, ...mapInfo }: MapShareOptions) {
+		super()
+		const shareId = generateId()
+		this.#state = {
+			...mapInfo,
+			shareId,
+			mapShareUrls: baseUrls.map(
+				(baseUrl) => new URL(`${shareId}`, addTrailingSlash(baseUrl)).href,
+			),
+			receiverDeviceId,
+			mapShareCreated: Date.now(),
+			status: 'pending',
+		}
+	}
+
+	get shareId() {
+		return this.#state.shareId
+	}
+
+	get state() {
+		return this.#state
+	}
+
+	/**
+	 * Create a download response for the map share
+	 */
+	downloadResponse(readable: ReadableStream): Response {
+		if (this.#state.status === 'canceled') {
+			throw new errors.DOWNLOAD_SHARE_CANCELED()
+		} else if (this.#state.status === 'declined') {
+			throw new errors.DOWNLOAD_SHARE_DECLINED()
+		} else if (this.#state.status !== 'pending') {
+			throw new errors.DOWNLOAD_SHARE_NOT_PENDING(
+				`Cannot download: share status is '${this.#state.status}'`,
+			)
+		}
+		this.#download?.removeAllEventListeners()
+		this.#download = new DownloadResponse(readable)
+		this.#download.addEventListener('update', (event) => {
+			this.#updateState(event)
+		})
+		return this.#download.response
+	}
+
+	/**
+	 * Decline the map share with a given reason
+	 */
+	decline(
+		reason: Extract<MapShareStateUpdate, { status: 'declined' }>['reason'],
+	) {
+		if (this.#state.status !== 'pending') {
+			throw new errors.DECLINE_SHARE_NOT_PENDING(
+				`Cannot decline: share status is '${this.#state.status}'`,
+			)
+		}
+		this.#updateState({ status: 'declined', reason })
+	}
+
+	/**
+	 * Cancel the map share
+	 */
+	cancel() {
+		if (
+			this.#state.status !== 'pending' &&
+			this.#state.status !== 'downloading'
+		) {
+			throw new errors.CANCEL_SHARE_NOT_CANCELABLE(
+				`Cannot cancel: share status is '${this.#state.status}'`,
+			)
+		}
+		this.#download?.cancel()
+		this.#updateState({ status: 'canceled' })
+	}
+
+	#updateState(update: MapShareStateUpdate) {
+		this.#state = { ...this.#state, ...update }
+		queueMicrotask(() => this.dispatchEvent(new StateUpdateEvent(update)))
+	}
+}
+
+/**
+ * Handles the download response of a map share and tracks its state.
+ *
+ * Currently we only support a single download per map share, but I'm keeping
+ * this as a separate class in case we want to support multiple downloads per
+ * share in the future (multiple downloads per share will make the "state" of a
+ * MapShare harder to reason about and define).
+ */
+export class DownloadResponse extends TypedEventTarget<
+	InstanceType<typeof StateUpdateEvent<DownloadStateUpdate>>
+> {
+	#stream: TransformStream
+	#bytesDownloaded = 0
+	#abortController = new AbortController()
+	#state: DownloadStateUpdate = { status: 'downloading', bytesDownloaded: 0 }
+	#response: Response
+
+	constructor(readable: ReadableStream<Uint8Array>) {
+		super()
+		this.#stream = new TransformStream({
+			start: () => {
+				this.#updateState({ status: 'downloading', bytesDownloaded: 0 })
+			},
+			transform: (chunk, controller) => {
+				this.#bytesDownloaded += chunk.length
+				this.#updateState({
+					status: 'downloading',
+					bytesDownloaded: this.#bytesDownloaded,
+				})
+				controller.enqueue(chunk)
+			},
+			flush: () => {
+				this.#updateState({ status: 'completed' })
+			},
+		})
+		readable
+			.pipeTo(this.#stream.writable, {
+				signal: this.#abortController.signal,
+				// preventAbort: true,
+				// preventCancel: true,
+			})
+			.catch((error) => {
+				if (error.name === 'AbortError') {
+					this.#updateState({ status: 'canceled' })
+				} else if (getErrorCode(error) === 'ECONNRESET') {
+					this.#updateState({ status: 'aborted' })
+				} else {
+					this.#updateState({ status: 'error', error })
+				}
+			})
+
+		this.#response = new Response(this.#stream.readable, {
+			headers: {
+				'Content-Type': 'application/vnd.smp+zip',
+			},
+		})
+	}
+
+	get response() {
+		return this.#response
+	}
+
+	get state() {
+		return this.#state
+	}
+
+	cancel() {
+		this.#abortController.abort()
+	}
+
+	#updateState(update: DownloadStateUpdate) {
+		this.#state = update
+		this.dispatchEvent(new StateUpdateEvent(update))
+	}
+}

package/src/lib/secret-stream-fetch.ts

@@ -0,0 +1,42 @@
+import { fetch as secretStreamFetchOrig } from 'secret-stream-http'
+
+import { errors } from './errors.js'
+
+/**
+ * A wrapper around secret-stream-http's fetch that tries multiple URLs until one works.
+ * This is useful when the server has multiple IPs for different network interfaces.
+ */
+export async function secretStreamFetch(
+	urls: string | URL | Array<string | URL>,
+	options: Parameters<typeof secretStreamFetchOrig>[1],
+) {
+	if (!Array.isArray(urls)) {
+		urls = [urls]
+	}
+	let response: Response | undefined
+	let error: unknown
+
+	// The server could have multiple IPs for different network interfaces, and
+	// not all of them may be on the same network as us, so try each URL until
+	// one works
+	for (const url of urls) {
+		try {
+			response = (await secretStreamFetchOrig(
+				url,
+				options,
+			)) as unknown as Response // Subtle difference bewteen Undici fetch Response and whatwg Response
+			break // Exit loop on successful fetch
+		} catch (err) {
+			error = err
+			// Ignore errors and try the next URL
+		}
+	}
+	if (!response) {
+		throw new errors.DOWNLOAD_ERROR({
+			message: 'Could not connect to map share sender',
+			urls,
+			cause: error,
+		})
+	}
+	return response
+}

package/src/lib/self-evicting-map.ts

@@ -0,0 +1,35 @@
+const DEFAULT_EVICTION_TIMEOUT_MS = 15 * 60 * 1000 // 15 minutes
+
+/**
+ * "Not a LRU": A Map that automatically evicts entries after a specified
+ * timeout. Used for MapShares which we don't want to keep indefinitely. NB: The
+ * use of the Typescript `object` type is intentional: this must be used with
+ * non-primitive values, otherwise behaviour would be unexpected because
+ * removing a value and re-adding it could result in it being evicted with the
+ * original timeout. This has limited applications, but works for our needs.
+ */
+export class SelfEvictingTimeoutMap<K, V extends object> extends Map<K, V> {
+	#evictionTimeoutMs: number
+	#timeouts = new Set<NodeJS.Timeout>()
+
+	constructor(
+		iterable?: ConstructorParameters<typeof Map<K, V>>[0],
+		{ evictionTimeoutMs = DEFAULT_EVICTION_TIMEOUT_MS } = {},
+	) {
+		super(iterable)
+		this.#evictionTimeoutMs = evictionTimeoutMs
+	}
+
+	override set(key: K, value: V): this {
+		super.set(key, value)
+		const timeout = setTimeout(() => {
+			this.#timeouts.delete(timeout)
+			if (this.get(key) === value) {
+				this.delete(key)
+			}
+		}, this.#evictionTimeoutMs)
+		timeout.unref()
+		this.#timeouts.add(timeout)
+		return this
+	}
+}

package/src/lib/state-update-event.ts

@@ -0,0 +1,14 @@
+import type { MapShareStateUpdate } from '../types.js'
+
+/**
+ * Event representing a state update in a map share
+ */
+export const StateUpdateEvent = class extends Event {
+	public static readonly type = 'update'
+	constructor(update: MapShareStateUpdate) {
+		super('update')
+		Object.assign(this, update)
+	}
+} as new <TUpdate extends MapShareStateUpdate>(
+	update: TUpdate,
+) => Event & { type: 'update' } & TUpdate

package/src/lib/utils.ts

@@ -0,0 +1,110 @@
+import crypto from 'node:crypto'
+
+import { randomBytes } from 'crypto'
+import type { SMPStyle } from 'styled-map-package'
+import z32 from 'z32'
+
+import type { BBox } from '../types.js'
+
+/**
+ * If the argument is an `Error` instance, return its `code` property if it is a string.
+ * Otherwise, returns `undefined`.
+ *
+ * @param {unknown} maybeError
+ * @returns {undefined | string}
+ * @example
+ * try {
+ *   // do something
+ * } catch (err) {
+ *   console.error(getErrorCode(err))
+ * }
+ */
+export function getErrorCode(maybeError: unknown) {
+	if (
+		maybeError instanceof Error &&
+		'code' in maybeError &&
+		typeof maybeError.code === 'string'
+	) {
+		return maybeError.code
+	}
+	return undefined
+}
+
+export function noop() {}
+
+export function generateId() {
+	return z32.encode(randomBytes(8))
+}
+
+export function getOrInsert<K, V>(map: Map<K, V>, key: K, value: V): V {
+	if (map.has(key)) {
+		return map.get(key)!
+	}
+	map.set(key, value)
+	return value
+}
+
+export function timingSafeEqual(a: string, b: string): boolean {
+	const aBuf = Buffer.from(a)
+	const bBuf = Buffer.from(b)
+	if (aBuf.length !== bBuf.length) {
+		return false
+	}
+	return crypto.timingSafeEqual(aBuf, bBuf)
+}
+
+/**
+ * Returns a bbox that is the smallest bounding box that contains all the input bboxes.
+ *
+ * @param bboxes
+ * @returns Bounding Box [w, s, e, n] of all input bboxes
+ */
+export function unionBBox(bboxes: [BBox, ...BBox[]]): BBox {
+	let [w, s, e, n] = bboxes[0]
+	for (let i = 1; i < bboxes.length; i++) {
+		const [w1, s1, e1, n1] = bboxes[i]
+		w = Math.min(w, w1)
+		s = Math.min(s, s1)
+		e = Math.max(e, e1)
+		n = Math.max(n, n1)
+	}
+	return [w, s, e, n]
+}
+
+export function getStyleBbox(style: SMPStyle): BBox {
+	const sourceBboxes: BBox[] = []
+	for (const source of Object.values(style.sources)) {
+		if (!('bounds' in source)) continue
+		sourceBboxes.push(source.bounds)
+	}
+	if (!isNonEmptyArray(sourceBboxes)) {
+		return [-180, -85.0511, 180, 85.0511]
+	}
+	return unionBBox(sourceBboxes)
+}
+
+export function getStyleMaxZoom(style: SMPStyle): number {
+	let maxzoom = -1
+	for (const source of Object.values(style.sources)) {
+		if (!('maxzoom' in source)) continue
+		maxzoom = Math.max(maxzoom, source.maxzoom ?? -1)
+	}
+	return maxzoom === -1 ? 22 : maxzoom
+}
+
+export function getStyleMinZoom(style: SMPStyle): number {
+	let minzoom = 99
+	for (const source of Object.values(style.sources)) {
+		if (!('minzoom' in source)) continue
+		minzoom = Math.min(minzoom, source.minzoom ?? 99)
+	}
+	return minzoom === 99 ? 0 : minzoom
+}
+
+function isNonEmptyArray<T>(arr: T[]): arr is [T, ...T[]] {
+	return arr.length > 0
+}
+
+export function addTrailingSlash(url: string): string {
+	return url.endsWith('/') ? url : url + '/'
+}

package/src/middlewares/localhost-only.ts

@@ -0,0 +1,16 @@
+import { type IRequestStrict, type RequestHandler } from 'itty-router'
+
+import { errors } from '../lib/errors.js'
+
+/**
+ * Middleware to restrict access to localhost only. The localhost listener must
+ * pass { isLocalhost: true } in the context.
+ */
+export const localhostOnly: RequestHandler<
+	IRequestStrict,
+	[{ isLocalhost: boolean }]
+> = async (_, { isLocalhost }) => {
+	if (!isLocalhost) {
+		throw new errors.FORBIDDEN()
+	}
+}