Documentation — CodeStuff Reverse Proxy

Reverse Proxy sits in front of a single upstream URL and forwards every request to it, while locally answering a per-property verification file so you (or CodeStuff) can confirm you control the domain without the upstream needing to know anything about it.

🧭 What It Does

Transparent forwarding — every request (method, headers, body) is passed straight through to your configured upstream URL.
Automatic verification files — a <propertyName>-<time>.xml file is generated per property and served locally.
Self-expiring tokens — each verification file expires 15 minutes after it's generated, so stale proofs can't linger.
Multi-property support — configure several properties in one instance and choose which one is actively listening.
Zero external dependencies — a single closed-source JAR, no database, no extra services to run.

🔒 Closed Source

This project is closed source. The Reverse Proxy JAR is distributed as a compiled binary through the Releases page. Source code is not published, and redistribution or reverse engineering of the binary outside the terms provided at download is not permitted.

✅ Requirements

Java 21 or newer on the host machine.
A domain or subdomain pointed at the host running the proxy, if you intend to verify ownership.

📦 Get the JAR

Download the latest codestuff-reverseproxy-x.x.x.jar from the Releases page and place it in a folder of your choice on the host.

🚀 First Run

From that folder, run the JAR with no flags:

java -jar codestuff-reverseproxy-1.0.0.jar

On the very first run there's no configuration.json yet, so the proxy opens a small local web console instead of forwarding traffic. Visit it in your browser to create your first property.

🗂️ configuration.json

Generated automatically on first run — you normally never need to hand-edit it.

{
  "listenPort": "8080",
  "bindAddress": "0.0.0.0",
  "properties": {
    "<propertyName>": {
      "url": "<url>",
      "verification": "<propertyName>-<time>.xml"
    }
  }
}

📋 Fields

Field	Description
`listenPort`	Port the proxy binds to.
`bindAddress`	Network interface to bind to — `0.0.0.0` listens on all interfaces.
`properties`	A map of property name → upstream URL and verification filename.

▶️ Default (Forwarding) Mode

java -jar codestuff-reverseproxy-1.0.0.jar

Configured properties	Behavior
None yet	Opens the setup console so you can create your first property.
Exactly one	Starts forwarding to it immediately — no console needed.
Multiple	Opens a select console so you can choose which property to listen for.

🎯 Pinning a Property

When you have multiple properties, skip the select console by pinning one directly at startup:

java -jar codestuff-reverseproxy-1.0.0.jar --property "my-site"

The proxy starts forwarding for my-site immediately, and exits with an error if no property by that name exists.

🛠️ Admin Mode

java -jar codestuff-reverseproxy-1.0.0.jar --properties

Opens the admin dashboard instead of forwarding traffic. Use this to add, edit, delete, or regenerate verification for any property. See Admin Dashboard below.

🔑 How It Works

Every property gets a verification filename in the form <propertyName>-<time>.xml. The timestamp is embedded directly in the filename, so its expiry can be recalculated at any time without extra state. Requesting GET /<verification-filename> on the proxy returns a small XML document confirming the property name, URL, and validity.

⏱️ Expiry

Verification files expire 15 minutes after they're generated. Once expired, requesting the file returns HTTP 410 Gone instead of 200. Regenerate a fresh one from the admin dashboard whenever you need to re-verify.

📊 Overview

Launching with --properties opens a dashboard listing every configured property, its upstream URL, and its verification status.

🧰 Available Actions

Action	Description
Add	Create a new property with a name and upstream URL.
Edit	Update a property's upstream URL. Its verification file stays the same.
Delete	Remove a property from `configuration.json` entirely.
Regenerate	Issue a fresh verification file with a new 15-minute expiry.

❓ General

Is the source code available?

No. Reverse Proxy is closed source and distributed as a compiled JAR only, via the Releases page.

Can I run multiple properties on one instance?

Yes — configure as many as you like from the admin dashboard, then choose which one is actively forwarding with --property "<name>".

What happens if I forget the --property flag?

If exactly one property is configured, the proxy just uses it. If there are several, a small web console opens so you can pick one interactively.

CodeStuff Reverse Proxy