@rivetkit/engine 1.0.0

package/packages/api-builder/src/context.rs

@@ -0,0 +1,98 @@
+use std::{fmt, ops::Deref};
+
+use anyhow::*;
+use axum::extract::{FromRequest, Request};
+use gas::prelude::*;
+
+use crate::{ApiError, GlobalApiCtx, RequestIds};
+
+/// Request-specific API context
+#[derive(Clone)]
+pub struct ApiCtx {
+	ray_id: Id,
+	req_id: Id,
+	standalone_ctx: StandaloneCtx,
+}
+
+impl Deref for ApiCtx {
+	type Target = StandaloneCtx;
+
+	fn deref(&self) -> &Self::Target {
+		&self.standalone_ctx
+	}
+}
+
+impl fmt::Debug for ApiCtx {
+	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+		f.debug_struct("ApiCtx")
+			.field("global", &"GlobalApiCtx { ... }")
+			.finish()
+	}
+}
+
+impl ApiCtx {
+	pub fn new(global: GlobalApiCtx, ray_id: Id, req_id: Id) -> Result<Self> {
+		let standalone_ctx = StandaloneCtx::new(
+			global.db.clone(),
+			global.config.clone(),
+			global.pools.clone(),
+			global.cache.clone(),
+			global.name,
+			ray_id,
+			req_id,
+		)?;
+
+		Ok(Self {
+			ray_id,
+			req_id,
+			standalone_ctx,
+		})
+	}
+
+	pub fn new_from_activity(ctx: &ActivityCtx) -> Result<Self> {
+		let req_id = Id::new_v1(ctx.config().dc_label());
+
+		Ok(Self {
+			ray_id: ctx.ray_id(),
+			req_id,
+			standalone_ctx: StandaloneCtx::new_from_activity(ctx, req_id)?,
+		})
+	}
+
+	pub fn new_from_operation(ctx: &OperationCtx) -> Result<Self> {
+		let req_id = Id::new_v1(ctx.config().dc_label());
+
+		Ok(Self {
+			ray_id: ctx.ray_id(),
+			req_id,
+			standalone_ctx: StandaloneCtx::new_from_operation(ctx, req_id)?,
+		})
+	}
+
+	pub fn ray_id(&self) -> Id {
+		self.ray_id
+	}
+
+	pub fn req_id(&self) -> Id {
+		self.req_id
+	}
+}
+
+impl FromRequest<GlobalApiCtx> for ApiCtx {
+	type Rejection = ApiError;
+
+	async fn from_request(req: Request, state: &GlobalApiCtx) -> Result<Self, Self::Rejection> {
+		let global = state.clone();
+
+		let dc_label = state.config.dc_label();
+
+		// Try to get request IDs from request extensions (set by logging middleware)
+		let request_ids = req
+			.extensions()
+			.get::<RequestIds>()
+			.copied()
+			.unwrap_or_else(|| RequestIds::new(dc_label));
+
+		ApiCtx::new(global, request_ids.ray_id, request_ids.req_id).map_err(ApiError::from)
+	}
+}

package/packages/api-builder/src/error_response.rs

@@ -0,0 +1,116 @@
+use std::{borrow::Cow, fmt};
+
+use axum::{
+	http::StatusCode,
+	response::{IntoResponse, Json, Response},
+};
+use rivet_error::*;
+use serde::{Deserialize, Serialize};
+
+/// API Error wrapper that implements IntoResponse for building error responses
+#[derive(Debug)]
+pub struct ApiError(anyhow::Error);
+
+impl From<anyhow::Error> for ApiError {
+	fn from(err: anyhow::Error) -> Self {
+		ApiError(err)
+	}
+}
+
+impl IntoResponse for ApiError {
+	fn into_response(self) -> Response {
+		let (status, error_response) =
+			if let Some(rivet_err) = self.0.chain().find_map(|x| x.downcast_ref::<RivetError>()) {
+				let status = match (rivet_err.group(), rivet_err.code()) {
+					("api", "not_found") => StatusCode::NOT_FOUND,
+					("api", "unauthorized") => StatusCode::UNAUTHORIZED,
+					("api", "forbidden") => StatusCode::FORBIDDEN,
+					_ => StatusCode::BAD_REQUEST,
+				};
+
+				(status, ErrorResponse::from(rivet_err))
+			} else if let Some(raw_err) = self
+				.0
+				.chain()
+				.find_map(|x| x.downcast_ref::<RawErrorResponse>())
+			{
+				(raw_err.0, raw_err.1.clone())
+			} else {
+				(
+					StatusCode::INTERNAL_SERVER_ERROR,
+					ErrorResponse::from(&RivetError {
+						schema: &rivet_error::INTERNAL_ERROR,
+						meta: None,
+						message: None,
+					}),
+				)
+			};
+
+		let error_ext = ErrorExt {
+			group: error_response.group.clone(),
+			code: error_response.code.clone(),
+			metadata: error_response.metadata.clone(),
+			// If internal error, print information about the root error
+			internal: if error_response.group == rivet_error::INTERNAL_ERROR.group
+				&& error_response.code == rivet_error::INTERNAL_ERROR.code
+			{
+				tracing::debug!(err=?self.0, "internal debug error");
+				Some(format!("{}", self.0).into())
+			} else {
+				None
+			},
+		};
+
+		// Build response
+		let mut res = (status, Json(error_response.clone())).into_response();
+
+		// Add extension so we can reference it when logging response
+		res.extensions_mut().insert(error_ext);
+
+		res
+	}
+}
+
+/// JSON data structured used to serialize JSON error responses.
+#[derive(Debug, Serialize, Deserialize, Clone)]
+pub struct ErrorResponse {
+	pub group: Cow<'static, str>,
+	pub code: Cow<'static, str>,
+	pub message: String,
+	#[serde(skip_serializing_if = "Option::is_none")]
+	pub metadata: Option<serde_json::Value>,
+}
+
+impl From<&RivetError> for ErrorResponse {
+	fn from(value: &RivetError) -> Self {
+		ErrorResponse {
+			group: value.group().into(),
+			code: value.code().into(),
+			message: value.message().into(),
+			metadata: value.metadata(),
+		}
+	}
+}
+
+/// Error response received from an upstream service. This will re-serialize in to the same error
+/// type.
+#[derive(Debug, Clone)]
+pub struct RawErrorResponse(pub StatusCode, pub ErrorResponse);
+
+impl fmt::Display for RawErrorResponse {
+	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+		write!(f, "{}: {}", self.1.code, self.1.message)
+	}
+}
+
+impl std::error::Error for RawErrorResponse {}
+
+/// Response extension that includes information about the root error for logging.
+#[derive(Clone)]
+pub struct ErrorExt {
+	pub group: Cow<'static, str>,
+	pub code: Cow<'static, str>,
+	pub metadata: Option<serde_json::Value>,
+	/// If this is an internal error, this provides a formatted string of the root error
+	pub internal: Option<Cow<'static, str>>,
+}

package/packages/api-builder/src/errors.rs

@@ -0,0 +1,29 @@
+use rivet_error::*;
+use serde::Serialize;
+
+#[derive(RivetError)]
+#[error("api", "not_found", "The requested resource was not found")]
+pub struct ApiNotFound;
+
+#[derive(RivetError)]
+#[error("api", "unauthorized", "Authentication required")]
+pub struct ApiUnauthorized;
+
+#[derive(RivetError)]
+#[error("api", "forbidden", "Access denied")]
+pub struct ApiForbidden;
+
+#[derive(RivetError)]
+#[error("api", "internal_error", "An internal server error occurred")]
+pub struct ApiInternalError;
+
+#[derive(RivetError, Serialize)]
+#[error(
+	"api",
+	"bad_request",
+	"Request is invalid",
+	"Request is invalid: {reason}"
+)]
+pub struct ApiBadRequest {
+	pub reason: String,
+}

package/packages/api-builder/src/extract.rs

@@ -0,0 +1,137 @@
+use axum::{
+	extract::{
+		Request,
+		rejection::{ExtensionRejection, JsonRejection, PathRejection},
+		{FromRequest, FromRequestParts},
+	},
+	response::IntoResponse,
+};
+use axum_extra::extract::QueryRejection;
+use http::request::Parts;
+use serde::Serialize;
+
+use crate::{error_response::ApiError, errors::ApiBadRequest};
+
+pub struct ExtractorError(ApiError);
+
+impl IntoResponse for ExtractorError {
+	fn into_response(self) -> axum::response::Response {
+		let mut res = self.0.into_response();
+
+		res.extensions_mut().insert(FailedExtraction);
+
+		res
+	}
+}
+
+#[derive(Clone, Copy)]
+pub struct FailedExtraction;
+
+pub struct Json<T>(pub T);
+
+impl<S, T> FromRequest<S> for Json<T>
+where
+	axum::extract::Json<T>: FromRequest<S, Rejection = JsonRejection>,
+	S: Send + Sync,
+{
+	type Rejection = ExtractorError;
+
+	async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
+		axum::extract::Json::<T>::from_request(req, state)
+			.await
+			.map(|json| Json(json.0))
+			.map_err(|err| {
+				ExtractorError(
+					ApiBadRequest {
+						reason: err.body_text(),
+					}
+					.build()
+					.into(),
+				)
+			})
+	}
+}
+
+impl<T: Serialize> IntoResponse for Json<T> {
+	fn into_response(self) -> axum::response::Response {
+		let Self(value) = self;
+		axum::extract::Json(value).into_response()
+	}
+}
+
+pub struct Query<T>(pub T);
+
+impl<S, T> FromRequestParts<S> for Query<T>
+where
+	axum_extra::extract::Query<T>: FromRequestParts<S, Rejection = QueryRejection>,
+	S: Send + Sync,
+{
+	type Rejection = ExtractorError;
+
+	async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+		let res = axum_extra::extract::Query::<T>::from_request_parts(parts, state)
+			.await
+			.map(|query| Query(query.0))
+			.map_err(|err| {
+				ExtractorError(
+					ApiBadRequest {
+						reason: err.body_text(),
+					}
+					.build()
+					.into(),
+				)
+			});
+
+		res
+	}
+}
+
+pub struct Extension<T>(pub T);
+
+impl<S, T> FromRequestParts<S> for Extension<T>
+where
+	axum::extract::Extension<T>: FromRequestParts<S, Rejection = ExtensionRejection>,
+	S: Send + Sync,
+{
+	type Rejection = ExtractorError;
+
+	async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+		axum::extract::Extension::<T>::from_request_parts(parts, state)
+			.await
+			.map(|ext| Extension(ext.0))
+			.map_err(|err| {
+				ExtractorError(
+					ApiBadRequest {
+						reason: err.body_text(),
+					}
+					.build()
+					.into(),
+				)
+			})
+	}
+}
+
+pub struct Path<T>(pub T);
+
+impl<S, T> FromRequestParts<S> for Path<T>
+where
+	axum::extract::Path<T>: FromRequestParts<S, Rejection = PathRejection>,
+	S: Send + Sync,
+{
+	type Rejection = ExtractorError;
+
+	async fn from_request_parts(parts: &mut Parts, state: &S) -> Result<Self, Self::Rejection> {
+		axum::extract::Path::<T>::from_request_parts(parts, state)
+			.await
+			.map(|ext| Path(ext.0))
+			.map_err(|err| {
+				ExtractorError(
+					ApiBadRequest {
+						reason: err.body_text(),
+					}
+					.build()
+					.into(),
+				)
+			})
+	}
+}

package/packages/api-builder/src/global_context.rs

@@ -0,0 +1,31 @@
+use anyhow::*;
+use gas::prelude::*;
+
+/// Global API context that contains shared resources
+#[derive(Clone)]
+pub struct GlobalApiCtx {
+	pub db: gas::prelude::db::DatabaseHandle,
+	pub config: rivet_config::Config,
+	pub pools: rivet_pools::Pools,
+	pub cache: rivet_cache::Cache,
+	pub name: &'static str,
+}
+
+impl GlobalApiCtx {
+	pub async fn new(
+		config: rivet_config::Config,
+		pools: rivet_pools::Pools,
+		name: &'static str,
+	) -> Result<Self> {
+		let cache = rivet_cache::CacheInner::from_env(&config, pools.clone())?;
+		let db = gas::prelude::db::DatabaseKv::from_pools(pools.clone()).await?;
+
+		Ok(Self {
+			db,
+			config,
+			pools,
+			cache,
+			name,
+		})
+	}
+}

package/packages/api-builder/src/lib.rs

@@ -0,0 +1,19 @@
+pub mod context;
+pub mod error_response;
+pub mod errors;
+pub mod extract;
+pub mod global_context;
+pub mod metrics;
+pub mod middleware;
+pub mod prelude;
+pub mod request_ids;
+pub mod router;
+pub mod wrappers;
+
+pub use context::*;
+pub use error_response::*;
+pub use errors::*;
+pub use global_context::*;
+pub use middleware::*;
+pub use request_ids::*;
+pub use router::*;

package/packages/api-builder/src/metrics.rs

@@ -0,0 +1,29 @@
+use rivet_metrics::{
+	BUCKETS,
+	otel::{global::*, metrics::*},
+};
+
+lazy_static::lazy_static! {
+	static ref METER: Meter = meter("rivet-api-builder");
+
+	// TODO: Request body size
+	// TODO: Response body size
+	// Keys "method", "path"
+	pub static ref API_REQUEST_PENDING: UpDownCounter<i64> = METER.i64_up_down_counter("rivet_api_request_pending")
+			.with_description("Total number of requests in progress.")
+			.build();
+
+	/// Expected attributes: "method", "path"
+	pub static ref API_REQUEST_TOTAL: Counter<u64> = METER.u64_counter("rivet_api_request_total")
+		.with_description("Total number of requests.")
+		.build();
+	/// Expected attributes: "method", "path", "status", "error_code"
+	pub static ref API_REQUEST_DURATION: Histogram<f64> = METER.f64_histogram("rivet_api_request_duration")
+		.with_description("Duration of API requests.")
+		.with_boundaries(BUCKETS.to_vec())
+		.build();
+	/// Expected attributes: "method", "path", "status", "error_code"
+	pub static ref API_REQUEST_ERRORS: Counter<u64> = METER.u64_counter("rivet_api_request_errors")
+		.with_description("All errors made to this request.")
+		.build();
+}

package/packages/api-builder/src/middleware.rs

@@ -0,0 +1,232 @@
+use std::{net::SocketAddr, time::Instant};
+
+use anyhow::Result;
+use axum::{
+	body::{Body, HttpBody},
+	extract::{ConnectInfo, State},
+	http::{Request, StatusCode},
+	middleware::Next,
+	response::Response,
+};
+use hyper::header::HeaderName;
+use opentelemetry::trace::TraceContextExt;
+use rivet_metrics::KeyValue;
+use tower_http::trace::TraceLayer;
+use tracing::Instrument;
+use tracing_opentelemetry::OpenTelemetrySpanExt;
+
+use crate::{ErrorExt, RequestIds, metrics};
+
+pub const X_RIVET_RAY_ID: HeaderName = HeaderName::from_static("x-rivet-ray-id");
+
+// TODO: Remove this since this is duplicate logs & traces, but this is just to see what Axum adds
+// natively vs our logging. We can add this once we're satisfied with our own logging.
+pub fn create_trace_layer()
+-> TraceLayer<tower_http::classify::SharedClassifier<tower_http::classify::ServerErrorsAsFailures>>
+{
+	TraceLayer::new_for_http()
+}
+
+/// HTTP request logging and metrics middleware
+pub async fn http_logging_middleware(
+	State(config): State<rivet_config::Config>,
+	mut req: Request<Body>,
+	next: Next,
+) -> Result<Response, StatusCode> {
+	let start = Instant::now();
+
+	// Extract socket address from request extensions
+	let remote_addr = req
+		.extensions()
+		.get::<ConnectInfo<SocketAddr>>()
+		.map(|ci| ci.0)
+		.unwrap_or(SocketAddr::from(([0, 0, 0, 0], 0)));
+
+	// Get trace context
+	let current_span_ctx = tracing::Span::current()
+		.context()
+		.span()
+		.span_context()
+		.clone();
+
+	// Add request IDs to request extensions if not already added by guard so they can be accessed by handlers
+	let request_ids = if let Some(request_ids) = req.extensions().get::<RequestIds>() {
+		*request_ids
+	} else {
+		let request_ids = RequestIds::new(config.dc_label());
+		req.extensions_mut().insert(request_ids);
+		request_ids
+	};
+
+	// Create span for this request
+	let req_span = tracing::info_span!(
+		parent: None,
+		"http_request",
+		method = %req.method(),
+		uri = %req.uri(),
+		ray_id = %request_ids.ray_id,
+		req_id = %request_ids.req_id,
+	);
+	req_span.add_link(current_span_ctx);
+
+	// Extract headers for logging
+	let headers = req.headers();
+	let referrer = headers
+		.get("referer")
+		.map_or("-", |h| h.to_str().unwrap_or("-"))
+		.to_string();
+	let user_agent = headers
+		.get("user-agent")
+		.map_or("-", |h| h.to_str().unwrap_or("-"))
+		.to_string();
+	let x_forwarded_for = headers
+		.get("x-forwarded-for")
+		.map_or("-", |h| h.to_str().unwrap_or("-"))
+		.to_string();
+
+	let method = req.method().clone();
+	let uri = req.uri().clone();
+	let path = uri.path().to_string();
+	let protocol = req.version();
+
+	// Log request metadata
+	tracing::debug!(
+		%method,
+		%uri,
+		body_size_hint = ?req.body().size_hint(),
+		%remote_addr,
+		"http request"
+	);
+
+	// Metrics
+	metrics::API_REQUEST_PENDING.add(
+		1,
+		&[
+			KeyValue::new("method", method.to_string()),
+			KeyValue::new("path", path.clone()),
+		],
+	);
+	metrics::API_REQUEST_TOTAL.add(
+		1,
+		&[
+			KeyValue::new("method", method.to_string()),
+			KeyValue::new("path", path.clone()),
+		],
+	);
+
+	// Clone values for the async block
+	let method_clone = method.clone();
+	let path_clone = path.clone();
+
+	// Process the request
+	let response = async move {
+		let mut response = next.run(req).await;
+
+		// Add ray_id to response headers
+		if let Ok(ray_id_value) = request_ids.ray_id.to_string().parse() {
+			response.headers_mut().insert(X_RIVET_RAY_ID, ray_id_value);
+		}
+
+		let status = response.status();
+		let status_code = status.as_u16();
+
+		let error = response.extensions().get::<ErrorExt>();
+
+		// Log based on status
+		if status.is_server_error() {
+			let group = error.as_ref().map_or("-", |x| &x.group);
+			let code = error.as_ref().map_or("-", |x| &x.code);
+			let meta = error.as_ref().and_then(|x| x.metadata.as_ref()).unwrap_or(&serde_json::Value::Null);
+			let internal = error.as_ref().and_then(|x| x.internal.as_ref()).map_or("-", |x| x.as_ref());
+
+			tracing::error!(
+				status=?status_code,
+				%group,
+				%code,
+				%meta,
+				%internal,
+				"http server error"
+			);
+		} else if status.is_client_error() {
+			let group = error.as_ref().map_or("-", |x| &x.group);
+			let code = error.as_ref().map_or("-", |x| &x.code);
+			let meta = error.as_ref().and_then(|x| x.metadata.as_ref()).unwrap_or(&serde_json::Value::Null);
+
+			tracing::info!(
+				status=?status_code,
+				%group,
+				%code,
+				%meta,
+				"http client error"
+			);
+		} else if status.is_redirection() {
+			tracing::debug!(status=?status_code, "http redirection");
+		} else if status.is_informational() {
+			tracing::debug!(status=?status_code, "http informational");
+		}
+
+		let duration = start.elapsed().as_secs_f64();
+
+		tracing::debug!(
+			%remote_addr,
+			%method,
+			%uri,
+			?protocol,
+			status = status_code,
+			body_bytes_sent = response.body().size_hint().lower(),
+			request_duration = %format!("{:.3}ms", duration * 1000.0),
+			%referrer,
+			%user_agent,
+			%x_forwarded_for,
+			error_group = %error.as_ref().map_or("-", |x| &x.group),
+			error_code = %error.as_ref().map_or("-", |x| &x.code),
+			error_meta = %error.as_ref().and_then(|x| x.metadata.as_ref()).unwrap_or(&serde_json::Value::Null),
+			error_internal = %error.as_ref().and_then(|x| x.internal.as_ref()).map_or("-", |x| x.as_ref()),
+			"http response"
+		);
+
+		// Update metrics
+		metrics::API_REQUEST_PENDING.add(
+			-1,
+			&[
+				KeyValue::new("method", method_clone.to_string()),
+				KeyValue::new("path", path_clone.clone()),
+			],
+		);
+
+		let error_code: String = if status.is_success() {
+			String::new()
+		} else if let Some(err) = &error {
+			format!("{}.{}", err.group, err.code)
+		} else {
+			String::new()
+		};
+		metrics::API_REQUEST_DURATION.record(
+			duration,
+			&[
+				KeyValue::new("method", method_clone.to_string()),
+				KeyValue::new("path", path_clone.clone()),
+				KeyValue::new("status", status.to_string()),
+				KeyValue::new("error_code", error_code.clone()),
+			],
+		);
+
+		if !status.is_success() {
+			metrics::API_REQUEST_ERRORS.add(
+				1,
+				&[
+					KeyValue::new("method", method_clone.to_string()),
+					KeyValue::new("path", path_clone.clone()),
+					KeyValue::new("status", status.to_string()),
+					KeyValue::new("error_code", error_code),
+				],
+			);
+		}
+
+		response
+	}
+	.instrument(req_span)
+	.await;
+
+	Ok(response)
+}

package/packages/api-builder/src/prelude.rs

@@ -0,0 +1,18 @@
+/// Prelude module for easy importing of common API types and handler methods
+pub use crate::{ApiCtx, ApiError, GlobalApiCtx};
+
+// Error types
+pub use crate::errors::{ApiForbidden, ApiInternalError, ApiNotFound, ApiUnauthorized};
+
+// HTTP method handlers
+pub use crate::router::ApiRouter;
+pub use crate::wrappers::{bin, delete, get, patch, post, put};
+
+// Common types
+pub use anyhow::Result;
+pub use axum::{
+	Router,
+	extract::{Extension, Path, Query},
+	response::{IntoResponse, Json},
+};
+pub use serde::{Deserialize, Serialize};