fix: resole comments

Author: think-in-universe

crates/api/src/routes/credits.rs

@@ -6,7 +6,7 @@ use axum::{
 };
 use serde::{Deserialize, Serialize};
 use services::subscription::ports::{CreditsSummary, SubscriptionError};
-use url::Url;
+use url::{Host, Url};
 use utoipa::ToSchema;
 
 /// Request to create a credit purchase checkout session
@@ -34,10 +34,12 @@ fn validate_redirect_url(url_str: &str, field_name: &str) -> Result<(), ApiError
     match url.scheme() {
         "https" => Ok(()),
         "http" => {
-            let host_ok = url
-                .host_str()
-                .map(|h| h == "localhost" || h == "127.0.0.1")
-                .unwrap_or(false);
+            let host_ok = match url.host() {
+                Some(Host::Domain(d)) => d == "localhost",
+                Some(Host::Ipv4(ip)) => ip.is_loopback(),
+                Some(Host::Ipv6(ip)) => ip.is_loopback(),
+                _ => false,
+            };
             if host_ok {
                 Ok(())
             } else {

crates/api/src/routes/subscriptions.rs

@@ -9,7 +9,7 @@ use axum::{
 };
 use serde::{Deserialize, Serialize};
 use services::subscription::ports::{SubscriptionError, SubscriptionPlan, SubscriptionWithPlan};
-use url::Url;
+use url::{Host, Url};
 use utoipa::ToSchema;
 
 /// Request to create a new subscription
@@ -34,7 +34,7 @@ fn default_provider() -> String {
 }
 
 /// Validates that a URL is valid and secure for Stripe checkout/portal redirects.
-/// Requires https for production. Allows http only for localhost/127.0.0.1 (development).
+/// Requires https for production. Allows http only for loopback (localhost, 127.0.0.1, [::1]).
 fn validate_redirect_url(url_str: &str, field_name: &str) -> Result<(), ApiError> {
     let url = Url::parse(url_str).map_err(|_| {
         ApiError::bad_request(format!(
@@ -45,22 +45,23 @@ fn validate_redirect_url(url_str: &str, field_name: &str) -> Result<(), ApiError
     match url.scheme() {
         "https" => Ok(()),
         "http" => {
-            // Allow http only for local development (localhost, 127.0.0.1)
-            let host_ok = url
-                .host_str()
-                .map(|h| h == "localhost" || h == "127.0.0.1")
-                .unwrap_or(false);
+            let host_ok = match url.host() {
+                Some(Host::Domain(d)) => d == "localhost",
+                Some(Host::Ipv4(ip)) => ip.is_loopback(),
+                Some(Host::Ipv6(ip)) => ip.is_loopback(),
+                _ => false,
+            };
             if host_ok {
                 Ok(())
             } else {
                 Err(ApiError::bad_request(format!(
-                    "Invalid {}: URL must use https for non-localhost addresses (http is only allowed for localhost/127.0.0.1 during development)",
+                    "Invalid {}: URL must use https for non-localhost addresses (http is only allowed for localhost/127.0.0.1/[::1] during development)",
                     field_name
                 )))
             }
         }
         _ => Err(ApiError::bad_request(format!(
-            "Invalid {}: URL scheme must be https (or http for localhost/127.0.0.1 only)",
+            "Invalid {}: URL scheme must be https (or http for loopback only)",
             field_name
         ))),
     }

crates/database/src/migrations/sql/V25__add_user_credits.sql

@@ -1,4 +1,5 @@
--- Table for purchased credits balance per user
+-- Table for purchased credits balance per user.
+-- Unit: nano-USD (1e-9 USD; 1_000_000_000 = $1). Same unit as cost_nano_usd and monthly_credits.
 CREATE TABLE user_credits (
     user_id UUID PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
     balance BIGINT NOT NULL DEFAULT 0 CHECK (balance >= 0),
@@ -12,7 +13,8 @@ CREATE TRIGGER update_user_credits_updated_at
     FOR EACH ROW
     EXECUTE FUNCTION update_updated_at_column();
 
--- Table for credit transaction audit (purchases, grants, admin adjustments)
+-- Table for credit transaction audit (purchases, grants, admin adjustments).
+-- amount is in nano-USD (same unit as user_credits.balance).
 CREATE TABLE credit_transactions (
     id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
     user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,

crates/services/src/subscription/ports.rs

@@ -367,11 +367,18 @@ pub trait SubscriptionService: Send + Sync {
     async fn get_credits(&self, user_id: UserId) -> Result<CreditsSummary, SubscriptionError>;
 }
 
-/// Summary of user's credits (balance, used, effective limit)
+/// Summary of user's credits (balance, used, effective limit).
+///
+/// **Unit: nano-USD** (1 credit = 1e-9 USD; 1_000_000_000 = $1). All fields use this unit so they
+/// can be compared: usage is recorded as `cost_nano_usd`, plan limits and purchased balance
+/// are in the same unit.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 #[cfg_attr(feature = "utoipa", derive(utoipa::ToSchema))]
 pub struct CreditsSummary {
+    /// Purchased credits balance (nano-USD).
     pub balance: i64,
+    /// Usage in the current period (sum of cost_nano_usd).
     pub used_credits: i64,
+    /// Effective limit: plan limit + balance (nano-USD).
     pub effective_max_credits: i64,
 }

crates/services/src/subscription/service.rs

@@ -47,6 +47,10 @@ struct CachedCreditLimit {
 const TTL_CACHE_SECS: u64 = 600; // 10 minutes
 /// Default monthly credits when plan has no monthly_credits config. 1 USD in nano-dollars ($1 = 1_000_000_000).
 const DEFAULT_MONTHLY_CREDITS_NANO_USD: u64 = 1_000_000_000;
+/// When falling back from monthly_tokens: 1.5 USD per M tokens. M = 1 million tokens.
+const TOKENS_TO_CREDITS_PER_M: u64 = 1_000_000;
+/// 1.5 USD in nano-USD. Used for monthly_tokens fallback: limit_nano_usd = (monthly_tokens / M) * this.
+const NANO_USD_PER_1_5_USD: u64 = 1_500_000_000;
 
 pub struct SubscriptionServiceImpl {
     db_pool: deadpool_postgres::Pool,
@@ -1310,6 +1314,20 @@ impl SubscriptionService for SubscriptionServiceImpl {
                     .and_then(|c| c.subscription_plans)
                     .unwrap_or_default();
 
+                // Use monthly_credits when set (nano USD); else monthly_tokens → nano USD at 1.5 USD per M tokens. Never fail for missing config.
+                let plan_limit_max = |config: &SubscriptionPlanConfig| {
+                    if let Some(ref lim) = config.monthly_credits {
+                        return lim.max;
+                    }
+                    if let Some(ref lim) = config.monthly_tokens {
+                        // fallback: 1.5 USD per M tokens => limit_nano_usd = (monthly_tokens / M) * 1.5 * 1e9
+                        let nano_usd = (lim.max as u128 * NANO_USD_PER_1_5_USD as u128
+                            / TOKENS_TO_CREDITS_PER_M as u128)
+                            .min(u64::MAX as u128) as u64;
+                        return nano_usd;
+                    }
+                    DEFAULT_MONTHLY_CREDITS_NANO_USD
+                };
                 let (plan_credits, period_start, period_end) = match self
                     .subscription_repo
                     .get_active_subscription(user_id)
@@ -1324,8 +1342,7 @@ impl SubscriptionService for SubscriptionServiceImpl {
                         );
                         let plan_credits = subscription_plans
                             .get(&plan_name)
-                            .and_then(|c| c.monthly_credits.as_ref())
-                            .map(|l| l.max)
+                            .map(plan_limit_max)
                             .unwrap_or(DEFAULT_MONTHLY_CREDITS_NANO_USD);
                         let period_end = sub.current_period_end;
                         let period_start = sub_one_month_same_day(period_end);
@@ -1334,8 +1351,7 @@ impl SubscriptionService for SubscriptionServiceImpl {
                     None => {
                         let plan_credits = subscription_plans
                             .get("free")
-                            .and_then(|c| c.monthly_credits.as_ref())
-                            .map(|l| l.max)
+                            .map(plan_limit_max)
                             .unwrap_or(DEFAULT_MONTHLY_CREDITS_NANO_USD);
                         let (period_start, period_end) = current_calendar_month_period(Utc::now());
                         (plan_credits, period_start, period_end)
@@ -1547,6 +1563,7 @@ impl SubscriptionService for SubscriptionServiceImpl {
         let customer_id = self.get_or_create_stripe_customer(user_id, None).await?;
 
         let base_client = self.get_stripe_client();
+        // Hour-granular idempotency: same user+credits within the same clock hour reuses Stripe session (avoids duplicate checkouts; retry after hour gets new session).
         let idempotency_key = format!(
             "credit_checkout_{}_{}_{}",
             user_id,
@@ -1603,6 +1620,20 @@ impl SubscriptionService for SubscriptionServiceImpl {
             .and_then(|c| c.subscription_plans)
             .unwrap_or_default();
 
+        // Use monthly_credits when set (nano USD); else monthly_tokens → nano USD at 1.5 USD per M tokens. Never fail for missing config.
+        let plan_limit_max = |config: &SubscriptionPlanConfig| {
+            if let Some(ref lim) = config.monthly_credits {
+                return lim.max;
+            }
+            if let Some(ref lim) = config.monthly_tokens {
+                // fallback: 1.5 USD per M tokens => limit_nano_usd = (monthly_tokens / M) * 1.5 * 1e9
+                let nano_usd = (lim.max as u128 * NANO_USD_PER_1_5_USD as u128
+                    / TOKENS_TO_CREDITS_PER_M as u128)
+                    .min(u64::MAX as u128) as u64;
+                return nano_usd;
+            }
+            DEFAULT_MONTHLY_CREDITS_NANO_USD
+        };
         let (plan_credits, period_start, period_end) = match self
             .subscription_repo
             .get_active_subscription(user_id)
@@ -1614,8 +1645,7 @@ impl SubscriptionService for SubscriptionServiceImpl {
                     resolve_plan_name_from_config("stripe", &sub.price_id, &subscription_plans);
                 let plan_credits = subscription_plans
                     .get(&plan_name)
-                    .and_then(|c| c.monthly_credits.as_ref())
-                    .map(|l| l.max)
+                    .map(plan_limit_max)
                     .unwrap_or(DEFAULT_MONTHLY_CREDITS_NANO_USD);
                 let period_end = sub.current_period_end;
                 let period_start = sub_one_month_same_day(period_end);
@@ -1624,8 +1654,7 @@ impl SubscriptionService for SubscriptionServiceImpl {
             None => {
                 let plan_credits = subscription_plans
                     .get("free")
-                    .and_then(|c| c.monthly_credits.as_ref())
-                    .map(|l| l.max)
+                    .map(plan_limit_max)
                     .unwrap_or(DEFAULT_MONTHLY_CREDITS_NANO_USD);
                 let (period_start, period_end) = current_calendar_month_period(Utc::now());
                 (plan_credits, period_start, period_end)

crates/services/src/system_configs/ports.rs

@@ -102,7 +102,8 @@ pub struct SubscriptionPlanConfig {
     /// Agent instance limits (e.g. { "max": 1 })
     #[serde(skip_serializing_if = "Option::is_none")]
     pub agent_instances: Option<PlanLimitConfig>,
-    /// Monthly token limits (e.g. { "max": 1000000 }). Kept for backward compatibility.
+    /// Monthly token limits (e.g. { "max": 1000000 }). Backward compatibility only: when monthly_credits is unset,
+    /// this is converted to a nano-USD limit at 1.5 USD per M tokens (M = 1e6). Not used when monthly_credits is set.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub monthly_tokens: Option<PlanLimitConfig>,
     /// Monthly credit limits in nano-USD (e.g. { "max": 1000000000 } = $1). Used for quota enforcement.