add private bucket pmtiles map served by bun

.dockerignore

@@ -0,0 +1,5 @@
+.git
+node_modules
+data
+.env*
+proofs

Dockerfile

@@ -0,0 +1,15 @@
+FROM oven/bun:1.2.14 AS build
+WORKDIR /app
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile
+COPY src ./src
+COPY public ./public
+RUN bun run build
+
+FROM oven/bun:1.2.14
+WORKDIR /app
+COPY --from=build --chown=bun:bun /app /app
+USER bun
+ENV PORT=7860
+EXPOSE 7860
+CMD ["bun", "src/server.ts"]

README.md

@@ -1,10 +1,68 @@
 ---
 title: Bucket Atlas
-emoji: 🦀
-colorFrom: pink
-colorTo: pink
+emoji: 🗺️
+colorFrom: green
+colorTo: yellow
 sdk: docker
+app_port: 7860
 pinned: false
+license: mit
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Bucket Atlas
+
+Explore Florence with MapLibre and PMTiles, served from a private Hugging Face bucket through Bun's S3 client. Pan around the city, visit landmarks, change map layers, inspect buildings, and see how many archive bytes the browser reads.
+
+## Storage configuration
+
+The initial Space and bucket are private. Set these **Space secrets**:
+
+- `HF_S3_ACCESS_KEY_ID`
+- `HF_S3_SECRET_ACCESS_KEY`
+
+Use a credential with read access to `cfahlgren1/bucket-atlas`. S3 requires both values. An access-key ID by itself is insufficient. No HF token or S3 secret is sent to the browser.
+
+Optional Space variables default to:
+
+```text
+HF_S3_NAMESPACE=cfahlgren1
+HF_S3_BUCKET=bucket-atlas
+PMTILES_KEY=maps/florence.pmtiles
+```
+
+The app serves only the configured archive through `/maps/florence.pmtiles`. The Bun server signs an S3 request, verifies the upstream returns the requested range, and streams the bytes to the browser. A single request is limited to 8 MiB. Requests for full archives and multiple ranges are rejected. Responses use private, no-store caching. The browser still caches PMTiles directory and tile data in memory.
+
+Viewer access is provided by the private Space. Making the Space public makes the selected map readable through the app, even though the bucket itself remains private.
+
+## Local development
+
+```sh
+bun install --frozen-lockfile
+bun run build
+# Use the S3 secrets from your environment:
+bun start
+```
+
+For explicit local development, download the sample and set `LOCAL_PMTILES`:
+
+```sh
+mkdir -p data
+curl -fL 'https://pmtiles.io/protomaps(vector)ODbL_firenze.pmtiles' -o data/florence.pmtiles
+LOCAL_PMTILES=data/florence.pmtiles bun start
+bun test
+bun run check
+```
+
+The local archive is not included in the Docker image. There is no automatic local fallback in the deployed Space. Without valid S3 credentials, the UI reports that storage needs setup.
+
+## Map data and credits
+
+The [Protomaps Florence sample](https://github.com/protomaps/PMTiles/blob/main/js/examples/maplibre.html) contains a regional OpenStreetMap basemap snapshot from August 2024. It is 6,601,156 bytes, with native zoom levels through 15. Higher display zooms reuse those tiles. It covers central Florence, not all of Tuscany. Building heights use the source value when present and a 7 m visual default otherwise.
+
+Map data © OpenStreetMap contributors, distributed under ODbL. [OpenStreetMap copyright and license](https://www.openstreetmap.org/copyright). Tiles distributed by Protomaps. Fonts are loaded from Google Fonts and the Protomaps font assets host. The byte counter measures PMTiles response payloads only, not scripts, fonts, HTTP overhead, or total network traffic.
+
+## Verification
+
+`bun test` uses the real sample file and a real HTTP server. It verifies byte equality and headers, HEAD, invalid and multiple ranges, fixed-path access, PMTiles metadata parsing, and actual tile decoding. These tests use the local development backend; they do not prove live S3 credentials or HF gateway behavior.
+
+The browser UI was also exercised locally, including navigation, popups and layer controls. The S3 deployment requires a final authenticated range/read and browser check once the Space secret is available.

bun.lock

@@ -0,0 +1,93 @@
+{
+  "lockfileVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "bucket-atlas",
+      "dependencies": {
+        "maplibre-gl": "5.13.0",
+        "pmtiles": "4.5.0",
+      },
+      "devDependencies": {
+        "@types/bun": "1.2.14",
+        "typescript": "5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@mapbox/geojson-rewind": ["@mapbox/geojson-rewind@0.5.2", "", { "dependencies": { "get-stream": "^6.0.1", "minimist": "^1.2.6" }, "bin": { "geojson-rewind": "geojson-rewind" } }, "sha512-tJaT+RbYGJYStt7wI3cq4Nl4SXxG8W7JDG5DMJu97V25RnbNg3QtQtf+KD+VLjNpWKYsRvXDNmNrBgEETr1ifA=="],
+
+    "@mapbox/jsonlint-lines-primitives": ["@mapbox/jsonlint-lines-primitives@2.0.3", "", {}, "sha512-0SElaV0uMxEnxzBhhX9WTuPyUeMsAN/SS0i16tjuba4/mio63MG9khjC1a0JAiPGXAwvwm4UfHJURCN7nyudQg=="],
+
+    "@mapbox/point-geometry": ["@mapbox/point-geometry@1.1.0", "", {}, "sha512-YGcBz1cg4ATXDCM/71L9xveh4dynfGmcLDqufR+nQQy3fKwsAZsWd/x4621/6uJaeB9mwOHE6hPeDgXz9uViUQ=="],
+
+    "@mapbox/tiny-sdf": ["@mapbox/tiny-sdf@2.2.0", "", {}, "sha512-LVL4wgI9YAum5V+LNVQO6QgFBPw7/MIIY4XJPNsPDMrjEwcE+JfKk1LuIl8GnF197ejVdC9QdPaxrx5gfgdGXg=="],
+
+    "@mapbox/unitbezier": ["@mapbox/unitbezier@0.0.1", "", {}, "sha512-nMkuDXFv60aBr9soUG5q+GvZYL+2KZHVvsqFCzqnkGEf46U2fvmytHaEVc1/YZbiLn8X+eR3QzX1+dwDO1lxlw=="],
+
+    "@mapbox/vector-tile": ["@mapbox/vector-tile@2.0.5", "", { "dependencies": { "@mapbox/point-geometry": "~1.1.0", "@types/geojson": "^7946.0.16", "pbf": "^4.0.2" } }, "sha512-pXj8m7KTsqZt+1jsE0xIpGvqTSbblfkuEJL/NJmNePMtEwxO8V3XMDo9WMSfDeqHvCtBI9Lmt4mGcGR10zecmw=="],
+
+    "@mapbox/whoots-js": ["@mapbox/whoots-js@3.1.0", "", {}, "sha512-Es6WcD0nO5l+2BOQS4uLfNPYQaNDfbot3X1XUoloz+x0mPDS3eeORZJl06HXjwBG1fOGwCRnzK88LMdxKRrd6Q=="],
+
+    "@maplibre/maplibre-gl-style-spec": ["@maplibre/maplibre-gl-style-spec@24.10.0", "", { "dependencies": { "@mapbox/jsonlint-lines-primitives": "~2.0.2", "@mapbox/unitbezier": "^1.0.0", "json-stringify-pretty-compact": "^4.0.0", "minimist": "^1.2.8", "quickselect": "^3.0.0", "tinyqueue": "^3.0.0" }, "bin": { "gl-style-format": "dist/gl-style-format.mjs", "gl-style-migrate": "dist/gl-style-migrate.mjs", "gl-style-validate": "dist/gl-style-validate.mjs" } }, "sha512-lichxSiagMEBBrqHF0trtMQH9RKh+9jUlIJl0qW0QHvt2H/tbvUWdE+ZzI2Jd0/pT7j/iavLonlPu7EQ/ixTOw=="],
+
+    "@maplibre/mlt": ["@maplibre/mlt@1.2.1", "", { "dependencies": { "@mapbox/point-geometry": "^1.1.0" } }, "sha512-5n5dgolE2EYxwCKgx8vlwURCB8A+kyfJJyThlYimjlGgOcOe2Bhw9VxxnnHC91OC9PgHg+nVdgVPTYPkIo62vg=="],
+
+    "@maplibre/vt-pbf": ["@maplibre/vt-pbf@4.3.2", "", { "dependencies": { "@mapbox/point-geometry": "^1.1.0", "@types/geojson": "^7946.0.16", "pbf": "^5.1.0" } }, "sha512-j6p0AdjvAR19Z3XaCysle7A4ZSo08tYOzxD0Y9NQylwPAkwJJeYub5b2eVucdeDh7erhv69DahoLOevDRERRUw=="],
+
+    "@types/bun": ["@types/bun@1.2.14", "", { "dependencies": { "bun-types": "1.2.14" } }, "sha512-VsFZKs8oKHzI7zwvECiAJ5oSorWndIWEVhfbYqZd4HI/45kzW7PN2Rr5biAzvGvRuNmYLSANY+H59ubHq8xw7Q=="],
+
+    "@types/geojson": ["@types/geojson@7946.0.16", "", {}, "sha512-6C8nqWur3j98U6+lXDfTUWIfgvZU+EumvpHKcYjujKH7woYyLj2sUmff0tRhrqM7BohUw7Pz3ZB1jj2gW9Fvmg=="],
+
+    "@types/geojson-vt": ["@types/geojson-vt@3.2.5", "", { "dependencies": { "@types/geojson": "*" } }, "sha512-qDO7wqtprzlpe8FfQ//ClPV9xiuoh2nkIgiouIptON9w5jvD/fA4szvP9GBlDVdJ5dldAl0kX/sy3URbWwLx0g=="],
+
+    "@types/node": ["@types/node@26.5.0", "", { "dependencies": { "undici-types": "~8.9.0" } }, "sha512-dVSGpriSoCgz8WnDNTuSSuSv1PC/ALXihO4ulRZt7Md8k9mlbdin3lGOcDE8SnWOgf513ByWlXd7BK4azmyg/A=="],
+
+    "@types/supercluster": ["@types/supercluster@7.1.3", "", { "dependencies": { "@types/geojson": "*" } }, "sha512-Z0pOY34GDFl3Q6hUFYf3HkTwKEE02e7QgtJppBt+beEAxnyOpJua+voGFvxINBHa06GwLFFym7gRPY2SiKIfIA=="],
+
+    "bun-types": ["bun-types@1.2.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-Kuh4Ub28ucMRWeiUUWMHsT9Wcbr4H3kLIO72RZZElSDxSu7vpetRvxIUDUaW6QtaIeixIpm7OXtNnZPf82EzwA=="],
+
+    "earcut": ["earcut@3.2.3", "", {}, "sha512-vnS4AVwp1KHAF13i1vp1/2D5evWy3k5u/iW/B81QVsUZtV8cv2tU0b2VNFlqvh4kYwrFMDdjPCfAmfyJW9y14Q=="],
+
+    "fflate": ["fflate@0.8.3", "", {}, "sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA=="],
+
+    "geojson-vt": ["geojson-vt@4.0.3", "", {}, "sha512-jR1MwkLaZGa8Zftct9ZFruyWFrdl9ZyD2OliXNy9Qq5bBPeg5wHVpBQF9p5GjnicSDQqvBVpysxTPKmWdsfWMA=="],
+
+    "get-stream": ["get-stream@6.0.1", "", {}, "sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg=="],
+
+    "gl-matrix": ["gl-matrix@3.4.4", "", {}, "sha512-latSnyDNt/8zYUB6VIJ6PCh2jBjJX6gnDsoCZ7LyW7GkqrD51EWwa9qCoGixj8YqBtETQK/xY7OmpTF8xz1DdQ=="],
+
+    "json-stringify-pretty-compact": ["json-stringify-pretty-compact@4.0.0", "", {}, "sha512-3CNZ2DnrpByG9Nqj6Xo8vqbjT4F6N+tb4Gb28ESAZjYZ5yqvmc56J+/kuIwkaAMOyblTQhUW7PxMkUb8Q36N3Q=="],
+
+    "kdbush": ["kdbush@4.1.0", "", {}, "sha512-e9vurzrXJQrFX6ckpHP3bvj5l+9CnYzkxDNnNQ1h2QTqdWsUAJgXiKdGNcOa1EY85dU8KbQ+z/FdQdB7P+9yfQ=="],
+
+    "maplibre-gl": ["maplibre-gl@5.13.0", "", { "dependencies": { "@mapbox/geojson-rewind": "^0.5.2", "@mapbox/jsonlint-lines-primitives": "^2.0.2", "@mapbox/point-geometry": "^1.1.0", "@mapbox/tiny-sdf": "^2.0.7", "@mapbox/unitbezier": "^0.0.1", "@mapbox/vector-tile": "^2.0.4", "@mapbox/whoots-js": "^3.1.0", "@maplibre/maplibre-gl-style-spec": "^24.3.1", "@maplibre/mlt": "^1.1.0", "@maplibre/vt-pbf": "^4.0.3", "@types/geojson": "^7946.0.16", "@types/geojson-vt": "3.2.5", "@types/supercluster": "^7.1.3", "earcut": "^3.0.2", "geojson-vt": "^4.0.2", "gl-matrix": "^3.4.4", "kdbush": "^4.0.2", "murmurhash-js": "^1.0.0", "pbf": "^4.0.1", "potpack": "^2.1.0", "quickselect": "^3.0.0", "supercluster": "^8.0.1", "tinyqueue": "^3.0.0" } }, "sha512-UsIVP34rZdM4TjrjhwBAhbC3HT7AzFx9p/draiAPlLr8/THozZF6WmJnZ9ck4q94uO55z7P7zoGCh+AZVoagsQ=="],
+
+    "minimist": ["minimist@1.2.8", "", {}, "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA=="],
+
+    "murmurhash-js": ["murmurhash-js@1.0.0", "", {}, "sha512-TvmkNhkv8yct0SVBSy+o8wYzXjE4Zz3PCesbfs8HiCXXdcTuocApFv11UWlNFWKYsP2okqrhb7JNlSm9InBhIw=="],
+
+    "pbf": ["pbf@4.0.2", "", { "dependencies": { "resolve-protobuf-schema": "^2.1.0" }, "bin": { "pbf": "bin/pbf" } }, "sha512-J0ajxARhZfpUEebxYs1vhMGMuLSXtBe1e+fFPDrf2uA2hgo+UshKfNUWOz92HJNz6/NFEXseQPddnHkTreWRqg=="],
+
+    "pmtiles": ["pmtiles@4.5.0", "", { "dependencies": { "fflate": "^0.8.2" } }, "sha512-CBeD4SoUluFziGdy/8k7FOjQxQy486n+929W/tWophauvMICpkZ26vGBWhDt/6b1FZQWNaf4jFdT/5+q0Wii5w=="],
+
+    "potpack": ["potpack@2.1.0", "", {}, "sha512-pcaShQc1Shq0y+E7GqJqvZj8DTthWV1KeHGdi0Z6IAin2Oi3JnLCOfwnCo84qc+HAp52wT9nK9H7FAJp5a44GQ=="],
+
+    "protocol-buffers-schema": ["protocol-buffers-schema@3.6.1", "", {}, "sha512-VG2K63Igkiv9p76tk1lilczEK1cT+kCjKtkdhw1dQZV3k3IXJbd3o6Ho8b9zJZaHSnT2hKe4I+ObmX9w6m5SmQ=="],
+
+    "quickselect": ["quickselect@3.0.0", "", {}, "sha512-XdjUArbK4Bm5fLLvlm5KpTFOiOThgfWWI4axAZDWg4E/0mKdZyI9tNEfds27qCi1ze/vwTR16kvmmGhRra3c2g=="],
+
+    "resolve-protobuf-schema": ["resolve-protobuf-schema@2.1.0", "", { "dependencies": { "protocol-buffers-schema": "^3.3.1" } }, "sha512-kI5ffTiZWmJaS/huM8wZfEMer1eRd7oJQhDuxeCLe3t7N7mX3z94CN0xPxBQxFYQTSNz9T0i+v6inKqSdK8xrQ=="],
+
+    "supercluster": ["supercluster@8.0.1", "", { "dependencies": { "kdbush": "^4.0.2" } }, "sha512-IiOea5kJ9iqzD2t7QJq/cREyLHTtSmUT6gQsweojg9WH2sYJqZK9SswTu6jrscO6D1G5v5vYZ9ru/eq85lXeZQ=="],
+
+    "tinyqueue": ["tinyqueue@3.0.0", "", {}, "sha512-gRa9gwYU3ECmQYv3lslts5hxuIa90veaEcxDYuu3QGOIAEM2mOZkVHp48ANJuu1CURtRdHKUBY5Lm1tHV+sD4g=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@8.9.0", "", {}, "sha512-KTDyRTYX8sWmKXAikPHHSyc63CRPETMctyjKFupcC6OBLXT3xsN0e9aF7m+mIXutFWpUXuedtowG7iLOzp0kQg=="],
+
+    "@maplibre/maplibre-gl-style-spec/@mapbox/unitbezier": ["@mapbox/unitbezier@1.0.0", "", {}, "sha512-fqd515fjBmANKGGsQ286E2Wvj/XvDFpGzwJxq4CI6jMQue6Oy04uCKp+JWKF00xRTmk6cEu1jPJ9p3xqH8YWqQ=="],
+
+    "@maplibre/vt-pbf/pbf": ["pbf@5.1.2", "", { "dependencies": { "resolve-protobuf-schema": "^2.1.0" }, "bin": { "pbf": "bin/pbf" } }, "sha512-mnvGdvOrIvJOBGUEdGkrVXjN8E/VkIJCkf2eS1DH2yv82ORUlLttmDt0rWY38yYZmVwciZwBUvHM20qxBZf40w=="],
+  }
+}

env.example

@@ -0,0 +1,6 @@
+HF_S3_NAMESPACE=cfahlgren1
+HF_S3_BUCKET=bucket-atlas
+PMTILES_KEY=maps/florence.pmtiles
+HF_S3_ACCESS_KEY_ID=
+HF_S3_SECRET_ACCESS_KEY=
+PORT=7860

package.json

@@ -0,0 +1,19 @@
+{
+  "name": "bucket-atlas",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "bun build src/client.ts --outdir public/assets --target browser --minify",
+    "start": "bun src/server.ts",
+    "test": "bun test",
+    "check": "tsc --noEmit"
+  },
+  "dependencies": {
+    "maplibre-gl": "5.13.0",
+    "pmtiles": "4.5.0"
+  },
+  "devDependencies": {
+    "@types/bun": "1.2.14",
+    "typescript": "5.9.3"
+  }
+}

public/index.html

@@ -0,0 +1,89 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <title>Bucket Atlas · Florence</title>
+    <link rel="stylesheet" href="/assets/client.css" />
+    <link rel="stylesheet" href="/styles.css" />
+  </head>
+  <body>
+    <div id="map" aria-label="Interactive map of Florence"></div>
+    <header>
+      <a class="brand" href="/" aria-label="Bucket Atlas home"
+        ><span class="brand-icon">◈</span> bucket<span>atlas</span></a
+      >
+      <div class="header-right">
+        <span class="pill"><i></i> PRIVATE BUCKET</span
+        ><a
+          href="https://huggingface.co/docs/hub/storage-buckets"
+          target="_blank"
+          rel="noreferrer"
+          >Built on Hugging Face ↗</a
+        >
+      </div>
+    </header>
+    <main class="panel">
+      <div class="eyebrow">THE WORLD, ONE FILE AT A TIME</div>
+      <h1>Find your<br /><em>Florence.</em></h1>
+      <p class="intro">
+        Follow the Arno. Wander the old streets.<br />A little corner of
+        Tuscany, ready to explore.
+      </p>
+      <div class="location">
+        <span>◎</span>
+        <div>
+          <strong>Florence</strong
+          ><small>Tuscany, Italy · 43.77° N, 11.25° E</small>
+        </div>
+        <span class="country">IT</span>
+      </div>
+      <div class="section-label">PLACES TO EXPLORE</div>
+      <div class="places">
+        <button data-place="duomo">
+          <span>01</span>
+          <div>Under the dome<small>Piazza del Duomo</small></div>
+          <b>↗</b></button
+        ><button data-place="bridge">
+          <span>02</span>
+          <div>Across the Arno<small>Ponte Vecchio</small></div>
+          <b>↗</b></button
+        ><button data-place="garden">
+          <span>03</span>
+          <div>A greener perspective<small>Boboli Gardens</small></div>
+          <b>↗</b>
+        </button>
+      </div>
+      <div class="section-label">MAKE IT YOUR MAP</div>
+      <div class="toggles">
+        <label><input type="checkbox" id="buildings" checked /> Buildings</label
+        ><label><input type="checkbox" id="parks" checked /> Green spaces</label
+        ><label
+          ><input type="checkbox" id="labels" checked /> Street names</label
+        >
+      </div>
+      <button class="reset" id="reset">↺ &nbsp; Back to the city</button>
+      <div id="status" role="status">Connecting to the map…</div>
+    </main>
+    <div class="map-tools">
+      <button id="tilt" aria-label="Toggle tilted map">3D</button
+      ><button id="theme" aria-label="Toggle dark map">◐</button>
+    </div>
+    <div class="legend">
+      <span><i class="water"></i>Water</span
+      ><span><i class="park"></i>Green space</span
+      ><span><i class="building"></i>Buildings</span><span>OSM · Aug 2024</span>
+    </div>
+    <aside class="transfer">
+      <div class="transfer-icon">⇣</div>
+      <div><strong id="bytes">0 KB</strong><span>read this session</span></div>
+      <div class="divider"></div>
+      <div><strong id="requests">0</strong><span>range requests</span></div>
+      <div class="file-note">
+        <strong>ONE PMTILES FILE</strong
+        ><span id="archive">Loading archive details…</span>
+      </div>
+    </aside>
+    <script type="module" src="/assets/client.js"></script>
+  </body>
+</html>

public/styles.css

@@ -0,0 +1,506 @@
+@import url("https://fonts.googleapis.com/css2?family=DM+Sans:wght@400;500;600;700&family=Playfair+Display:ital,wght@1,500&display=swap");
+:root {
+  font-family: "DM Sans", sans-serif;
+  color: #263d36;
+  background: #e7ece2;
+  font-synthesis: none;
+}
+* {
+  box-sizing: border-box;
+}
+body {
+  margin: 0;
+}
+button,
+a,
+input {
+  -webkit-tap-highlight-color: transparent;
+}
+button {
+  font: inherit;
+  cursor: pointer;
+}
+a {
+  color: inherit;
+  text-decoration: none;
+}
+button:focus-visible,
+a:focus-visible,
+input:focus-visible {
+  outline: 3px solid #e0a642;
+  outline-offset: 3px;
+}
+#map {
+  position: fixed;
+  inset: 0;
+}
+header {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 82px;
+  background: #fffffff2;
+  border-bottom: 1px solid #263d3613;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0 36px;
+  z-index: 3;
+}
+.brand {
+  font-size: 25px;
+  letter-spacing: -1.3px;
+  font-weight: 700;
+  display: flex;
+  align-items: center;
+}
+.brand > span:last-child {
+  font-weight: 400;
+}
+.brand-icon {
+  width: 38px;
+  height: 38px;
+  display: grid;
+  place-items: center;
+  background: #274c40;
+  color: #f9f3df;
+  border-radius: 11px;
+  margin-right: 11px;
+  font-size: 30px;
+}
+.header-right {
+  display: flex;
+  align-items: center;
+  gap: 24px;
+  font-size: 12px;
+}
+.pill {
+  font-size: 10px;
+  letter-spacing: 1px;
+  border: 1px solid #dde6df;
+  border-radius: 20px;
+  padding: 9px 13px;
+  display: flex;
+  align-items: center;
+  gap: 7px;
+}
+.pill i {
+  background: #5c9678;
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+}
+.panel {
+  position: fixed;
+  left: 26px;
+  top: 108px;
+  width: 340px;
+  padding: 29px;
+  background: #fffcf6f5;
+  backdrop-filter: blur(12px);
+  border: 1px solid #ffffff;
+  border-radius: 18px;
+  box-shadow: 0 12px 50px #203c3020;
+  z-index: 2;
+}
+.eyebrow {
+  font-size: 9px;
+  letter-spacing: 1.8px;
+  font-weight: 700;
+  color: #718478;
+}
+h1 {
+  font-size: 49px;
+  line-height: 1.06;
+  letter-spacing: -2.2px;
+  font-weight: 500;
+  margin: 22px 0 16px;
+}
+h1 em {
+  font-family: "Playfair Display", Georgia, serif;
+  font-weight: 500;
+  color: #45745a;
+}
+.intro {
+  font-size: 12px;
+  line-height: 1.8;
+  color: #7a847b;
+  margin: 0 0 22px;
+}
+.location {
+  border-top: 1px solid #e1e6dc;
+  border-bottom: 1px solid #e1e6dc;
+  padding: 17px 0;
+  display: flex;
+  gap: 12px;
+  align-items: center;
+}
+.location > span:first-child {
+  font-size: 26px;
+  color: #7c987e;
+}
+.location strong {
+  font-size: 13px;
+}
+.location small {
+  display: block;
+  font-size: 9px;
+  margin-top: 5px;
+  color: #8a9187;
+}
+.country {
+  margin-left: auto;
+  font-size: 10px;
+  background: #eceee4;
+  padding: 6px;
+  border-radius: 5px;
+}
+.section-label {
+  font-size: 9px;
+  font-weight: 700;
+  letter-spacing: 1.5px;
+  color: #83917f;
+  margin: 24px 0 12px;
+}
+.places {
+  display: grid;
+  gap: 4px;
+}
+.places button {
+  display: flex;
+  align-items: center;
+  text-align: left;
+  border: 0;
+  background: transparent;
+  padding: 11px 5px;
+  border-radius: 8px;
+  color: inherit;
+}
+.places button:hover,
+.places button.active {
+  background: #edf0e5;
+}
+.places button > span {
+  font-size: 10px;
+  color: #94a18d;
+  margin-right: 17px;
+}
+.places button div {
+  font-size: 12px;
+  font-weight: 500;
+}
+.places small {
+  display: block;
+  font-size: 10px;
+  font-weight: 400;
+  color: #8a9287;
+  margin-top: 4px;
+}
+.places b {
+  margin-left: auto;
+  color: #859a83;
+  font-size: 18px;
+  font-weight: 400;
+}
+.toggles {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  font-size: 11px;
+}
+.toggles label {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+}
+.toggles input {
+  accent-color: #3b7356;
+  width: 13px;
+  height: 13px;
+}
+.reset {
+  border: 1px solid #dce3d4;
+  border-radius: 7px;
+  background: transparent;
+  padding: 10px;
+  width: 100%;
+  color: #677c65;
+  font-size: 11px;
+  margin-top: 20px;
+}
+#status {
+  font-size: 10px;
+  line-height: 1.5;
+  color: #6f826b;
+  margin-top: 15px;
+}
+#status.error {
+  color: #a74936;
+}
+.transfer {
+  position: fixed;
+  bottom: 42px;
+  left: 50%;
+  transform: translateX(-25%);
+  display: flex;
+  align-items: center;
+  gap: 20px;
+  background: #fffcf6f5;
+  border: 1px solid white;
+  border-radius: 13px;
+  padding: 17px 24px;
+  box-shadow: 0 5px 25px #203c3020;
+  z-index: 2;
+}
+.transfer-icon {
+  background: #e6eddd;
+  color: #6b875e;
+  width: 34px;
+  height: 34px;
+  display: grid;
+  place-items: center;
+  border-radius: 9px;
+  font-size: 23px;
+}
+.transfer strong {
+  display: block;
+  font-size: 17px;
+  font-weight: 500;
+  white-space: nowrap;
+}
+.transfer span {
+  display: block;
+  font-size: 9px;
+  color: #899180;
+  margin-top: 4px;
+  white-space: nowrap;
+}
+.divider {
+  width: 1px;
+  height: 30px;
+  background: #e1e6dc;
+}
+.file-note {
+  padding-left: 17px;
+  border-left: 1px solid #e1e6dc;
+}
+.file-note strong {
+  font-size: 8px;
+  letter-spacing: 1px;
+  color: #7a8970;
+}
+.legend {
+  position: fixed;
+  bottom: 123px;
+  left: calc(50% + 95px);
+  transform: translateX(-50%);
+  display: flex;
+  gap: 14px;
+  font-size: 9px;
+  z-index: 2;
+  background: #fffaf0db;
+  border-radius: 20px;
+  padding: 9px 15px;
+  white-space: nowrap;
+}
+.legend span {
+  display: flex;
+  align-items: center;
+  gap: 5px;
+}
+.legend i {
+  width: 7px;
+  height: 7px;
+  border-radius: 50%;
+}
+.water {
+  background: #8dbbb7;
+}
+.park {
+  background: #a8bf8b;
+}
+.building {
+  background: #c9bda9;
+}
+.map-tools {
+  position: fixed;
+  top: 111px;
+  right: 26px;
+  z-index: 2;
+  display: grid;
+  gap: 10px;
+}
+.map-tools button {
+  width: 40px;
+  height: 40px;
+  border-radius: 10px;
+  background: #fffcf6;
+  border: 1px solid #fff;
+  color: #435b47;
+  box-shadow: 0 4px 12px #203c3015;
+}
+.maplibregl-ctrl-top-right {
+  top: 210px;
+  right: 16px;
+}
+.maplibregl-popup-content {
+  font-family: "DM Sans", sans-serif;
+  border-radius: 10px;
+  padding: 14px 20px;
+  color: #344e40;
+  max-width: 240px;
+}
+.maplibregl-popup-content h3 {
+  font-size: 14px;
+  margin: 0 0 5px;
+}
+.maplibregl-popup-content p {
+  font-size: 11px;
+  margin: 0;
+  line-height: 1.5;
+}
+.maplibregl-ctrl-attrib {
+  font-size: 9px !important;
+}
+.maplibregl-canvas {
+  outline: none;
+}
+@media (max-height: 840px) and (min-width: 761px) {
+  .panel {
+    padding: 22px;
+    top: 96px;
+  }
+  h1 {
+    font-size: 40px;
+    margin: 14px 0 12px;
+  }
+  .intro {
+    margin-bottom: 14px;
+  }
+  .section-label {
+    margin-top: 17px;
+  }
+  .places button {
+    padding: 8px 5px;
+  }
+  .reset {
+    margin-top: 14px;
+  }
+  .panel .location {
+    padding: 12px 0;
+  }
+}
+@media (max-width: 760px) {
+  header {
+    height: 65px;
+    padding: 0 17px;
+  }
+  .brand {
+    font-size: 22px;
+  }
+  .header-right > a {
+    display: none;
+  }
+  .header-right .pill {
+    font-size: 8px;
+    padding: 7px 9px;
+  }
+  .panel {
+    left: 12px;
+    top: 80px;
+    width: 232px;
+    padding: 19px;
+    border-radius: 13px;
+  }
+  h1 {
+    font-size: 36px;
+    margin: 15px 0 12px;
+  }
+  .eyebrow {
+    font-size: 7px;
+  }
+  .intro {
+    font-size: 10px;
+    margin-bottom: 12px;
+  }
+  .location {
+    padding: 12px 0;
+  }
+  .location small {
+    font-size: 8px;
+  }
+  .section-label {
+    margin-top: 17px;
+    font-size: 8px;
+  }
+  .places button {
+    padding: 8px 3px;
+  }
+  .places button div {
+    font-size: 11px;
+  }
+  .places small {
+    font-size: 9px;
+  }
+  .toggles {
+    font-size: 10px;
+    gap: 7px;
+  }
+  .reset {
+    margin-top: 12px;
+  }
+  .transfer {
+    left: 12px;
+    right: 12px;
+    bottom: 31px;
+    transform: none;
+    gap: 14px;
+    padding: 13px 15px;
+  }
+  .transfer strong {
+    font-size: 14px;
+  }
+  .file-note {
+    margin-left: auto;
+    padding-left: 12px;
+  }
+  .file-note strong {
+    font-size: 7px;
+  }
+  .transfer span {
+    font-size: 8px;
+  }
+  .transfer-icon {
+    display: none;
+  }
+  .legend {
+    display: none;
+  }
+  .map-tools {
+    top: 81px;
+    right: 12px;
+  }
+  .maplibregl-ctrl-top-right {
+    top: 180px;
+    right: 2px;
+  }
+}
+@media (max-height: 650px) {
+  .intro,
+  .location,
+  .section-label,
+  .toggles,
+  .reset {
+    display: none;
+  }
+  .panel {
+    width: 235px;
+  }
+  h1 {
+    font-size: 34px;
+  }
+  .transfer {
+    bottom: 27px;
+  }
+}

src/client.ts

@@ -0,0 +1,353 @@
+import maplibregl, { type LayerSpecification } from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+import { FetchSource, PMTiles, Protocol } from "pmtiles";
+
+function element(id: string) {
+  const node = document.getElementById(id);
+  if (!node) throw new Error(`Missing ${id}`);
+  return node;
+}
+const status = element("status");
+let bytes = 0;
+let requests = 0;
+const formatBytes = (value: number) =>
+  value < 1024 * 1024
+    ? `${(value / 1024).toFixed(1)} KB`
+    : `${(value / 1024 / 1024).toFixed(2)} MB`;
+class MeteredSource extends FetchSource {
+  override async getBytes(...args: Parameters<FetchSource["getBytes"]>) {
+    const result = await super.getBytes(...args);
+    bytes += result.data.byteLength;
+    requests++;
+    element("bytes").textContent = formatBytes(bytes);
+    element("requests").textContent = String(requests);
+    return result;
+  }
+}
+const archive = new PMTiles(
+  new MeteredSource(`${location.origin}/maps/florence.pmtiles`),
+);
+const protocol = new Protocol();
+protocol.add(archive);
+maplibregl.addProtocol("pmtiles", protocol.tile);
+const places = {
+  duomo: {
+    name: "Piazza del Duomo",
+    description: "The cathedral at the heart of Florence.",
+    center: [11.2566, 43.7731],
+  },
+  bridge: {
+    name: "Ponte Vecchio",
+    description: "Florence's historic bridge over the Arno.",
+    center: [11.2531, 43.7679],
+  },
+  garden: {
+    name: "Boboli Gardens",
+    description: "The terraced gardens behind Palazzo Pitti.",
+    center: [11.2483, 43.7625],
+  },
+};
+let dark = false;
+const styleLayers: LayerSpecification[] = [
+  {
+    id: "background",
+    type: "background",
+    paint: { "background-color": "#efece0" },
+  },
+  {
+    id: "green",
+    type: "fill",
+    source: "city",
+    "source-layer": "landuse",
+    filter: [
+      "in",
+      ["get", "pmap:kind"],
+      [
+        "literal",
+        [
+          "park",
+          "forest",
+          "wood",
+          "garden",
+          "nature_reserve",
+          "grass",
+          "recreation_ground",
+          "cemetery",
+        ],
+      ],
+    ],
+    paint: { "fill-color": "#b8caa0", "fill-opacity": 0.8 },
+  },
+  {
+    id: "natural",
+    type: "fill",
+    source: "city",
+    "source-layer": "natural",
+    paint: { "fill-color": "#bccba8", "fill-opacity": 0.7 },
+  },
+  {
+    id: "water",
+    type: "fill",
+    source: "city",
+    "source-layer": "water",
+    filter: ["==", ["geometry-type"], "Polygon"],
+    paint: { "fill-color": "#91bbb6" },
+  },
+  {
+    id: "waterways",
+    type: "line",
+    source: "city",
+    "source-layer": "physical_line",
+    filter: ["==", ["get", "pmap:kind"], "waterway"],
+    paint: { "line-color": "#91bbb6", "line-width": 2 },
+  },
+  {
+    id: "roads-casing",
+    type: "line",
+    source: "city",
+    "source-layer": "roads",
+    paint: {
+      "line-color": "#d5cfbc",
+      "line-width": ["interpolate", ["linear"], ["zoom"], 11, 1, 15, 6, 18, 14],
+    },
+  },
+  {
+    id: "roads",
+    type: "line",
+    source: "city",
+    "source-layer": "roads",
+    paint: {
+      "line-color": "#fff9ec",
+      "line-width": [
+        "interpolate",
+        ["linear"],
+        ["zoom"],
+        11,
+        0.5,
+        15,
+        3.5,
+        18,
+        10,
+      ],
+    },
+  },
+  {
+    id: "buildings",
+    type: "fill-extrusion",
+    source: "city",
+    "source-layer": "buildings",
+    paint: {
+      "fill-extrusion-color": "#c9bda9",
+      "fill-extrusion-height": ["coalesce", ["get", "height"], 7],
+      "fill-extrusion-opacity": 0.82,
+    },
+  },
+  {
+    id: "street-labels",
+    type: "symbol",
+    source: "city",
+    "source-layer": "roads",
+    minzoom: 14,
+    layout: {
+      "symbol-placement": "line",
+      "text-field": ["coalesce", ["get", "name"], ""],
+      "text-font": ["Noto Sans Regular"],
+      "text-size": 11,
+    },
+    paint: {
+      "text-color": "#7e8070",
+      "text-halo-color": "#f8f5e9",
+      "text-halo-width": 2,
+    },
+  },
+];
+const map = new maplibregl.Map({
+  container: "map",
+  center: [11.2543, 43.77],
+  zoom: 13.8,
+  minZoom: 12,
+  maxZoom: 18,
+  maxBounds: [
+    [11.205, 43.733],
+    [11.305, 43.801],
+  ],
+  pitch: 0,
+  bearing: 0,
+  attributionControl: false,
+  style: {
+    version: 8,
+    glyphs:
+      "https://protomaps.github.io/basemaps-assets/fonts/{fontstack}/{range}.pbf",
+    sources: {
+      city: {
+        type: "vector",
+        url: `pmtiles://${location.origin}/maps/florence.pmtiles`,
+        attribution:
+          '<a href="https://protomaps.com">Protomaps</a> · © <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a>',
+      },
+    },
+    layers: styleLayers,
+  },
+});
+map.addControl(new maplibregl.NavigationControl(), "top-right");
+map.addControl(
+  new maplibregl.AttributionControl({ compact: true }),
+  "bottom-right",
+);
+function padding() {
+  return {
+    left: innerWidth > 760 ? 380 : 180,
+    right: innerWidth > 760 ? 70 : 20,
+    top: 95,
+    bottom: 120,
+  };
+}
+map.on("load", () => {
+  map.easeTo({ padding: padding(), duration: 0 });
+  status.textContent = "Ready to explore. Click a building to inspect it.";
+});
+map.on("error", () => {
+  status.textContent =
+    "The map could not load. Check the Space's storage credentials and try again.";
+  status.classList.add("error");
+});
+fetch("/api/map")
+  .then((r) => r.json())
+  .then((data: unknown) => {
+    if (typeof data !== "object" || data === null) return;
+    if ("size" in data && typeof data.size === "number")
+      element("archive").textContent =
+        `${formatBytes(data.size)} · Florence snapshot`;
+    else element("archive").textContent = "Storage not connected";
+    if ("available" in data && data.available === false) {
+      status.textContent =
+        "Setup needed: add the S3 access key and secret in Space settings.";
+      status.classList.add("error");
+    }
+  })
+  .catch(() => {
+    status.textContent = "Could not reach the map service.";
+    status.classList.add("error");
+  });
+for (const button of document.querySelectorAll<HTMLButtonElement>(
+  "[data-place]",
+))
+  button.addEventListener("click", () => {
+    const id = button.dataset.place;
+    const place =
+      id === "duomo"
+        ? places.duomo
+        : id === "bridge"
+          ? places.bridge
+          : places.garden;
+    const lng = place.center[0] ?? 11.2543;
+    const lat = place.center[1] ?? 43.77;
+    map.flyTo({
+      center: [lng, lat],
+      zoom: 16,
+      pitch: 35,
+      padding: padding(),
+      duration: 1400,
+    });
+    document
+      .querySelectorAll("[data-place]")
+      .forEach((node) => node.classList.remove("active"));
+    button.classList.add("active");
+    const content = document.createElement("div");
+    const title = document.createElement("h3");
+    title.textContent = place.name;
+    const text = document.createElement("p");
+    text.textContent = place.description;
+    content.append(title, text);
+    new maplibregl.Popup({ offset: 10 })
+      .setLngLat([lng, lat])
+      .setDOMContent(content)
+      .addTo(map);
+  });
+for (const [id, layers] of [
+  ["buildings", ["buildings"]],
+  ["parks", ["green", "natural"]],
+  ["labels", ["street-labels"]],
+] satisfies [string, string[]][])
+  element(id).addEventListener("change", (event) => {
+    if (!(event.target instanceof HTMLInputElement)) return;
+    for (const layer of layers)
+      if (map.getLayer(layer))
+        map.setLayoutProperty(
+          layer,
+          "visibility",
+          event.target.checked ? "visible" : "none",
+        );
+  });
+element("reset").addEventListener("click", () => {
+  map.flyTo({
+    center: [11.2543, 43.77],
+    zoom: 13.8,
+    pitch: 0,
+    bearing: 0,
+    padding: padding(),
+  });
+  document
+    .querySelectorAll("[data-place]")
+    .forEach((node) => node.classList.remove("active"));
+});
+element("tilt").addEventListener("click", () =>
+  map.easeTo({ pitch: map.getPitch() > 10 ? 0 : 50, duration: 700 }),
+);
+element("theme").addEventListener("click", () => {
+  if (!map.isStyleLoaded()) return;
+  dark = !dark;
+  map.setPaintProperty(
+    "background",
+    "background-color",
+    dark ? "#243a36" : "#efece0",
+  );
+  map.setPaintProperty("water", "fill-color", dark ? "#152e32" : "#91bbb6");
+  map.setPaintProperty("green", "fill-color", dark ? "#3c5845" : "#b8caa0");
+  map.setPaintProperty("natural", "fill-color", dark ? "#385041" : "#bccba8");
+  map.setPaintProperty("roads", "line-color", dark ? "#688071" : "#fff9ec");
+  map.setPaintProperty(
+    "roads-casing",
+    "line-color",
+    dark ? "#263e35" : "#d5cfbc",
+  );
+  map.setPaintProperty(
+    "buildings",
+    "fill-extrusion-color",
+    dark ? "#7b8875" : "#c9bda9",
+  );
+  map.setPaintProperty(
+    "street-labels",
+    "text-color",
+    dark ? "#d7dec8" : "#7e8070",
+  );
+  map.setPaintProperty(
+    "street-labels",
+    "text-halo-color",
+    dark ? "#243a36" : "#f8f5e9",
+  );
+});
+map.on("click", "buildings", (event) => {
+  const feature = event.features?.[0];
+  if (!feature) return;
+  const content = document.createElement("div");
+  const title = document.createElement("h3");
+  title.textContent = String(feature.properties?.name || "Florentine building");
+  const text = document.createElement("p");
+  const height = feature.properties?.height;
+  text.textContent =
+    typeof height === "number"
+      ? `Mapped height: ${height} m`
+      : "Building footprint from OpenStreetMap. Height is not recorded.";
+  content.append(title, text);
+  new maplibregl.Popup()
+    .setLngLat(event.lngLat)
+    .setDOMContent(content)
+    .addTo(map);
+});
+map.on("mouseenter", "buildings", () => {
+  map.getCanvas().style.cursor = "pointer";
+});
+map.on("mouseleave", "buildings", () => {
+  map.getCanvas().style.cursor = "";
+});

src/ranges.ts

@@ -0,0 +1,19 @@
+export function parseRange(value: string | null, size: number) {
+  if (!value) return null;
+  const match = /^bytes=(\d*)-(\d*)$/.exec(value);
+  if (!match || (!match[1] && !match[2])) return null;
+  const start = match[1]
+    ? Number(match[1])
+    : Math.max(0, size - Number(match[2]));
+  const end =
+    match[1] && match[2] ? Math.min(Number(match[2]), size - 1) : size - 1;
+  if (
+    !Number.isSafeInteger(start) ||
+    !Number.isSafeInteger(end) ||
+    start < 0 ||
+    start > end ||
+    start >= size
+  )
+    return null;
+  return { start, end, length: end - start + 1 };
+}

src/server.test.ts

@@ -0,0 +1,91 @@
+import { describe, test, expect, afterAll } from "bun:test";
+import { resolve } from "node:path";
+import { PMTiles } from "pmtiles";
+import { parseRange } from "./ranges";
+
+process.env.LOCAL_PMTILES = resolve("data/florence.pmtiles");
+const { handler } = await import("./server");
+const server = Bun.serve({ port: 0, fetch: handler });
+const url = server.url.toString();
+afterAll(() => server.stop(true));
+const file = Bun.file(process.env.LOCAL_PMTILES);
+describe("real archive HTTP serving", () => {
+  test("byte ranges match archive bytes and headers", async () => {
+    for (const [start, end] of [
+      [0, 126],
+      [1000, 8191],
+      [file.size - 10, file.size - 1],
+    ]) {
+      const r = await fetch(`${url}maps/florence.pmtiles`, {
+        headers: { Range: `bytes=${start}-${end}` },
+      });
+      expect(r.status).toBe(206);
+      expect(r.headers.get("content-range")).toBe(
+        `bytes ${start}-${end}/${file.size}`,
+      );
+      expect(new Uint8Array(await r.arrayBuffer())).toEqual(
+        new Uint8Array(await file.slice(start, end + 1).arrayBuffer()),
+      );
+      expect(r.headers.get("cache-control")).toBe("private, no-store");
+    }
+  });
+  test("HEAD exposes size without a body", async () => {
+    const r = await fetch(`${url}maps/florence.pmtiles`, { method: "HEAD" });
+    expect(r.status).toBe(200);
+    expect(r.headers.get("content-length")).toBe(String(file.size));
+    expect(await r.text()).toBe("");
+  });
+  test("invalid, multiple, and missing ranges are rejected", async () => {
+    for (const value of [
+      "bytes=9-1",
+      "bytes=0-1,5-6",
+      `bytes=${file.size}-`,
+      "bytes=-0",
+      "",
+    ]) {
+      const r = await fetch(`${url}maps/florence.pmtiles`, {
+        headers: { Range: value },
+      });
+      expect(r.status).toBe(416);
+    }
+  });
+  test("only fixed archive path is accessible", async () => {
+    expect(
+      (
+        await fetch(`${url}maps/another.pmtiles`, {
+          headers: { Range: "bytes=0-10" },
+        })
+      ).status,
+    ).toBe(404);
+    expect(
+      (await fetch(`${url}maps/florence.pmtiles`, { method: "POST" })).status,
+    ).toBe(405);
+  });
+  test("PMTiles client reads actual metadata and a tile", async () => {
+    const p = new PMTiles(`${url}maps/florence.pmtiles`);
+    const header = await p.getHeader();
+    expect(header.specVersion).toBe(3);
+    const tile = await p.getZxy(14, 8704, 5971);
+    expect(tile?.data.byteLength).toBeGreaterThan(0);
+    const meta = await p.getMetadata();
+    expect(meta).toHaveProperty("vector_layers");
+  });
+});
+test("range edge cases", () => {
+  expect(parseRange("bytes=-10", 100)).toEqual({
+    start: 90,
+    end: 99,
+    length: 10,
+  });
+  expect(parseRange("bytes=95-999", 100)).toEqual({
+    start: 95,
+    end: 99,
+    length: 5,
+  });
+  expect(parseRange("bytes=1-", 100)).toEqual({
+    start: 1,
+    end: 99,
+    length: 99,
+  });
+  expect(parseRange("bytes=9007199254740993-", 100)).toBeNull();
+});

src/server.ts

@@ -0,0 +1,164 @@
+import { S3Client } from "bun";
+import { join } from "node:path";
+import { parseRange } from "./ranges";
+
+const root = join(import.meta.dir, "..");
+const localPath = process.env.LOCAL_PMTILES;
+const key = process.env.PMTILES_KEY || "maps/florence.pmtiles";
+const configured =
+  !!localPath ||
+  !!(process.env.HF_S3_ACCESS_KEY_ID && process.env.HF_S3_SECRET_ACCESS_KEY);
+const client =
+  configured && !localPath
+    ? new S3Client({
+        endpoint: `https://s3.hf.co/${process.env.HF_S3_NAMESPACE || "cfahlgren1"}`,
+        bucket: process.env.HF_S3_BUCKET || "bucket-atlas",
+        region: "us-east-1",
+        virtualHostedStyle: false,
+        accessKeyId: process.env.HF_S3_ACCESS_KEY_ID,
+        secretAccessKey: process.env.HF_S3_SECRET_ACCESS_KEY,
+      })
+    : null;
+const local = localPath ? Bun.file(localPath) : null;
+const object = client?.file(key);
+let metadata: Promise<{ size: number; etag: string }> | undefined;
+function getMetadata() {
+  metadata ??= (async () => {
+    if (local)
+      return {
+        size: local.size,
+        etag: `"local-${local.size}-${local.lastModified}"`,
+      };
+    if (!object) throw new Error("Storage is not configured");
+    const stat = await object.stat();
+    return { size: stat.size, etag: stat.etag };
+  })().catch((error) => {
+    metadata = undefined;
+    throw error;
+  });
+  return metadata;
+}
+const commonHeaders = {
+  "Cache-Control": "private, no-store",
+  "X-Content-Type-Options": "nosniff",
+};
+export async function handler(req: Request): Promise<Response> {
+  const path = new URL(req.url).pathname;
+  if (req.method !== "GET" && req.method !== "HEAD")
+    return new Response("Method not allowed", {
+      status: 405,
+      headers: { Allow: "GET, HEAD" },
+    });
+  if (path === "/healthz")
+    return Response.json({
+      status: configured ? "ready" : "needs-storage-credentials",
+    });
+  if (path === "/api/map") {
+    let size: number | null = null;
+    let available = false;
+    if (configured) {
+      try {
+        size = (await getMetadata()).size;
+        available = true;
+      } catch {
+        /* The frontend displays the storage error. */
+      }
+    }
+    return Response.json(
+      {
+        name: "Florence",
+        region: "Tuscany, Italy",
+        path: "/maps/florence.pmtiles",
+        size,
+        available,
+        storage: local
+          ? "local development file"
+          : "private Hugging Face bucket",
+        snapshot: "August 2024",
+      },
+      { headers: commonHeaders },
+    );
+  }
+  if (path === "/maps/florence.pmtiles") {
+    if (!configured)
+      return new Response(
+        "Add HF_S3_ACCESS_KEY_ID and HF_S3_SECRET_ACCESS_KEY in Space secrets.",
+        { status: 503, headers: commonHeaders },
+      );
+    try {
+      const meta = await getMetadata();
+      const headers = new Headers({
+        ...commonHeaders,
+        "Accept-Ranges": "bytes",
+        "Content-Type": "application/octet-stream",
+        ETag: meta.etag,
+      });
+      if (req.method === "HEAD") {
+        headers.set("Content-Length", String(meta.size));
+        return new Response(null, { headers });
+      }
+      const range = parseRange(req.headers.get("Range"), meta.size);
+      if (!range) {
+        headers.set("Content-Range", `bytes */${meta.size}`);
+        return new Response("A valid single byte range is required.", {
+          status: 416,
+          headers,
+        });
+      }
+      if (range.length > 8 * 1024 * 1024)
+        return new Response("Range exceeds 8 MiB", {
+          status: 413,
+          headers: commonHeaders,
+        });
+      const contentRange = `bytes ${range.start}-${range.end}/${meta.size}`;
+      let body: ReadableStream<Uint8Array>;
+      if (local)
+        body = new Blob([
+          await local.slice(range.start, range.end + 1).arrayBuffer(),
+        ]).stream();
+      else {
+        if (!object) throw new Error("Missing storage");
+        const upstream = await fetch(object.presign({ expiresIn: 60 }), {
+          headers: { Range: `bytes=${range.start}-${range.end}` },
+          signal: AbortSignal.any([req.signal, AbortSignal.timeout(20000)]),
+          redirect: "error",
+        });
+        if (
+          upstream.status !== 206 ||
+          upstream.headers.get("content-range") !== contentRange ||
+          !upstream.body
+        ) {
+          await upstream.body?.cancel();
+          throw new Error("Invalid upstream byte range");
+        }
+        body = upstream.body;
+      }
+      headers.set("Content-Range", contentRange);
+      headers.set("Content-Length", String(range.length));
+      return new Response(body, { status: 206, headers });
+    } catch {
+      return new Response(
+        "Map storage is unavailable. Check the Space's S3 configuration.",
+        { status: 502, headers: commonHeaders },
+      );
+    }
+  }
+  const assets: Record<string, string> = {
+    "/": "public/index.html",
+    "/styles.css": "public/styles.css",
+    "/assets/client.js": "public/assets/client.js",
+    "/assets/client.css": "public/assets/client.css",
+  };
+  const asset = assets[path];
+  if (!asset) return new Response("Not found", { status: 404 });
+  const file = Bun.file(join(root, asset));
+  return new Response(req.method === "HEAD" ? null : file, {
+    headers: { "Content-Type": file.type, ...commonHeaders },
+  });
+}
+if (import.meta.main)
+  Bun.serve({
+    hostname: "0.0.0.0",
+    port: Number(process.env.PORT || 7860),
+    fetch: handler,
+  });

tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "types": ["bun"],
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"]
+}