Wildcard tenants
A small multi-tenant product as four Hono services in one npm workspace. Each tenant gets a subdomain through a wildcard hostname, a gateway catches every other subdomain of the lane, and the exact hostnames app. and go. win over both.
Requirements
Section titled “Requirements”- devlanes, with
devlanes setuprun once - Node 22 or later
Run it
Section titled “Run it”cd web-wildcard-tenantsdevlanes startdevlanes start --no-ui prints the start as text:
example-wildcard-tenants@0 (main): 4/4 readyready app http://127.0.0.1:20540 https://app.example-wildcard-tenants.localhostready sites http://127.0.0.1:20543ready gateway http://127.0.0.1:20541ready links http://127.0.0.1:20542 https://go.example-wildcard-tenants.localhostOpen https://app.example-wildcard-tenants.localhost. The page says This is lane 0 of example-wildcard-tenants., sets a session cookie and links to the tenant pages, the short links and a subdomain no service claims.
During a start
Section titled “During a start”- The first start of a lane runs the
installtask (npm installat the example root), which installs every workspace underapps/andpackages/. - devlanes computes the lane var
sites_domainfromdomain('example-wildcard-sites'):example-wildcard-sites.localhostin lane 0,example-wildcard-sites1.localhostin lane 1. - It starts the four services with
run_script, each from its ownapps/<service>/package.json, and waits for/healthzon each. - The proxy routes the hostnames:
| Hostname | Service | Route |
|---|---|---|
app. | app | exact |
go. | links | exact |
*. | sites | wildcard |
*. | gateway | wildcard with fallback: true |
app sets session=...; Domain=example-wildcard-tenants.localhost, so the browser sends the cookie to every name under the lane domain, go. and the gateway’s subdomains included. Tenant pages sit under example-wildcard-sites.localhost, which is another site, and never get it. sites reads the tenant from the Host header, gateway names the subdomain it got, and links redirects /hello and /sale to alice’s and bob’s pages. Every service also answers /request, which returns the service, the hostname it got and the Cookie header.
Resolving wildcard names
Section titled “Resolving wildcard names”Windows 11, macOS 26 and Linux with systemd-resolved answer every *.localhost name with loopback, wildcards included, and Chrome, Edge and Firefox do so on any OS. Older macOS, Windows Server and programs that do their own DNS (workerd, musl or pure-Go binaries, containers) do not. The hosts file cannot hold wildcards, so those programs reach *.example-wildcard-sites.localhost only through the resolver strategy described in the HTTPS guide.
Try next
Section titled “Try next”On Windows, add --ssl-revoke-best-effort to every curl command below.
Ask each hostname which service answered. Exact names win and the fallback takes any other depth below the lane domain:
Terminal window curl -fsS https://app.example-wildcard-tenants.localhost/requestcurl -fsS https://go.example-wildcard-tenants.localhost/requestcurl -fsS https://billing.example-wildcard-tenants.localhost/requestcurl -fsS https://a.b.example-wildcard-tenants.localhost/request{"service":"app","host":"app.example-wildcard-tenants.localhost","cookie":null}{"service":"links","host":"go.example-wildcard-tenants.localhost","cookie":null}{"service":"gateway","host":"billing.example-wildcard-tenants.localhost","cookie":null}{"service":"gateway","host":"a.b.example-wildcard-tenants.localhost","cookie":null}Take the app’s cookie to the gateway and to a tenant. curl’s cookie jar applies
Domainthe way a browser does:Terminal window curl -fsS -c jar.txt -o /dev/null https://app.example-wildcard-tenants.localhost/curl -fsS -b jar.txt https://billing.example-wildcard-tenants.localhost/requestcurl -fsS -b jar.txt https://alice.example-wildcard-sites.localhost/requestrm jar.txt{"service":"gateway","host":"billing.example-wildcard-tenants.localhost","cookie":"session=bada74b0b665"}{"service":"sites","host":"alice.example-wildcard-sites.localhost","cookie":null}In a browser, open the app, then a tenant link and the
billing.link: the tenant page says the session was not sent, the gateway page shows it.Follow a short link:
curl -sS -o /dev/null -w '%{http_code} %{redirect_url}\n' https://go.example-wildcard-tenants.localhost/saleprints302 https://bob.example-wildcard-sites.localhost/sale.Request the bare sites domain. A wildcard does not cover its parent, so no route has the name and the TLS handshake fails:
curl -sS https://example-wildcard-sites.localhost/printscurl: (35) schannel: next InitializeSecurityContext failed: SEC_E_LOGON_DENIED (0x8009030c) - The logon attempt failedon Windows.devlanes stop links, then open https://go.example-wildcard-tenants.localhost/hello. The proxy answers503withDL201 Service not runninginstead of handing the name to the gateway, becausego.is still an exact route.devlanes start linksbrings it back.Check that the system resolver handles wildcard names without hosts-file entries:
node -e "require('node:dns').lookup('alice.example-wildcard-sites.localhost', { all: true }, (err, addrs) => console.log(err ?? addrs))"prints[ { address: '::1', family: 6 }, { address: '127.0.0.1', family: 4 } ]on Windows 11.Start a second lane:
git worktree add ../examples-checkout -b feat/checkout, thencd ../examples-checkout/web-wildcard-tenants && devlanes start.devlanes lane new --name example-wildcard-tenants-review --startin this folder gives the same lane 1 without a worktree.devlanes url lsthen lists both lanes’ routes, next to those of your other projects:ready app.example-wildcard-tenants.localhost -> example-wildcard-tenants@0:app port=20540ready *.example-wildcard-sites.localhost -> example-wildcard-tenants@0:sites port=20543ready *.example-wildcard-tenants.localhost -> example-wildcard-tenants@0:gateway port=20541 fallbackready go.example-wildcard-tenants.localhost -> example-wildcard-tenants@0:links port=20542ready app.example-wildcard-tenants1.localhost -> example-wildcard-tenants@1:app port=20530ready *.example-wildcard-sites1.localhost -> example-wildcard-tenants@1:sites port=20533ready *.example-wildcard-tenants1.localhost -> example-wildcard-tenants@1:gateway port=20531 fallbackready go.example-wildcard-tenants1.localhost -> example-wildcard-tenants@1:links port=20532https://app.example-wildcard-tenants1.localhost says
This is lane 1 of example-wildcard-tenants., its tenants live underexample-wildcard-sites1.localhost, and its session cookie never reaches lane 0.devlanes lane clean 0 --yesstops lane 0 and deletes its data and logs. Run it with1for the second lane.
devlanes.yaml: thesites_domainlane var, theinstalltask and the four services with their hostnames.apps/app/src/session.ts: sets the session cookie on the lane domain.apps/sites/src/app.tsx: reads the tenant fromHost;views/TenantPage.tsxshows which cookies arrived.apps/gateway/andapps/links/: the catch-all page and the short-link redirects.packages/shared/: the environment parsing, the lane values and the/healthz,/laneand/requestroutes the services share.