cso-voxelhttp

VoxelHTTP REST API — Cloudflare Worker

This directory is a Cloudflare Python Worker port of the uploaded FastAPI VoxelHTTP server. It retains the /v4, /v5, and /v6 endpoints and reuses the existing Pydantic response models. Database access is changed from a local SQLModel/SQLite session to Cloudflare D1 prepared statements.

What is implemented

• GET/HEAD /v4/ping
• v4 cube transaction/rank endpoints
• v5 slot detail/history/template/lobby/newbie/simple/list endpoints
• v5 translation lookup/list endpoints
• v6 cheer/detail/list/search/rank endpoints
• Original error envelope for validation errors, internal errors and unimplemented operations

The following operations deliberately remain 501 Not Implemented, matching the original project: resource/image uploads, statistics creation, translation upload, and v6 notification endpoints. Authentication-dependent writes were already stubs in the uploaded API; this port does not invent their behavior.

1. Create the D1 database

Install a current Node.js LTS and Wrangler, then from this directory run:

npx wrangler d1 create voxelhttp-db

Copy the returned database ID into wrangler.jsonc in place of REPLACE_WITH_YOUR_D1_DATABASE_ID. Keep database_name in sync if you chose another name.

2. Import the source metadata database

The original README points to the CSNZ voxel metadata SQLite database. Download that database and export it to SQL. D1 imports SQL text, not the binary SQLite file itself (see Cloudflare’s import guide).

python scripts/export_sqlite.py voxelhttp_metadata_distilled.sqlite.db > metadata.sql
npx wrangler d1 execute voxelhttp-db --remote --file=metadata.sql

If you are testing without an existing metadata file, skip the import step. The migration below creates the tables, but a fresh database will naturally have no slot records.

Then apply the API’s supplemental tables and indexes:

npx wrangler d1 migrations apply voxelhttp-db --remote

For local development, use --local instead of --remote in both D1 commands. Start with a local import and test it before importing a large dump into the remote database.

3. Run the Worker locally

Python Workers require Python 3.13 or newer and the python_workers compatibility flag. This project uses the official Python Workers ASGI adapter for FastAPI.

uv sync --dev
uv run pywrangler dev

Then test:

curl http://localhost:8787/v4/ping
curl 'http://localhost:8787/v5/slots/list/search?q=voxel&limit=10&offset=0'
curl 'http://localhost:8787/v6/slots/detail/00000000000000000000'

The last example returns null for a missing slot (assuming the ID passes the 20-digit validation rule).

4. Deploy

npx wrangler deploy

Do not deploy until the D1 binding ID in wrangler.jsonc has been replaced.

API behavior notes

• Query limit must be 1..100; offset must be zero or greater. As in the source implementation, the page offset is multiplied by limit.
• V6 list/search endpoints accept the optional mode query. The V6 search endpoint also accepts comma-separated tag values.
• User-provided values are passed as D1 bound parameters; SQL fragments and sort orders are allow-listed in code.
• slot.tags is stored as JSON text and parsed for the v6 detail/search responses.
• The Worker does not use a local SQLite file at runtime. D1 is the durable database binding.

Files

• src/voxelhttp/worker.py — Worker FastAPI app and D1 query layer
• src/voxelhttp/models/ — response/request models carried over from the original
• migrations/0001_schema.sql — tables and indexes used by the API
• scripts/export_sqlite.py — SQLite-to-SQL export utility for importing upstream data
• wrangler.jsonc — Worker and D1 binding configuration