cloudillo_ref/

handler.rs

//! Reference (Ref) REST endpoints for managing shareable tokens and authentication workflows

use axum::{
	extract::{Path, Query, State},
	http::StatusCode,
	Json,
};
use serde::{Deserialize, Serialize};

use crate::prelude::*;
use cloudillo_core::extract::{OptionalAuth, OptionalRequestId};
use cloudillo_types::meta_adapter::{CreateRefOptions, ListRefsOptions, RefData};
use cloudillo_types::types::{serialize_timestamp_iso, serialize_timestamp_iso_opt, ApiResponse};
use cloudillo_types::utils;

/// Response structure for ref details (authenticated users get full data)
#[serde_with::skip_serializing_none]
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RefResponse {
	#[serde(rename = "refId")]
	pub ref_id: String,
	pub r#type: String,
	pub description: Option<String>,
	#[serde(rename = "createdAt", serialize_with = "serialize_timestamp_iso")]
	pub created_at: Timestamp,
	#[serde(
		rename = "expiresAt",
		serialize_with = "serialize_timestamp_iso_opt",
		skip_serializing_if = "Option::is_none"
	)]
	pub expires_at: Option<Timestamp>,
	/// Usage count: None = unlimited, Some(n) = n uses remaining
	pub count: Option<u32>,
	/// Resource ID for share links (e.g., file_id for share.file type)
	#[serde(rename = "resourceId")]
	pub resource_id: Option<String>,
	/// Access level for share links ("read" or "write")
	#[serde(rename = "accessLevel")]
	pub access_level: Option<String>,
}

/// Minimal response structure for unauthenticated requests (only refId and type)
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct RefResponseMinimal {
	#[serde(rename = "refId")]
	pub ref_id: String,
	pub r#type: String,
}

impl From<RefData> for RefResponse {
	fn from(ref_data: RefData) -> Self {
		Self {
			ref_id: ref_data.ref_id.to_string(),
			r#type: ref_data.r#type.to_string(),
			description: ref_data.description.map(|d| d.to_string()),
			created_at: ref_data.created_at,
			expires_at: ref_data.expires_at,
			count: ref_data.count,
			resource_id: ref_data.resource_id.map(|s| s.to_string()),
			access_level: ref_data
				.access_level
				.map(|c| if c == 'W' { "write" } else { "read" }.to_string()),
		}
	}
}

impl From<RefData> for RefResponseMinimal {
	fn from(ref_data: RefData) -> Self {
		Self { ref_id: ref_data.ref_id.to_string(), r#type: ref_data.r#type.to_string() }
	}
}

/// Request structure for creating a new ref
#[derive(Debug, Deserialize)]
pub struct CreateRefRequest {
	/// Type of reference (e.g., "email-verify", "password-reset", "invite", "share.file")
	pub r#type: String,
	/// Human-readable description
	pub description: Option<String>,
	/// Optional expiration timestamp
	pub expires_at: Option<i64>,
	/// Number of times this ref can be used:
	/// - Omit field: defaults to 1 (single use)
	/// - null: unlimited uses
	/// - number: that many uses
	#[serde(default)]
	pub count: Patch<u32>,
	/// Resource ID for share links (e.g., file_id for share.file type)
	#[serde(rename = "resourceId")]
	pub resource_id: Option<String>,
	/// Access level for share links ("read" or "write", default: "read")
	#[serde(rename = "accessLevel")]
	pub access_level: Option<String>,
}

/// Query parameters for listing refs
#[derive(Debug, Deserialize, Default)]
pub struct ListRefsQuery {
	/// Filter by ref type
	pub r#type: Option<String>,
	/// Filter by status: 'active', 'used', 'expired', 'all' (default: 'active')
	pub filter: Option<String>,
	/// Filter by resource_id (for listing share links for a specific resource)
	#[serde(rename = "resourceId")]
	pub resource_id: Option<String>,
}

// Re-export service types for backward compatibility
pub use crate::service::{create_ref_internal, CreateRefInternalParams};

/// GET /api/refs - List refs for the current tenant
#[axum::debug_handler]
pub async fn list_refs(
	State(app): State<App>,
	tn_id: TnId,
	Query(query_params): Query<ListRefsQuery>,
	OptionalRequestId(req_id): OptionalRequestId,
) -> ClResult<(StatusCode, Json<ApiResponse<Vec<RefResponse>>>)> {
	info!(
		tn_id = ?tn_id,
		r#type = ?query_params.r#type,
		filter = ?query_params.filter,
		resource_id = ?query_params.resource_id,
		"GET /api/refs - Listing refs"
	);

	let opts = ListRefsOptions {
		typ: query_params.r#type,
		filter: query_params.filter.or(Some("active".to_string())),
		resource_id: query_params.resource_id,
	};

	let refs = app.meta_adapter.list_refs(tn_id, &opts).await?;

	let response_data: Vec<RefResponse> = refs.into_iter().map(RefResponse::from).collect();

	let total = response_data.len();
	let mut response = ApiResponse::with_pagination(response_data, 0, total, total);
	if let Some(id) = req_id {
		response = response.with_req_id(id);
	}

	Ok((StatusCode::OK, Json(response)))
}

/// POST /api/refs - Create a new ref for authentication workflows
#[axum::debug_handler]
pub async fn create_ref(
	State(app): State<App>,
	tn_id: TnId,
	OptionalRequestId(req_id): OptionalRequestId,
	Json(create_req): Json<CreateRefRequest>,
) -> ClResult<(StatusCode, Json<ApiResponse<RefResponse>>)> {
	info!(
		tn_id = ?tn_id,
		ref_type = %create_req.r#type,
		description = ?create_req.description,
		resource_id = ?create_req.resource_id,
		access_level = ?create_req.access_level,
		"POST /api/refs - Creating new ref"
	);

	// Validate ref type is not empty
	if create_req.r#type.is_empty() {
		return Err(Error::ValidationError("ref type is required".to_string()));
	}

	// Validate expiration if provided
	if let Some(expires_timestamp) = create_req.expires_at {
		let expiration = Timestamp(expires_timestamp);
		if expiration.0 <= Timestamp::now().0 {
			return Err(Error::ValidationError(
				"Expiration time must be in the future".to_string(),
			));
		}
	}

	// Parse and validate access_level
	let access_level_char = match create_req.access_level.as_deref() {
		Some("write" | "W") => Some('W'),
		Some("read" | "R") | None => {
			// Default to read if resource_id is present
			if create_req.resource_id.is_some() {
				Some('R')
			} else {
				None
			}
		}
		Some(other) => {
			return Err(Error::ValidationError(format!(
				"Invalid access_level '{}': must be 'read' or 'write'",
				other
			)));
		}
	};

	// Validate share.file type requires resource_id
	if create_req.r#type == "share.file" && create_req.resource_id.is_none() {
		return Err(Error::ValidationError(
			"resource_id is required for share.file type".to_string(),
		));
	}

	let ref_id = utils::random_id()?;

	// Convert Patch<u32> to Option<u32>:
	// - Undefined (field omitted): default to 1 (single use)
	// - Null (explicit null): unlimited uses
	// - Value(n): use that count
	let count = match create_req.count {
		Patch::Undefined => Some(1),
		Patch::Null => None,
		Patch::Value(n) => Some(n),
	};

	let opts = CreateRefOptions {
		typ: create_req.r#type.clone(),
		description: create_req.description.clone(),
		expires_at: create_req.expires_at.map(Timestamp),
		count,
		resource_id: create_req.resource_id.clone(),
		access_level: access_level_char,
	};

	let ref_data = app.meta_adapter.create_ref(tn_id, &ref_id, &opts).await.map_err(|e| {
		warn!("Failed to create ref: {}", e);
		e
	})?;

	let response_data = RefResponse::from(ref_data);
	let mut response = ApiResponse::new(response_data);
	if let Some(id) = req_id {
		response = response.with_req_id(id);
	}

	Ok((StatusCode::CREATED, Json(response)))
}

/// GET /api/refs/{ref_id} - Get a specific ref by ID
///
/// Returns full ref details if authenticated, only refId and type if not authenticated.
#[axum::debug_handler]
pub async fn get_ref(
	State(app): State<App>,
	tn_id: TnId,
	OptionalAuth(auth): OptionalAuth,
	Path(ref_id): Path<String>,
	OptionalRequestId(req_id): OptionalRequestId,
) -> ClResult<(StatusCode, Json<serde_json::Value>)> {
	let is_authenticated = auth.is_some();

	info!(
		tn_id = ?tn_id,
		ref_id = %ref_id,
		authenticated = is_authenticated,
		"GET /api/refs/:id - Getting ref"
	);

	// Verify the ref exists first
	app.meta_adapter.get_ref(tn_id, &ref_id).await?.ok_or(Error::NotFound)?;

	// Reconstruct RefData from tuple (we have ref_type, ref_description)
	// Note: The return type is Option<(Box<str>, Box<str>)> which contains (type, description)
	// We need to use list_refs to get the full RefData with timestamps and count
	let opts = ListRefsOptions { typ: None, filter: Some("all".to_string()), resource_id: None };

	let refs = app.meta_adapter.list_refs(tn_id, &opts).await?;
	let ref_data = refs
		.into_iter()
		.find(|r| r.ref_id.as_ref() == ref_id.as_str())
		.ok_or(Error::NotFound)?;

	// Return different response based on authentication
	let response_value = if is_authenticated {
		// Authenticated: return full details
		let response_data = RefResponse::from(ref_data);
		let mut response = ApiResponse::new(response_data);
		if let Some(id) = req_id {
			response = response.with_req_id(id);
		}
		serde_json::to_value(response)?
	} else {
		// Unauthenticated: return only refId and type
		let response_data = RefResponseMinimal::from(ref_data);
		let mut response = ApiResponse::new(response_data);
		if let Some(id) = req_id {
			response = response.with_req_id(id);
		}
		serde_json::to_value(response)?
	};

	Ok((StatusCode::OK, Json(response_value)))
}

/// DELETE /api/refs/{ref_id} - Delete/revoke a ref
#[axum::debug_handler]
pub async fn delete_ref(
	State(app): State<App>,
	tn_id: TnId,
	Path(ref_id): Path<String>,
	OptionalRequestId(req_id): OptionalRequestId,
) -> ClResult<(StatusCode, Json<ApiResponse<()>>)> {
	info!(
		tn_id = ?tn_id,
		ref_id = %ref_id,
		"DELETE /api/refs/:id - Deleting ref"
	);

	// Verify the ref exists first
	app.meta_adapter.get_ref(tn_id, &ref_id).await?.ok_or(Error::NotFound)?;

	// Delete the ref
	app.meta_adapter.delete_ref(tn_id, &ref_id).await.map_err(|e| {
		warn!("Failed to delete ref: {}", e);
		e
	})?;

	let mut response = ApiResponse::new(());
	if let Some(id) = req_id {
		response = response.with_req_id(id);
	}

	Ok((StatusCode::OK, Json(response)))
}

// vim: ts=4