Reverse Proxy & TURN

Traffic in the other direction. Reverse proxy puts Ocalt in front of a server you own somewhere else — your hostname, Ocalt’s certificate, your machine serving. TURN mints relay credentials for peers who cannot reach each other directly.

TURN is live. Reverse proxy is pending. NEW TURN works now and mints real relay credentials. The reverse proxy verbs below are specified and being built.

These run as separate services on separate addresses from VPN & Proxy and from the sites Ocalt hosts. Inbound proxying, outbound masking and media relaying never share an address — what happens on one cannot affect the reputation of another.

Reverse Proxy

Point a hostname at Ocalt with DOMAIN, then hand Ocalt an origin to forward to. Ocalt terminates TLS, so the certificate is handled for you and your origin never needs one.

Front a Server You Own

DOMAIN "app.tld.com" TO "mysite.ocalt.site" SET ?d
AFTER NEW REVERSE PROXY "app.tld.com" TO "https://203.0.113.9:8443" SET ?rp
AFTER EMIT ?rp("status")
AFTER EMIT ?rp("id")
(* https://app.tld.com now serves from your box, with Ocalt's certificate *)

Front a Tunnelled Machine

DIRECTIVE "home-nas" TUNNEL PORT 3000 SET ?tunnel
AFTER NEW REVERSE PROXY "app.tld.com" TO ?tunnel("url") SET ?rp
(* A machine with no public address, on your own domain *)

Caching and Forwarded Headers

REVERSE PROXY ?rp CACHE 3600 SECONDS
AFTER REVERSE PROXY ?rp FORWARD HEADER "X-Real-IP"
AFTER REVERSE PROXY ?rp FORWARD HEADER "X-Forwarded-Proto"
AFTER REVERSE PROXY ?rp TIMEOUT 30 SECONDS

Listing and Removing

REVERSE PROXY LIST SET ?all
AFTER FOREACH ?all SET ?p
OPEN
  EMIT ?p("host") & " -> " & ?p("origin") & " (" & ?p("status") & ")"
CLOSE
AFTER REVERSE PROXY REMOVE ?rp("id")

The hostname must be yours first. A reverse proxy can only be created for a domain already pointed at Ocalt and verified with DOMAIN — that is the proof of ownership. An unverified hostname is refused.

Every request through the proxy charges a query, exactly as a Site Mode page view does. A busy site fronted this way is metered by its traffic, not by the one statement that set it up.

TURN

Two browsers behind restrictive networks often cannot reach each other, however correct the signalling. A TURN server relays the media between them. NEW TURN mints credentials for one.

Minting Relay Credentials

NEW TURN SET ?turn
AFTER EMIT ?turn("urls")
AFTER EMIT ?turn("username")
AFTER EMIT ?turn("credential")
AFTER EMIT ?turn("expires")

Handing Them to a Browser

NEW TURN SET ?turn
AFTER CAST ?turn AS JSON SET ?ice
AFTER HTML "script" TEXT `const ICE = ` & ?ice & `;
const pc = new RTCPeerConnection({ iceServers: [{
  urls: ICE.urls, username: ICE.username, credential: ICE.credential
}]});`

Longer or Shorter Validity

NEW TURN VALID 4 HOURS SET ?turn
AFTER NEW TURN VALID 60 SECONDS SET ?shortlived
(* Default is 1 hour. Maximum is 24 hours. *)

The relay is at turn.ocalt.com. A credential is valid for an hour by default; the shortest is ten seconds and the longest is a day.

A relay is a way out, never a way in. Private addresses, loopback and Ocalt’s own address are refused as peers. Without that, anyone with an account could point a relay at a private network and use it to look around. Two browsers relaying to each other use their public addresses — which is what TURN is for — so nothing legitimate is affected.

Credentials are short-lived by design. The username encodes an expiry and the credential is an HMAC over it — a leaked pair stops working when it expires rather than becoming an open relay. Mint them per session, in the script that serves the page.

A relay carries real bytes. Unlike a script execution, a relayed call consumes bandwidth for as long as it lasts. Each connection charges a query, and sustained relay traffic is metered separately — peers that can connect directly never touch the relay and cost nothing. TURN is the fallback, not the default path.

Full Verb Reference

Verb	Description
`NEW REVERSE PROXY "host" TO "origin" SET ?rp`	Front an origin you own, with automatic TLS
`REVERSE PROXY ?rp CACHE n SECONDS`	Cache responses at the edge
`REVERSE PROXY ?rp FORWARD HEADER "name"`	Pass a header through to the origin
`REVERSE PROXY ?rp TIMEOUT n SECONDS`	How long to wait on the origin
`REVERSE PROXY LIST SET ?all / REMOVE "id"`	List or tear down
`NEW TURN [VALID n HOURS] SET ?turn`	Short-lived relay credentials — `urls`, `username`, `credential`, `expires`