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
• Just
  • Installation packages here
• Cloudflare Account
• Wrangler CLI
  • 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:

   # Copy the environment example
   cp .env.example .env
   
   # Edit .env with your settings
   # Set PROXY_DOMAIN to your workers.dev domain or custom domain
   # Set PROXY_SECRET_KEY to your desired secret key

3. Deploy:

   just 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 by replacing the official domain with your configured domain. The format is:

Roblox URL:    https://{subdomain}.roblox.com/{path}
Worker URL:    https://{subdomain}.your-domain.com/{path}

Examples

Using curl:

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

# Get groups with query parameters
curl -X GET \
  -H "X-Proxy-Secret: your-secret-key" \
  "https://groups.your-domain.com/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://games.your-domain.com/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

# Generate config from template
just generate-config

# Start development server
just dev

# Build WebAssembly binary
just build

# Deploy to Cloudflare
just 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".

Note

Make sure your system's hosts file allows subdomain resolution for localhost. Most modern operating systems support this by default.

When running the development server, you can access different Roblox API endpoints by using subdomains with localhost. For example:

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

# Test games endpoint
curl -H "X-Proxy-Secret: development" \
  "http://games.localhost:8787/v1/games?universeIds=1,2,3"

# Test groups endpoint
curl -H "X-Proxy-Secret: development" \
  "http://groups.localhost:8787/v1/groups/search?keyword=test"

⚠️ 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

It's important to protect your worker from unauthorized usage and potential costly bills.

Some good practices would be to use a custom domain instead of workers.dev, implement Cloudflare's Web Application Firewall (WAF) rules, regularly monitor your worker's metrics, and periodic rotation of your secret keys which minimizes the impact of potential key leaks.

❓ 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 common Roblox API endpoints including users, games, groups, friends, avatar, presence, and thumbnails. To add support for additional subdomains:

1. Open wrangler.template.toml
2. Add a new route entry following the existing pattern:

   { pattern = "your-subdomain.${PROXY_DOMAIN}", custom_domain = true }

3. Deploy your changes

If you find any endpoints that aren't working correctly, please open an issue.

Why use TinyGo instead of regular Go?

Although the built WebAssembly binary doesn't exceed Cloudflare's free plan limit of 3MB, TinyGo is still required due to memory constraints in the Workers runtime environment. Regular Go's WebAssembly output includes a larger runtime and garbage collector that would increase the memory usage of Cloudflare Workers. TinyGo produces a more efficient WebAssembly binary with a smaller runtime footprint that works within these memory constraints.

📄 License

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

---

Made with ❤️ by the robalyx team