WebProxy Server

WebProxy Server is a distributed cache engine for organizational systems. It authenticates users against your own authentication service, groups them into clusters, and relays resource requests and responses only within the matching cluster.

The runtime is intentionally small:

1. The frontend WebProxy client opens the websocket endpoint.
2. The client sends an authentication token with /s <token>.
3. The server calls your authentication service using AUTHENTICATION_URL.
4. If the token is valid, the user is cached and added to a cluster, based on the user's organization and network.
5. Resource requests are broadcast only to peers in the same cluster.
6. Responses are routed back to the requesting user.

All configuration is read from environment variables, centralized in src/webproxy_server/environment.gleam.

The server identifies each connecting client by IP, which feeds authorization and the Administrator IPs gate. Because the server usually sits behind a reverse proxy, by default it trusts the X-Forwarded-For header (falling back to X-Real-IP) rather than the raw socket address.

• USE_NATIVE_CONNECTION_IP unset or false → use X-Forwarded-For, then X-Real-IP, then the transport-level connection IP if neither header is present.
• USE_NATIVE_CONNECTION_IP=true → always use the transport-level connection IP, ignoring the headers. Use this only when clients connect directly, since forwarded headers can be spoofed when not set by a trusted proxy.

AUTHORIZED_ADMINISTRATOR_IPS is a JSON string holding an array of IP addresses, for example ["10.0.0.5", "10.0.0.6"]. It gates the /upgrade command on top of the existing SysAdmin check, so a SysAdmin must also connect from an authorized IP to enter intervention mode.

• Unset, empty, or malformed → the list is treated as empty and no one is allowed to upgrade.
• Contains "*" → any IP address is allowed to upgrade. The server prints a warning at boot because this is potentially dangerous.
• Otherwise → only the listed IP addresses are allowed to upgrade.

Set AUTHENTICATION_URL to the full HTTPS URL of your authentication endpoint.

The WebProxy sends a GET request to that URL with these headers:

• Authorization: <user token>
• Accept: application/json

Your service should return a non-2xx response for an invalid token. For a valid token, return a JSON user object with this shape:

{
  "id": "string",
  "displayName": "string",
  "organization_id": "string",
  "scopes": ["string"],
  "isAdmin": false
}

Field details:

• id: unique user identifier
• displayName: human-readable username, such as an email address
• organization_id: the user's organization identifier
• scopes: array of scopes granted to the user
• isAdmin: whether the user is a trusted internal SysAdmin

VERY IMPORTANT:

• Only trusted internal users should have isAdmin: true.
• The server treats isAdmin: true users as SysAdmins, which unlocks special intervention commands.
• created_at is added by the server at decode time and is not required from the auth service.

Users are partitioned into clusters using their organization_id and the client network identity captured from the websocket connection.

In practice, the current implementation hashes the pair (organization_id, client IP address) into a cluster id. Users only share cache traffic with peers that resolve to the same cluster id, so data never leaves the organization-and-network boundary that produced that cluster.

If you need a different grouping rule, update the cluster id generation in src/webproxy_server/cluster.gleam.

Once a SysAdmin connection has entered intervention mode with /upgrade, the following privileged commands become available. They are rejected on any other connection. Each command replies with a short status line.

Deletes a single value from one of the tables. <table> is one of:

• users — <value> is the user's display_name (NOT their id or auth token). Every stored user with that display name is removed.
• clusters — <value> is a cluster id.
• pending_resources — <value> is a pending resource id.

Reports each matching cluster's id, ip address, organization, and the display names of its members.

• /su-clinfo — reports every cluster.
• /su-clinfo <cluster_id> — reports only that cluster.
• /su-clinfo user <display_name> — reports only the clusters the named user belongs to.

Pushes a /d <resource_name> frame to live connections so they evict the cached resource.

• /su-invalidate <resource_name> — targets every connection.
• /su-invalidate <resource_name> user <display_name> — targets only the connections of the named user.
• /su-invalidate <resource_name> cluster <cluster_id> — targets only the connections in that cluster.

The request path is designed for cache sharing between nodes in the same organization and network:

1. A client asks for a resource with /r <resource_name>.
2. The server stores a pending resource entry.
3. The request is broadcast to peers in the same cluster.
4. A peer answers with /p <resource_id> <response_json>.
5. The server deletes the pending entry and forwards the response to the original requester.

gleam run  # Run the project
gleam test # Run the tests

Build the image:

docker build -t webproxy-server .

Run the container:

docker run --rm \
  -e AUTHENTICATION_URL="https://your-auth-server.example.com/auth" \
  -e PORT=8080 \
  -e AUTHORIZED_ADMINISTRATOR_IPS='["10.0.0.5"]' \
  -p 8080:8080 \
  webproxy-server

Docker is the recommended way to run the service in production or in a test environment that should match the release image.

For local development, run the project directly with Gleam:

export AUTHENTICATION_URL="https://your-auth-server.example.com/auth"
export PORT=8080
export AUTHORIZED_ADMINISTRATOR_IPS='["10.0.0.5"]'
gleam run

If PORT is not set, the server falls back to 8080. See Environment Variables for the full list.

This project is licensed under the MIT License. See LICENSE.