Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,15 @@ and listed with their assets on the

### Added

- **A static service forwards paths to another server.** `forward = {
"/api" = "{service.api.url}" }` on a `kind = "static"` service, also in a
profile, sends requests below a prefix on as a reverse proxy in front of
the bundle would: the path unchanged, `Host` kept, `X-Forwarded-*` added,
answers streamed (server-sent events), WebSocket upgrades passed. A
single-page app that calls its API on its own origin now runs as a static
build in an acceptance profile without a proxy of its own (#551,
ADR-0110). Needs `requires = "0.49.0"`.

- **An order menu on the start page.** The same menu as the sidebar's (by
name, last opened first, last edited first; favourites always first) sits
in the filter row and orders the tiles and the list. The order is one
Expand Down
154 changes: 154 additions & 0 deletions crates/devstack-config/src/forward.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,154 @@
//! `forward` of a `kind = "static"` service (ADR-0110): which requests go to
//! another server, and where. The check and the static server share these
//! rules, so a file `devstack check` passes is one the server takes.

/// A prefix such as `/api` or `/api/v2`: a path of plain segments, without a
/// trailing `/` (it matches at a segment boundary anyway).
pub fn prefix(p: &str) -> Result<(), String> {
let Some(rest) = p.strip_prefix('/') else {
return Err("a path prefix starts with `/`, e.g. `/api`".into());
};
if rest.is_empty() {
return Err(
"`/` would forward every request, the bundle's files too: name a prefix below it"
.into(),
);
}
for seg in rest.split('/') {
if seg.is_empty() || seg == "." || seg == ".." {
return Err(
"plain path segments only, without `//`, `.`, `..` or a trailing `/`".into(),
);
}
if let Some(c) = seg
.chars()
.find(|c| !(c.is_ascii_alphanumeric() || "-._~".contains(*c)))
{
return Err(format!("`{c}`: a prefix takes letters, digits and `-._~`"));
}
}
Ok(())
}

/// Whether request path `path` lies below `prefix`: the prefix itself, or
/// the prefix followed by `/` (`/api` takes `/api/x`, not `/apix`).
pub fn matches(prefix: &str, path: &str) -> bool {
path.strip_prefix(prefix)
.is_some_and(|rest| rest.is_empty() || rest.starts_with('/'))
}

/// The forward whose prefix takes `path`: the longest one.
pub fn pick<'a, T>(forwards: &'a [(String, T)], path: &str) -> Option<&'a (String, T)> {
forwards
.iter()
.filter(|(p, _)| matches(p, path))
.max_by_key(|(p, _)| p.len())
}

/// A target: an origin `http://host[:port]` (one trailing `/` allowed),
/// as host and port.
pub fn origin(t: &str) -> Result<(String, u16), String> {
if t.starts_with("https://") {
return Err(
"devstack forwards to plain HTTP only: give the target's `http://` port (a service with `health.insecure_tls` speaks HTTPS)".into(),
);
}
let Some(rest) = t.strip_prefix("http://") else {
return Err("a target is an origin, `http://host:port`, e.g. `{service.api.url}`".into());
};
let authority = rest.strip_suffix('/').unwrap_or(rest);
if authority.is_empty() {
return Err("names no host: `http://host:port`".into());
}
if authority.contains(['/', '?', '#', '@']) {
return Err(
"a target is an origin without a path: the request's path goes on unchanged".into(),
);
}
let (host, port) = match authority.strip_prefix('[') {
// An IPv6 address, `[::1]:8080`.
Some(v6) => {
let (h, after) = v6
.split_once(']')
.ok_or_else(|| "an unclosed `[` in the host".to_string())?;
(h, after.strip_prefix(':'))
}
None => match authority.rsplit_once(':') {
Some((h, p)) => (h, Some(p)),
None => (authority, None),
},
};
if host.is_empty() {
return Err("names no host: `http://host:port`".into());
}
let port = match port {
None => 80,
Some(p) => p
.parse::<u16>()
.ok()
.filter(|p| *p > 0)
.ok_or_else(|| format!("`{p}` is not a port"))?,
};
Ok((host.to_string(), port))
}

#[cfg(test)]
mod tests {
use super::*;

#[test]
fn prefixes() {
for ok in ["/api", "/api/v2", "/file", "/otel", "/a-b_c.d~e"] {
assert_eq!(prefix(ok), Ok(()), "{ok}");
}
for bad in [
"api", "/", "/api/", "//api", "/a/../b", "/a b", "/a?x", "/a%20",
] {
assert!(prefix(bad).is_err(), "{bad}");
}
}

#[test]
fn the_longest_prefix_wins_at_a_segment_boundary() {
let f = vec![
("/api".to_string(), 1),
("/api/files".to_string(), 2),
("/file".to_string(), 3),
];
let to = |p: &str| pick(&f, p).map(|(_, n)| *n);
assert_eq!(to("/api"), Some(1));
assert_eq!(to("/api/users/7"), Some(1));
assert_eq!(to("/api/files"), Some(2));
assert_eq!(to("/api/files/a.pdf"), Some(2));
assert_eq!(to("/api/filesystem"), Some(1));
assert_eq!(to("/apix"), None, "not at a segment boundary");
assert_eq!(to("/files"), None);
assert_eq!(to("/"), None);
assert_eq!(to("/main.js"), None);
}

#[test]
fn origins() {
assert_eq!(
origin("http://127.0.0.1:5000"),
Ok(("127.0.0.1".into(), 5000))
);
assert_eq!(
origin("http://127.0.0.1:5000/"),
Ok(("127.0.0.1".into(), 5000))
);
assert_eq!(origin("http://localhost"), Ok(("localhost".into(), 80)));
assert_eq!(origin("http://[::1]:8080"), Ok(("::1".into(), 8080)));
for bad in [
"https://127.0.0.1:5001",
"127.0.0.1:5000",
"http://127.0.0.1:5000/api",
"http://127.0.0.1:x",
"http://:5000",
"http://",
"http://user@host:1",
] {
assert!(origin(bad).is_err(), "{bad}");
}
}
}
5 changes: 5 additions & 0 deletions crates/devstack-config/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@
//! interpolation. See ADR-0017 and plan §4.

pub mod compat;
pub mod forward;
pub mod interpolate;
pub mod model;
pub mod validate;
Expand Down Expand Up @@ -79,6 +80,10 @@ pub const LINK_SINCE: &str = "0.44.0";
/// sets it wants `requires` at least this.
pub const SHORTCUT_SINCE: &str = "0.48.0";

/// The first devstack that knows a static service's `forward` (ADR-0110): a
/// file that sets it wants `requires` at least this.
pub const FORWARD_SINCE: &str = "0.49.0";

/// `"1.2.3"`, `"v1.2"`, `"1"` as numbers; `None` when malformed. A
/// pre-release or build suffix (`1.2.3-rc1`, `1.2.3+abc`) is ignored here;
/// [`version_order`] takes it into account.
Expand Down
14 changes: 14 additions & 0 deletions crates/devstack-config/src/model.rs
Original file line number Diff line number Diff line change
Expand Up @@ -150,6 +150,9 @@ pub struct ServiceProfile {
/// What ends what `run` started outside its process tree (ADR-0059).
pub stop: Option<String>,
pub spa: Option<bool>,
/// Added to the service's `forward` (ADR-0110).
#[serde(default)]
pub forward: BTreeMap<String, String>,
pub cwd: Option<String>,
pub health: Option<Health>,
/// Added to the service's `env`, over the profile's.
Expand Down Expand Up @@ -286,6 +289,7 @@ impl Stack {
}
if k != Kind::Static {
svc.spa = None;
svc.forward.clear();
}
if k != Kind::Service {
svc.hot_reload = None;
Expand Down Expand Up @@ -313,6 +317,9 @@ impl Stack {
if o.spa.is_some() {
svc.spa = o.spa;
}
for (k, v) in &o.forward {
svc.forward.insert(k.clone(), v.clone());
}
if o.cwd.is_some() {
svc.cwd = o.cwd.clone();
}
Expand Down Expand Up @@ -916,6 +923,13 @@ pub struct Service {
/// `kind = "static"`: answer paths without a file extension with
/// `index.html` (client-side routes of a single-page app). Default `true`.
pub spa: Option<bool>,
/// `kind = "static"`: requests below a path prefix go to another server,
/// as a reverse proxy in front of the bundle would send them (ADR-0110):
/// `{ "/api" = "{service.api.url}" }`. The longest prefix wins, at a
/// segment boundary; the path goes on unchanged; a target is an origin
/// (`http://host:port`).
#[serde(default)]
pub forward: BTreeMap<String, String>,
/// Working directory relative to the repository.
pub cwd: Option<String>,
/// Paths whose change starts a candidate build (ADR-0003).
Expand Down
91 changes: 91 additions & 0 deletions crates/devstack-config/src/validate.rs
Original file line number Diff line number Diff line change
Expand Up @@ -209,6 +209,49 @@ impl Check<'_> {
}
}

/// A `forward` target (ADR-0110): its placeholders as in `env`, and an
/// origin `http://host:port` once they have a value. A `${VAR}` has one
/// only at the start, where the static server checks it.
fn forward_target(&mut self, path: &str, s: &str) {
self.text(
path,
s,
Scope::Service {
port: true,
artifact: true,
},
);
let Ok(segs) = interpolate::parse(s) else {
return; // reported above
};
let mut probe = String::new();
for seg in &segs {
match seg {
Segment::Literal(l) => probe.push_str(l),
Segment::Env { .. } => return,
Segment::Placeholder(ph) => probe.push_str(&match ph {
Placeholder::ServiceUrl(n) => match self.stack.services.get(n) {
Some(svc) => format!("{}://127.0.0.1:1", svc.scheme()),
None => return, // reported above
},
// `https://` with a named tunnel: not a local origin.
Placeholder::ServicePublicUrl(_) => "https://public".into(),
Placeholder::ComposePort { part, .. } => part.of("127.0.0.1:1"),
Placeholder::ServicePort(_) | Placeholder::Port => "1".into(),
Placeholder::IsMain => "true".into(),
Placeholder::LaneSuffix => String::new(),
Placeholder::Repo
| Placeholder::Artifact
| Placeholder::Lane
| Placeholder::ComposeProject(_) => "/path".into(),
}),
}
}
if let Err(why) = crate::forward::origin(&probe) {
self.err(path, format!("`{s}`: {why}"));
}
}

fn compose_service(&mut self, path: &str, what: &str, group: &str, service: &str) {
match self.stack.compose.get(group) {
None => self.err(path, format!("`{what}`: no compose group `{group}`")),
Expand Down Expand Up @@ -267,6 +310,11 @@ fn skipped_needs(c: &mut Check, stack: &Stack) {
.enumerate()
.map(|(i, d)| (format!("{p}.ensure_dirs[{i}]"), d.as_str())),
);
texts.extend(
svc.forward
.iter()
.map(|(k, t)| (format!("{p}.forward.\"{k}\""), t.as_str())),
);
for (at, t) in texts {
let Ok(segs) = interpolate::parse(t) else {
continue; // reported where the text is checked
Expand Down Expand Up @@ -654,6 +702,19 @@ pub fn validate(stack: &Stack) -> Vec<Issue> {
if svc.spa.is_some() && svc.kind != Kind::Static {
c.err(format!("{p}.spa"), "`spa` belongs to `kind = \"static\"`");
}
if !svc.forward.is_empty() && svc.kind != Kind::Static {
c.err(
format!("{p}.forward"),
"`forward` belongs to `kind = \"static\"`: another kind's own server forwards (a dev server's proxy config)", // ADR-0110
);
}
for (prefix, target) in &svc.forward {
let at = format!("{p}.forward.\"{prefix}\"");
if let Err(why) = crate::forward::prefix(prefix) {
c.err(&at, format!("`{prefix}`: {why}"));
}
c.forward_target(&at, target);
}
if svc.hot_reload.is_some() && (svc.kind != Kind::Service || svc.build.is_none()) {
c.err(
format!("{p}.hot_reload"),
Expand Down Expand Up @@ -1334,6 +1395,36 @@ pub fn warnings(stack: &Stack) -> Vec<Issue> {
});
}
}
let forward = crate::version_order(crate::FORWARD_SINCE);
if stack
.stack
.requires
.as_deref()
.is_none_or(|r| crate::version_order(r) < forward)
{
let profiled = stack.profiles.iter().flat_map(|(p, prof)| {
prof.services
.iter()
.filter(|(_, s)| !s.forward.is_empty())
.map(move |(n, _)| format!("profiles.{p}.services.{n}.forward"))
});
let paths: Vec<String> = stack
.services
.iter()
.filter(|(_, s)| !s.forward.is_empty())
.map(|(n, _)| format!("services.{n}.forward"))
.chain(profiled)
.collect();
for path in paths {
out.push(Issue {
path,
message: format!(
"a devstack before {v} does not know this key and fails on it with \"unknown field\": `requires = \"{v}\"` makes it ask to be updated instead",
v = crate::FORWARD_SINCE
),
});
}
}
if step == 0 {
return out;
}
Expand Down
Loading
Loading