glb-compressor Server

HTTP compression server built on Bun.serve(). Provides synchronous and streaming (SSE) compression endpoints with full CORS support.

Starting the Server

# Production (from installed package)
glb-server

# Development (hot reload)
bun run dev

# Custom port
PORT=3000 bun run start

Default port: 8080 (override via PORT env var).

Endpoints

GET /healthz

Health check. Returns 200 ok.

POST /compress

Synchronous compression. Returns compressed GLB binary.

Accepts: multipart/form-data (field: file) or raw application/octet-stream.

Query params / form fields:

• preset - Compression preset: default, balanced, aggressive, max
• simplify - Mesh simplification ratio (0, 1), e.g. 0.5

Form fields override query params when both are provided.

Response headers:

| Header | Description | | ---------------------- | ---------------------------------- | | X-Request-ID | UUID tracking this request | | X-Original-Size | Input file size in bytes | | X-Compressed-Size | Output file size in bytes | | X-Compression-Method | gltfpack or meshopt | | X-Compression-Ratio | Percentage reduction (e.g. 84.1) | | Content-Disposition | Suggested download filename |

Example:

# Multipart upload
curl -X POST -F "file=@model.glb" \
  "http://localhost:8080/compress?preset=aggressive" \
  -o compressed.glb

# Raw binary upload
curl -X POST --data-binary @model.glb \
  -H "Content-Type: application/octet-stream" \
  "http://localhost:8080/compress?preset=balanced" \
  -o compressed.glb

POST /compress-stream

SSE streaming compression with real-time progress. Multipart only.

Content-Type: text/event-stream

SSE events:

| Event | Data shape | | -------- | ------------------------------------------------------------------------------------- | | log | { message: string } | | result | { requestId, filename, data (base64), originalSize, compressedSize, ratio, method } | | error | { message, requestId, code } |

Stream closes after result or error event.

Example (JavaScript):

const form = new FormData();
form.append('file', glbFile);

const response = await fetch(
	'http://localhost:8080/compress-stream?preset=aggressive',
	{ method: 'POST', body: form },
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

// Parse SSE events from the stream
while (true) {
	const { done, value } = await reader.read();
	if (done) break;
	const text = decoder.decode(value);
	// Parse "event: <type>\ndata: <json>\n\n" format
	console.log(text);
}

Error Responses

All errors return structured JSON:

{
	"error": { "code": "ERROR_CODE", "message": "Human-readable message" },
	"requestId": "uuid"
}

Error codes:

| Code | HTTP | Description | | ---------------------- | ---- | ----------------------------------- | | NO_FILE_PROVIDED | 400 | No file in form data | | INVALID_GLB | 400 | Failed GLB magic byte validation | | FILE_TOO_LARGE | 413 | Exceeds 100 MB limit | | INVALID_CONTENT_TYPE | 415 | Non-multipart on streaming endpoint | | COMPRESSION_FAILED | 500 | Pipeline error during compression |

CORS

Full CORS enabled on all endpoints. Exposed headers: X-Request-ID, X-Original-Size, X-Compressed-Size, X-Compression-Method, X-Compression-Ratio.

Limits

• Max file size: 100 MB
• gltfpack timeout: 60 seconds per file

Architecture Notes

• import.meta.main guard: safe to import server/main.ts as a library without starting the server.
• Request ID (X-Request-ID) is generated per request and logged server-side.
• The /compress-stream endpoint sends the compressed GLB as base64 in the result SSE event (~33% larger than binary). For large files near the 100 MB limit, prefer /compress.