roverse

A secure and efficient Cloudflare Worker proxy for Roblox API endpoints.

📚 Table of Contents

• 🔧 How It Works
• 📋 Requirements
• 🚀 Getting Started
• 📖 Usage Guide
• 🛠️ Development
• ⚠️ Pitfalls
• ❓ FAQ
• 📄 License

🔧 How It Works

Roverse uses Cloudflare Workers to create a secure proxy layer between your application and Roblox's API endpoints. When you make a request to your worker, it forwards that request to the corresponding Roblox API endpoint while keeping all necessary headers and authentication.

📋 Requirements

• Go 1.23.5 or later
• TinyGo 0.29.0 or later
• Node.js
• Cloudflare Account
• Wrangler CLI
  • just run npm install -g wrangler

🚀 Getting Started

1. Clone and Setup:

   # Clone the repository
   git clone https://github.com/robalyx/roverse.git
   cd roverse
   
   # Install dependencies
   go mod tidy

2. Configure Environment:

   • Set your worker name in wrangler.toml
   • Configure your secret key:

     wrangler secret put PROXY_SECRET_KEY

3. Deploy:

   make deploy

📖 Usage Guide

All requests to the proxy must include the X-Proxy-Secret header with your configured secret key. This authentication mechanism ensures that only authorized clients can access your proxy, preventing unauthorized usage and potential abuse of your worker's resources.

Converting Roblox URLs to Worker Requests

To use the proxy, convert any Roblox API URL to a worker request by taking the subdomain and path. The format is:

Roblox URL:    https://{subdomain}.roblox.com/{path}
Worker URL:    https://your-worker.workers.dev/{subdomain}/{path}

Examples

Using curl:

# Get user details  
curl -X GET \
  -H "X-Proxy-Secret: your-secret-key" \
  "https://your-worker.workers.dev/users/v1/users/1"

# Get groups with query parameters
curl -X GET \
  -H "X-Proxy-Secret: your-secret-key" \
  "https://your-worker.workers.dev/groups/v1/groups/search?keyword=test&prioritizeExactMatch=false&limit=10"

# Get games with universe IDs
curl -X GET \
  -H "X-Proxy-Secret: your-secret-key" \
  "https://your-worker.workers.dev/games/v1/games?universeIds=1,2,3"

The proxy will keep all your original headers (except the secret key) and forward them to the Roblox API.

🛠️ Development

Commands

# Start development server
make dev

# Build WebAssembly binary
make build

# Deploy to Cloudflare
make deploy

Testing Dev Server

Before testing, you may want to modify the PROXY_SECRET_KEY in your .dev.vars file. By default, it's set to "development".

You can test the dev server using curl:

# Test the proxy with the users endpoint
curl -H "X-Proxy-Secret: development" \
  http://localhost:8787/users/v1/users/1

⚠️ Pitfalls

Using workers.dev Domains

Using the default workers.dev domain can expose your worker to unwanted traffic. There are bots that scan for new SSL certificates and monitor these domains, looking for workers to abuse. These bots can quickly find and target your worker even before you start using it.

We strongly recommend using a custom domain instead of the default workers.dev domain. Custom domains are much less likely to be targeted by automated scanning, as they require more effort to discover and aren't immediately identifiable as Cloudflare Workers.

This is especially important if you're on the paid plan, as unauthorized requests will still count towards your quota even if they're blocked by your authentication. You may check the other pitfalls for more information.

Triggering Cloudflare's Abuse Protection

Cloudflare's abuse protection system may trigger if your worker receives too many requests per second, especially on the free plan. This may also happen if too much traffic originates from a single IP address or a small range of IPs.

If you need to handle higher request volumes, consider upgrading to the paid Workers plan which allows for thousands of requests per second. We recommend implementing your own rate limiting and request distribution strategies to stay within these boundaries and ensure reliable service.

There is no reason for Cloudflare to block your worker as long as you're not abusing the service. You may learn more about the limits here.

Protecting Against Unauthorized Usage

I'm sure you wouldn't want to wake up to a 100k dollar bill in your bank account, so to protect your worker from unauthorized usage, you can link a custom domain and implement Cloudflare's Web Application Firewall (WAF) rules:

1. Link a custom domain to your worker in the Cloudflare Dashboard under your worker's settings at Domains & Routes.

2. Navigate to your domain settings, then Security > WAF > Custom Rules to create firewall rules specific to your hostname.

3. If you're expecting requests from a specific IP only, you can create a rule with an expression like:

   (ip.src ne YOUR_IP_ADDRESS and http.host wildcard "your-subdomain.example.com")

   Replace YOUR_IP_ADDRESS and your-subdomain.example.com with your actual values.

This setup helps ensure your worker's request quota isn't consumed by unauthorized traffic. Please do test to ensure that your setup is working as expected.

❓ FAQ

Why use a proxy for Roblox APIs?

A proxy provides additional security, rate limiting control, and also helps prevent exposure of your original IP address when making API requests.

How secure is the secret key authentication?

The secret key is stored securely in Cloudflare Workers' environment variables. It's never exposed in logs or error messages, and all requests without the correct key are immediately rejected.

What endpoints are supported?

The proxy supports all Roblox API endpoints. If you find any endpoints that aren't working correctly, please open an issue and we'll investigate it.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Made with ❤️ by the robalyx team