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

package/packages/epoxy/src/consts.rs

@@ -3,40 +3,8 @@ use std::time::Duration;
 /// Timeout for HTTP request to a peer datacenter.
 pub const REQUEST_TIMEOUT: Duration = Duration::from_secs(10);
 
-/// Response is `list<Instance>
+/// Number of changelog entries to fetch in a single catch-up page.
 ///
-/// ## Based on size
-///
-/// Instance = 250 bytes for an avg key size (bare minimum 115 bytes)
-///
-/// Reasonable total download size = 64 MiB
-///
-/// That's ~268k instances
-///
-/// ## Based on FDB limitation
-///
-/// FDB starts having performance issues between 10k-100k keys in a single range read based on
-/// rudimentary tests.
-///
-/// Can likely parallelize FDB transactions to return larger chunks.
-///
-/// ## Main limitation
-///
-/// FDB is the main limitation here, so we opt to use an FDB-friendly chunk size.
-///
-/// ## Estimated download time
-///
-/// Our current impl is incredily slow since we do not parallelize downloads.
-///
-/// Assume we have 10M keys with a 5k chunk size. This results in 2000 round trips.
-///
-/// If we have a latency of 200 ms (worst case), this takes 400 seconds total to propagate.
-pub const DOWNLOAD_INSTANCE_COUNT: u64 = 5_000;
-
-/// Number of keys to recover in a single chunk during the recovery process.
-///
-/// Keys are recovered in chunks to avoid memory issues and provide progress updates.
-/// The recovery process scans all key-instance markers and rebuilds the committed values.
-///
-/// This number is relatively small since we have to do a lot of operations per key.
-pub const RECOVER_KEY_CHUNK_SIZE: u64 = 500;
+/// This keeps learner range reads bounded while still making steady progress through the
+/// immutable per-key commit history.
+pub const CHANGELOG_READ_COUNT: u64 = 5_000;

package/packages/epoxy/src/http_client.rs

@@ -1,14 +1,12 @@
-use anyhow::*;
+use anyhow::{Context, Result, bail};
 use epoxy_protocol::{
 	PROTOCOL_VERSION,
 	protocol::{self, ReplicaId},
-	versioned,
 };
 use futures_util::{StreamExt, stream::FuturesUnordered};
 use gas::prelude::*;
 use rivet_api_builder::ApiCtx;
 use std::future::Future;
-use vbare::OwnedVersionedData;
 
 use crate::utils;
 
@@ -37,7 +35,13 @@ where
 	Fut: Future<Output = Result<T>> + Send,
 	T: Send,
 {
-	let quorum_size = utils::calculate_quorum(replica_ids.len(), quorum_type);
+	let target_responses = utils::calculate_fanout_quorum(replica_ids.len(), quorum_type);
+
+	if target_responses == 0 {
+		tracing::warn!("no fanout, target is 0");
+
+		return Ok(Vec::new());
+	}
 
 	// Create futures for all replicas (excluding the sender)
 	let mut responses = futures_util::stream::iter(
@@ -57,32 +61,22 @@ where
 	)
 	.collect::<FuturesUnordered<_>>()
 	.await;
-	tracing::debug!(?quorum_size, len = ?responses.len(), ?quorum_type, "fanout quorum size");
-
-	// Choose how many successful responses we need before considering a success
-	let target_responses = match quorum_type {
-		// Only require 1 response
-		utils::QuorumType::Any => 1,
-		// Include all responses
-		utils::QuorumType::All => responses.len(),
-		// Subtract 1 from quorum size since we're not counting ourselves
-		utils::QuorumType::Fast | utils::QuorumType::Slow => quorum_size - 1,
-	};
+	tracing::debug!(?target_responses, len=?responses.len(), "fanout target");
 
 	// Collect responses until we reach quorum or all futures complete
 	let mut successful_responses = Vec::new();
 	while successful_responses.len() < target_responses {
 		if let Some(response) = responses.next().await {
 			match response {
-				std::result::Result::Ok(result) => match result {
-					std::result::Result::Ok(response) => {
+				Ok(result) => match result {
+					Ok(response) => {
 						successful_responses.push(response);
 					}
-					std::result::Result::Err(err) => {
+					Err(err) => {
 						tracing::warn!(?err, "received error from replica");
 					}
 				},
-				std::result::Result::Err(err) => {
+				Err(err) => {
 					tracing::warn!(?err, "received timeout from replica");
 				}
 			}
@@ -105,11 +99,52 @@ pub async fn send_message(
 	send_message_to_address(ctx, replica_url, request).await
 }
 
+#[tracing::instrument(skip_all, fields(%from_replica_id, %to_replica_id, count))]
+pub async fn read_changelog(
+	ctx: &ApiCtx,
+	config: &protocol::ClusterConfig,
+	from_replica_id: ReplicaId,
+	to_replica_id: ReplicaId,
+	after_versionstamp: Option<Vec<u8>>,
+	count: u64,
+) -> Result<protocol::ChangelogReadResponse> {
+	let replica_url = find_replica_address(config, to_replica_id)?;
+	let response = send_request_to_address(
+		ctx,
+		replica_url,
+		"changelog-read",
+		protocol::Request {
+			from_replica_id,
+			to_replica_id,
+			kind: protocol::RequestKind::ChangelogReadRequest(protocol::ChangelogReadRequest {
+				after_versionstamp,
+				count,
+			}),
+		},
+	)
+	.await?;
+
+	match response.kind {
+		protocol::ResponseKind::ChangelogReadResponse(response) => Ok(response),
+		_ => bail!("unexpected response type for changelog read request"),
+	}
+}
+
 #[tracing::instrument(skip_all, fields(%replica_url))]
 pub async fn send_message_to_address(
 	ctx: &ApiCtx,
 	replica_url: String,
 	request: protocol::Request,
+) -> Result<protocol::Response> {
+	send_request_to_address(ctx, replica_url, "message", request).await
+}
+
+#[tracing::instrument(skip_all, fields(%replica_url, endpoint))]
+async fn send_request_to_address(
+	ctx: &ApiCtx,
+	replica_url: String,
+	endpoint: &'static str,
+	request: protocol::Request,
 ) -> Result<protocol::Response> {
 	let from_replica_id = request.from_replica_id;
 	let to_replica_id = request.to_replica_id;
@@ -124,7 +159,7 @@ pub async fn send_message_to_address(
 	}
 
 	let mut replica_url = url::Url::parse(&replica_url)?;
-	replica_url.set_path(&format!("/v{PROTOCOL_VERSION}/epoxy/message"));
+	replica_url.set_path(&format!("/v{PROTOCOL_VERSION}/epoxy/{endpoint}"));
 
 	tracing::debug!(
 		to_replica = to_replica_id,
@@ -135,9 +170,7 @@ pub async fn send_message_to_address(
 	let client = rivet_pools::reqwest::client().await?;
 
 	// Create the request
-	let request = versioned::Request::wrap_latest(request)
-		.serialize()
-		.context("failed to serialize epoxy request")?;
+	let request = serde_bare::to_vec(&request).context("failed to serialize epoxy request")?;
 
 	// Send the request
 	let response_result = client
@@ -148,8 +181,8 @@ pub async fn send_message_to_address(
 		.await;
 
 	let response = match response_result {
-		std::result::Result::Ok(resp) => resp,
-		std::result::Result::Err(e) => {
+		Ok(resp) => resp,
+		Err(e) => {
 			tracing::error!(
 				to_replica = to_replica_id,
 				replica_url = %replica_url,
@@ -181,7 +214,7 @@ pub async fn send_message_to_address(
 	}
 
 	let body = response.bytes().await?;
-	let response_body = versioned::Response::deserialize(&body)?;
+	let response_body = serde_bare::from_slice(&body)?;
 
 	tracing::debug!(
 		to_replica = to_replica_id,

package/packages/epoxy/src/http_routes.rs

@@ -1,24 +1,84 @@
 use anyhow::*;
 use axum::body::Bytes;
-use epoxy_protocol::versioned;
+use epoxy_protocol::{PROTOCOL_VERSION, protocol};
 use rivet_api_builder::prelude::*;
-use vbare::OwnedVersionedData;
+use std::time::Instant;
+
+use crate::metrics;
 
 #[derive(Deserialize)]
-pub struct VersionedPath {
+pub struct ProtocolPath {
 	pub version: u16,
 }
 
 pub fn mount_routes(
 	router: axum::Router<rivet_api_builder::GlobalApiCtx>,
 ) -> axum::Router<rivet_api_builder::GlobalApiCtx> {
-	router.route("/v{version}/epoxy/message", bin::post(message))
+	router
+		.route("/v{version}/epoxy/message", bin::post(message))
+		.route(
+			"/v{version}/epoxy/changelog-read",
+			bin::post(changelog_read),
+		)
+}
+
+pub async fn message(ctx: ApiCtx, path: ProtocolPath, _query: (), body: Bytes) -> Result<Vec<u8>> {
+	assert_protocol_version(path.version)?;
+	let request = deserialize_request(&body)?;
+	ensure!(
+		!matches!(request.kind, protocol::RequestKind::ChangelogReadRequest(_)),
+		"use /epoxy/changelog-read for changelog reads"
+	);
+
+	handle_request(ctx, request).await
+}
+
+pub async fn changelog_read(
+	ctx: ApiCtx,
+	path: ProtocolPath,
+	_query: (),
+	body: Bytes,
+) -> Result<Vec<u8>> {
+	assert_protocol_version(path.version)?;
+	let request = deserialize_request(&body)?;
+	ensure!(
+		matches!(request.kind, protocol::RequestKind::ChangelogReadRequest(_)),
+		"/epoxy/changelog-read only accepts changelog read requests"
+	);
+
+	handle_request(ctx, request).await
 }
 
-pub async fn message(ctx: ApiCtx, path: VersionedPath, _query: (), body: Bytes) -> Result<Vec<u8>> {
-	let request = versioned::Request::deserialize(&body, path.version)?;
+fn assert_protocol_version(version: u16) -> Result<()> {
+	ensure!(
+		version == PROTOCOL_VERSION,
+		"unsupported epoxy protocol version: {version}"
+	);
+	Ok(())
+}
+
+fn deserialize_request(body: &[u8]) -> Result<protocol::Request> {
+	serde_bare::from_slice(body).map_err(Into::into)
+}
+
+fn request_kind_label(kind: &protocol::RequestKind) -> &'static str {
+	match kind {
+		protocol::RequestKind::UpdateConfigRequest(_) => "update_config",
+		protocol::RequestKind::PrepareRequest(_) => "prepare",
+		protocol::RequestKind::AcceptRequest(_) => "accept",
+		protocol::RequestKind::CommitRequest(_) => "commit",
+		protocol::RequestKind::ChangelogReadRequest(_) => "changelog_read",
+		protocol::RequestKind::HealthCheckRequest => "health_check",
+		protocol::RequestKind::CoordinatorUpdateReplicaStatusRequest(_) => {
+			"coordinator_update_replica_status"
+		}
+		protocol::RequestKind::BeginLearningRequest(_) => "begin_learning",
+		protocol::RequestKind::KvGetRequest(_) => "kv_get",
+		protocol::RequestKind::KvPurgeCacheRequest(_) => "kv_purge_cache",
+	}
+}
 
-	// Assert that the request is intended for this replica
+async fn handle_request(ctx: ApiCtx, request: protocol::Request) -> Result<Vec<u8>> {
 	let current_replica_id = ctx.config().epoxy_replica_id();
 	ensure!(
 		request.to_replica_id == current_replica_id,
@@ -27,8 +87,11 @@ pub async fn message(ctx: ApiCtx, path: VersionedPath, _query: (), body: Bytes)
 		current_replica_id
 	);
 
-	// Process message directly using ops
-	let response = crate::replica::message_request::message_request(&ctx, request).await?;
+	let kind_label = request_kind_label(&request.kind);
+	let start = Instant::now();
+	let res = crate::replica::message_request::message_request(&ctx, request).await;
+	let result_label = if res.is_ok() { "ok" } else { "err" };
+	metrics::record_request(kind_label, result_label, start.elapsed());
 
-	versioned::Response::wrap_latest(response).serialize(path.version)
+	serde_bare::to_vec(&res?).map_err(Into::into)
 }

package/packages/epoxy/src/keys/keys.rs

@@ -1,6 +1,30 @@
-use anyhow::*;
-use std::result::Result::Ok;
+use anyhow::Result;
+use epoxy_protocol::protocol;
+use serde::{Deserialize, Serialize};
 use universaldb::prelude::*;
+use universaldb::tuple::Versionstamp;
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
+pub struct CommittedValue {
+	pub value: Vec<u8>,
+	pub version: u64,
+	pub mutable: bool,
+}
+
+/// In-flight accepted proposal state stored under `kv/{key}/accepted`.
+///
+/// This uses raw `serde_bare` serialization rather than the versioned protocol path because
+/// accepted state is transient. It is cleared on every commit and never survives a full
+/// consensus round, so forward-compatible deserialization is not needed.
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
+pub struct KvAcceptedValue {
+	pub value: Vec<u8>,
+	pub ballot: protocol::Ballot,
+	#[serde(default)]
+	pub version: u64,
+	#[serde(default)]
+	pub mutable: bool,
+}
 
 #[derive(Debug, Clone)]
 pub struct KvValueKey {
@@ -18,6 +42,60 @@ impl KvValueKey {
 }
 
 impl FormalKey for KvValueKey {
+	type Value = CommittedValue;
+
+	fn deserialize(&self, raw: &[u8]) -> Result<Self::Value> {
+		serde_bare::from_slice(raw).map_err(Into::into)
+	}
+
+	fn serialize(&self, value: Self::Value) -> Result<Vec<u8>> {
+		serde_bare::to_vec(&value).map_err(Into::into)
+	}
+}
+
+impl TuplePack for KvValueKey {
+	fn pack<W: std::io::Write>(
+		&self,
+		w: &mut W,
+		tuple_depth: TupleDepth,
+	) -> std::io::Result<VersionstampOffset> {
+		let t = (KV, &self.key, VALUE);
+		t.pack(w, tuple_depth)
+	}
+}
+
+impl<'de> TupleUnpack<'de> for KvValueKey {
+	fn unpack(input: &[u8], tuple_depth: TupleDepth) -> PackResult<(&[u8], Self)> {
+		let (input, (root, key, leaf)) = <(usize, Vec<u8>, usize)>::unpack(input, tuple_depth)?;
+		if root != KV {
+			return Err(PackError::Message("expected KV root".into()));
+		}
+		if leaf != VALUE {
+			return Err(PackError::Message("expected VALUE leaf".into()));
+		}
+
+		let v = KvValueKey { key };
+
+		Ok((input, v))
+	}
+}
+
+#[derive(Debug, Clone)]
+pub struct LegacyCommittedValueKey {
+	key: Vec<u8>,
+}
+
+impl LegacyCommittedValueKey {
+	pub fn new(key: Vec<u8>) -> Self {
+		Self { key }
+	}
+
+	pub fn key(&self) -> &[u8] {
+		&self.key
+	}
+}
+
+impl FormalKey for LegacyCommittedValueKey {
 	type Value = Vec<u8>;
 
 	fn deserialize(&self, raw: &[u8]) -> Result<Self::Value> {
@@ -29,7 +107,7 @@ impl FormalKey for KvValueKey {
 	}
 }
 
-impl TuplePack for KvValueKey {
+impl TuplePack for LegacyCommittedValueKey {
 	fn pack<W: std::io::Write>(
 		&self,
 		w: &mut W,
@@ -40,11 +118,125 @@ impl TuplePack for KvValueKey {
 	}
 }
 
-impl<'de> TupleUnpack<'de> for KvValueKey {
+impl<'de> TupleUnpack<'de> for LegacyCommittedValueKey {
 	fn unpack(input: &[u8], tuple_depth: TupleDepth) -> PackResult<(&[u8], Self)> {
-		let (input, (_, key, _)) = <(usize, Vec<u8>, usize)>::unpack(input, tuple_depth)?;
+		let (input, (root, key, leaf)) = <(usize, Vec<u8>, usize)>::unpack(input, tuple_depth)?;
+		if root != KV {
+			return Err(PackError::Message("expected KV root".into()));
+		}
+		if leaf != COMMITTED_VALUE {
+			return Err(PackError::Message("expected COMMITTED_VALUE leaf".into()));
+		}
 
-		let v = KvValueKey { key };
+		let v = LegacyCommittedValueKey { key };
+
+		Ok((input, v))
+	}
+}
+
+#[derive(Debug, Clone)]
+pub struct KvBallotKey {
+	key: Vec<u8>,
+}
+
+impl KvBallotKey {
+	pub fn new(key: Vec<u8>) -> Self {
+		Self { key }
+	}
+
+	pub fn key(&self) -> &[u8] {
+		&self.key
+	}
+}
+
+impl FormalKey for KvBallotKey {
+	type Value = protocol::Ballot;
+
+	fn deserialize(&self, raw: &[u8]) -> Result<Self::Value> {
+		serde_bare::from_slice(raw).map_err(Into::into)
+	}
+
+	fn serialize(&self, value: Self::Value) -> Result<Vec<u8>> {
+		serde_bare::to_vec(&value).map_err(Into::into)
+	}
+}
+
+impl TuplePack for KvBallotKey {
+	fn pack<W: std::io::Write>(
+		&self,
+		w: &mut W,
+		tuple_depth: TupleDepth,
+	) -> std::io::Result<VersionstampOffset> {
+		let t = (KV, &self.key, BALLOT);
+		t.pack(w, tuple_depth)
+	}
+}
+
+impl<'de> TupleUnpack<'de> for KvBallotKey {
+	fn unpack(input: &[u8], tuple_depth: TupleDepth) -> PackResult<(&[u8], Self)> {
+		let (input, (root, key, leaf)) = <(usize, Vec<u8>, usize)>::unpack(input, tuple_depth)?;
+		if root != KV {
+			return Err(PackError::Message("expected KV root".into()));
+		}
+		if leaf != BALLOT {
+			return Err(PackError::Message("expected BALLOT leaf".into()));
+		}
+
+		let v = KvBallotKey { key };
+
+		Ok((input, v))
+	}
+}
+
+#[derive(Debug, Clone)]
+pub struct KvAcceptedKey {
+	key: Vec<u8>,
+}
+
+impl KvAcceptedKey {
+	pub fn new(key: Vec<u8>) -> Self {
+		Self { key }
+	}
+
+	pub fn key(&self) -> &[u8] {
+		&self.key
+	}
+}
+
+impl FormalKey for KvAcceptedKey {
+	type Value = KvAcceptedValue;
+
+	fn deserialize(&self, raw: &[u8]) -> Result<Self::Value> {
+		serde_bare::from_slice(raw).map_err(Into::into)
+	}
+
+	fn serialize(&self, value: Self::Value) -> Result<Vec<u8>> {
+		serde_bare::to_vec(&value).map_err(Into::into)
+	}
+}
+
+impl TuplePack for KvAcceptedKey {
+	fn pack<W: std::io::Write>(
+		&self,
+		w: &mut W,
+		tuple_depth: TupleDepth,
+	) -> std::io::Result<VersionstampOffset> {
+		let t = (KV, &self.key, ACCEPTED);
+		t.pack(w, tuple_depth)
+	}
+}
+
+impl<'de> TupleUnpack<'de> for KvAcceptedKey {
+	fn unpack(input: &[u8], tuple_depth: TupleDepth) -> PackResult<(&[u8], Self)> {
+		let (input, (root, key, leaf)) = <(usize, Vec<u8>, usize)>::unpack(input, tuple_depth)?;
+		if root != KV {
+			return Err(PackError::Message("expected KV root".into()));
+		}
+		if leaf != ACCEPTED {
+			return Err(PackError::Message("expected ACCEPTED leaf".into()));
+		}
+
+		let v = KvAcceptedKey { key };
 
 		Ok((input, v))
 	}
@@ -66,14 +258,14 @@ impl KvOptimisticCacheKey {
 }
 
 impl FormalKey for KvOptimisticCacheKey {
-	type Value = Vec<u8>;
+	type Value = CommittedValue;
 
 	fn deserialize(&self, raw: &[u8]) -> Result<Self::Value> {
-		Ok(raw.to_vec())
+		serde_bare::from_slice(raw).map_err(Into::into)
 	}
 
 	fn serialize(&self, value: Self::Value) -> Result<Vec<u8>> {
-		Ok(value)
+		serde_bare::to_vec(&value).map_err(Into::into)
 	}
 }
 
@@ -83,17 +275,74 @@ impl TuplePack for KvOptimisticCacheKey {
 		w: &mut W,
 		tuple_depth: TupleDepth,
 	) -> std::io::Result<VersionstampOffset> {
-		let t = (KV, &self.key, OPTIMISTIC_CACHED_VALUE);
+		let t = (KV, &self.key, CACHE);
 		t.pack(w, tuple_depth)
 	}
 }
 
 impl<'de> TupleUnpack<'de> for KvOptimisticCacheKey {
 	fn unpack(input: &[u8], tuple_depth: TupleDepth) -> PackResult<(&[u8], Self)> {
-		let (input, (_, key, _)) = <(usize, Vec<u8>, usize)>::unpack(input, tuple_depth)?;
+		let (input, (root, key, leaf)) = <(usize, Vec<u8>, usize)>::unpack(input, tuple_depth)?;
+		if root != KV {
+			return Err(PackError::Message("expected KV root".into()));
+		}
+		if leaf != CACHE {
+			return Err(PackError::Message("expected CACHE leaf".into()));
+		}
 
 		let v = KvOptimisticCacheKey { key };
 
 		Ok((input, v))
 	}
 }
+
+#[derive(Debug, Clone)]
+pub struct ChangelogKey {
+	versionstamp: Versionstamp,
+}
+
+impl ChangelogKey {
+	pub fn new(versionstamp: Versionstamp) -> Self {
+		Self { versionstamp }
+	}
+
+	pub fn versionstamp(&self) -> &Versionstamp {
+		&self.versionstamp
+	}
+}
+
+impl FormalKey for ChangelogKey {
+	type Value = protocol::ChangelogEntry;
+
+	fn deserialize(&self, raw: &[u8]) -> Result<Self::Value> {
+		serde_bare::from_slice(raw).map_err(Into::into)
+	}
+
+	fn serialize(&self, value: Self::Value) -> Result<Vec<u8>> {
+		serde_bare::to_vec(&value).map_err(Into::into)
+	}
+}
+
+impl TuplePack for ChangelogKey {
+	fn pack<W: std::io::Write>(
+		&self,
+		w: &mut W,
+		tuple_depth: TupleDepth,
+	) -> std::io::Result<VersionstampOffset> {
+		let t = (CHANGELOG, self.versionstamp.clone());
+		t.pack(w, tuple_depth)
+	}
+}
+
+impl<'de> TupleUnpack<'de> for ChangelogKey {
+	fn unpack(input: &[u8], tuple_depth: TupleDepth) -> PackResult<(&[u8], Self)> {
+		let (input, (root, versionstamp)) = <(usize, Versionstamp)>::unpack(input, tuple_depth)?;
+		if root != CHANGELOG {
+			return Err(PackError::Message("expected CHANGELOG root".into()));
+		}
+
+		let v = ChangelogKey { versionstamp };
+
+		Ok((input, v))
+	}
+}

package/packages/epoxy/src/keys/mod.rs

@@ -4,6 +4,16 @@ use universaldb::prelude::*;
 pub mod keys;
 pub mod replica;
 
+pub use self::keys::{
+	ChangelogKey, CommittedValue, KvAcceptedKey, KvAcceptedValue, KvBallotKey,
+	KvOptimisticCacheKey, KvValueKey, LegacyCommittedValueKey,
+};
+pub use self::replica::ConfigKey;
+
 pub fn subspace(replica_id: ReplicaId) -> universaldb::utils::Subspace {
-	universaldb::utils::Subspace::new(&(RIVET, EPOXY, REPLICA, replica_id))
+	universaldb::utils::Subspace::new(&(RIVET, EPOXY_V2, REPLICA, replica_id))
+}
+
+pub fn legacy_subspace(replica_id: ReplicaId) -> universaldb::utils::Subspace {
+	universaldb::utils::Subspace::new(&(RIVET, EPOXY_V1, REPLICA, replica_id))
 }