@comapeo/map-server 1.0.0-pre.0

package/src/context.ts

@@ -0,0 +1,203 @@
+import fs, { type Stats } from 'node:fs'
+import fsPromises from 'node:fs/promises'
+import path from 'node:path'
+import { Readable, Writable } from 'node:stream'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+import { Reader } from 'styled-map-package'
+import type { SetRequired } from 'type-fest'
+
+import type { ServerOptions } from './index.js'
+import { CUSTOM_MAP_ID, FALLBACK_MAP_ID } from './lib/constants.js'
+import { errors } from './lib/errors.js'
+import {
+	getErrorCode,
+	getStyleBbox,
+	getStyleMaxZoom,
+	getStyleMinZoom,
+	noop,
+} from './lib/utils.js'
+
+type ContextOptions = SetRequired<ServerOptions, 'keyPair'> & {
+	getRemotePort: () => Promise<number>
+}
+
+let tmpCounter = 0
+
+export class Context {
+	#defaultOnlineStyleUrl: URL
+	#mapFileUrls: Map<string, URL>
+	#mapReaders: Map<string, Promise<Reader>> = new Map()
+	#keyPair: { publicKey: Uint8Array; secretKey: Uint8Array }
+	getRemotePort: () => Promise<number>
+
+	constructor({
+		defaultOnlineStyleUrl,
+		customMapPath,
+		fallbackMapPath,
+		keyPair,
+		getRemotePort,
+	}: ContextOptions) {
+		this.#defaultOnlineStyleUrl = new URL(defaultOnlineStyleUrl)
+		this.#mapFileUrls = new Map([
+			[
+				CUSTOM_MAP_ID,
+				typeof customMapPath === 'string'
+					? pathToFileURL(customMapPath)
+					: customMapPath,
+			],
+			[
+				FALLBACK_MAP_ID,
+				typeof fallbackMapPath === 'string'
+					? pathToFileURL(fallbackMapPath)
+					: fallbackMapPath,
+			],
+		])
+		this.#keyPair = keyPair
+		this.getRemotePort = getRemotePort
+	}
+	getDefaultOnlineStyleUrl() {
+		return this.#defaultOnlineStyleUrl
+	}
+	getKeyPair() {
+		return this.#keyPair
+	}
+	async getMapInfo(mapId: string) {
+		const mapFileUrl = this.#mapFileUrls.get(mapId)
+		if (!mapFileUrl) {
+			throw new errors.MAP_NOT_FOUND(`Map not found: ${mapId}`)
+		}
+		let stats: Stats
+		try {
+			stats = await fsPromises.stat(mapFileUrl)
+		} catch (err) {
+			if (getErrorCode(err) === 'ENOENT') {
+				throw new errors.MAP_NOT_FOUND(`Map not found: ${mapId}`)
+			}
+			throw err
+		}
+		const reader = await this.getReader(mapId)
+		const style = await reader.getStyle()
+		const mapName = style.name || path.basename(fileURLToPath(mapFileUrl))
+		return {
+			mapId,
+			mapName,
+			bounds: getStyleBbox(style),
+			maxzoom: getStyleMaxZoom(style),
+			minzoom: getStyleMinZoom(style),
+			estimatedSizeBytes: stats.size,
+			mapCreated: stats.ctimeMs,
+		}
+	}
+	getReader(mapId: string) {
+		const readerPromise = this.#mapReaders.get(mapId)
+		if (readerPromise) {
+			return readerPromise
+		}
+		const mapFileUrl = this.#mapFileUrls.get(mapId)
+		if (!mapFileUrl) {
+			throw new errors.MAP_NOT_FOUND(`Map ID not found: ${mapId}`)
+		}
+		const reader = new Reader(fileURLToPath(mapFileUrl))
+		this.#mapReaders.set(mapId, Promise.resolve(reader))
+		return Promise.resolve(reader)
+	}
+	createMapReadableStream(mapId: string) {
+		const mapFileUrl = this.#mapFileUrls.get(mapId)
+		if (!mapFileUrl) {
+			throw new errors.MAP_NOT_FOUND(`Map ID not found: ${mapId}`)
+		}
+		return Readable.toWeb(
+			fs.createReadStream(mapFileUrl),
+		) as ReadableStream<Uint8Array> // small discrepancy in types
+	}
+	/**
+	 * Creates a writable stream to write map data to the specified map ID.
+	 * The data is first written to a temporary file, and once the stream is closed,
+	 * the temporary file replaces the existing map file. This ensures that the map
+	 * file is only updated when the write operation is fully complete.
+	 *
+	 * @param mapId - The ID of the map to write data to.
+	 * @returns A writable stream to write map data.
+	 */
+	createMapWritableStream(mapId: string) {
+		const mapFileUrl = this.#mapFileUrls.get(mapId)
+		if (!mapFileUrl) {
+			throw new errors.MAP_NOT_FOUND(`Map ID not found: ${mapId}`)
+		}
+		const tempPath = `${fileURLToPath(mapFileUrl)}.download-${tmpCounter++}`
+		const writable = Writable.toWeb(fs.createWriteStream(tempPath))
+		const writer = writable.getWriter()
+		return new WritableStream({
+			async write(chunk) {
+				await writer.write(chunk)
+			},
+			close: async () => {
+				// Finish writing to the temp file
+				await writer.close()
+
+				// Validate the uploaded map file BEFORE replacing the existing one
+				const tempReader = new Reader(tempPath)
+				try {
+					await tempReader.opened()
+				} catch {
+					// Clean up temp file on validation failure
+					await fsPromises.unlink(tempPath).catch(noop)
+					throw new errors.INVALID_MAP_FILE()
+				} finally {
+					await tempReader.close().catch(noop)
+				}
+
+				// Graceful replacement of SMP Reader when map file is updated
+				const readerPromise = (async () => {
+					const existingReaderPromise = this.#mapReaders.get(mapId)
+					if (existingReaderPromise) {
+						const existingReader = await existingReaderPromise
+						await existingReader.close().catch(noop)
+					}
+					await fsPromises.cp(tempPath, mapFileUrl, { force: true })
+					return new Reader(fileURLToPath(mapFileUrl))
+				})()
+				this.#mapReaders.set(mapId, readerPromise)
+				// Wait for the file copy to complete before closing the stream
+				await readerPromise
+			},
+			async abort(err) {
+				try {
+					await writer.abort(err)
+				} finally {
+					await fsPromises.unlink(tempPath).catch(noop)
+				}
+			},
+		})
+	}
+	/**
+	 * Deletes the map file for the specified map ID.
+	 * Closes any existing reader and removes it from the cache.
+	 *
+	 * @param mapId - The ID of the map to delete.
+	 */
+	async deleteMap(mapId: string) {
+		const mapFileUrl = this.#mapFileUrls.get(mapId)
+		if (!mapFileUrl) {
+			throw new errors.MAP_NOT_FOUND(`Map ID not found: ${mapId}`)
+		}
+		// Close and remove the reader if it exists
+		const existingReaderPromise = this.#mapReaders.get(mapId)
+		if (existingReaderPromise) {
+			const existingReader = await existingReaderPromise
+			await existingReader.close().catch(noop)
+			this.#mapReaders.delete(mapId)
+		}
+		// Delete the map file
+		const mapFilePath = fileURLToPath(mapFileUrl)
+		try {
+			await fsPromises.unlink(mapFilePath)
+		} catch (err) {
+			if (getErrorCode(err) === 'ENOENT') {
+				throw new errors.MAP_NOT_FOUND(`Map not found: ${mapId}`)
+			}
+			throw err
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,193 @@
+import assert from 'node:assert'
+import { once } from 'node:events'
+import http from 'node:http'
+import { type AddressInfo } from 'node:net'
+
+import { createServerAdapter } from '@whatwg-node/server'
+import pDefer from 'p-defer'
+import {
+	Agent,
+	createServer as createSecretStreamServer,
+} from 'secret-stream-http'
+import z32 from 'z32'
+
+import { Context } from './context.js'
+import { fetchAPI } from './lib/fetch-api.js'
+import { RootRouter } from './routes/root.js'
+import type { FetchContext } from './types.js'
+
+export type {
+	MapInfo,
+	MapShareState,
+	MapShareStateUpdate,
+	DownloadStateUpdate,
+} from './types.js'
+export type { DownloadState } from './lib/download-request.js'
+export type {
+	MapShareCreateParams,
+	MapShareDeclineParams,
+} from './routes/map-shares.js'
+export type { DownloadCreateParams } from './routes/downloads.js'
+
+export type ServerOptions = {
+	defaultOnlineStyleUrl: string | URL
+	customMapPath: string | URL
+	fallbackMapPath: string | URL
+	keyPair?: {
+		publicKey: Uint8Array
+		secretKey: Uint8Array
+	}
+}
+
+export type ListenOptions = {
+	localPort?: number
+	remotePort?: number
+}
+
+type ListenResult = {
+	localPort: number
+	remotePort: number
+}
+
+export function createServer(options: ServerOptions) {
+	validateOptions(options)
+	if (!options.keyPair) {
+		options.keyPair = Agent.keyPair()
+	}
+
+	const deferredListen = pDefer<ListenResult>()
+	const context = new Context({
+		...options,
+		keyPair: options.keyPair,
+		getRemotePort: async () => {
+			const listenOptions = await deferredListen.promise
+			return listenOptions.remotePort
+		},
+	})
+	const router = RootRouter({ base: '/' }, context)
+	// Use native fetch API to avoid ponyfill bugs with stream error propagation
+	const serverAdapter = createServerAdapter<FetchContext>(router.fetch, {
+		fetchAPI,
+	})
+	const localHttpServer = http.createServer((req, res) => {
+		serverAdapter(req, res, { isLocalhost: true })
+	})
+
+	const remoteHttpServer = http.createServer((req, res) => {
+		serverAdapter(req, res, {
+			isLocalhost: false,
+			// @ts-expect-error - the types for this are too hard and making them work would not add any type safety.
+			remoteDeviceId: z32.encode(req.socket.remotePublicKey),
+		})
+	})
+	const secretStreamServer = createSecretStreamServer(remoteHttpServer, {
+		keyPair: options.keyPair,
+	})
+
+	// Track connections for proper cleanup
+	const connections = new Set<any>()
+	const onConnection = (socket: any) => {
+		connections.add(socket)
+		socket.once('close', () => {
+			connections.delete(socket)
+		})
+	}
+	localHttpServer.on('connection', onConnection)
+	secretStreamServer.on('connection', onConnection)
+
+	return {
+		async listen(opts: ListenOptions = {}) {
+			localHttpServer.listen(opts.localPort, '127.0.0.1')
+			secretStreamServer.listen(opts.remotePort, '0.0.0.0')
+			await Promise.all([
+				once(localHttpServer, 'listening'),
+				once(secretStreamServer, 'listening'),
+			])
+			const localPort = (localHttpServer.address() as AddressInfo).port
+			const remotePort = (secretStreamServer.address() as AddressInfo).port
+			deferredListen.resolve({ localPort, remotePort })
+			return { localPort, remotePort }
+		},
+		async close() {
+			// Remove connection listeners
+			localHttpServer.off('connection', onConnection)
+			secretStreamServer.off('connection', onConnection)
+			localHttpServer.close()
+			secretStreamServer.close()
+			// Destroy all active connections to ensure clean shutdown
+			for (const socket of connections) {
+				socket.destroy()
+			}
+			connections.clear()
+			await Promise.all([
+				once(localHttpServer, 'close'),
+				once(secretStreamServer, 'close'),
+			])
+		},
+	}
+}
+
+function validateOptions(options: unknown): asserts options is ServerOptions {
+	assert(
+		typeof options === 'object' && options !== null,
+		new TypeError('options must be an object'),
+	)
+	assert(
+		'defaultOnlineStyleUrl' in options,
+		new TypeError('missing defaultOnlineStyleUrl'),
+	)
+	assert('customMapPath' in options, new TypeError('missing customMapPath'))
+	assert('fallbackMapPath' in options, new TypeError('missing fallbackMapPath'))
+
+	assert(
+		typeof options.defaultOnlineStyleUrl === 'string' ||
+			options.defaultOnlineStyleUrl instanceof URL,
+		new TypeError('defaultOnlineStyleUrl must be a string or URL'),
+	)
+	assert(
+		URL.canParse(options.defaultOnlineStyleUrl),
+		new TypeError('defaultOnlineStyleUrl must be a valid URL'),
+	)
+	assert(
+		(typeof options.customMapPath === 'string' && options.customMapPath) ||
+			options.customMapPath instanceof URL,
+		new TypeError('customMapPath must be a string or URL'),
+	)
+	assert(
+		(typeof options.fallbackMapPath === 'string' && options.fallbackMapPath) ||
+			options.fallbackMapPath instanceof URL,
+		new TypeError('fallbackMapPath must be a string or URL'),
+	)
+	const parsedOptions: ServerOptions = {
+		defaultOnlineStyleUrl: options.defaultOnlineStyleUrl,
+		customMapPath: options.customMapPath,
+		fallbackMapPath: options.fallbackMapPath,
+	}
+
+	if ('keyPair' in options && options.keyPair !== undefined) {
+		assert(
+			typeof options.keyPair === 'object' && options.keyPair !== null,
+			new TypeError('keyPair must be an object'),
+		)
+		assert(
+			'publicKey' in options.keyPair,
+			new TypeError('keyPair must have a publicKey'),
+		)
+		assert(
+			options.keyPair.publicKey instanceof Uint8Array,
+			new TypeError('keyPair.publicKey must be a Uint8Array'),
+		)
+		assert(
+			'secretKey' in options.keyPair,
+			new TypeError('keyPair must have a secretKey'),
+		)
+		assert(
+			options.keyPair.secretKey instanceof Uint8Array,
+			new TypeError('keyPair.secretKey must be a Uint8Array'),
+		)
+		parsedOptions.keyPair = {
+			publicKey: options.keyPair.publicKey,
+			secretKey: options.keyPair.secretKey,
+		}
+	}
+}

package/src/lib/constants.ts

@@ -0,0 +1,6 @@
+/** Hard-coded mapId for the custom (offline) background map */
+export const CUSTOM_MAP_ID = 'custom'
+/** Hard-coded mapId for the fallback (offline) background map */
+export const FALLBACK_MAP_ID = 'fallback'
+/** Hard-coded mapId for the default (online) background map */
+export const DEFAULT_MAP_ID = 'default'

package/src/lib/download-request.ts

@@ -0,0 +1,142 @@
+import { Agent as SecretStreamAgent } from 'secret-stream-http'
+import z32 from 'z32'
+
+import { TypedEventTarget } from '../lib/event-target.js'
+import type { DownloadCreateParams } from '../routes/downloads.js'
+import { type DownloadStateUpdate } from '../types.js'
+import { StatusError } from './errors.js'
+import { errors, jsonError } from './errors.js'
+import { secretStreamFetch } from './secret-stream-fetch.js'
+import { StateUpdateEvent } from './state-update-event.js'
+import { addTrailingSlash, generateId, getErrorCode, noop } from './utils.js'
+
+export type DownloadState = DownloadStateUpdate &
+	Omit<DownloadCreateParams, 'mapShareUrls'> & { downloadId: string }
+
+export class DownloadRequest extends TypedEventTarget<
+	InstanceType<typeof StateUpdateEvent<DownloadStateUpdate>>
+> {
+	#state: DownloadState
+	#abortController = new AbortController()
+	#transform = new TransformStream({
+		transform: (chunk, controller) => {
+			if (this.#state.status !== 'downloading') {
+				throw new Error('Download has been cancelled or encountered an error')
+			}
+			this.#updateState({
+				status: 'downloading',
+				bytesDownloaded: this.#state.bytesDownloaded + chunk.byteLength,
+			})
+			controller.enqueue(chunk)
+		},
+	})
+	#dispatcher: SecretStreamAgent
+
+	constructor(
+		stream: WritableStream<Uint8Array>,
+		{ mapShareUrls, ...rest }: DownloadCreateParams,
+		keyPair: { publicKey: Uint8Array; secretKey: Uint8Array },
+	) {
+		super()
+		this.#state = {
+			...rest,
+			status: 'downloading',
+			bytesDownloaded: 0,
+			downloadId: generateId(),
+		}
+		let remotePublicKey: Uint8Array
+		try {
+			remotePublicKey = z32.decode(this.#state.senderDeviceId)
+		} catch {
+			throw new errors.INVALID_SENDER_DEVICE_ID(
+				`Invalid sender device ID: ${this.#state.senderDeviceId}`,
+			)
+		}
+		if (remotePublicKey.length !== 32) {
+			throw new errors.INVALID_SENDER_DEVICE_ID(
+				`Invalid sender device ID: ${this.#state.senderDeviceId}`,
+			)
+		}
+		this.#dispatcher = new SecretStreamAgent({ remotePublicKey, keyPair })
+		this.#start({ mapShareUrls, stream, remotePublicKey, keyPair }).catch(
+			async (error) => {
+				// In case the error happens before we pipe to the stream, we need to abort the stream
+				await stream.abort().catch(noop)
+				if (error.name === 'AbortError') {
+					this.#updateState({ status: 'aborted' })
+				} else if (getErrorCode(error) === 'DOWNLOAD_SHARE_CANCELED') {
+					this.#updateState({ status: 'canceled' })
+				} else if (getErrorCode(error)) {
+					// Specific known error from the server
+					this.#updateState({ status: 'error', error })
+				} else {
+					// Once the download has started, the sender can only close the
+					// connection to cancel the download, which we only see as an
+					// ECONNRESET error here, which could happen for multiple reasons.
+					// Rather than immediately updating the state to error, we first check
+					// with the sender to see if we can access the status of the share,
+					// namely whether it was canceled, or if a different error occurred on
+					// the server side.
+					try {
+						const response = await secretStreamFetch(mapShareUrls, {
+							dispatcher: this.#dispatcher,
+							signal: AbortSignal.timeout(2000),
+						})
+						const json = await response.json()
+						if (json.status) {
+							this.#updateState({ status: json.status, error: json.error })
+							return
+						}
+					} catch {
+						// Ignore errors from checking the status and update state with original error
+					}
+					this.#updateState({ status: 'error', error: jsonError(error) })
+				}
+			},
+		)
+	}
+
+	async #start({
+		mapShareUrls,
+		stream,
+	}: {
+		mapShareUrls: string[]
+		stream: WritableStream<Uint8Array>
+		remotePublicKey: Uint8Array
+		keyPair: { publicKey: Uint8Array; secretKey: Uint8Array }
+	}) {
+		const downloadUrls = mapShareUrls.map(
+			(baseUrl) => new URL('download', addTrailingSlash(baseUrl)),
+		)
+		const response = await secretStreamFetch(downloadUrls, {
+			dispatcher: this.#dispatcher,
+		})
+		if (!response.body) {
+			throw new errors.DOWNLOAD_ERROR('Could not connect to map share sender')
+		}
+		if (!response.ok) {
+			throw new StatusError(response.status, await response.json())
+		}
+		if (this.#abortController.signal.aborted) {
+			response.body.cancel().catch(noop)
+			throw new DOMException('Download aborted', 'AbortError')
+		}
+		await response.body.pipeThrough(this.#transform).pipeTo(stream, {
+			signal: this.#abortController.signal,
+		})
+		this.#updateState({ status: 'completed' })
+	}
+
+	get state() {
+		return this.#state
+	}
+
+	cancel() {
+		this.#abortController.abort()
+	}
+
+	#updateState(update: DownloadStateUpdate) {
+		this.#state = { ...this.#state, ...update }
+		this.dispatchEvent(new StateUpdateEvent(update))
+	}
+}