Subdomain-only gateway routing; drop path prefixes

Collapse the two proxy shapes (path_prefix + host) to a single checkbox: a
service is either port-only, or exposed at <service-name>.<gateway.domain>. Path
routes and their prefix-stripping foot-guns are gone; the subdomain is always the
service name (rename the service to change it).

- Schema: CaddySpec is just `enable` (presence = expose). service_proxy_targets
  returns (expose, port, base_url); Deployment carries `subdomain` (was
  proxy_path/proxy_host). Registry/deploy/mesh/CLI updated in lockstep.
- Generator: compute_routes emits one host route per exposed service/frontend
  (address = name). acme mode = one *.<domain> site with a reverse_proxy matcher
  per service + a file_server matcher per frontend; the :<port> site redirects to
  the dashboard. off mode = a HTTP control plane on :<port> (dashboard at / +
  /api → castle-api); other services are port-only.
- Dashboard/API: castle-app and castle-api are ordinary subdomains. The dashboard
  derives the API base at runtime (castle-api.<domain> on a subdomain, else /api)
  and calls it cross-origin — castle-api already allows CORS *. Frontends build
  with VITE_BASE=/ (served at their subdomain root).
- CLI: `service create` drops --path/--host; --no-proxy makes it port-only.
- Docs/tests reworked for the model; docs use generic placeholders only (no
  personal host/domain/IP details).
This commit is contained in:
2026-06-30 20:47:03 -07:00
parent a022a136fe
commit 43ef1cc588
23 changed files with 382 additions and 712 deletions

View File

@@ -267,10 +267,10 @@ def _build_deployed_service(
if svc.manage and svc.manage.systemd and not svc.manage.systemd.enable:
managed = False
# Routing fields (port/proxy_path/proxy_host/base_url) come from the shared
# deriver, so the registry written here and the Caddyfile computed from
# castle.yaml stay in lockstep.
proxy_path, proxy_host, port, base_url = service_proxy_targets(name, svc)
# Routing comes from the shared deriver, so the registry written here and the
# Caddyfile computed from castle.yaml stay in lockstep. `expose` is the
# checkbox; the subdomain is the service name.
expose, port, base_url = service_proxy_targets(name, svc)
health_path = None
if svc.expose and svc.expose.http:
health_path = svc.expose.http.health_path
@@ -301,27 +301,11 @@ def _build_deployed_service(
)
stop_cmd = _build_stop_cmd(name, run, source_dir)
# Proxy: a path prefix (handle_path on the gateway) and/or a hostname (a
# dedicated host site block, so a root-based app serves unchanged).
proxy_path = None
proxy_host = None
if svc.proxy and svc.proxy.caddy and svc.proxy.caddy.enable:
caddy = svc.proxy.caddy
proxy_host = caddy.host
if caddy.path_prefix:
proxy_path = caddy.path_prefix
elif not caddy.host:
# No explicit path and no host → default to /<name>.
proxy_path = f"/{name}"
# Resolve stack from referenced program
stack = None
if svc.program and svc.program in config.programs:
stack = config.programs[svc.program].stack
# Remote services proxy to an external base_url
base_url = getattr(run, "base_url", None)
return Deployment(
runner=run.runner,
run_cmd=run_cmd,
@@ -333,8 +317,7 @@ def _build_deployed_service(
stack=stack,
port=port,
health_path=health_path,
proxy_path=proxy_path,
proxy_host=proxy_host,
subdomain=(name if expose else None),
base_url=base_url,
managed=managed,
)
@@ -576,8 +559,8 @@ def _format_deployed(name: str, deployed: Deployment) -> str:
parts.append(f"port={deployed.port}")
if deployed.schedule:
parts.append(f"schedule={deployed.schedule}")
if deployed.proxy_path:
parts.append(f"proxy={deployed.proxy_path}")
if deployed.subdomain:
parts.append(f"subdomain={deployed.subdomain}")
return " ".join(parts)

View File

@@ -46,45 +46,34 @@ class GatewayRoute:
return not self.address.startswith("/")
# (proxy_path, proxy_host, port, base_url) for a service's gateway route(s).
ProxyTargets = tuple[str | None, str | None, int | None, str | None]
# (expose?, port, base_url) — expose=True → route <service-name>.<domain> here.
ProxyTargets = tuple[bool, int | None, str | None]
def service_proxy_targets(name: str, svc: ServiceSpec) -> ProxyTargets:
"""Derive a service's gateway routing fields from its spec.
"""Derive a service's gateway exposure from its spec.
The single source of truth shared by the registry build (``deploy``) and
route computation (``compute_routes``), so the deployed registry and a
freshly regenerated Caddyfile can never disagree about ports/paths/hosts.
route computation (``compute_routes``), so they never disagree. ``expose`` is
the checkbox (``proxy.caddy`` present and enabled); the subdomain is always the
service name, so there's nothing else to derive.
"""
port = None
if svc.expose and svc.expose.http:
port = svc.expose.http.internal.port
proxy_path = None
proxy_host = None
if svc.proxy and svc.proxy.caddy and svc.proxy.caddy.enable:
caddy = svc.proxy.caddy
proxy_host = caddy.host
if caddy.path_prefix:
proxy_path = caddy.path_prefix
elif not caddy.host:
# No explicit path and no host → default to /<name>.
proxy_path = f"/{name}"
expose = bool(svc.proxy and svc.proxy.caddy and svc.proxy.caddy.enable)
base_url = getattr(svc.run, "base_url", None)
return proxy_path, proxy_host, port, base_url
return expose, port, base_url
def _local_proxy_targets(
def _local_exposures(
config: CastleConfig | None, registry: NodeRegistry
) -> list[tuple[str, ProxyTargets]]:
"""Local services' routing fields, name-sorted for deterministic output.
"""Each local service's (expose?, port, base_url), name-sorted.
Prefers ``castle.yaml`` (``config.services``) as the source of truth so a
regenerated Caddyfile always reflects the current spec — this is what closes
the registry-staleness drift. Falls back to the deployed registry snapshot
only when config isn't available (load failed, or a pure-registry context).
regenerated Caddyfile always reflects the current spec; falls back to the
deployed registry snapshot when config isn't available.
"""
services = getattr(config, "services", None)
if services is not None:
@@ -92,7 +81,7 @@ def _local_proxy_targets(
(name, service_proxy_targets(name, svc)) for name, svc in services.items()
)
return sorted(
(name, (d.proxy_path, d.proxy_host, d.port, d.base_url))
(name, (d.subdomain is not None, d.port, d.base_url))
for name, d in registry.deployed.items()
)
@@ -102,10 +91,11 @@ def compute_routes(
config: CastleConfig | None = None,
remote_registries: dict[str, NodeRegistry] | None = None,
) -> list[GatewayRoute]:
"""Build the full ordered list of gateway routes (host, proxy, remote, static).
Order matters for Caddy precedence: host matchers first, then path proxies,
then cross-node, then static frontends (the root app last)."""
"""Build the ordered list of gateway routes. Every route is a host route whose
address is the service/frontend **name** (published at ``<name>.<domain>``);
``proxy`` routes reverse-proxy a local port, ``static`` routes file-serve a
frontend's dist. Path routes no longer exist. ``remote_registries`` is accepted
for signature compatibility but cross-node routing is out of scope here."""
if config is None:
try:
from castle_core.config import load_config
@@ -116,38 +106,15 @@ def compute_routes(
node = registry.node.hostname
routes: list[GatewayRoute] = []
local_paths: set[str] = set()
# Local proxy routes, derived from castle.yaml when available (else the
# deployed registry) so a regenerated Caddyfile tracks the current spec.
local = _local_proxy_targets(config, registry)
# Host-based proxy routes (whole host → backend root).
for name, (proxy_path, proxy_host, port, base_url) in local:
if proxy_host and (port or base_url):
# Exposed services → a subdomain reverse-proxy (address = service name).
for name, (expose, port, base_url) in _local_exposures(config, registry):
if expose and (port or base_url):
target = base_url or f"localhost:{port}"
routes.append(GatewayRoute(proxy_host, "proxy", target, name, node))
# Path-prefix proxy routes.
for name, (proxy_path, proxy_host, port, base_url) in local:
if proxy_path and (port or base_url):
local_paths.add(proxy_path)
target = base_url or f"localhost:{port}"
routes.append(GatewayRoute(proxy_path, "proxy", target, name, node))
# Cross-node routes — local paths take precedence.
if remote_registries:
for hostname, remote_reg in remote_registries.items():
for name, d in remote_reg.deployed.items():
if d.proxy_path and d.port and d.proxy_path not in local_paths:
local_paths.add(d.proxy_path)
routes.append(
GatewayRoute(d.proxy_path, "remote", f"{hostname}:{d.port}", name, hostname)
)
routes.append(GatewayRoute(name, "proxy", target, name, node))
# Static frontends — a behavior=frontend program with build outputs and no
# service of its own; served in place from <source>/<dist>. castle-app is the
# root app (/), others mount at /<name>.
# service of its own; served in place from <source>/<dist> at <name>.<domain>.
if config is not None:
for name, prog in sorted(config.programs.items()):
if prog.behavior != "frontend" or not prog.source:
@@ -157,10 +124,7 @@ def compute_routes(
if name in config.services: # self-serving frontend → already a proxy route
continue
serve_dir = str(Path(prog.source) / prog.build.outputs[0])
address = "/" if name == "castle-app" else f"/{name}"
if address != "/" and address in local_paths:
continue
routes.append(GatewayRoute(address, "static", serve_dir, name, node))
routes.append(GatewayRoute(name, "static", serve_dir, name, node))
return routes
@@ -180,33 +144,51 @@ def _host_matcher_block(label: str, host: str, target: str) -> list[str]:
]
def _host_static_block(label: str, host: str, serve_dir: str) -> list[str]:
"""A host matcher that file-serves a frontend's dist (with SPA fallback)."""
matcher = f"@host_{label.replace('-', '_').replace('.', '_')}"
return [
f" {matcher} host {host}",
f" handle {matcher} {{",
f" root * {serve_dir}",
" try_files {path} /index.html",
" file_server",
" }",
"",
]
# Castle's own control plane: the dashboard frontend and the API it calls. These
# names are the subdomains they're published at in acme mode, and the pair served
# on the :<port> site in off mode (no domain → no subdomains).
_DASHBOARD = "castle-app"
_API = "castle-api"
def generate_caddyfile_from_registry(
registry: NodeRegistry,
remote_registries: dict[str, NodeRegistry] | None = None,
) -> str:
"""Render the route list to a Caddyfile.
"""Render the routes to a Caddyfile. Every exposed service/frontend is a
subdomain `<name>.<domain>`; there are no path routes.
Two modes, set by `gateway.tls`:
- **off (default)** — HTTP-only. Everything (host matchers + path prefixes +
static) lives in one `:<port>` site with `auto_https off`, so a named host
can't pull the listener into TLS or try to bind :80/:443.
- **acme** — host routes are served under a single `*.<domain>` site with a
real Let's Encrypt **wildcard** cert obtained via a DNS-01 challenge (one
cert for all of them). Publicly trusted → no CA install on clients. Each
host route is published at `<label>.<domain>`, where `<label>` is the first
DNS label of the service's `proxy.caddy.host` (so a bare `claw`, or a legacy
`claw.civil.lan`, both yield `claw.<domain>`). Requires `gateway.domain`;
the DNS provider token reaches Caddy via `{env.<TOKEN>}`.
- **acme** — one `*.<domain>` site (a single DNS-01 wildcard cert) with a host
matcher per route: `reverse_proxy` for services, `file_server` for frontends.
The `:<port>` site just redirects to the dashboard subdomain (the "browse to
the box by IP" entry).
- **off / no domain** — no subdomains available, so the `:<port>` site serves
castle's control plane only: the dashboard at `/` + `reverse_proxy /api/*` →
castle-api (the one surviving path, for the dashboard's own backend). Other
services are reachable at their `host:port` directly.
"""
routes = compute_routes(registry, None, remote_registries)
node = registry.node
gw_port = node.gateway_port
mode = (node.gateway_tls or "").lower()
domain = node.gateway_domain
tls_acme = mode == "acme" and bool(domain) # acme without a domain → off-mode
host_routes = [r for r in routes if r.is_host]
tls_acme = mode == "acme" and bool(domain)
lines: list[str] = []
if tls_acme:
@@ -220,80 +202,48 @@ def generate_caddyfile_from_registry(
if os.environ.get("CASTLE_ACME_STAGING") == "1":
lines.append(f" acme_ca {_ACME_STAGING_CA}")
lines += ["}", ""]
# One wildcard site → a single DNS-01 cert covers every host route, so a
# new host-routed service needs no new cert or challenge. The published
# subdomain is the host's first label (a bare `claw` or `claw.civil.lan`
# both → `claw.<domain>`), keeping services domain-agnostic.
if host_routes:
# One wildcard site → a single cert covers every subdomain; a new service
# needs no new cert or challenge.
if routes:
lines.append(f"*.{domain} {{")
for r in host_routes:
sub = (r.address.split(".")[0] if r.address else "") or r.name or ""
lines += _host_matcher_block(r.name or r.address, f"{sub}.{domain}", r.target)
for r in routes:
host = f"{r.address}.{domain}"
if r.kind == "static":
lines += _host_static_block(r.name or r.address, host, r.target)
else:
lines += _host_matcher_block(r.name or r.address, host, r.target)
lines.append("}")
lines.append("")
else:
# HTTP-only: keep auto-HTTPS off so the bare-port site stays plain HTTP
# and named hosts don't trigger cert provisioning.
if mode == "acme" and not domain:
lines.append("# gateway.tls=acme but gateway.domain is unset — host routes")
lines.append("# fall back to plain-HTTP matchers on the gateway port.")
lines += ["{", " auto_https off", "}", ""]
lines.append(f":{gw_port} {{")
# Trailing-slash redirect: `handle_path /foo/*` doesn't match the bare `/foo`,
# so without this the no-slash form falls through to the root catch-all
# (serving the wrong app). Redirect /foo → /foo/ for each path-prefix route.
# (Caddy's bare path matcher is exact, so /foo/bar is unaffected.)
redirs = [r.address for r in routes if r.address.startswith("/") and r.address != "/"]
for prefix in redirs:
lines.append(f" redir {prefix} {prefix}/")
if redirs:
lines.append("")
root_static: GatewayRoute | None = None
for r in routes:
if r.kind == "static" and r.address == "/":
root_static = r # the root app is the catch-all, emitted last
continue
if r.kind == "static":
lines += [
f" handle_path {r.address}/* {{",
f" root * {r.target}",
" try_files {path} /index.html",
" file_server",
" }",
"",
]
elif r.is_host: # host-based proxy
if tls_acme:
continue # emitted in the *.<domain> wildcard site above
lines += _host_matcher_block(r.name or r.address, r.address, r.target)
else: # path-prefix proxy (local or remote)
if r.kind == "remote":
lines.append(f" # {r.name} on {r.node}")
lines += [
f" handle_path {r.address}/* {{",
f" reverse_proxy {r.target}",
" }",
"",
]
if root_static is not None:
# Redirect the bare gateway port to the dashboard subdomain.
lines += [
" handle {",
f" root * {root_static.target}",
" try_files {path} /index.html",
" file_server",
" }",
]
else:
lines += [
" handle / {",
f" root * {SPECS_DIR / 'app'}",
" file_server",
" }",
f":{gw_port} {{",
f" redir https://{_DASHBOARD}.{domain}{{uri}}",
"}",
]
return "\n".join(lines)
lines.append("}")
# off mode: HTTP-only control plane on :<port>.
if mode == "acme" and not domain:
lines.append("# gateway.tls=acme but gateway.domain is unset — serving the")
lines.append("# control plane on the gateway port; services are port-only.")
lines += ["{", " auto_https off", "}", "", f":{gw_port} {{"]
api = next((r for r in routes if r.name == _API and r.kind == "proxy"), None)
if api is not None:
lines += [
" handle_path /api/* {",
f" reverse_proxy {api.target}",
" }",
"",
]
app = next((r for r in routes if r.name == _DASHBOARD and r.kind == "static"), None)
root = app.target if app is not None else str(SPECS_DIR / "app")
lines += [
" handle {",
f" root * {root}",
" try_files {path} /index.html",
" file_server",
" }",
"}",
]
return "\n".join(lines)

View File

@@ -146,12 +146,10 @@ class ExposeSpec(BaseModel):
class CaddySpec(BaseModel):
# The "expose" checkbox: when present and enabled, the gateway routes
# <service-name>.<gateway.domain> to this service (whole host → backend root).
# The subdomain is always the service name — rename the service to change it.
enable: bool = True
path_prefix: str | None = None
# Route by hostname instead of (or alongside) a path prefix. The whole host
# maps to the backend root, so an app built with base="/" works unchanged —
# the fix for proxying a root-based SPA the gateway can't rebuild.
host: str | None = None
extra_snippets: list[str] = Field(default_factory=list)

View File

@@ -52,8 +52,9 @@ class Deployment:
stack: str | None = None
port: int | None = None
health_path: str | None = None
proxy_path: str | None = None
proxy_host: str | None = None
# Exposed at <subdomain>.<gateway.domain> (the subdomain is the service name),
# or None when the service is reachable only at its host:port.
subdomain: str | None = None
base_url: str | None = None
schedule: str | None = None
managed: bool = False
@@ -121,8 +122,7 @@ def load_registry(path: Path | None = None) -> NodeRegistry:
stack=comp_data.get("stack"),
port=comp_data.get("port"),
health_path=comp_data.get("health_path"),
proxy_path=comp_data.get("proxy_path"),
proxy_host=comp_data.get("proxy_host"),
subdomain=comp_data.get("subdomain"),
base_url=comp_data.get("base_url"),
schedule=comp_data.get("schedule"),
managed=comp_data.get("managed", False),
@@ -178,10 +178,8 @@ def save_registry(registry: NodeRegistry, path: Path | None = None) -> None:
entry["port"] = comp.port
if comp.health_path:
entry["health_path"] = comp.health_path
if comp.proxy_path:
entry["proxy_path"] = comp.proxy_path
if comp.proxy_host:
entry["proxy_host"] = comp.proxy_host
if comp.subdomain:
entry["subdomain"] = comp.subdomain
if comp.base_url:
entry["base_url"] = comp.base_url
if comp.schedule:

View File

@@ -71,11 +71,10 @@ async def _run(
def _vite_base(name: str) -> str:
"""The base path a castle-served static frontend builds against.
Matches the Caddyfile serve prefix: castle-app is the root app ('/'); every
other static frontend mounts at '/<name>/'. Exposed to the build as VITE_BASE
so the bundle's absolute asset URLs resolve at the gateway subpath (the
vite.config reads `base: process.env.VITE_BASE ?? '/'`)."""
return "/" if name == "castle-app" else f"/{name}/"
Every frontend now serves at the **root of its own subdomain**
(`<name>.<gateway.domain>`), so the base is always '/'. Exposed to the build
as VITE_BASE (the vite.config reads `base: process.env.VITE_BASE ?? '/'`)."""
return "/"
def _source_dir(comp: ProgramSpec, root: Path) -> Path:

View File

@@ -1,8 +1,7 @@
"""Tests for Caddyfile generation from registry."""
"""Tests for Caddyfile generation — subdomain-only routing model."""
from __future__ import annotations
import pytest
from castle_core.config import CastleConfig, GatewayConfig
@@ -11,10 +10,12 @@ from castle_core.generators.caddyfile import (
generate_caddyfile_from_registry,
)
from castle_core.manifest import (
BuildSpec,
CaddySpec,
ExposeSpec,
HttpExposeSpec,
HttpInternal,
ProgramSpec,
ProxySpec,
RunPython,
ServiceSpec,
@@ -40,9 +41,7 @@ def _make_registry(
gateway_tls: str | None = None,
gateway_domain: str | None = None,
acme_email: str | None = None,
acme_dns_provider: str = "cloudflare",
) -> NodeRegistry:
"""Create a test registry."""
return NodeRegistry(
node=NodeConfig(
hostname="test",
@@ -50,363 +49,151 @@ def _make_registry(
gateway_tls=gateway_tls,
gateway_domain=gateway_domain,
acme_email=acme_email,
acme_dns_provider=acme_dns_provider,
),
deployed=deployed or {},
)
class TestCaddyfileFromRegistry:
"""Tests for registry-based Caddyfile generation."""
def test_contains_gateway_port(self) -> None:
"""Caddyfile uses the configured gateway port."""
registry = _make_registry(gateway_port=18000)
caddyfile = generate_caddyfile_from_registry(registry)
assert ":18000 {" in caddyfile
def test_contains_service_routes(self) -> None:
"""Caddyfile has reverse proxy routes for deployed services."""
registry = _make_registry(
deployed={
"test-svc": Deployment(
runner="python",
run_cmd=["uv", "run", "test-svc"],
port=19000,
proxy_path="/test-svc",
),
}
)
caddyfile = generate_caddyfile_from_registry(registry)
assert "handle_path /test-svc/*" in caddyfile
assert "reverse_proxy localhost:19000" in caddyfile
def test_disables_auto_https(self) -> None:
"""The gateway is HTTP-only; auto_https must be off so named hosts don't
flip the listener to TLS or try to bind :80."""
caddyfile = generate_caddyfile_from_registry(_make_registry())
assert "auto_https off" in caddyfile
def test_host_route_uses_matcher_in_main_site(self) -> None:
"""A proxy_host becomes a host matcher inside the :9000 site (not a
separate site block, which would split the listener into TLS)."""
registry = _make_registry(
deployed={
"lake": Deployment(
runner="python",
run_cmd=["lake"],
port=8420,
proxy_host="lake.example.lan",
),
}
)
caddyfile = generate_caddyfile_from_registry(registry)
assert "@host_lake host lake.example.lan" in caddyfile
assert "handle @host_lake {" in caddyfile
assert "reverse_proxy localhost:8420" in caddyfile
# No separate hostname site block on the gateway port.
assert "lake.example.lan:9000 {" not in caddyfile
def test_skips_non_proxied(self) -> None:
"""Components without proxy_path are not in Caddyfile."""
registry = _make_registry(
deployed={
"test-tool": Deployment(
runner="command",
run_cmd=["test-tool"],
),
}
)
caddyfile = generate_caddyfile_from_registry(registry)
assert "test-tool" not in caddyfile
def test_fallback_when_no_static(self) -> None:
"""Uses fallback dashboard path when static dir doesn't exist."""
registry = _make_registry()
caddyfile = generate_caddyfile_from_registry(registry)
assert "handle / {" in caddyfile
assert "file_server" in caddyfile
def test_proxy_routes_before_dashboard(self) -> None:
"""Service proxy routes appear before the dashboard catch-all."""
registry = _make_registry(
deployed={
"test-svc": Deployment(
runner="python",
run_cmd=["uv", "run", "test-svc"],
port=19000,
proxy_path="/test-svc",
),
}
)
caddyfile = generate_caddyfile_from_registry(registry)
proxy_pos = caddyfile.index("handle_path")
handle_pos = caddyfile.index("handle /")
assert proxy_pos < handle_pos
def test_multiple_services(self) -> None:
"""Multiple services get separate proxy routes."""
registry = _make_registry(
deployed={
"svc-a": Deployment(
runner="python",
run_cmd=["uv", "run", "svc-a"],
port=9001,
proxy_path="/svc-a",
),
"svc-b": Deployment(
runner="python",
run_cmd=["uv", "run", "svc-b"],
port=9002,
proxy_path="/svc-b",
),
}
)
caddyfile = generate_caddyfile_from_registry(registry)
assert "handle_path /svc-a/*" in caddyfile
assert "reverse_proxy localhost:9001" in caddyfile
assert "handle_path /svc-b/*" in caddyfile
assert "reverse_proxy localhost:9002" in caddyfile
def _service(port: int, path: str | None = None, host: str | None = None) -> ServiceSpec:
"""A minimal python ServiceSpec with an HTTP port and a caddy proxy route."""
caddy = CaddySpec(path_prefix=path, host=host)
return ServiceSpec(
run=RunPython(runner="python", program="svc"),
expose=ExposeSpec(http=HttpExposeSpec(internal=HttpInternal(port=port))),
proxy=ProxySpec(caddy=caddy),
def _dep(port: int, *, expose: bool, name: str | None = None, runner: str = "python") -> Deployment:
"""A deployed service; exposed at <name>.<domain> when expose=True."""
return Deployment(
runner=runner, run_cmd=["x"], port=port, subdomain=(name if expose else None)
)
def _config(services: dict[str, ServiceSpec]) -> CastleConfig:
def _acme(deployed: dict[str, Deployment], domain: str | None = "example.com") -> NodeRegistry:
return _make_registry(
gateway_tls="acme", gateway_domain=domain, acme_email="p@e.com", deployed=deployed
)
class TestAcmeMode:
"""gateway.tls=acme → one *.domain wildcard site; every service is a subdomain."""
def test_global_acme_block(self) -> None:
cf = generate_caddyfile_from_registry(_acme({"api": _dep(9020, expose=True, name="api")}))
assert "email p@e.com" in cf
assert "acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}" in cf
def test_service_is_a_subdomain_matcher(self) -> None:
cf = generate_caddyfile_from_registry(
_acme({"openclaw": _dep(18789, expose=True, name="openclaw")})
)
assert "*.example.com {" in cf
# Subdomain is the service name.
assert "@host_openclaw host openclaw.example.com" in cf
assert "reverse_proxy localhost:18789" in cf
def test_port_9000_redirects_to_dashboard(self) -> None:
cf = generate_caddyfile_from_registry(_acme({"api": _dep(9020, expose=True, name="api")}))
assert ":9000 {" in cf
assert "redir https://castle-app.example.com{uri}" in cf
def test_no_path_routes(self) -> None:
cf = generate_caddyfile_from_registry(_acme({"api": _dep(9020, expose=True, name="api")}))
assert "handle_path" not in cf
assert "redir /" not in cf # no path-prefix trailing-slash redirects
assert "auto_https off" not in cf
def test_unexposed_service_not_routed(self) -> None:
cf = generate_caddyfile_from_registry(_acme({"pg": _dep(5432, expose=False, name="pg")}))
assert "pg.example.com" not in cf
def test_staging_toggle(self, monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv("CASTLE_ACME_STAGING", "1")
cf = generate_caddyfile_from_registry(_acme({"api": _dep(9020, expose=True, name="api")}))
assert "acme_ca https://acme-staging-v02.api.letsencrypt.org/directory" in cf
def test_static_frontend_is_a_file_server_subdomain(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
# Static frontends come from config.programs, so hand the generator a config.
import castle_core.config as config_mod
cfg = _config(
services={},
programs={
"castle-app": ProgramSpec(
behavior="frontend", source="/data/repos/castle/app",
build=BuildSpec(outputs=["dist"]),
)
},
)
monkeypatch.setattr(config_mod, "load_config", lambda *a, **k: cfg)
cf = generate_caddyfile_from_registry(_acme({}))
assert "@host_castle_app host castle-app.example.com" in cf
assert "root * /data/repos/castle/app/dist" in cf
assert "try_files {path} /index.html" in cf
assert "file_server" in cf
class TestOffMode:
"""No domain → HTTP-only control plane on :<port>: dashboard at / + /api → castle-api.
Other services are port-only (not routed)."""
def test_control_plane(self) -> None:
cf = generate_caddyfile_from_registry(
_make_registry(deployed={"castle-api": _dep(9020, expose=True, name="castle-api")})
)
assert "auto_https off" in cf
assert "handle_path /api/* {" in cf
assert "reverse_proxy localhost:9020" in cf
assert "handle {" in cf # dashboard catch-all (SPA fallback)
def test_other_services_not_routed_in_off_mode(self) -> None:
cf = generate_caddyfile_from_registry(
_make_registry(deployed={"litellm": _dep(4000, expose=True, name="litellm")})
)
assert "litellm" not in cf # no subdomains without a domain
def _service(port: int, *, expose: bool) -> ServiceSpec:
return ServiceSpec(
run=RunPython(runner="python", program="svc"),
expose=ExposeSpec(http=HttpExposeSpec(internal=HttpInternal(port=port))),
proxy=ProxySpec(caddy=CaddySpec()) if expose else None,
)
def _config(
services: dict[str, ServiceSpec], programs: dict[str, ProgramSpec] | None = None
) -> CastleConfig:
return CastleConfig(
root=None, # type: ignore[arg-type]
gateway=GatewayConfig(port=9000),
repo=None,
programs={},
programs=programs or {},
services=services,
jobs={},
)
class TestLocalRoutesFromConfig:
"""castle.yaml is the source of truth for local routes — a regenerated
Caddyfile must track the spec even when the deployed registry is stale.
This is the regression guard for the service-edit drift."""
class TestConfigSourceOfTruth:
"""compute_routes derives exposure/port from castle.yaml (the checkbox), so a
regenerated Caddyfile tracks the spec, not a stale registry."""
def test_exposed_service_becomes_a_route(self) -> None:
routes = compute_routes(_make_registry(), _config({"claw": _service(18789, expose=True)}))
r = next(r for r in routes if r.name == "claw")
assert r.kind == "proxy"
assert r.address == "claw" # subdomain label = name
assert r.target == "localhost:18789"
def test_unexposed_service_has_no_route(self) -> None:
routes = compute_routes(_make_registry(), _config({"pg": _service(5432, expose=False)}))
assert not [r for r in routes if r.name == "pg"]
def test_config_port_overrides_stale_registry(self) -> None:
# Registry was deployed with the OLD port; castle.yaml now says 8002.
registry = _make_registry(
deployed={
"app": Deployment(
runner="python", run_cmd=["app"], port=8001, proxy_path="/app"
),
}
deployed={"claw": _dep(8001, expose=True, name="claw")}
)
config = _config({"app": _service(port=8002, path="/app")})
config = _config({"claw": _service(8002, expose=True)})
routes = compute_routes(registry, config)
targets = {r.target for r in routes if r.address == "/app"}
assert targets == {"localhost:8002"} # config wins, not the stale 8001
assert {r.target for r in routes if r.name == "claw"} == {"localhost:8002"}
def test_config_path_overrides_stale_registry(self) -> None:
registry = _make_registry(
deployed={
"app": Deployment(
runner="python", run_cmd=["app"], port=8001, proxy_path="/old"
),
}
def test_fallback_to_registry_without_config(self) -> None:
# load_config is isolated (raises) → generate uses the registry snapshot.
cf = generate_caddyfile_from_registry(
_acme({"claw": _dep(8001, expose=True, name="claw")})
)
config = _config({"app": _service(port=8001, path="/new")})
addrs = {r.address for r in compute_routes(registry, config) if r.kind == "proxy"}
assert addrs == {"/new"}
def test_falls_back_to_registry_without_config(self) -> None:
# No config available (load_config is isolated to raise) → use registry.
registry = _make_registry(
deployed={
"app": Deployment(
runner="python", run_cmd=["app"], port=8001, proxy_path="/app"
),
}
)
caddyfile = generate_caddyfile_from_registry(registry)
assert "reverse_proxy localhost:8001" in caddyfile
class TestCaddyfileOffMode:
"""gateway.tls unset/off → HTTP-only: host matchers live on the :<port> site."""
def _host_registry(self) -> NodeRegistry:
return _make_registry(
deployed={
"claw": Deployment(
runner="node", run_cmd=["claw"], port=18789, proxy_host="claw.civil.lan"
),
"api": Deployment(
runner="python", run_cmd=["api"], port=9020, proxy_path="/api"
),
},
)
def test_host_matcher_and_auto_https_off(self) -> None:
caddyfile = generate_caddyfile_from_registry(self._host_registry())
assert "auto_https off" in caddyfile
assert "@host_claw host claw.civil.lan" in caddyfile
assert "tls internal" not in caddyfile # internal mode is gone
assert "claw.civil.lan {" not in caddyfile # not a standalone TLS site
def test_path_routes_on_http_port(self) -> None:
caddyfile = generate_caddyfile_from_registry(self._host_registry())
assert ":9000 {" in caddyfile
assert "handle_path /api/*" in caddyfile
def test_routing_is_runner_agnostic(self) -> None:
"""A compose-runner service with a host route is matched like any other."""
registry = _make_registry(
deployed={
"supabase": Deployment(
runner="compose",
run_cmd=["docker", "compose", "-p", "castle-supabase", "up"],
port=8000,
proxy_host="supabase.lan",
),
},
)
caddyfile = generate_caddyfile_from_registry(registry)
assert "@host_supabase host supabase.lan" in caddyfile
assert "reverse_proxy localhost:8000" in caddyfile
class TestCaddyfileTlsAcme:
"""gateway.tls=acme → host routes served under one *.domain wildcard site
with a Let's Encrypt cert via DNS-01."""
def _acme_registry(self, domain: str | None = "civil.payne.io") -> NodeRegistry:
return _make_registry(
gateway_tls="acme",
gateway_domain=domain,
acme_email="paul@example.com",
deployed={
"claw": Deployment(
runner="node", run_cmd=["claw"], port=18789, proxy_host="claw.civil.lan"
),
"api": Deployment(
runner="python", run_cmd=["api"], port=9020, proxy_path="/api"
),
},
)
def test_global_email_and_acme_dns(self) -> None:
caddyfile = generate_caddyfile_from_registry(self._acme_registry())
assert "email paul@example.com" in caddyfile
assert "acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}" in caddyfile
def test_wildcard_site_with_derived_host_matcher(self) -> None:
caddyfile = generate_caddyfile_from_registry(self._acme_registry())
assert "*.civil.payne.io {" in caddyfile
# Published name = the host's first label under the gateway domain.
assert "@host_claw host claw.civil.payne.io" in caddyfile
assert "reverse_proxy localhost:18789" in caddyfile
def test_subdomain_from_host_label_not_service_name(self) -> None:
# Service is named "openclaw" but declares host label "claw" → the label
# wins (published as claw.<domain>), so the declared name is authoritative.
registry = _make_registry(
gateway_tls="acme",
gateway_domain="civil.payne.io",
acme_email="paul@example.com",
deployed={
"openclaw": Deployment(
runner="node", run_cmd=["c"], port=18789, proxy_host="claw"
),
},
)
caddyfile = generate_caddyfile_from_registry(registry)
assert "host claw.civil.payne.io" in caddyfile
assert "openclaw.civil.payne.io" not in caddyfile
def test_path_routes_stay_on_http_port(self) -> None:
caddyfile = generate_caddyfile_from_registry(self._acme_registry())
assert ":9000 {" in caddyfile
assert "handle_path /api/*" in caddyfile
def test_no_auto_https_off_and_no_internal_ca(self) -> None:
caddyfile = generate_caddyfile_from_registry(self._acme_registry())
assert "auto_https off" not in caddyfile
assert "tls internal" not in caddyfile
# The .lan host must not leak into the :9000 site as a plain matcher.
assert "claw.civil.lan" not in caddyfile
def test_staging_toggle(self, monkeypatch: pytest.MonkeyPatch) -> None:
monkeypatch.setenv("CASTLE_ACME_STAGING", "1")
caddyfile = generate_caddyfile_from_registry(self._acme_registry())
assert "acme_ca https://acme-staging-v02.api.letsencrypt.org/directory" in caddyfile
def test_acme_without_domain_falls_back_to_http(self) -> None:
# No domain → no *.None site; host route degrades to an off-mode matcher.
caddyfile = generate_caddyfile_from_registry(self._acme_registry(domain=None))
assert "*." not in caddyfile
assert "auto_https off" in caddyfile
assert "@host_claw host claw.civil.lan" in caddyfile
class TestCaddyfileRemoteRegistries:
"""Tests for cross-node routing in Caddyfile."""
def test_remote_routes_included(self) -> None:
"""Remote services get reverse_proxy entries to their hostname."""
local = _make_registry(
deployed={
"local-svc": Deployment(
runner="python", run_cmd=["svc"], port=9001, proxy_path="/local"
),
}
)
remote = _make_registry(
deployed={
"remote-svc": Deployment(
runner="python", run_cmd=["svc"], port=9050, proxy_path="/remote"
),
}
)
remote.node.hostname = "devbox"
caddyfile = generate_caddyfile_from_registry(local, remote_registries={"devbox": remote})
assert "reverse_proxy localhost:9001" in caddyfile
assert "reverse_proxy devbox:9050" in caddyfile
assert "handle_path /remote/*" in caddyfile
def test_local_takes_precedence(self) -> None:
"""If local and remote use the same path, local wins."""
local = _make_registry(
deployed={
"svc": Deployment(
runner="python", run_cmd=["svc"], port=9001, proxy_path="/api"
),
}
)
remote = _make_registry(
deployed={
"svc": Deployment(
runner="python", run_cmd=["svc"], port=9001, proxy_path="/api"
),
}
)
remote.node.hostname = "devbox"
caddyfile = generate_caddyfile_from_registry(local, remote_registries={"devbox": remote})
assert "reverse_proxy localhost:9001" in caddyfile
assert "devbox" not in caddyfile
def test_no_remote_when_none(self) -> None:
"""No remote routes when remote_registries is None."""
local = _make_registry(
deployed={
"svc": Deployment(
runner="python", run_cmd=["svc"], port=9001, proxy_path="/api"
),
}
)
caddyfile = generate_caddyfile_from_registry(local, remote_registries=None)
assert "reverse_proxy localhost:9001" in caddyfile
# Only one reverse_proxy line
assert caddyfile.count("reverse_proxy") == 1
assert "@host_claw host claw.example.com" in cf

View File

@@ -46,7 +46,7 @@ class TestLoadConfig:
"""Service has correct proxy spec."""
config = load_config(castle_root)
svc = config.services["test-svc"]
assert svc.proxy.caddy.path_prefix == "/test-svc"
assert svc.proxy.caddy.enable is True # exposed at <name>.<gateway.domain>
def test_service_run_spec(self, castle_root: Path) -> None:
"""Service has correct RunSpec."""

View File

@@ -92,9 +92,9 @@ class TestServiceSpec:
s = ServiceSpec(
id="svc",
run=RunPython(runner="python", program="svc"),
proxy=ProxySpec(caddy=CaddySpec(path_prefix="/svc")),
proxy=ProxySpec(caddy=CaddySpec()),
)
assert s.proxy.caddy.path_prefix == "/svc"
assert s.proxy.caddy.enable is True
def test_service_with_manage(self) -> None:
"""Service with systemd management."""
@@ -185,10 +185,10 @@ class TestModelSerialization:
internal=HttpInternal(port=9001), health_path="/health"
)
),
proxy=ProxySpec(caddy=CaddySpec(path_prefix="/svc")),
proxy=ProxySpec(caddy=CaddySpec()),
manage=ManageSpec(systemd=SystemdSpec()),
)
data = s.model_dump(exclude_none=True, exclude={"id"})
assert data["run"]["runner"] == "python"
assert data["expose"]["http"]["internal"]["port"] == 9001
assert data["proxy"]["caddy"]["path_prefix"] == "/svc"
assert data["proxy"]["caddy"]["enable"] is True