wild-cloud/wild-pc
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: raw-TCP exposure with castle-managed TLS + reach model

Browse Source 
Expose raw-TCP services (postgres) by name at <name>.<domain>:<port> and
cut the gateway's ACME wildcard cert onto them so they present a trusted
cert. Replaces the proxy/public booleans with a single `reach` enum
(off|internal|public); legacy input still parses via derived accessors.

Core:
- expose.tcp{port,tls} + TlsSpec(material: pair|combined|off, reload)
- tls.py: materialize cert files from Caddy's wildcard, reconcile on
  renewal; `castle tls` CLI; optional cert_obtained events-exec hook
  (gateway.cert_hook, gated so a plugin-less Caddy still parses)
- apply waits (bounded) for the wildcard to issue before materializing so
  a fresh-node TLS service starts with its cert in place, then scopes
  materialization to the deployments being applied
- reach: internal|public requires an expose block (no silent no-op);
  public raw-TCP guarded until tunnel support lands
- chain.pem (${tls_ca}) is the issuer chain (leaf stripped), a real CA
  bundle distinct from cert.pem
- one shared ${...} resolver (resolve_placeholders) for env and container
  run fields; run.env now expands like volumes/args; $$ escapes a literal
- validate the generated Caddyfile before reloading the gateway so an
  invalid config never degrades routing

Docs: docs/tcp-exposure.md. Tests cover reach/expose validation,
placeholder expansion + escape, issuer-chain material, TLS materialize.
This commit is contained in:
Paul Payne
2026-07-04 23:04:26 -07:00
parent 0e8bf2571f
commit 3c566540aa
20 changed files with 1382 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
core/tests/test_caddyfile.py
View File

@@ -185,6 +185,21 @@ class TestConfigSourceOfTruth:
routes = compute_routes(_make_registry(), _config({"pg": _service(5432, expose=False)}))
assert not [r for r in routes if r.name == "pg"]
def test_tcp_service_has_no_http_route(self) -> None:
"""A raw-TCP service (reach: internal + expose.tcp) is reachable by
name+port via DNS, but must NOT get an HTTP gateway route."""
tcp = SystemdDeployment.model_validate(
{
"manager": "systemd",
"run": RunPython(launcher="python", program="pg"),
"reach": "internal",
"expose": {"tcp": {"port": 5432}},
}
)
assert tcp.tcp_port == 5432 and tcp.http_exposed is False
routes = compute_routes(_make_registry(), _config({"pg": tcp}))
assert not [r for r in routes if r.name == "pg"]
def test_config_port_overrides_stale_registry(self) -> None:
registry = _make_registry(
deployed={"claw": _dep(8001, expose=True, name="claw")}

39
core/tests/test_deploy_run_cmd.py
View File

@@ -107,6 +107,45 @@ def test_container_without_secrets_has_no_env_file() -> None:
assert "--env-file" not in cmd
def test_container_placeholders_expand_in_run_fields() -> None:
"""${key} placeholders expand consistently across a container's env, volumes,
and args — env used to be the odd one out that passed through literally."""
run = RunContainer(
launcher="container",
image="img:latest",
env={"DATA": "${data_dir}/x"},
volumes=["${tls_dir}:/tls:ro"],
args=["--advertise", "${name}:${port}"],
)
ph = {
"name": "svc",
"port": "5432",
"data_dir": "/data/castle/svc",
"tls_dir": "/data/castle/svc/tls",
}
with patch("castle_core.deploy.shutil.which", return_value="/usr/bin/docker"):
cmd = _build_run_cmd("svc", run, {}, [], placeholders=ph)
joined = " ".join(cmd)
assert "DATA=/data/castle/svc/x" in joined # env expanded
assert "/data/castle/svc/tls:/tls:ro" in joined # volume expanded
assert "svc:5432" in cmd # arg expanded
def test_container_double_dollar_escapes_placeholder() -> None:
"""$${key} passes a literal ${key} through to the container's own shell/env
instead of castle expanding it (docker-compose-style escape)."""
run = RunContainer(
launcher="container",
image="img:latest",
args=["sh", "-c", "exec myd --advertise $${name}:${port}"],
)
ph = {"name": "svc", "port": "5432"}
with patch("castle_core.deploy.shutil.which", return_value="/usr/bin/docker"):
cmd = _build_run_cmd("svc", run, {}, [], placeholders=ph)
# castle expands ${port} but leaves $${name} as a literal ${name} for the shell
assert "exec myd --advertise ${name}:5432" in cmd
def test_compose_runner_up_with_resolved_file(tmp_path: Path) -> None:
"""A compose service runs `docker compose -p <project> -f <abs-file> up`."""
run = RunCompose(launcher="compose", file="docker-compose.yml")

86
core/tests/test_manifest.py
View File

@@ -4,6 +4,7 @@ from __future__ import annotations
import pytest
from castle_core.manifest import (
Reach,
BuildSpec,
CaddyDeployment,
ExposeSpec,
@@ -110,14 +111,78 @@ class TestSystemdDeployment:
)
assert s.manage.systemd.enable is True
def test_public_requires_proxy(self) -> None:
"""public without proxy is invalid (public needs an exposed process)."""
with pytest.raises(ValueError, match="public requires proxy"):
SystemdDeployment(
id="bad",
manager="systemd",
run=RunPython(launcher="python", program="svc"),
public=True,
def test_reach_ladder_and_legacy_mapping(self) -> None:
"""`reach` is canonical; legacy proxy/public map to it, and the derived
proxy/public accessors reflect it (public implies internal)."""
# An exposed reach needs an expose block (see test_reach_requires_expose),
# so give the base one; reach off doesn't, tested separately below.
base = dict(
id="svc",
manager="systemd",
run=RunPython(launcher="python", program="svc"),
expose={"http": {"internal": {"port": 9001}}},
)
# legacy input still parses
s_proxy = SystemdDeployment.model_validate({**base, "proxy": True})
assert s_proxy.reach == Reach.INTERNAL
assert s_proxy.proxy is True and s_proxy.public is False
s_pub = SystemdDeployment.model_validate({**base, "proxy": True, "public": True})
assert s_pub.reach == Reach.PUBLIC
assert s_pub.proxy is True and s_pub.public is True
# legacy public alone now simply means public (which implies internal)
assert SystemdDeployment.model_validate({**base, "public": True}).reach == Reach.PUBLIC
# new canonical field (reach off needs no expose block)
no_expose = dict(
id="svc", manager="systemd", run=RunPython(launcher="python", program="svc")
)
assert SystemdDeployment(**no_expose, reach=Reach.OFF).reach == Reach.OFF
assert SystemdDeployment(**base, reach=Reach.PUBLIC).public is True
def test_reach_requires_expose(self) -> None:
"""An exposed reach with no expose block is rejected (it would otherwise
silently no-op — no route, no subdomain, no tunnel). Replaces the old
'public requires proxy' guard."""
base = dict(manager="systemd", run=RunPython(launcher="python", program="svc"))
for reach in ("internal", "public"):
with pytest.raises(ValueError, match="requires an `expose` block"):
SystemdDeployment.model_validate({**base, "reach": reach})
# legacy public: true with no expose maps to reach public → same rejection
with pytest.raises(ValueError, match="requires an `expose` block"):
SystemdDeployment.model_validate({**base, "public": True})
def test_tcp_exposure_is_not_http_exposed(self) -> None:
"""A raw-TCP service is reachable by name+port but never HTTP-routed."""
base = dict(manager="systemd", run=RunCommand(launcher="command", argv=["pg"]))
tcp = SystemdDeployment.model_validate(
{**base, "reach": "internal", "expose": {"tcp": {"port": 5432}}}
)
assert tcp.tcp_port == 5432
assert tcp.http_exposed is False # <-- no Caddy route
http = SystemdDeployment.model_validate(
{**base, "reach": "internal", "expose": {"http": {"internal": {"port": 9001}}}}
)
assert http.http_exposed is True and http.tcp_port is None
def test_expose_is_one_protocol(self) -> None:
with pytest.raises(ValueError, match="http OR tcp"):
SystemdDeployment.model_validate(
{
"manager": "systemd",
"run": RunCommand(launcher="command", argv=["x"]),
"expose": {"http": {"internal": {"port": 1}}, "tcp": {"port": 2}},
}
)
def test_public_tcp_guarded(self) -> None:
"""reach: public on a raw-TCP service is rejected until step 5 lands."""
with pytest.raises(ValueError, match="public for a raw-TCP"):
SystemdDeployment.model_validate(
{
"manager": "systemd",
"run": RunCommand(launcher="command", argv=["x"]),
"reach": "public",
"expose": {"tcp": {"port": 5432}},
}
)
def test_no_run_is_invalid(self) -> None:
@@ -166,11 +231,12 @@ class TestModelSerialization:
internal=HttpInternal(port=9001), health_path="/health"
)
),
proxy=True,
reach=Reach.INTERNAL,
manage=ManageSpec(systemd=SystemdSpec()),
)
data = s.model_dump(exclude_none=True, exclude={"id"})
assert data["manager"] == "systemd"
assert data["run"]["launcher"] == "python"
assert data["expose"]["http"]["internal"]["port"] == 9001
assert data["proxy"] is True
assert data["reach"] == "internal"
assert "proxy" not in data # derived accessor, not serialized

112
core/tests/test_tls.py Normal file
View File

@@ -0,0 +1,112 @@
"""Tests for castle-managed TLS material (core/src/castle_core/tls.py)."""
from __future__ import annotations
from pathlib import Path
import pytest
import castle_core.config as C
import castle_core.tls as T
from castle_core.manifest import SystemdDeployment
def _write_wildcard(xdg: Path, domain: str, tag: str, acme_dir: str) -> None:
d = xdg / "caddy" / "certificates" / acme_dir / f"wildcard_.{domain}"
d.mkdir(parents=True, exist_ok=True)
(d / f"wildcard_.{domain}.crt").write_bytes(f"CERT-{tag}\n".encode())
(d / f"wildcard_.{domain}.key").write_bytes(f"KEY-{tag}\n".encode())
@pytest.fixture
def tls_env(tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
"""Isolate Caddy's cert store (XDG_DATA_HOME, read live) and DATA_DIR (patched
on the tls module) to a temp dir — no importlib.reload, so no global leak."""
domain = "civil.payne.io"
xdg = tmp_path / "xdg"
_write_wildcard(xdg, domain, "PROD", "acme-v02.api.letsencrypt.org-directory")
_write_wildcard(xdg, domain, "STAGING", "acme-staging-v02.api.letsencrypt.org-directory")
monkeypatch.setenv("XDG_DATA_HOME", str(xdg))
monkeypatch.setattr(T, "DATA_DIR", tmp_path / "data") # tls_dir_for reads this
return T, C, domain
def _cfg(C, domain, dep):
return C.CastleConfig(
root=None, gateway=C.GatewayConfig(port=9000, domain=domain), repo=None,
programs={}, deployments={"postgres": dep},
)
def _pg(material: str):
return SystemdDeployment.model_validate(
{
"manager": "systemd",
"program": "postgres",
"run": {"launcher": "container", "image": "postgres:17"},
"reach": "internal",
"expose": {"tcp": {"port": 5432, "tls": {"material": material}}},
}
)
def test_prefers_prod_over_staging(tls_env) -> None:
T, _, domain = tls_env
crt, _ = T.wildcard_cert(domain)
assert crt.read_text().strip() == "CERT-PROD"
def test_pair_material_and_idempotency(tls_env) -> None:
T, C, domain = tls_env
pg = _pg("pair")
cfg = _cfg(C, domain, pg)
assert T.materialize_tls(cfg, "postgres", pg) is True # first write
assert T.materialize_tls(cfg, "postgres", pg) is False # idempotent
td = T.tls_dir_for("postgres")
assert sorted(p.name for p in td.iterdir()) == ["cert.pem", "chain.pem", "key.pem"]
assert (td / "cert.pem").read_text().strip() == "CERT-PROD"
assert oct((td / "key.pem").stat().st_mode)[-3:] == "600" # secret
assert oct((td / "cert.pem").stat().st_mode)[-3:] == "644" # public
def test_material_switch_cleans_stale(tls_env) -> None:
T, C, domain = tls_env
pair = _pg("pair")
T.materialize_tls(_cfg(C, domain, pair), "postgres", pair)
combined = _pg("combined")
assert T.materialize_tls(_cfg(C, domain, combined), "postgres", combined) is True
td = T.tls_dir_for("postgres")
assert sorted(p.name for p in td.iterdir()) == ["chain.pem", "combined.pem"]
assert (td / "combined.pem").read_text() == "KEY-PROD\nCERT-PROD\n" # key + cert
assert oct((td / "combined.pem").stat().st_mode)[-3:] == "600"
def test_pair_chain_is_issuer_not_leaf(tls_env, tmp_path) -> None:
"""`chain.pem` (${tls_ca}) is the issuer chain — the intermediates only, leaf
stripped — so it's a real CA bundle distinct from the leaf-bearing cert.pem
(regression: they used to be byte-identical)."""
T, C, domain = tls_env
leaf = b"-----BEGIN CERTIFICATE-----\nLEAF\n-----END CERTIFICATE-----\n"
inter = b"-----BEGIN CERTIFICATE-----\nINTERMEDIATE\n-----END CERTIFICATE-----\n"
crt_dir = (
Path(tmp_path) / "xdg" / "caddy" / "certificates"
/ "acme-v02.api.letsencrypt.org-directory" / f"wildcard_.{domain}"
)
(crt_dir / f"wildcard_.{domain}.crt").write_bytes(leaf + inter)
pg = _pg("pair")
assert T.materialize_tls(_cfg(C, domain, pg), "postgres", pg) is True
td = T.tls_dir_for("postgres")
assert (td / "cert.pem").read_bytes() == leaf + inter # server presents leaf+chain
assert (td / "chain.pem").read_bytes() == inter # CA bundle = intermediates
assert (td / "cert.pem").read_bytes() != (td / "chain.pem").read_bytes()
def test_material_off_is_noop(tls_env) -> None:
T, C, domain = tls_env
off = SystemdDeployment.model_validate(
{"manager": "systemd", "program": "postgres",
"run": {"launcher": "container", "image": "postgres:17"},
"reach": "internal", "expose": {"tcp": {"port": 5432}}}
)
assert T.materialize_tls(_cfg(C, domain, off), "postgres", off) is False
assert not T.tls_dir_for("postgres").exists()