@rivetkit/engine 1.0.0 → 2.2.1-pr.4600.b74ff3b

package/packages/config/src/config/pegboard.rs

@@ -7,39 +7,35 @@ pub struct Pegboard {
 	/// Time to delay an actor from rescheduling after a rescheduling failure.
 	///
 	/// Unit is in milliseconds.
-	///
-	/// **Experimental**
 	pub base_retry_timeout: Option<usize>,
-	/// How long to wait after creating and not receiving a starting state before setting actor as lost.
+	/// How long to wait for an ack response from the outbound request layer before setting actor as lost.
 	///
 	/// Unit is in milliseconds.
+	pub actor_allocation_threshold: Option<i64>,
+	/// How long to wait after creating and not receiving a starting state before setting actor as lost.
 	///
-	/// **Experimental**
+	/// Unit is in milliseconds.
 	pub actor_start_threshold: Option<i64>,
 	/// How long to wait after stopping and not receiving a stop state before setting actor as lost.
 	///
 	/// Unit is in milliseconds.
-	///
-	/// **Experimental**
 	pub actor_stop_threshold: Option<i64>,
+	/// How long to wait after starting to attempt to reallocate before before setting actor to sleep.
+	///
+	/// Unit is in milliseconds.
+	pub actor_retry_duration_threshold: Option<i64>,
 	/// How long an actor goes without retries before it's retry count is reset to 0, effectively resetting its
 	/// backoff to 0.
 	///
 	/// Unit is in milliseconds.
-	///
-	/// **Experimental**
 	pub retry_reset_duration: Option<i64>,
 	/// Maximum exponent for the reschedule backoff calculation.
 	///
 	/// This controls the maximum backoff duration when rescheduling actors.
-	///
-	/// **Experimental**
 	pub reschedule_backoff_max_exponent: Option<usize>,
 	/// How long after last ping before considering a runner ineligible for allocation.
 	///
 	/// Unit is in milliseconds.
-	///
-	/// **Experimental**
 	pub runner_eligible_threshold: Option<i64>,
 	/// How long to wait after last ping before forcibly removing a runner from the database
 	/// and deleting its workflow, evicting all actors.
@@ -47,15 +43,116 @@ pub struct Pegboard {
 	/// Note that the runner may still be running and can reconnect.
 	///
 	/// Unit is in milliseconds.
-	///
-	/// **Experimental**
 	pub runner_lost_threshold: Option<i64>,
 	/// How long after last ping before considering a hibernating request disconnected.
 	///
 	/// Unit is in milliseconds.
-	///
-	/// **Experimental**
 	pub hibernating_request_eligible_threshold: Option<i64>,
+	/// Time to delay a serverless runner from attempting a new outbound connection after a connection failure.
+	///
+	/// Unit is in milliseconds.
+	pub serverless_base_retry_timeout: Option<usize>,
+	/// How long a serverless runner goes without connection failures before it's retry count is reset to 0,
+	/// effectively resetting its backoff to 0.
+	///
+	/// Unit is in milliseconds.
+	pub serverless_retry_reset_duration: Option<i64>,
+	/// Maximum exponent for the serverless backoff calculation.
+	///
+	/// This controls the maximum backoff duration when serverlessly connecting to runners.
+	pub serverless_backoff_max_exponent: Option<usize>,
+
+	/// Global pool desired max.
+	pub pool_desired_max_override: Option<u32>,
+
+	/// Default metadata poll interval for serverless runners when not specified in runner config.
+	///
+	/// Unit is in milliseconds.
+	pub default_metadata_poll_interval: Option<u64>,
+
+	/// Minimum metadata poll interval for serverless runners.
+	///
+	/// The actual poll interval will be the maximum of this value and the runner config's
+	/// `metadata_poll_interval` setting. This prevents excessive polling even if the
+	/// runner config specifies a very short interval.
+	///
+	/// Unit is in milliseconds.
+	pub min_metadata_poll_interval: Option<u64>,
+
+	/// Number of consecutive successes required to clear an active runner pool error.
+	///
+	/// This prevents a single success from clearing an error during flapping conditions.
+	/// Higher values provide more stability but slower recovery from transient errors.
+	pub runner_pool_consecutive_successes_to_clear_error: Option<u32>,
+
+	/// Amount of runners to query from the allocation queue and choose at random when allocating an actor.
+	pub actor_allocation_candidate_sample_size: Option<usize>,
+
+	/// Max response payload size in bytes from actors.
+	pub runner_max_response_payload_body_size: Option<usize>,
+	/// Ping interval for runner updates in milliseconds.
+	pub runner_update_ping_interval_ms: Option<u64>,
+	/// Max time since last pong before the runner connection is terminated. Unit is in milliseconds.
+	pub runner_ping_timeout_ms: Option<i64>,
+	/// GC interval for actor event demuxer in milliseconds.
+	pub runner_event_demuxer_gc_interval_ms: Option<u64>,
+	/// Max time since last seen before actor is considered stale, in milliseconds.
+	pub runner_event_demuxer_max_last_seen_ms: Option<u64>,
+
+	// === Gateway Settings ===
+	/// WebSocket open/handshake timeout in milliseconds.
+	pub gateway_websocket_open_timeout_ms: Option<u64>,
+	/// Timeout for response to start in milliseconds.
+	pub gateway_response_start_timeout_ms: Option<u64>,
+	/// Ping interval for gateway updates in milliseconds.
+	pub gateway_update_ping_interval_ms: Option<u64>,
+	/// GC interval for in-flight requests in milliseconds.
+	pub gateway_gc_interval_ms: Option<u64>,
+	/// Tunnel ping timeout in milliseconds.
+	pub gateway_tunnel_ping_timeout_ms: Option<i64>,
+	/// Hibernating WebSocket message ack timeout in milliseconds.
+	pub gateway_hws_message_ack_timeout_ms: Option<u64>,
+	/// Max pending message buffer size for hibernating WebSockets in bytes.
+	pub gateway_hws_max_pending_size: Option<u64>,
+	/// Max HTTP request body size in bytes for requests to actors.
+	pub gateway_http_max_request_body_size: Option<usize>,
+
+	// === Envoy Settings ===
+	/// How long to wait before considering an envoy lost and evicting all of its actors.
+	///
+	/// Unit is in milliseconds.
+	pub envoy_lost_threshold: Option<i64>,
+	/// Max time since last pong before the envoy connection is terminated. Unit is in milliseconds.
+	pub envoy_ping_timeout: Option<i64>,
+	/// GC interval for actor event demuxer in milliseconds.
+	pub envoy_event_demuxer_gc_interval: Option<u64>,
+	/// Max time since last seen before actor is considered stale, in milliseconds.
+	pub envoy_event_demuxer_max_last_seen_threshold: Option<u64>,
+	/// Max response payload size in bytes from actors.
+	pub envoy_max_response_payload_size: Option<usize>,
+	/// Ping interval for envoy updates in milliseconds.
+	pub envoy_update_ping_interval: Option<u64>,
+	/// How long after last ping before considering a envoy ineligible for allocation.
+	///
+	/// Unit is in milliseconds.
+	pub envoy_eligible_threshold: Option<i64>,
+
+	// === Serverless Settings ===
+	/// Drain grace period for serverless runners.
+	///
+	/// This time is subtracted from the configured request duration. Once `duration - grace` is reached, the
+	/// runner is sent stop commands for all of its actors. After the grace period is over (i.e. the full
+	/// duration is reached) the runner websocket is forcibly closed.
+	///
+	/// Unit is in milliseconds.
+	pub serverless_drain_grace_period: Option<u64>,
+
+	// === KV Preload Settings ===
+	/// Maximum total size of all preloaded KV data sent with the actor start command.
+	/// Setting to 0 disables all preloading.
+	///
+	/// Unit is in bytes. Default: 1,048,576 (1 MiB).
+	pub preload_max_total_bytes: Option<u64>,
 }
 
 impl Pegboard {
@@ -63,14 +160,24 @@ impl Pegboard {
 		self.base_retry_timeout.unwrap_or(2000)
 	}
 
+	pub fn actor_allocation_threshold(&self) -> i64 {
+		self.actor_allocation_threshold.unwrap_or(2_000)
+	}
+
 	pub fn actor_start_threshold(&self) -> i64 {
 		self.actor_start_threshold.unwrap_or(30_000)
 	}
 
+	/// When changing this default, update
+	/// website/src/content/docs/actors/versions.mdx (SIGTERM Handling section).
 	pub fn actor_stop_threshold(&self) -> i64 {
 		self.actor_stop_threshold.unwrap_or(30_000)
 	}
 
+	pub fn actor_retry_duration_threshold(&self) -> i64 {
+		self.actor_retry_duration_threshold.unwrap_or(300_000)
+	}
+
 	pub fn retry_reset_duration(&self) -> i64 {
 		self.retry_reset_duration.unwrap_or(10 * 60 * 1000)
 	}
@@ -91,4 +198,123 @@ impl Pegboard {
 		self.hibernating_request_eligible_threshold
 			.unwrap_or(90_000)
 	}
+
+	pub fn serverless_base_retry_timeout(&self) -> usize {
+		self.serverless_base_retry_timeout.unwrap_or(2000)
+	}
+
+	pub fn serverless_retry_reset_duration(&self) -> i64 {
+		self.serverless_retry_reset_duration
+			.unwrap_or(10 * 60 * 1000)
+	}
+
+	pub fn serverless_backoff_max_exponent(&self) -> usize {
+		self.serverless_backoff_max_exponent.unwrap_or(8)
+	}
+
+	pub fn runner_pool_error_consecutive_successes_to_clear(&self) -> u32 {
+		self.runner_pool_consecutive_successes_to_clear_error
+			.unwrap_or(3)
+	}
+
+	pub fn default_metadata_poll_interval(&self) -> u64 {
+		self.default_metadata_poll_interval.unwrap_or(10_000)
+	}
+
+	pub fn min_metadata_poll_interval(&self) -> u64 {
+		self.min_metadata_poll_interval.unwrap_or(5_000)
+	}
+
+	pub fn actor_allocation_candidate_sample_size(&self) -> usize {
+		self.actor_allocation_candidate_sample_size.unwrap_or(100)
+	}
+
+	pub fn gateway_websocket_open_timeout_ms(&self) -> u64 {
+		self.gateway_websocket_open_timeout_ms.unwrap_or(15_000)
+	}
+
+	pub fn gateway_response_start_timeout_ms(&self) -> u64 {
+		self.gateway_response_start_timeout_ms
+			.unwrap_or(5 * 60 * 1000) // 5 minutes
+	}
+
+	pub fn gateway_update_ping_interval_ms(&self) -> u64 {
+		self.gateway_update_ping_interval_ms.unwrap_or(3_000)
+	}
+
+	pub fn gateway_gc_interval_ms(&self) -> u64 {
+		self.gateway_gc_interval_ms.unwrap_or(15_000)
+	}
+
+	pub fn gateway_tunnel_ping_timeout_ms(&self) -> i64 {
+		self.gateway_tunnel_ping_timeout_ms.unwrap_or(30_000)
+	}
+
+	pub fn gateway_hws_message_ack_timeout_ms(&self) -> u64 {
+		self.gateway_hws_message_ack_timeout_ms.unwrap_or(30_000)
+	}
+
+	pub fn gateway_hws_max_pending_size(&self) -> u64 {
+		self.gateway_hws_max_pending_size
+			.unwrap_or(128 * 1024 * 1024) // 128 MiB
+	}
+
+	pub fn runner_max_response_payload_body_size(&self) -> usize {
+		self.runner_max_response_payload_body_size
+			.unwrap_or(20 * 1024 * 1024) // 20 MiB
+	}
+
+	pub fn runner_update_ping_interval_ms(&self) -> u64 {
+		self.runner_update_ping_interval_ms.unwrap_or(3_000)
+	}
+
+	pub fn runner_ping_timeout_ms(&self) -> i64 {
+		self.runner_ping_timeout_ms.unwrap_or(15_000)
+	}
+
+	pub fn runner_event_demuxer_gc_interval_ms(&self) -> u64 {
+		self.runner_event_demuxer_gc_interval_ms.unwrap_or(30_000)
+	}
+
+	pub fn runner_event_demuxer_max_last_seen_ms(&self) -> u64 {
+		self.runner_event_demuxer_max_last_seen_ms.unwrap_or(30_000)
+	}
+
+	pub fn envoy_lost_threshold(&self) -> i64 {
+		self.envoy_lost_threshold.unwrap_or(15_000)
+	}
+
+	pub fn envoy_ping_timeout(&self) -> i64 {
+		self.envoy_ping_timeout.unwrap_or(15_000)
+	}
+
+	pub fn envoy_event_demuxer_gc_interval(&self) -> u64 {
+		self.envoy_event_demuxer_gc_interval.unwrap_or(30_000)
+	}
+
+	pub fn envoy_event_demuxer_max_last_seen_threshold(&self) -> u64 {
+		self.envoy_event_demuxer_max_last_seen_threshold
+			.unwrap_or(30_000)
+	}
+
+	pub fn envoy_max_response_payload_size(&self) -> usize {
+		self.envoy_max_response_payload_size
+			.unwrap_or(20 * 1024 * 1024) // 20 MiB
+	}
+
+	pub fn envoy_update_ping_interval(&self) -> u64 {
+		self.envoy_update_ping_interval.unwrap_or(3_000)
+	}
+
+	pub fn envoy_eligible_threshold(&self) -> i64 {
+		self.envoy_eligible_threshold.unwrap_or(10_000)
+	}
+
+	pub fn serverless_drain_grace_period(&self) -> u64 {
+		self.serverless_drain_grace_period.unwrap_or(10_000)
+	}
+
+	pub fn preload_max_total_bytes(&self) -> u64 {
+		self.preload_max_total_bytes.unwrap_or(1_048_576)
+	}
 }

package/packages/config/src/config/pubsub.rs

@@ -3,6 +3,8 @@ use serde::{Deserialize, Serialize};
 
 use crate::secret::Secret;
 
+use super::db::PostgresSsl;
+
 #[derive(Debug, Serialize, Deserialize, Clone, JsonSchema)]
 #[serde(rename_all = "snake_case", deny_unknown_fields)]
 pub enum PubSub {
@@ -18,13 +20,21 @@ impl Default for PubSub {
 }
 
 #[derive(Debug, Serialize, Deserialize, Clone, JsonSchema)]
+#[serde(deny_unknown_fields)]
 pub struct Postgres {
 	/// URL to connect to Postgres with
 	///
+	/// Supports standard PostgreSQL connection parameters including `sslmode`.
+	/// Supported sslmode values: `disable`, `prefer` (default), `require`.
+	/// To verify server certificates, use `sslmode=require` with `ssl.root_cert_path`.
+	///
 	/// See: https://docs.rs/postgres/0.19.10/postgres/config/struct.Config.html#url
 	pub url: Secret<String>,
 	#[serde(default = "default_mem_opt")]
 	pub memory_optimization: bool,
+	/// SSL configuration options
+	#[serde(default)]
+	pub ssl: Option<PostgresSsl>,
 }
 
 impl Default for Postgres {
@@ -32,6 +42,7 @@ impl Default for Postgres {
 		Self {
 			url: Secret::new("postgresql://postgres:postgres@127.0.0.1:5432/postgres".into()),
 			memory_optimization: true,
+			ssl: None,
 		}
 	}
 }

package/packages/config/src/config/runtime.rs

@@ -4,19 +4,50 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
 #[derive(Debug, Clone, Serialize, Deserialize, Default, JsonSchema)]
+#[serde(deny_unknown_fields)]
 pub struct Runtime {
+	/// Adjusts worker curve around this value (in millicores, i.e. 1000 = 1 core). Is not a hard limit. When
+	/// unset, uses /sys/fs/cgroup/cpu.max, and if that is unset uses total host cpu.
+	pub worker_cpu_max: Option<usize>,
+	/// Determine load shedding ratio based on linear mapping on cpu usage. We will gradually
+	/// pull less workflows as the cpu usage increases. Units are in (permilli overall cpu usage, permilli)
+	/// Default:
+	///       |     .   .
+	///  100% | _____   .
+	///       |     .\  .
+	/// % wfs |     . \ .
+	///       |     .  \.
+	///    5% |     .   \_____
+	///       |_____.___.______
+	///       0    70% 90%
+	///         avg cpu usage
+	worker_load_shedding_curve: Option<[(u64, u64); 2]>,
 	/// Time (in seconds) to allow for the gasoline worker engine to stop gracefully after receiving SIGTERM.
 	/// Defaults to 30 seconds.
 	worker_shutdown_duration: Option<u32>,
 	/// Time (in seconds) to allow for guard to wait for pending requests after receiving SIGTERM. Defaults
 	/// to 1 hour.
 	guard_shutdown_duration: Option<u32>,
+	/// Time (in seconds) after which the engine process will forcibly exit after receiving SIGTERM.
+	/// Must be greater than both worker_shutdown_duration and guard_shutdown_duration.
+	/// Defaults to guard_shutdown_duration + 30 seconds.
+	force_shutdown_duration: Option<u32>,
 	/// Whether or not to allow running the engine when the previous version that was run is higher than
 	/// the current version.
 	allow_version_rollback: Option<bool>,
+	/// Time (in seconds) after completion before considering a workflow eligible for pruning. Defaults to 7
+	/// days. Set to 0 to never prune workflow data.
+	gasoline_prune_eligibility_duration: Option<u64>,
+	/// Time (in seconds) to periodically check for workflows to prune. Defaults to 12 hours.
+	gasoline_prune_interval_duration: Option<u64>,
 }
 
 impl Runtime {
+	pub fn worker_load_shedding_curve(&self) -> [(u64, u64); 2] {
+		self.worker_load_shedding_curve
+			.unwrap_or([(700, 1000), (900, 50)])
+	}
+
 	pub fn worker_shutdown_duration(&self) -> Duration {
 		Duration::from_secs(self.worker_shutdown_duration.unwrap_or(30) as u64)
 	}
@@ -25,7 +56,34 @@ impl Runtime {
 		Duration::from_secs(self.guard_shutdown_duration.unwrap_or(60 * 60) as u64)
 	}
 
+	/// Returns the force shutdown duration, defaulting to guard_shutdown_duration + 30 seconds.
+	pub fn force_shutdown_duration(&self) -> Duration {
+		self.force_shutdown_duration.map_or_else(
+			|| self.guard_shutdown_duration() + Duration::from_secs(30),
+			|secs| Duration::from_secs(secs as u64),
+		)
+	}
+
 	pub fn allow_version_rollback(&self) -> bool {
 		self.allow_version_rollback.unwrap_or_default()
 	}
+
+	pub fn gasoline_prune_eligibility_duration(&self) -> Option<Duration> {
+		if let Some(prune_eligibility_duration) = self.gasoline_prune_eligibility_duration {
+			if prune_eligibility_duration == 0 {
+				None
+			} else {
+				Some(Duration::from_secs(prune_eligibility_duration))
+			}
+		} else {
+			Some(Duration::from_secs(60 * 60 * 24 * 7))
+		}
+	}
+
+	pub fn gasoline_prune_interval_duration(&self) -> Duration {
+		Duration::from_secs(
+			self.gasoline_prune_interval_duration
+				.unwrap_or(60 * 60 * 12),
+		)
+	}
 }

package/packages/config/src/config/telemetry.rs

@@ -2,6 +2,7 @@ use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
 
 #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(deny_unknown_fields)]
 pub struct Telemetry {
 	pub enabled: bool,
 }

package/packages/config/src/config/topology.rs

@@ -1,6 +1,7 @@
 use anyhow::{Context, Result};
 use schemars::JsonSchema;
 use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
 use url::Url;
 
 #[derive(Debug, Serialize, Deserialize, Clone, JsonSchema)]
@@ -8,8 +9,8 @@ use url::Url;
 pub struct Topology {
 	/// Must be included in `datacenters`
 	pub datacenter_label: u16,
-	/// List of all datacenters, including this datacenter.
-	pub datacenters: Vec<Datacenter>,
+	/// Map of all datacenters, including this datacenter.
+	pub datacenters: DatacentersRepr,
 }
 
 impl Topology {
@@ -47,23 +48,78 @@ impl Default for Topology {
 	fn default() -> Self {
 		Topology {
 			datacenter_label: 1,
-			datacenters: vec![Datacenter {
-				name: "default".into(),
-				datacenter_label: 1,
-				is_leader: true,
-				public_url: Url::parse(&format!(
-					"http://127.0.0.1:{}",
-					crate::defaults::ports::GUARD
-				))
-				.unwrap(),
-				peer_url: Url::parse(&format!(
-					"http://127.0.0.1:{}",
-					crate::defaults::ports::API_PEER
-				))
-				.unwrap(),
-				proxy_url: None,
-				valid_hosts: None,
-			}],
+			datacenters: DatacentersRepr::Map(
+				[(
+					"default".to_string(),
+					Datacenter {
+						name: "default".into(),
+						datacenter_label: 1,
+						is_leader: true,
+						public_url: Url::parse(&format!(
+							"http://127.0.0.1:{}",
+							crate::defaults::ports::GUARD
+						))
+						.unwrap(),
+						peer_url: Url::parse(&format!(
+							"http://127.0.0.1:{}",
+							crate::defaults::ports::API_PEER
+						))
+						.unwrap(),
+						proxy_url: None,
+						valid_hosts: None,
+					},
+				)]
+				.into(),
+			),
+		}
+	}
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+#[serde(untagged)]
+pub enum DatacentersRepr {
+	Map(HashMap<String, Datacenter>),
+	/// Deprecated.
+	List(Vec<Datacenter>),
+}
+
+impl DatacentersRepr {
+	pub fn iter(&self) -> DatacentersIter<'_> {
+		self.into_iter()
+	}
+
+	pub fn len(&self) -> usize {
+		match self {
+			DatacentersRepr::Map(m) => m.len(),
+			DatacentersRepr::List(l) => l.len(),
+		}
+	}
+}
+
+pub enum DatacentersIter<'a> {
+	Map(std::collections::hash_map::Values<'a, String, Datacenter>),
+	List(std::slice::Iter<'a, Datacenter>),
+}
+
+impl<'a> Iterator for DatacentersIter<'a> {
+	type Item = &'a Datacenter;
+
+	fn next(&mut self) -> Option<Self::Item> {
+		match self {
+			DatacentersIter::Map(iter) => iter.next(),
+			DatacentersIter::List(iter) => iter.next(),
+		}
+	}
+}
+
+impl<'a> IntoIterator for &'a DatacentersRepr {
+	type Item = &'a Datacenter;
+	type IntoIter = DatacentersIter<'a>;
+
+	fn into_iter(self) -> Self::IntoIter {
+		match self {
+			DatacentersRepr::Map(map) => DatacentersIter::Map(map.values()),
+			DatacentersRepr::List(vec) => DatacentersIter::List(vec.iter()),
 		}
 	}
 }
@@ -71,6 +127,9 @@ impl Default for Topology {
 #[derive(Debug, Serialize, Deserialize, Clone, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct Datacenter {
+	/// When configuring `datacenters` via a hashmap this is automatically derived from the key. Required
+	/// when configuring via list (which is deprecated)
+	#[serde(default = "String::new")]
 	pub name: String,
 	pub datacenter_label: u16,
 	pub is_leader: bool,

package/packages/config/src/defaults.rs

@@ -3,9 +3,12 @@ pub mod hosts {
 
 	pub const GUARD: IpAddr = IpAddr::V6(Ipv6Addr::UNSPECIFIED);
 	pub const API_PEER: IpAddr = IpAddr::V6(Ipv6Addr::UNSPECIFIED);
+	pub const METRICS: IpAddr = IpAddr::V6(Ipv6Addr::UNSPECIFIED);
 }
 
 pub mod ports {
 	pub const GUARD: u16 = 6420;
 	pub const API_PEER: u16 = 6421;
+
+	pub const METRICS: u16 = 6430;
 }

package/packages/config/src/lib.rs

@@ -79,11 +79,15 @@ fn add_source<P: AsRef<Path>>(
 	let path = path.as_ref();
 
 	if !path.exists() {
+		tracing::debug!(path=%path.display(), "ignoring non-existent config path");
+
 		// Silently ignore non-existent paths
 		return Ok(settings);
 	}
 
 	if path.is_dir() {
+		tracing::debug!(path=%path.display(), "loading config from directory");
+
 		for entry in std::fs::read_dir(path)? {
 			let entry = entry?;
 			let path = entry.path();
@@ -96,9 +100,14 @@ fn add_source<P: AsRef<Path>>(
 			}
 		}
 	} else if path.is_file() {
+		tracing::debug!(path=%path.display(), "loading config from file");
+
 		settings = add_file_source(settings, path)?;
 	} else {
-		bail!("Invalid path: {}", path.display());
+		bail!(
+			"Invalid Rivet config path: {}. Ensure the path exists and is either a directory with config files or a specific config file.",
+			path.display()
+		);
 	}
 
 	Ok(settings)

package/packages/config-schema-gen/Cargo.toml

@@ -0,0 +1,11 @@
+[package]
+name = "rivet-config-schema-gen"
+version.workspace = true
+authors.workspace = true
+license.workspace = true
+edition.workspace = true
+
+[build-dependencies]
+rivet-config.workspace = true
+schemars.workspace = true
+serde_json.workspace = true

package/packages/config-schema-gen/build.rs

@@ -0,0 +1,26 @@
+use std::{fs, path::Path};
+
+fn main() {
+	let schema = schemars::schema_for!(rivet_config::config::Root);
+
+	// Create out directory at workspace root
+	let workspace_root = std::env::var("CARGO_MANIFEST_DIR")
+		.map(|dir| {
+			Path::new(&dir)
+				.parent()
+				.unwrap()
+				.parent()
+				.unwrap()
+				.parent()
+				.unwrap()
+				.to_path_buf()
+		})
+		.unwrap();
+	let out_dir = workspace_root.join("engine").join("artifacts");
+	fs::create_dir_all(&out_dir).unwrap();
+
+	// Write pretty-formatted JSON to out/config-schema.json
+	let json = serde_json::to_string_pretty(&schema).expect("Failed to serialize JSON Schema");
+	fs::write(out_dir.join("config-schema.json"), json)
+		.expect("Failed to write config-schema.json");
+}

package/packages/config-schema-gen/src/lib.rs

@@ -0,0 +1,2 @@
+// This crate exists only to trigger the build.rs script
+// which generates the JSON schema at build time.