feat: give each agency portal domain its own Worker route when CLOUDFLARE_SAAS_PORTAL_WORKER names the portal Worker, added with the domain's custom hostname and removed with it, so a Cloudflare for SaaS zone shared with tracking and redirect domains sends only portal domains to the portal

This commit is contained in:
Matthew Meszaros
2026-11-10 13:35:47 +01:00
parent 4ec61b4619
commit 9128106295
7 changed files with 227 additions and 15 deletions
+2 -1
View File
@@ -1532,7 +1532,8 @@ func main() {
go jobs.NewFormsDomainSweep(organizationRepoForHandler, customHosts).WithPortals(brandRepository, brandService).Start(ctx, time.Hour)
// Behind a Cloudflare for SaaS zone of their own, verified agency portal domains are registered there as they verify.
portalEdge := edgehost.Open(repository.NewEdgeHostnameRepository(primaryDB.Pool, repository.EdgePortal),
cfsaas.Config{ZoneID: config.CloudflareSaaSPortalZoneID(), APIToken: config.CloudflareSaaSPortalAPIToken(), Origin: config.CloudflareSaaSPortalOrigin()},
cfsaas.Config{ZoneID: config.CloudflareSaaSPortalZoneID(), APIToken: config.CloudflareSaaSPortalAPIToken(),
Origin: config.CloudflareSaaSPortalOrigin(), Worker: config.CloudflareSaaSPortalWorker()},
func() []string {
return []string{config.PortalCNAMETarget(), config.FormsHostname(), config.TrackingHostname()}
})
+24 -9
View File
@@ -142,22 +142,37 @@ no workflow deploys this Worker; a deploy is a reviewed manual step.
Pages origin). Set the token with `wrangler secret put PORTAL_EDGE_TOKEN
--config deploy/cloudflare/portal/wrangler.jsonc`. Give each rate-limit
binding a `namespace_id` not used by another Worker on the account.
4. Route requests to it: a Worker route `portal.warmbly.com/*` for the shared
address, a route `*/*` on the zone for custom hostnames, plus routes with no
Worker for the zone's other names (`warmbly.com/*`, `*.warmbly.com/*`) so they
keep their current handling; the more specific `portal.warmbly.com/*` wins
over the last. Confirm that each existing hostname on the zone still answers
as before.
4. Route requests to it. Attach `PORTAL_DOMAIN` to the Worker for the shared
address, as a custom domain or a route `portal.warmbly.com/*`. Agency portal
domains reach it one of two ways:
- **The zone also holds other customer hostnames** (tracking or redirect
domains registered through `CLOUDFLARE_SAAS_ZONE_ID`, or any added by
hand). Add no catch-all route: it would send those names to the portal,
which answers `404` for them. Set `CLOUDFLARE_SAAS_PORTAL_WORKER` to the
Worker's name in the next step instead, and the backend adds a route
`<domain>/*` for each portal domain as it registers it and removes it with
the domain. This is how Warmbly Cloud runs.
- **The zone holds portal domains only.** Add one route `*/*` on the zone,
plus routes with no Worker for the zone's own names (`warmbly.com/*`,
`*.warmbly.com/*`) so they keep their current handling.
Either way, confirm that each existing hostname on the zone still answers as
before.
5. Set `PORTAL_DOMAIN`, `CLOUDFLARE_SAAS_PORTAL_ZONE_ID` and
`CLOUDFLARE_SAAS_PORTAL_API_TOKEN` on the backend and roll it. Connect links
and reports are built on the portal address from then on, and verified portal
domains are registered on the zone within two minutes.
`CLOUDFLARE_SAAS_PORTAL_API_TOKEN` on the backend, and
`CLOUDFLARE_SAAS_PORTAL_WORKER` for per-domain routes, then roll it. The
token needs `SSL and Certificates: Edit` on the zone, and `Workers Routes:
Edit` as well for per-domain routes. Connect links and reports are built on
the portal address from then on, and verified portal domains are registered
on the zone within two minutes.
6. Verify on the shared address and on one test portal domain: the certificate,
a connect link (also framed through `/embed.js`), a report, a `404` for
`/f/<id>`, the dashboard on the portal domain and the "nothing at this
address" page at the shared address's root. To roll back, remove the Worker
routes and unset `PORTAL_DOMAIN` on the backend, which stops new links being
built; registered hostnames stay and serve nothing until the routes return.
With per-domain routes, unsetting `CLOUDFLARE_SAAS_PORTAL_WORKER` stops new
routes and leaves the existing ones in place.
To rotate the token, move the current value into the backend's
`PORTAL_EDGE_PREVIOUS_TOKENS` with a `PORTAL_EDGE_PREVIOUS_UNTIL` cutoff, set the
@@ -84,8 +84,8 @@ The shared portal address, `PORTAL_DOMAIN`, and every agency portal domain that
1. Enable Cloudflare for SaaS on the zone `PORTAL_DOMAIN` is on (`warmbly.com`), create a proxied fallback origin record and set it as the zone's fallback origin, and create `PORTAL_DOMAIN` (`portal.warmbly.com`) as a proxied record in that zone.
2. Add a generated `PORTAL_EDGE_TOKEN` (at least 32 characters) to the backend's secret, add the name to the backend's `secret_keys` in the runtime var file, apply the runtime stack and roll the backend.
3. Build the page app with `pnpm --dir portal build` and deploy the Worker with `API_ORIGIN` (the public API origin), `PORTAL_DOMAIN`, `DASHBOARD_ORIGIN` (the dashboard's production Pages origin) and the secret `PORTAL_EDGE_TOKEN` holding the same value. Route `PORTAL_DOMAIN` and the zone's custom hostnames to it while leaving the zone's other names on their current handling. Rebuild and redeploy it when a release changes `portal/`.
4. Set `PORTAL_DOMAIN`, `CLOUDFLARE_SAAS_PORTAL_ZONE_ID` and `CLOUDFLARE_SAAS_PORTAL_API_TOKEN` on the backend and roll it. Connect links and reports are built on the portal address from then on, verified portal domains are registered on the zone within two minutes, and Cloudflare issues each certificate once the domain's records are in place.
3. Build the page app with `pnpm --dir portal build` and deploy the Worker with `API_ORIGIN` (the public API origin), `PORTAL_DOMAIN`, `DASHBOARD_ORIGIN` (the dashboard's production Pages origin) and the secret `PORTAL_EDGE_TOKEN` holding the same value. Attach `PORTAL_DOMAIN` to it and leave the zone's other names on their current handling. Rebuild and redeploy it when a release changes `portal/`.
4. Set `PORTAL_DOMAIN`, `CLOUDFLARE_SAAS_PORTAL_ZONE_ID` and `CLOUDFLARE_SAAS_PORTAL_API_TOKEN` on the backend and roll it. When the zone also holds other customer hostnames, such as tracking domains, set `CLOUDFLARE_SAAS_PORTAL_WORKER` to the Worker's name as well, so each portal domain gets its own route and no other name is sent to the portal; see [configuration](/development/configuration/#agency-portal-domains-behind-cloudflare-for-saas). Connect links and reports are built on the portal address from then on, verified portal domains are registered on the zone within two minutes, and Cloudflare issues each certificate once the domain's records are in place.
The exact routes, checks, rotation and rollback are in `deploy/cloudflare/README.md`; the variables are in [configuration](/development/configuration/#portal-service).
@@ -191,6 +191,9 @@ Optional, and only for an instance that serves agency portal domains from a Clou
| `CLOUDFLARE_SAAS_PORTAL_ZONE_ID` | The Cloudflare zone `PORTAL_DOMAIN` is on | unset | yes |
| `CLOUDFLARE_SAAS_PORTAL_API_TOKEN` | A token with `SSL and Certificates: Edit` on that zone. Treat it as a secret | unset | yes |
| `CLOUDFLARE_SAAS_PORTAL_ORIGIN` | Origin server for the hostnames the backend creates, when it differs from the zone's fallback origin | the zone's fallback origin | yes |
| `CLOUDFLARE_SAAS_PORTAL_WORKER` | Name of the portal Worker on that zone. Each portal domain then gets its own Worker route (`<domain>/*`) when it is registered, removed with it. The token also needs `Workers Routes: Edit` on the zone | unset: the zone routes its custom hostnames itself | yes |
Set `CLOUDFLARE_SAAS_PORTAL_WORKER` when the zone also holds other customer hostnames, such as tracking or redirect domains: one route for every custom hostname would send those to the portal too, and a route for each portal domain touches nothing else. A portal domain reads as registered only once its route exists, and a route to another Worker is never changed or removed. On a zone that holds portal domains only, leave it unset and route every custom hostname to the Worker once.
On Warmbly Cloud the [portal service](#portal-service) is a Cloudflare Worker on that zone, configured by `deploy/cloudflare/portal/wrangler.jsonc`; its deployment is in `deploy/cloudflare/README.md`.
+7
View File
@@ -36,6 +36,9 @@ func CloudflareSaaSOrigin() string {
// CLOUDFLARE_SAAS_PORTAL_ZONE_ID the zone PORTAL_DOMAIN is on.
// CLOUDFLARE_SAAS_PORTAL_API_TOKEN a token allowed to edit that zone's custom hostnames.
// CLOUDFLARE_SAAS_PORTAL_ORIGIN optional origin for the hostnames it creates; empty uses the zone's fallback origin.
// CLOUDFLARE_SAAS_PORTAL_WORKER optional name of the portal Worker; each hostname then gets its own route to it,
//
// for a zone that also holds other customer hostnames and so cannot route every one to the portal.
func CloudflareSaaSPortalZoneID() string {
return strings.TrimSpace(os.Getenv("CLOUDFLARE_SAAS_PORTAL_ZONE_ID"))
}
@@ -47,3 +50,7 @@ func CloudflareSaaSPortalAPIToken() string {
func CloudflareSaaSPortalOrigin() string {
return strings.TrimSpace(os.Getenv("CLOUDFLARE_SAAS_PORTAL_ORIGIN"))
}
func CloudflareSaaSPortalWorker() string {
return strings.TrimSpace(os.Getenv("CLOUDFLARE_SAAS_PORTAL_WORKER"))
}
+65 -3
View File
@@ -22,7 +22,9 @@ type Config struct {
ZoneID string
APIToken string
// Origin overrides the zone's fallback origin for the hostnames this creates; optional.
Origin string
Origin string
// Worker is the Worker script that answers the hostnames this creates, each through a route of its own; optional.
Worker string
BaseURL string
HTTPClient *http.Client
}
@@ -36,6 +38,7 @@ type Client struct {
func New(cfg Config) *Client {
cfg.ZoneID = strings.TrimSpace(cfg.ZoneID)
cfg.APIToken = strings.TrimSpace(cfg.APIToken)
cfg.Worker = strings.TrimSpace(cfg.Worker)
if cfg.ZoneID == "" || cfg.APIToken == "" {
return nil
}
@@ -121,6 +124,9 @@ func (e *APIError) Error() string {
// duplicateCode is Cloudflare's answer to a create for a hostname the zone already has.
const duplicateCode = 1406
// duplicateRouteCode is Cloudflare's answer to a create for a route pattern the zone already has.
const duplicateRouteCode = 10020
func (c *Client) do(ctx context.Context, method, path string, body any, out any) error {
var rd io.Reader
if body != nil {
@@ -185,9 +191,22 @@ func (c *Client) Find(ctx context.Context, name string) (*Hostname, error) {
return nil, nil
}
// Ensure registers name unless the zone already has it, and returns the zone's view either way.
// Ensure registers name unless the zone already has it, and returns the zone's
// view either way. With a Worker set, the name also has its route to that
// Worker before this answers, so a registered name is never left to the origin.
func (c *Client) Ensure(ctx context.Context, name string) (*Hostname, error) {
name = normalize(name)
h, err := c.ensureHostname(ctx, name)
if err != nil || h == nil {
return h, err
}
if err := c.ensureRoute(ctx, name); err != nil {
return nil, err
}
return h, nil
}
func (c *Client) ensureHostname(ctx context.Context, name string) (*Hostname, error) {
if h, err := c.Find(ctx, name); err != nil || h != nil {
return h, err
}
@@ -215,8 +234,51 @@ func (c *Client) Ensure(ctx context.Context, name string) (*Hostname, error) {
return created.hostname(), nil
}
// Remove deletes name from the zone; one the zone does not have is already removed.
// routePattern is every path on one hostname and nothing else, so no other name on the zone is touched.
func routePattern(name string) string { return name + "/*" }
// ensureRoute sends name to the Worker; a pattern the zone already routes is left as it is.
func (c *Client) ensureRoute(ctx context.Context, name string) error {
if c.cfg.Worker == "" {
return nil
}
err := c.do(ctx, http.MethodPost, "/workers/routes", map[string]any{"pattern": routePattern(name), "script": c.cfg.Worker}, nil)
var ae *APIError
if errors.As(err, &ae) && ae.has(duplicateRouteCode) {
return nil
}
return err
}
// removeRoute deletes the route this created for name, never one to another Worker.
func (c *Client) removeRoute(ctx context.Context, name string) error {
if c.cfg.Worker == "" {
return nil
}
var routes []struct {
ID string `json:"id"`
Pattern string `json:"pattern"`
Script string `json:"script"`
}
if err := c.do(ctx, http.MethodGet, "/workers/routes", nil, &routes); err != nil {
return err
}
for _, r := range routes {
if r.Pattern == routePattern(name) && r.Script == c.cfg.Worker {
if err := c.do(ctx, http.MethodDelete, "/workers/routes/"+url.PathEscape(r.ID), nil, nil); err != nil {
return err
}
}
}
return nil
}
// Remove deletes name from the zone, its route first; one the zone does not have is already removed.
func (c *Client) Remove(ctx context.Context, name string) error {
name = normalize(name)
if err := c.removeRoute(ctx, name); err != nil {
return err
}
h, err := c.Find(ctx, name)
if err != nil || h == nil {
return err
+124
View File
@@ -0,0 +1,124 @@
package cfsaas
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"strconv"
"strings"
"testing"
)
// routedZone is fakeZone plus the zone's Worker routes.
type routedZone struct {
*fakeZone
routes map[string]string // id -> pattern
script map[string]string // id -> script
posts int
refuse bool
}
func (z *routedZone) ServeHTTP(w http.ResponseWriter, r *http.Request) {
if !strings.Contains(r.URL.Path, "/workers/routes") {
z.fakeZone.ServeHTTP(w, r)
return
}
reply := func(result any) {
b, _ := json.Marshal(map[string]any{"success": true, "errors": []any{}, "result": result})
_, _ = w.Write(b)
}
switch r.Method {
case http.MethodPost:
z.posts++
if z.refuse {
w.WriteHeader(http.StatusForbidden)
_, _ = w.Write([]byte(`{"success":false,"errors":[{"code":10000,"message":"Authentication error"}]}`))
return
}
var body struct{ Pattern, Script string }
_ = json.NewDecoder(r.Body).Decode(&body)
for _, p := range z.routes {
if p == body.Pattern {
w.WriteHeader(http.StatusConflict)
_, _ = w.Write([]byte(`{"success":false,"errors":[{"code":10020,"message":"A route with the same pattern already exists."}]}`))
return
}
}
id := "r" + strconv.Itoa(z.posts)
z.routes[id], z.script[id] = body.Pattern, body.Script
reply(map[string]any{"id": id, "pattern": body.Pattern, "script": body.Script})
case http.MethodGet:
out := []any{}
for id, p := range z.routes {
out = append(out, map[string]any{"id": id, "pattern": p, "script": z.script[id]})
}
reply(out)
case http.MethodDelete:
id := r.URL.Path[strings.LastIndex(r.URL.Path, "/")+1:]
delete(z.routes, id)
delete(z.script, id)
reply(map[string]any{"id": id})
}
}
func newRouted(t *testing.T, worker string) (*Client, *routedZone) {
z := &routedZone{fakeZone: &fakeZone{hosts: map[string]string{}}, routes: map[string]string{}, script: map[string]string{}}
srv := httptest.NewServer(z)
t.Cleanup(srv.Close)
return New(Config{ZoneID: "zone", APIToken: "tok", Worker: worker, BaseURL: srv.URL}), z
}
func TestEnsureRoutesOnlyItsOwnHostnameToTheWorker(t *testing.T) {
c, z := newRouted(t, "portal")
// Another customer's name on the same zone, answered by something else.
z.routes["other"], z.script["other"] = "links.other.example/*", "tracking"
for range 2 {
if _, err := c.Ensure(context.Background(), "Portal.Agency.Example."); err != nil {
t.Fatal(err)
}
}
if len(z.routes) != 2 || z.routes["r1"] != "portal.agency.example/*" || z.script["r1"] != "portal" {
t.Fatalf("routes = %v, scripts = %v", z.routes, z.script)
}
if z.routes["other"] != "links.other.example/*" || z.script["other"] != "tracking" {
t.Fatal("another name's route was changed")
}
}
func TestEnsureFailsWhenTheRouteIsRefused(t *testing.T) {
c, z := newRouted(t, "portal")
z.refuse = true
if h, err := c.Ensure(context.Background(), "portal.agency.example"); err == nil || h != nil {
t.Fatalf("a hostname without its route must not read as registered: %+v, %v", h, err)
}
// The hostname is there, so the next attempt only has the route left to add.
z.refuse = false
if _, err := c.Ensure(context.Background(), "portal.agency.example"); err != nil || len(z.routes) != 1 || z.creates != 1 {
t.Fatalf("retry: %v, routes %v, creates %d", err, z.routes, z.creates)
}
}
func TestEnsureAddsNoRouteWithoutAWorker(t *testing.T) {
c, z := newRouted(t, "")
if _, err := c.Ensure(context.Background(), "portal.agency.example"); err != nil || z.posts != 0 {
t.Fatalf("got %v, route creates = %d", err, z.posts)
}
}
func TestRemoveTakesOnlyItsOwnRoute(t *testing.T) {
c, z := newRouted(t, "portal")
z.routes["other"], z.script["other"] = "links.other.example/*", "tracking"
// The same pattern sent somewhere else by hand is not this client's to delete.
z.routes["manual"], z.script["manual"] = "manual.agency.example/*", "something-else"
_, _ = c.Ensure(context.Background(), "portal.agency.example")
if err := c.Remove(context.Background(), "portal.agency.example"); err != nil {
t.Fatal(err)
}
if len(z.hosts) != 0 || len(z.routes) != 2 {
t.Fatalf("left hostnames %v, routes %v", z.hosts, z.routes)
}
if err := c.Remove(context.Background(), "manual.agency.example"); err != nil || z.routes["manual"] == "" {
t.Fatalf("a route to another Worker was removed: %v, %v", err, z.routes)
}
}