1use std::net::{IpAddr, Ipv4Addr};
10
11use ipnet::Ipv4Net;
12use serde::{Deserialize, Serialize};
13
14pub const MAX_SANDBOX_LINKS: usize = 16;
16
17pub const MAX_GATEWAY_LINKED_SERVICES: usize = 16;
20
21pub const MAX_LINK_PORTS: usize = 16;
23
24const REFUSED_LINK_PORTS: &[u16] = &[0, 53];
26
27const LINK_ADDRESS_SPACES: &[(Ipv4Addr, u8)] = &[
32 (Ipv4Addr::new(10, 0, 0, 0), 8),
33 (Ipv4Addr::new(100, 64, 0, 0), 10),
34 (Ipv4Addr::new(172, 16, 0, 0), 12),
35 (Ipv4Addr::new(192, 168, 0, 0), 16),
36];
37
38const MAX_LINK_ADDRESSES: usize = 16;
40
41const WIDEST_LINK_PREFIX: u8 = 8;
43
44#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
47#[serde(rename_all = "camelCase", deny_unknown_fields)]
48pub struct GatewayLink {
49 pub id: String,
51 pub host: String,
54 pub ports: Vec<u16>,
56 pub ranges: Vec<Ipv4Net>,
58 #[serde(default, skip_serializing_if = "Vec::is_empty")]
62 pub addresses: Vec<Ipv4Addr>,
63}
64
65impl GatewayLink {
66 pub fn validate(&self) -> Result<(), String> {
68 crate::stack_authoring::validate_resource_id(&self.id)
69 .map_err(|reason| format!("link id '{}' {reason}", self.id))?;
70 if self.host.is_empty()
71 || self.host.len() > 253
72 || self.host.parse::<Ipv4Addr>().is_ok()
73 || !self.host.split('.').all(|label| {
74 !label.is_empty()
75 && label.len() <= 63
76 && !label.starts_with('-')
77 && !label.ends_with('-')
78 && label
79 .bytes()
80 .all(|b| b.is_ascii_lowercase() || b.is_ascii_digit() || b == b'-')
81 })
82 {
83 return Err(format!(
84 "link '{}': host must be a lowercase DNS name",
85 self.id
86 ));
87 }
88 if self.ports.is_empty()
89 || self.ports.len() > MAX_LINK_PORTS
90 || self
91 .ports
92 .iter()
93 .any(|port| REFUSED_LINK_PORTS.contains(port))
94 {
95 return Err(format!(
96 "link '{}': ports must be 1 to {MAX_LINK_PORTS}, nonzero and not 53",
97 self.id
98 ));
99 }
100 if self.ranges.is_empty() {
101 return Err(format!(
102 "link '{}': at least one range is required",
103 self.id
104 ));
105 }
106 for range in &self.ranges {
107 if !is_link_range(*range) {
108 return Err(format!(
109 "link '{}': range {range} must be a private range no wider than /8",
110 self.id
111 ));
112 }
113 }
114 if self.addresses.len() > MAX_LINK_ADDRESSES {
115 return Err(format!(
116 "link '{}': at most {MAX_LINK_ADDRESSES} fixed addresses",
117 self.id
118 ));
119 }
120 if let Some(address) = self
121 .addresses
122 .iter()
123 .find(|address| !self.admits(IpAddr::V4(**address)))
124 {
125 return Err(format!(
126 "link '{}': address {address} must lie in the link's ranges",
127 self.id
128 ));
129 }
130 Ok(())
131 }
132
133 pub fn matches(&self, host: &str, port: u16) -> bool {
135 self.host == host && self.ports.contains(&port)
136 }
137
138 pub fn admits(&self, address: IpAddr) -> bool {
140 let IpAddr::V4(address) = address else {
141 return false;
142 };
143 is_link_address(address) && self.ranges.iter().any(|range| range.contains(&address))
144 }
145}
146
147pub fn is_link_range(range: Ipv4Net) -> bool {
150 range.prefix_len() >= WIDEST_LINK_PREFIX
151 && link_address_spaces().any(|space| space.contains(&range))
152}
153
154pub fn is_link_address(address: Ipv4Addr) -> bool {
156 link_address_spaces().any(|space| space.contains(&address))
157}
158
159fn link_address_spaces() -> impl Iterator<Item = Ipv4Net> {
160 LINK_ADDRESS_SPACES
161 .iter()
162 .map(|&(address, prefix)| Ipv4Net::new_assert(address, prefix))
163}
164
165pub trait InternalEndpoints {
170 fn internal_ports(&self) -> Result<Vec<u16>, String>;
172}
173
174impl InternalEndpoints for crate::Container {
175 fn internal_ports(&self) -> Result<Vec<u16>, String> {
176 let mut ports: Vec<u16> = self.ports.iter().map(|port| port.port).collect();
177 ports.sort_unstable();
178 ports.dedup();
179 if ports.is_empty() {
180 return Err("it declares no port, so it has no internal endpoint".into());
181 }
182 Ok(ports)
183 }
184}
185
186pub fn internal_ports(stack: &crate::Stack, id: &str) -> Result<Vec<u16>, String> {
188 let entry = stack
189 .resources
190 .get(id)
191 .ok_or_else(|| "no such resource in the stack".to_string())?;
192 if crate::sandbox_egress::is_managed_gateway(stack, id) {
193 return Err("it is the deployment's egress gateway".into());
194 }
195 if let Some(container) = entry.config.downcast_ref::<crate::Container>() {
196 return container.internal_ports();
197 }
198 Err(format!(
199 "a {} is not a linkable service; link a Container with a declared port",
200 entry.config.resource_type()
201 ))
202}
203
204pub fn platform_refusal(platform: crate::Platform) -> Option<&'static str> {
206 match platform {
207 crate::Platform::Aws
210 | crate::Platform::Kubernetes
211 | crate::Platform::Local
212 | crate::Platform::Azure => None,
213 crate::Platform::Gcp => Some(
215 "links are not available on Google Cloud yet: they go through the deployment's \
216 egress gateway, which Google Cloud internet sandboxes do not use yet",
217 ),
218 _ => Some("links are not available on this platform"),
219 }
220}
221
222pub fn azure_link_refusal(stack: &crate::Stack, id: &str) -> Option<String> {
227 let container = stack
228 .resources
229 .get(id)?
230 .config
231 .downcast_ref::<crate::Container>()?;
232 if !container.public_endpoints.is_empty() {
233 return Some(
234 "on Azure a linked container cannot also have a public endpoint: it joins one \
235 load balancer pool, which the public endpoint already uses"
236 .into(),
237 );
238 }
239 if container
240 .internal_ports()
241 .is_ok_and(|ports| ports.len() != 1)
242 {
243 return Some(
244 "on Azure a linked container must declare exactly one port: its internal load \
245 balancer forwards one host port"
246 .into(),
247 );
248 }
249 None
250}
251
252pub fn validate_sandbox_links(
254 stack: &crate::Stack,
255 sandbox: &crate::Sandbox,
256 platform: crate::Platform,
257) -> Result<(), String> {
258 if sandbox.gateway_links.is_empty() {
259 return Ok(());
260 }
261 if let Some(reason) = platform_refusal(platform) {
262 return Err(reason.into());
263 }
264 if sandbox.egress != crate::SandboxEgress::Internet {
265 return Err(
266 "links go through the deployment's egress gateway and need egress `internet`".into(),
267 );
268 }
269 if sandbox.gateway_links.len() > MAX_SANDBOX_LINKS {
270 return Err(format!("at most {MAX_SANDBOX_LINKS} links are allowed"));
271 }
272 let linked_services = gateway_link_targets(stack).len();
273 if linked_services > MAX_GATEWAY_LINKED_SERVICES {
274 return Err(format!(
275 "the deployment's sandboxes link {linked_services} services; at most \
276 {MAX_GATEWAY_LINKED_SERVICES} are allowed"
277 ));
278 }
279 if !crate::sandbox_egress::gateway_image_serves_links(
280 crate::sandbox_egress::planned_gateway_image(stack),
281 ) {
282 return Err(
283 "the egress gateway image this release installs cannot enforce links; \
284 a later release enables them"
285 .into(),
286 );
287 }
288 for link in &sandbox.gateway_links {
289 let ports = internal_ports(stack, &link.id)
290 .map_err(|reason| format!("link '{}': {reason}", link.id))?;
291 if ports.len() > MAX_LINK_PORTS {
292 return Err(format!(
293 "link '{}': a linked service may declare at most {MAX_LINK_PORTS} ports",
294 link.id
295 ));
296 }
297 if let Some(port) = ports.iter().find(|port| REFUSED_LINK_PORTS.contains(port)) {
298 return Err(format!(
299 "link '{}': port {port} cannot be linked; the egress gateway answers DNS itself",
300 link.id
301 ));
302 }
303 if platform == crate::Platform::Azure {
304 if let Some(reason) = azure_link_refusal(stack, &link.id) {
305 return Err(format!("link '{}': {reason}", link.id));
306 }
307 }
308 }
309 Ok(())
310}
311
312pub fn gateway_link_targets(stack: &crate::Stack) -> std::collections::BTreeMap<String, Vec<u16>> {
315 stack
316 .resources()
317 .filter_map(|(_, entry)| entry.config.downcast_ref::<crate::Sandbox>())
318 .filter(|sandbox| sandbox.egress == crate::SandboxEgress::Internet)
319 .flat_map(|sandbox| &sandbox.gateway_links)
320 .filter_map(|link| Some((link.id.clone(), internal_ports(stack, &link.id).ok()?)))
321 .collect()
322}
323
324pub fn cluster_gateway_link(stack: &crate::Stack, id: &str) -> Option<GatewayLink> {
328 let ports = internal_ports(stack, id).ok()?;
329 let container = stack
330 .resources
331 .get(id)?
332 .config
333 .downcast_ref::<crate::Container>()?;
334 let cluster = stack
335 .resources
336 .get(container.cluster.as_deref()?)?
337 .config
338 .downcast_ref::<crate::ComputeCluster>()?;
339 let range: Ipv4Net = cluster.container_cidr().parse().ok()?;
340 let link = GatewayLink {
341 id: id.to_string(),
342 host: format!("{}.svc", id.to_ascii_lowercase()),
343 ports,
344 ranges: vec![range],
345 addresses: Vec::new(),
346 };
347 link.validate().is_ok().then_some(link)
349}
350
351pub fn cluster_gateway_links(
354 stack: &crate::Stack,
355 resource_prefix: &str,
356) -> std::collections::BTreeMap<String, Vec<GatewayLink>> {
357 stack
358 .resources()
359 .filter_map(|(_, entry)| entry.config.downcast_ref::<crate::Sandbox>())
360 .filter(|sandbox| sandbox.egress == crate::SandboxEgress::Internet)
361 .filter_map(|sandbox| {
362 let links: Vec<_> = sandbox
363 .gateway_links
364 .iter()
365 .filter_map(|link| cluster_gateway_link(stack, &link.id))
366 .collect();
367 (!links.is_empty()).then(|| (format!("{resource_prefix}/{}", sandbox.id), links))
368 })
369 .collect()
370}
371
372pub fn addressed_gateway_links(
379 stack: &crate::Stack,
380 resource_prefix: &str,
381 ranges: &[Ipv4Net],
382 address_of: impl Fn(&str) -> Option<Ipv4Addr>,
383) -> std::collections::BTreeMap<String, Vec<GatewayLink>> {
384 stack
385 .resources()
386 .filter_map(|(_, entry)| entry.config.downcast_ref::<crate::Sandbox>())
387 .filter(|sandbox| sandbox.egress == crate::SandboxEgress::Internet)
388 .filter_map(|sandbox| {
389 let links: Vec<_> = sandbox
390 .gateway_links
391 .iter()
392 .filter_map(|link| {
393 let address = address_of(&link.id)?;
394 let link = GatewayLink {
395 id: link.id.clone(),
396 host: format!("{}.svc", link.id.to_ascii_lowercase()),
397 ports: internal_ports(stack, &link.id).ok()?,
398 ranges: ranges.to_vec(),
399 addresses: vec![address],
400 };
401 link.validate().is_ok().then_some(link)
402 })
403 .collect();
404 (!links.is_empty()).then(|| (format!("{resource_prefix}/{}", sandbox.id), links))
405 })
406 .collect()
407}
408
409pub fn cluster_link_bindings(
412 stack: &crate::Stack,
413 sandbox: &crate::Sandbox,
414) -> std::collections::BTreeMap<String, crate::bindings::ContainerBinding> {
415 use crate::bindings::{BindingValue, ContainerBinding, HorizonContainerBinding};
416 sandbox
417 .gateway_links
418 .iter()
419 .filter_map(|link| {
420 let link = cluster_gateway_link(stack, &link.id)?;
421 let url = |port: u16| format!("http://{}:{port}", link.host);
422 Some((
423 link.id.clone(),
424 ContainerBinding::Horizon(HorizonContainerBinding {
425 container_name: BindingValue::value(link.id.clone()),
426 internal_url: BindingValue::value(url(link.ports[0])),
427 public_url: None,
428 internal_urls: link
429 .ports
430 .iter()
431 .map(|&port| (port, BindingValue::value(url(port))))
432 .collect(),
433 }),
434 ))
435 })
436 .collect()
437}
438
439#[cfg(test)]
440mod tests {
441 use super::*;
442
443 fn link() -> GatewayLink {
444 GatewayLink {
445 id: "api".into(),
446 host: "api.svc".into(),
447 ports: vec![8080],
448 addresses: Vec::new(),
449 ranges: vec!["10.244.0.0/16".parse().unwrap()],
450 }
451 }
452
453 #[test]
454 fn a_link_admits_only_its_ranges_inside_internal_address_spaces() {
455 let link = link();
456 link.validate().unwrap();
457 assert!(link.admits("10.244.3.7".parse().unwrap()));
458 for address in [
459 "10.0.0.1",
460 "169.254.169.254",
461 "127.0.0.1",
462 "168.63.129.16",
463 "8.8.8.8",
464 "fd00:ec2::254",
465 "fe80::1",
466 "::ffff:10.244.3.7",
467 ] {
468 assert!(!link.admits(address.parse().unwrap()), "{address}");
469 }
470 assert!(link.matches("api.svc", 8080));
471 assert!(!link.matches("api.svc", 8081));
472 assert!(!link.matches("other.svc", 8080));
473 }
474
475 #[test]
476 fn validation_refuses_ranges_outside_internal_spaces_and_bad_fields() {
477 for range in [
478 "169.254.0.0/16",
479 "127.0.0.0/8",
480 "0.0.0.0/0",
481 "8.8.8.0/24",
482 "168.63.129.16/32",
483 "10.0.0.0/7",
484 "172.0.0.0/8",
485 "192.168.0.0/15",
486 ] {
487 let mut link = link();
488 link.ranges = vec![range.parse().unwrap()];
489 assert!(link.validate().is_err(), "{range}");
490 }
491 for mutate in [
492 (|l: &mut GatewayLink| l.host = "API.svc".into()) as fn(&mut GatewayLink),
493 |l| l.host = "10.244.0.1".into(),
494 |l| l.host = "api.svc.".into(),
495 |l| l.ports = vec![],
496 |l| l.ports = vec![53],
497 |l| l.ports = vec![0],
498 |l| l.ranges = vec![],
499 |l| l.id = "Api".into(),
500 ] {
501 let mut link = link();
502 mutate(&mut link);
503 assert!(link.validate().is_err(), "{link:?}");
504 }
505 }
506}
507
508#[cfg(test)]
509mod builder_tests {
510 use super::{cluster_gateway_links, cluster_link_bindings, GatewayLink};
511 use crate::{Container, ContainerCode, ResourceSpec, Sandbox, SandboxCode, SandboxEgress};
512
513 #[test]
514 fn link_records_each_service_once_and_a_sandbox_without_links_serializes_unchanged() {
515 let api = Container::new("api".into())
516 .code(ContainerCode::Image {
517 image: "example.com/api:1".into(),
518 })
519 .permissions("execution".into())
520 .cpu(ResourceSpec {
521 min: "1".into(),
522 desired: "1".into(),
523 })
524 .memory(ResourceSpec {
525 min: "1Gi".into(),
526 desired: "1Gi".into(),
527 })
528 .port(8080)
529 .build();
530 let build = |linked: bool| {
531 let builder = Sandbox::new("agents".into());
532 let builder = if linked {
533 builder.link(&api).link(&api)
534 } else {
535 builder
536 };
537 builder
538 .code(SandboxCode::Image {
539 image: "ubuntu".into(),
540 bundled_from: None,
541 })
542 .egress(SandboxEgress::Internet)
543 .lifecycle(Default::default())
544 .build()
545 };
546 let linked = build(true);
547 assert_eq!(linked.gateway_links.len(), 1);
548 assert_eq!(linked.gateway_links[0].id, "api");
549 assert!(crate::ResourceDefinition::get_dependencies(&linked).is_empty());
551 let json = serde_json::to_value(&linked).unwrap();
552 assert_eq!(json["gatewayLinks"][0]["id"], "api");
553 let plain = serde_json::to_value(build(false)).unwrap();
554 assert!(plain.get("gatewayLinks").is_none());
555 assert_eq!(serde_json::from_value::<Sandbox>(json).unwrap(), linked);
556 }
557
558 #[test]
559 fn cluster_links_name_the_overlay_service_inside_its_cluster_range() {
560 use crate::{
561 CapacityGroup, ComputeCluster, Container, ContainerCode, ResourceLifecycle,
562 ResourceSpec, SandboxCode, SandboxEgress, Stack,
563 };
564 let cluster = |cidr: &str| {
565 ComputeCluster::new("compute".into())
566 .capacity_group(CapacityGroup {
567 group_id: "apps".into(),
568 instance_type: Some("m7g.large".into()),
569 profile: None,
570 min_size: 1,
571 max_size: 1,
572 scale_policy: None,
573 nested_virtualization: None,
574 data_disk_gib_range: None,
575 })
576 .container_cidr(cidr.into())
577 .build()
578 };
579 let api = Container::new("api".into())
580 .code(ContainerCode::Image {
581 image: "api".into(),
582 })
583 .cpu(ResourceSpec {
584 min: "1".into(),
585 desired: "1".into(),
586 })
587 .memory(ResourceSpec {
588 min: "1Gi".into(),
589 desired: "1Gi".into(),
590 })
591 .permissions("default".into())
592 .cluster("compute".into())
593 .port(8080)
594 .build();
595 let sandbox = |id: &str, linked: bool| {
596 let builder = crate::Sandbox::new(id.into());
597 let builder = if linked { builder.link(&api) } else { builder };
598 builder
599 .code(SandboxCode::Image {
600 image: "ubuntu".into(),
601 bundled_from: None,
602 })
603 .egress(SandboxEgress::Internet)
604 .lifecycle(Default::default())
605 .build()
606 };
607 let stack = |cidr: &str, linked: bool| {
608 Stack::new("s".into())
609 .add(cluster(cidr), ResourceLifecycle::Frozen)
610 .add(api.clone(), ResourceLifecycle::Live)
611 .add(sandbox("agents", linked), ResourceLifecycle::Live)
612 .add(sandbox("plain", false), ResourceLifecycle::Live)
613 .build()
614 };
615 let linked = stack("10.244.0.0/16", true);
616 let links = cluster_gateway_links(&linked, "p");
617 assert_eq!(links.keys().collect::<Vec<_>>(), ["p/agents"]);
618 assert_eq!(
619 links["p/agents"],
620 vec![GatewayLink {
621 id: "api".into(),
622 host: "api.svc".into(),
623 ports: vec![8080],
624 ranges: vec!["10.244.0.0/16".parse().unwrap()],
625 addresses: Vec::new(),
626 }]
627 );
628 links["p/agents"][0].validate().unwrap();
629 let bindings = cluster_link_bindings(&linked, &sandbox("agents", true));
630 let binding = &bindings["api"];
631 assert_eq!(
632 binding.get_internal_url().as_deref(),
633 Some("http://api.svc:8080")
634 );
635 assert!(binding.get_public_url().is_none());
636 assert!(cluster_gateway_links(&stack("10.244.0.0/16", false), "p").is_empty());
638 assert!(cluster_gateway_links(&stack("11.244.0.0/16", true), "p").is_empty());
639 let mut dns = stack("10.244.0.0/16", true);
642 dns.resources
643 .get_mut("api")
644 .unwrap()
645 .config
646 .downcast_mut::<Container>()
647 .unwrap()
648 .ports[0]
649 .port = 53;
650 assert!(cluster_gateway_links(&dns, "p").is_empty());
651 }
652}
653
654#[cfg(test)]
655mod azure_tests {
656 use super::azure_link_refusal;
657 use crate::{
658 Container, ContainerCode, ExposeProtocol, PublicEndpoint, ResourceLifecycle, ResourceSpec,
659 Stack,
660 };
661
662 fn container(id: &str, ports: &[u16], public: bool) -> Container {
663 let mut builder = Container::new(id.into())
664 .code(ContainerCode::Image {
665 image: "example.com/api:1".into(),
666 })
667 .permissions("execution".into())
668 .cpu(ResourceSpec {
669 min: "1".into(),
670 desired: "1".into(),
671 })
672 .memory(ResourceSpec {
673 min: "1Gi".into(),
674 desired: "1Gi".into(),
675 });
676 for &port in ports {
677 builder = builder.port(port);
678 }
679 if public {
680 builder = builder.public_endpoint(PublicEndpoint {
681 name: "web".into(),
682 port: ports[0],
683 protocol: ExposeProtocol::Http,
684 host_label: None,
685 wildcard_subdomains: false,
686 });
687 }
688 builder.build()
689 }
690
691 #[test]
692 fn azure_links_a_single_port_container_without_a_public_endpoint() {
693 let stack = Stack::new("s".into())
694 .add(container("api", &[8080], false), ResourceLifecycle::Live)
695 .add(
696 container("two", &[8080, 9090], false),
697 ResourceLifecycle::Live,
698 )
699 .add(container("web", &[8080], true), ResourceLifecycle::Live)
700 .build();
701 assert_eq!(azure_link_refusal(&stack, "api"), None);
702 assert!(azure_link_refusal(&stack, "two")
703 .unwrap()
704 .contains("exactly one port"));
705 assert!(azure_link_refusal(&stack, "web")
706 .unwrap()
707 .contains("public endpoint"));
708 }
709}
710
711#[cfg(test)]
712mod addressed_tests {
713 use super::addressed_gateway_links;
714 use crate::{
715 Container, ContainerCode, ResourceLifecycle, ResourceSpec, Sandbox, SandboxCode,
716 SandboxEgress, Stack,
717 };
718
719 #[test]
720 fn addressed_links_carry_the_owned_address_and_admit_only_it() {
721 let container = |id: &str| {
722 Container::new(id.into())
723 .code(ContainerCode::Image {
724 image: "api".into(),
725 })
726 .cpu(ResourceSpec {
727 min: "1".into(),
728 desired: "1".into(),
729 })
730 .memory(ResourceSpec {
731 min: "1Gi".into(),
732 desired: "1Gi".into(),
733 })
734 .permissions("default".into())
735 .port(8080)
736 .build()
737 };
738 let (api, billing) = (container("api"), container("billing"));
739 let sandbox = Sandbox::new("agents".into())
740 .link(&api)
741 .link(&billing)
742 .code(SandboxCode::Image {
743 image: "ubuntu".into(),
744 bundled_from: None,
745 })
746 .egress(SandboxEgress::Internet)
747 .lifecycle(Default::default())
748 .build();
749 let stack = Stack::new("s".into())
750 .add(api, ResourceLifecycle::Live)
751 .add(billing, ResourceLifecycle::Live)
752 .add(sandbox, ResourceLifecycle::Live)
753 .build();
754 let private: Vec<ipnet::Ipv4Net> = vec!["10.0.2.0/24".parse().unwrap()];
756 let links = addressed_gateway_links(&stack, "prefix", &private, |id| match id {
757 "api" => Some("10.0.2.9".parse().unwrap()),
758 _ => None,
759 });
760 let agents = &links["prefix/agents"];
761 assert_eq!(agents.len(), 1);
762 assert_eq!(agents[0].host, "api.svc");
763 assert_eq!(agents[0].ports, vec![8080]);
764 assert_eq!(
765 agents[0].addresses,
766 vec!["10.0.2.9".parse::<std::net::Ipv4Addr>().unwrap()]
767 );
768 assert_eq!(agents[0].ranges, private);
769 assert!(agents[0].validate().is_ok());
770 for outside in ["169.254.169.254", "10.0.3.9", "172.16.0.4"] {
771 assert!(
772 addressed_gateway_links(&stack, "prefix", &private, |_| Some(
773 outside.parse().unwrap()
774 ))
775 .is_empty(),
776 "{outside}"
777 );
778 }
779 assert!(addressed_gateway_links(&stack, "prefix", &private, |_| None).is_empty());
780 }
781}