use std::{
fmt,
time::{Duration, SystemTime, UNIX_EPOCH},
};
use serde::{Deserialize, Serialize};
use serde_json::Value;
use crate::{
error::SdkError,
image_service_builds,
sandbox_image_catalog::ImageServiceImage,
sandbox_images::{
ResolvedBuildContext, SandboxImageBuildError, SandboxImageBuildEvent,
SandboxImageBuildOptions, SandboxImageImportOptions,
},
sandbox_templates::models::SandboxTemplate,
};
pub type ImageBuildResult = SandboxTemplate;
pub const IDEMPOTENCY_KEY_HEADER: &str = "Idempotency-Key";
pub const CANCEL_HANDSHAKE_BUDGET: Duration = Duration::from_secs(30);
pub const DEPLOYMENT_RECOVERY_ALLOWANCE: Duration = Duration::from_secs(10 * 60);
pub const DEFAULT_WAIT_LIMIT: Duration = Duration::from_secs(2 * 60 * 60);
pub fn new_client_request_id() -> String {
hex::encode(rand::random::<[u8; 16]>())
}
pub fn validate_client_request_id(id: &str) -> Result<(), String> {
if id.is_empty() || id.len() > 128 {
return Err("client request id must be 1 to 128 characters".to_string());
}
if !id.bytes().all(|b| (0x21..=0x7e).contains(&b)) {
return Err("client request id must be printable ASCII without spaces".to_string());
}
Ok(())
}
macro_rules! wire_enum {
(
$(#[$meta:meta])*
$name:ident { $($(#[$variant_meta:meta])* $variant:ident => $wire:literal),+ $(,)? }
) => {
$(#[$meta])*
#[derive(Debug, Clone, PartialEq, Eq, Hash)]
pub enum $name {
$($(#[$variant_meta])* $variant,)+
Unknown(String),
}
impl $name {
pub fn as_str(&self) -> &str {
match self {
$(Self::$variant => $wire,)+
Self::Unknown(value) => value.as_str(),
}
}
}
impl From<String> for $name {
fn from(value: String) -> Self {
match value.as_str() {
$($wire => Self::$variant,)+
_ => Self::Unknown(value),
}
}
}
impl From<&str> for $name {
fn from(value: &str) -> Self {
Self::from(value.to_string())
}
}
impl From<$name> for String {
fn from(value: $name) -> Self {
value.as_str().to_string()
}
}
impl fmt::Display for $name {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_str())
}
}
impl Serialize for $name {
fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
serializer.serialize_str(self.as_str())
}
}
impl<'de> Deserialize<'de> for $name {
fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
Ok(Self::from(String::deserialize(deserializer)?))
}
}
};
}
wire_enum! {
ImageBuildStatus {
Pending => "pending",
Running => "running",
Succeeded => "succeeded",
Failed => "failed",
Cancelled => "cancelled",
}
}
impl ImageBuildStatus {
pub fn is_terminal(&self) -> bool {
matches!(self, Self::Succeeded | Self::Failed | Self::Cancelled)
}
}
wire_enum! {
ImageBuildPhase {
AwaitingContext => "awaiting_context",
StartingBuilder => "starting_builder",
Executing => "executing",
Snapshotting => "snapshotting",
Publishing => "publishing",
Finished => "finished",
}
}
wire_enum! {
ImageBuildKind {
Import => "import",
Dockerfile => "dockerfile",
Direct => "direct",
}
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ContextUploadCapability {
pub url: String,
#[serde(default)]
pub max_bytes: Option<u64>,
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ImageBuildInfo {
pub build_id: String,
#[serde(default = "unknown_kind")]
pub kind: ImageBuildKind,
#[serde(default)]
pub name: Option<String>,
#[serde(default = "unknown_status")]
pub status: ImageBuildStatus,
#[serde(default)]
pub phase: Option<ImageBuildPhase>,
#[serde(default)]
pub attempt_no: u64,
#[serde(default)]
pub builder_sandbox_id: Option<String>,
#[serde(default)]
pub operation_deadline_ms: Option<u64>,
#[serde(default)]
pub created_at_ms: Option<u64>,
#[serde(default)]
pub updated_at_ms: Option<u64>,
#[serde(default, deserialize_with = "deserialize_result")]
pub result: Option<ImageBuildResult>,
#[serde(default)]
pub error: Option<String>,
}
fn deserialize_result<'de, D>(deserializer: D) -> Result<Option<ImageBuildResult>, D::Error>
where
D: serde::Deserializer<'de>,
{
let wire: Option<ImageServiceImage> = Option::deserialize(deserializer)?;
Ok(wire.map(ImageServiceImage::into_template))
}
fn unknown_kind() -> ImageBuildKind {
ImageBuildKind::Unknown(String::new())
}
fn unknown_status() -> ImageBuildStatus {
ImageBuildStatus::Unknown(String::new())
}
impl ImageBuildInfo {
pub fn from_json(value: Value) -> Result<Self, serde_json::Error> {
serde_json::from_value(value)
}
pub fn operation_deadline(&self) -> Option<SystemTime> {
self.operation_deadline_ms
.map(|ms| UNIX_EPOCH + Duration::from_millis(ms) + DEPLOYMENT_RECOVERY_ALLOWANCE)
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CancelBuildSelector {
BuildId(String),
ClientRequestId(String),
}
impl CancelBuildSelector {
pub(crate) fn body(&self) -> Value {
match self {
Self::BuildId(build_id) => serde_json::json!({ "build_id": build_id }),
Self::ClientRequestId(id) => serde_json::json!({ "client_request_id": id }),
}
}
}
wire_enum! {
CancelBuildOutcome {
Cancelled => "cancelled",
AlreadyCancelled => "already_cancelled",
AlreadyCompleted => "already_completed",
AlreadyFailed => "already_failed",
NotAdmitted => "not_admitted",
}
}
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct CancelBuildResponse {
pub outcome: CancelBuildOutcome,
#[serde(default)]
pub build: Option<ImageBuildInfo>,
}
#[derive(Debug, Clone, Default)]
pub struct InterruptSignal {
token: tokio_util::sync::CancellationToken,
}
impl InterruptSignal {
pub fn new() -> Self {
Self::default()
}
pub fn trigger(&self) {
self.token.cancel();
}
pub fn is_triggered(&self) -> bool {
self.token.is_cancelled()
}
pub async fn triggered(&self) {
self.token.cancelled().await
}
}
#[derive(Debug, Clone, PartialEq)]
pub enum InterruptionOutcome {
Cancelled,
AlreadyCompleted(Option<Box<ImageBuildResult>>),
AlreadyCancelled,
AlreadyFailed(Option<String>),
NotAdmitted,
Unconfirmed(String),
}
#[derive(Debug, Clone, PartialEq)]
pub struct InterruptionReport {
pub build_id: Option<String>,
pub client_request_id: Option<String>,
pub outcome: InterruptionOutcome,
}
impl InterruptionOutcome {
pub fn name(&self) -> &'static str {
match self {
Self::Cancelled => "cancelled",
Self::AlreadyCompleted(_) => "already_completed",
Self::AlreadyCancelled => "already_cancelled",
Self::AlreadyFailed(_) => "already_failed",
Self::NotAdmitted => "not_admitted",
Self::Unconfirmed(_) => "unconfirmed",
}
}
}
impl InterruptionReport {
pub fn is_confirmed_cancelled(&self) -> bool {
matches!(
self.outcome,
InterruptionOutcome::Cancelled
| InterruptionOutcome::AlreadyCancelled
| InterruptionOutcome::AlreadyFailed(_)
)
}
}
impl fmt::Display for InterruptionReport {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
let build = self.build_id.as_deref();
match &self.outcome {
InterruptionOutcome::Cancelled => {
write!(f, "Build {} cancelled", build.unwrap_or("-"))
}
InterruptionOutcome::AlreadyCompleted(result) => {
write!(f, "Build {} already completed", build.unwrap_or("-"))?;
if let Some(result) = result {
write!(
f,
" (image '{}', {})",
result.name.as_deref().unwrap_or("-"),
result.id.as_deref().unwrap_or("-")
)?;
}
Ok(())
}
InterruptionOutcome::AlreadyCancelled => {
write!(f, "Build {} was already cancelled", build.unwrap_or("-"))
}
InterruptionOutcome::AlreadyFailed(error) => {
write!(f, "Build {} had already failed", build.unwrap_or("-"))?;
if let Some(error) = error {
write!(f, ": {error}")?;
}
Ok(())
}
InterruptionOutcome::NotAdmitted => write!(
f,
"No build was admitted for client request id {}; a delayed admission may still \
create one, which can be cancelled by that request id",
self.client_request_id.as_deref().unwrap_or("-")
),
InterruptionOutcome::Unconfirmed(reason) => match (build, &self.client_request_id) {
(Some(build_id), _) => write!(
f,
"Cancellation of build {build_id} was not confirmed: {reason}"
),
(None, Some(request_id)) => write!(
f,
"Cancellation of the build admitted with client request id {request_id} was \
not confirmed: {reason}"
),
(None, None) => write!(f, "Cancellation was not confirmed: {reason}"),
},
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ImageBuildConflict {
pub image_name: Option<String>,
pub active_build_id: Option<String>,
pub active_kind: Option<ImageBuildKind>,
pub active_status: Option<ImageBuildStatus>,
pub message: String,
}
impl fmt::Display for ImageBuildConflict {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.message)
}
}
#[derive(Debug, thiserror::Error)]
pub enum ImageBuildError {
#[error("{0}")]
Usage(String),
#[error("{0}")]
Auth(String),
#[error(
"build {build_id} not found: finished builds are kept only while they are their image's \
current build; a later build of the image or deleting the image retires them"
)]
NotFound { build_id: String },
#[error("{0}")]
InProgress(ImageBuildConflict),
#[error(
"client request id {client_request_id} was already used for a different request: {message}"
)]
IdempotencyKeyReused {
client_request_id: String,
message: String,
},
#[error("build {build_id} failed: {error}")]
Failed {
build_id: String,
error: String,
info: Box<ImageBuildInfo>,
},
#[error("build {build_id} was cancelled")]
Cancelled {
build_id: String,
info: Box<ImageBuildInfo>,
},
#[error(
"build {build_id} did not finish within {}s of waiting; it may still be running (check it \
by build id)",
waited.as_secs()
)]
Timeout { build_id: String, waited: Duration },
#[error("{0}")]
Interrupted(InterruptionReport),
#[error("Image Service request failed (HTTP {status}): {message}")]
Service { status: u16, message: String },
#[error("{0}")]
Sdk(#[from] SdkError),
#[error("IO error: {0}")]
Io(#[from] std::io::Error),
#[error("{0}")]
Json(#[from] serde_json::Error),
#[error("{0}")]
Other(String),
}
impl ImageBuildError {
pub(crate) fn other(message: impl Into<String>) -> Self {
Self::Other(message.into())
}
pub(crate) fn usage(message: impl Into<String>) -> Self {
Self::Usage(message.into())
}
pub fn build_id(&self) -> Option<&str> {
match self {
Self::NotFound { build_id }
| Self::Failed { build_id, .. }
| Self::Cancelled { build_id, .. }
| Self::Timeout { build_id, .. } => Some(build_id),
Self::Interrupted(report) => report.build_id.as_deref(),
Self::InProgress(conflict) => conflict.active_build_id.as_deref(),
_ => None,
}
}
pub fn to_json(&self) -> Value {
let mut payload = serde_json::json!({
"code": self.code(),
"message": self.to_string(),
"build_id": self.build_id(),
});
let object = payload.as_object_mut().expect("object");
match self {
Self::InProgress(conflict) => {
object.insert("image_name".into(), serde_json::json!(conflict.image_name));
object.insert(
"active_build_id".into(),
serde_json::json!(conflict.active_build_id),
);
object.insert(
"active_kind".into(),
serde_json::json!(conflict.active_kind.as_ref().map(ImageBuildKind::as_str)),
);
object.insert(
"active_status".into(),
serde_json::json!(
conflict
.active_status
.as_ref()
.map(ImageBuildStatus::as_str)
),
);
}
Self::IdempotencyKeyReused {
client_request_id, ..
} => {
object.insert(
"client_request_id".into(),
serde_json::json!(client_request_id),
);
}
Self::Failed { error, info, .. } => {
object.insert("error".into(), serde_json::json!(error));
object.insert(
"info".into(),
serde_json::to_value(info).unwrap_or(Value::Null),
);
}
Self::Cancelled { info, .. } => {
object.insert(
"info".into(),
serde_json::to_value(info).unwrap_or(Value::Null),
);
}
Self::Timeout { waited, .. } => {
object.insert("waited_secs".into(), serde_json::json!(waited.as_secs()));
}
Self::Interrupted(report) => {
object.insert(
"client_request_id".into(),
serde_json::json!(report.client_request_id),
);
object.insert("outcome".into(), serde_json::json!(report.outcome.name()));
object.insert(
"confirmed".into(),
serde_json::json!(report.is_confirmed_cancelled()),
);
if let InterruptionOutcome::AlreadyCompleted(Some(result)) = &report.outcome {
object.insert(
"result".into(),
serde_json::to_value(result).unwrap_or(Value::Null),
);
}
}
Self::Service { status, .. } => {
object.insert("status".into(), serde_json::json!(status));
}
_ => {}
}
payload
}
pub fn code(&self) -> &'static str {
match self {
Self::Usage(_) => "usage",
Self::Auth(_) => "auth",
Self::NotFound { .. } => "not_found",
Self::InProgress(_) => "image_build_in_progress",
Self::IdempotencyKeyReused { .. } => "client_request_id_mismatch",
Self::Failed { .. } => "failed",
Self::Cancelled { .. } => "cancelled",
Self::Timeout { .. } => "timeout",
Self::Interrupted(_) => "interrupted",
Self::Service { .. } => "service",
Self::Sdk(_) | Self::Io(_) | Self::Json(_) | Self::Other(_) => "internal",
}
}
}
impl From<SandboxImageBuildError> for ImageBuildError {
fn from(error: SandboxImageBuildError) -> Self {
match error {
SandboxImageBuildError::Build(error) => error,
SandboxImageBuildError::Usage(message) => Self::Usage(message),
SandboxImageBuildError::Auth(message) => Self::Auth(message),
SandboxImageBuildError::Http(error) => Self::Sdk(SdkError::Http(error)),
SandboxImageBuildError::Io(error) => Self::Io(error),
SandboxImageBuildError::Json(error) => Self::Json(error),
SandboxImageBuildError::Sdk(error) => Self::Sdk(error),
other => Self::Other(other.to_string()),
}
}
}
#[derive(Debug, Clone)]
pub struct ImageBuildClientOptions {
pub api_url: String,
pub bearer_token: String,
pub use_scope_headers: bool,
pub organization_id: Option<String>,
pub project_id: Option<String>,
pub namespace: String,
pub user_agent: Option<String>,
}
#[derive(Debug, Clone, Default)]
pub struct ImageBuildWaitOptions {
pub timeout: Option<Duration>,
pub follow_logs: bool,
}
#[derive(Clone)]
pub struct ImageBuildClient {
pub(crate) client: crate::Client,
pub(crate) ctx: ResolvedBuildContext,
}
impl ImageBuildClient {
pub fn new(options: ImageBuildClientOptions) -> Result<Self, ImageBuildError> {
image_service_builds::image_build_client(options)
}
pub async fn get(&self, build_id: &str) -> Result<ImageBuildHandle, ImageBuildError> {
reject_legacy_reference(build_id)?;
let info = image_service_builds::get_build(&self.client, build_id).await?;
Ok(ImageBuildHandle {
client: self.clone(),
build_id: info.build_id.clone(),
client_request_id: None,
info,
})
}
pub async fn wait_build<F>(
&self,
build_id: &str,
options: ImageBuildWaitOptions,
interrupt: &InterruptSignal,
emit: F,
) -> Result<ImageBuildResult, ImageBuildError>
where
F: FnMut(SandboxImageBuildEvent),
{
reject_legacy_reference(build_id)?;
let info = image_service_builds::lookup_and_wait(
&self.client,
Some(&self.ctx),
build_id,
&options,
interrupt,
emit,
)
.await?;
image_service_builds::terminal_result(&info)
}
pub async fn cancel(
&self,
selector: CancelBuildSelector,
) -> Result<CancelBuildResponse, ImageBuildError> {
if let CancelBuildSelector::BuildId(build_id) = &selector {
reject_legacy_reference(build_id)?;
}
image_service_builds::cancel_build(&self.client, &selector, CANCEL_HANDSHAKE_BUDGET).await
}
}
#[derive(Clone)]
pub struct ImageBuildHandle {
pub(crate) client: ImageBuildClient,
pub(crate) build_id: String,
pub(crate) client_request_id: Option<String>,
pub(crate) info: ImageBuildInfo,
}
impl ImageBuildHandle {
pub fn build_id(&self) -> &str {
&self.build_id
}
pub fn client_request_id(&self) -> Option<&str> {
self.client_request_id.as_deref()
}
pub fn info(&self) -> &ImageBuildInfo {
&self.info
}
pub async fn refresh(&mut self) -> Result<&ImageBuildInfo, ImageBuildError> {
self.info = image_service_builds::get_build(&self.client.client, &self.build_id).await?;
Ok(&self.info)
}
pub async fn wait<F>(
&mut self,
options: ImageBuildWaitOptions,
interrupt: &InterruptSignal,
emit: F,
) -> Result<ImageBuildResult, ImageBuildError>
where
F: FnMut(SandboxImageBuildEvent),
{
let info = image_service_builds::wait_for_terminal(
&self.client.client,
Some(&self.client.ctx),
&self.build_id,
self.client_request_id.as_deref(),
Some(self.info.clone()),
&options,
interrupt,
emit,
)
.await?;
self.info = info;
image_service_builds::terminal_result(&self.info)
}
pub async fn cancel(&self) -> Result<CancelBuildResponse, ImageBuildError> {
self.client
.cancel(CancelBuildSelector::BuildId(self.build_id.clone()))
.await
}
}
pub async fn start_build<F>(
options: SandboxImageBuildOptions,
docker_config_json: Option<String>,
interrupt: &InterruptSignal,
emit: F,
) -> Result<ImageBuildHandle, ImageBuildError>
where
F: FnMut(SandboxImageBuildEvent),
{
crate::sandbox_images::start_cas_build(options, docker_config_json, interrupt, emit).await
}
pub async fn start_import<F>(
options: SandboxImageImportOptions,
docker_config_json: Option<String>,
interrupt: &InterruptSignal,
emit: F,
) -> Result<ImageBuildHandle, ImageBuildError>
where
F: FnMut(SandboxImageBuildEvent),
{
crate::sandbox_images::start_cas_import(options, docker_config_json, interrupt, emit).await
}
pub(crate) fn reject_legacy_reference(build_id: &str) -> Result<(), ImageBuildError> {
let build_id = build_id.trim();
if build_id.is_empty() {
return Err(ImageBuildError::usage("build id must not be empty"));
}
if build_id.starts_with(crate::sandbox_image_catalog::SANDBOX_TEMPLATE_ID_PREFIX) {
return Err(ImageBuildError::usage(format!(
"'{build_id}' is a legacy sandbox template id; legacy images have no build \
operation to get, wait for or cancel"
)));
}
if build_id.starts_with(crate::sandbox_image_catalog::IMAGE_SERVICE_ID_PREFIX) {
return Err(ImageBuildError::usage(format!(
"'{build_id}' is an image id, not a build id; look the image up with describe, or \
use the build id admission returned"
)));
}
Ok(())
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn not_found_explains_retirement() {
let error = ImageBuildError::NotFound {
build_id: "build-x".to_string(),
};
let message = error.to_string();
assert!(message.starts_with("build build-x not found"), "{message}");
assert!(message.contains("current build"), "{message}");
assert!(message.contains("retires them"), "{message}");
assert_eq!(error.code(), "not_found");
assert_eq!(error.build_id(), Some("build-x"));
}
#[test]
fn client_request_ids_are_32_hex_and_validate() {
let id = new_client_request_id();
assert_eq!(id.len(), 32);
assert!(
id.bytes()
.all(|b| b.is_ascii_hexdigit() && !b.is_ascii_uppercase())
);
assert_ne!(id, new_client_request_id());
validate_client_request_id(&id).unwrap();
assert!(validate_client_request_id("").is_err());
assert!(validate_client_request_id(&"a".repeat(129)).is_err());
assert!(validate_client_request_id("has space").is_err());
validate_client_request_id("opaque-Key_1").unwrap();
}
#[test]
fn build_info_ignores_unknown_fields_and_keeps_unknown_enum_values() {
let info = ImageBuildInfo::from_json(serde_json::json!({
"build_id": "build-1",
"kind": "dockerfile",
"status": "paused",
"phase": "warming",
"future_field": {"x": 1},
"result": null,
"cleanup_pending": true,
"context_upload": {"url": "https://upload.test/ctx", "max_bytes": 8192},
"operation_deadline_ms": 1_000,
}))
.unwrap();
assert_eq!(info.status, ImageBuildStatus::Unknown("paused".to_string()));
assert_eq!(
info.phase,
Some(ImageBuildPhase::Unknown("warming".to_string()))
);
let json = serde_json::to_value(&info).unwrap();
assert!(json.get("cleanup_pending").is_none(), "{json}");
assert!(json.get("context_upload").is_none(), "{json}");
assert!(!json.to_string().contains("upload.test"), "{json}");
assert_eq!(
info.operation_deadline(),
Some(UNIX_EPOCH + Duration::from_millis(1_000) + DEPLOYMENT_RECOVERY_ALLOWANCE)
);
assert_eq!(
serde_json::to_value(&info.status).unwrap(),
Value::String("paused".to_string())
);
assert!(!ImageBuildStatus::Running.is_terminal());
assert!(ImageBuildStatus::Cancelled.is_terminal());
}
#[test]
fn legacy_references_are_refused_before_any_request() {
assert!(reject_legacy_reference("sandbox_template_1").is_err());
assert!(reject_legacy_reference("image_abc").is_err());
assert!(reject_legacy_reference(" ").is_err());
reject_legacy_reference("build-1").unwrap();
}
#[test]
fn interruption_reports_distinguish_not_admitted_from_cancelled() {
let report = InterruptionReport {
build_id: None,
client_request_id: Some("rid".to_string()),
outcome: InterruptionOutcome::NotAdmitted,
};
assert!(!report.is_confirmed_cancelled());
assert!(report.to_string().contains("No build was admitted"));
let report = InterruptionReport {
build_id: Some("build-1".to_string()),
client_request_id: None,
outcome: InterruptionOutcome::Cancelled,
};
assert!(report.is_confirmed_cancelled());
assert_eq!(report.to_string(), "Build build-1 cancelled");
}
}