WolfStar CDN

Cloudflare Worker CDN for image delivery and on-the-fly transformation.
Serves assets from R2 with Cloudflare Image Transformations, cache-aside caching, CORS, rate limiting, and security headers.

Official Site · Blog · WolfStar Invite Link · Support Server · Feedback

Share WolfStar Repository

^{Fast, secure asset delivery for the WolfStar Network.}

Table of contents

Table of Contents

• ✨ Features
• 🚀 Requirements
• 🛳 Getting Started
• 📦 Usage
• ⌨️ Local Development
• 💻 Online Development
• 🤝 Contributing
• ❤️ Sponsor

👋🏻 Welcome to WolfStar CDN

WolfStar CDN is a Cloudflare Worker that serves and transforms images from R2 storage for the WolfStar Network. Built with Nitro v3 and TypeScript, it prioritizes stability, speed, and security.

✨ Features

• R2 Asset Delivery: Serve objects directly from Cloudflare R2 with immutable long-lived cache headers.
• On-the-fly Image Transformations: Resize, reformat, and adjust quality via query parameters using Cloudflare Image Transformations.
• Cache-aside Caching: HIT/MISS path via the Cloudflare Cache API with X-Cache-Status headers.
• CORS: Dynamic origin validation from an allowlist of trusted origins.
• Rate Limiting: 20 requests per 60 seconds per IP via Cloudflare Rate Limit binding.
• Security Headers: X-Content-Type-Options, X-Frame-Options, and X-XSS-Protection on every response.
• Range Requests: Partial content (bytes=) support for large assets (mutually exclusive with image transforms).
• Health Check: Lightweight /health endpoint for uptime monitoring.
• Structured Logging: Wide-event request logs via evlog.

🚀 Requirements

• Node.js: 22+ (LTS)
• pnpm: 10+ (required — not npm or yarn)
• Wrangler: 4+ (Cloudflare CLI)
• Cloudflare account: With R2 storage enabled and Image Transformations available for transform routes

🛳 Getting Started

Quick Setup

1. Clone the repository

   git clone https://github.com/wolfstar-project/cdn.git
   cd cdn

2. Install dependencies

   pnpm install

3. Configure Cloudflare bindings

   Open wrangler.jsonc and update the required values:

   Binding	Kind	Description
   wolfstar_cdn	R2Bucket	Primary asset storage
   RATE_LIMITER	RateLimit	20 requests per 60 s per IP
   ALLOWED_ORIGINS	env var	Comma-separated list of allowed origins
   R2_WORKER_URL	env var	Base URL used when constructing fetches

   Note Secrets must be added via wrangler secret put <NAME> and must never be committed to the repository.

4. Start the development server

   pnpm dev

   Note The Cloudflare Cache API (caches.default) and rate limiting bindings are only available inside the Cloudflare Workers runtime. Some features will be skipped or no-op locally.

Available Scripts

• pnpm dev — Start Nitro dev server (local Workers emulation)
• pnpm build — Production build via Vite + Nitro
• pnpm deploy — Deploy prebuilt output via Wrangler
• pnpm preview — Preview the production build locally
• pnpm lint — Run Oxlint + Oxfmt check (no auto-fix)
• pnpm lint:fix — Run Oxlint & Oxfmt and fix issues
• pnpm typecheck — Type-check with tsc --noEmit (must pass with zero errors)

Project Structure

nitro.config.ts          -- Nitro config (preset, cloudflare bindings)
vite.config.ts           -- Vite config (nitro plugin)
wrangler.jsonc           -- Wrangler deployment and bindings configuration
server/
  error.ts               -- Global error handler
  middleware/
    01.cors.ts           -- CORS middleware (dynamic origin validation)
    02.rate-limiter.ts   -- Rate limiting (20 req/60s)
    03.cache.ts          -- Cache-read middleware (HIT path)
  plugins/
    security-headers.ts  -- Security headers
    cache-writer.ts      -- Cache-write plugin (MISS path)
  routes/
    health.get.ts        -- Health check endpoint
    [...path].ts         -- Catch-all CDN route
  utils/
    types.ts             -- Type definitions
    constants.ts         -- Image extensions, dimension limits, cache TTL
    errors.ts            -- Error response factory
    blob.ts              -- Blob/R2 utilities (fetch, transform, range, parse)

Development Tools

• Nitro v3 — Cloudflare Workers server runtime
• TypeScript — Type safety
• Vite — Build tooling
• Wrangler — Cloudflare Workers CLI
• Oxlint — Code linting
• Oxfmt — Code formatting
• evlog — Structured wide-event logging
• @vite-hub/blob — R2 blob storage abstraction

📦 Usage

Fetch an asset

GET /path/to/image.png

Transform an image

Transformations apply when the file extension is an image (jpg, jpeg, png, gif, webp, svg, tiff, avif) and at least one transform parameter is present.

Param	Description	Valid values
w	Width	1–4096
h	Height	1–4096
q	Quality (default 85)	1–100
fit	Resize fit mode	scale-down, contain, cover, crop, pad
f	Output format	webp, avif, jpeg, png

GET /avatars/user.png?w=256&h=256&fit=cover&f=webp&q=80

Range requests and image transformations are mutually exclusive. Combining both returns 400.

Health check

GET /health

Returns JSON with worker status, timestamp, and Cloudflare region.

⌨️ Local Development

Refer to CONTRIBUTING.md for detailed setup instructions, code style, and the pull request process.

Before committing:

1. pnpm build — must build successfully
2. pnpm lint:fix — fix lint and format issues
3. pnpm typecheck — must pass with zero type errors
4. Commit messages must follow Conventional Commits

💻 Online Development

Click any of the buttons below to start a new development environment to demo or contribute to the codebase without having to install anything on your machine:

🤝 Contributing

Thank you to all the people who already contributed to WolfStar CDN! Please make sure to read the Contributing Guide before making a pull request.

❤️ Sponsor

If you like WolfStar and want to support the project, consider making a donation. Every contribution helps to maintain and improve the network.

Thank you for your support!

---

---

📝 License

Copyright © 2024 WolfStar. This project is Apache 2.0 licensed.