time.c

Go to the documentation of this file.

 
/* Storage capacities in elements; text buffers include the terminating NUL. */
#define UTIL_TIME_TEMP_BUFFER_SIZE 64
 
#include "ascii-chat/common/error_codes.h"
#include <ascii-chat/util/time.h>
 
#undef SOKOL_TIME_INCLUDED
#define SOKOL_TIME_IMPL
#include <ascii-chat-deps/sokol/sokol_time.h>
#include <ascii-chat/common.h>
#include <ascii-chat/asciichat_errno.h>
#include <libplatform/lifecycle.h>
#include <libplatform/rwlock.h>
#include <libplatform/compiler.h>
#include <libplatform/system.h>
#include <libplatform/terminal.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <time.h>
#include <ctype.h>
#include <libplatform/atomic.h>
 
// ============================================================================
// Global State
// ============================================================================

static struct {
  timer_record_t *timers; 
  rwlock_t rwlock;        
  lifecycle_t lifecycle;  
} g_timer_manager = {
    .timers = NULL,
    .lifecycle = LIFECYCLE_INIT,
};

static bool g_sokol_time_initialized = false;
 
// ============================================================================
// Human-Readable Time Formatting Helper
// ============================================================================

static int format_human_readable_time_ago(double total_seconds, int minutes, int hours, int days, int months, int years,
                                          const char *suffix, char *buffer, size_t buffer_size) {
  int written = 0;
 
  if (total_seconds < 3) {
    written = safe_snprintf(buffer, buffer_size, "a moment %s", suffix);
  } else if (total_seconds < 10) {
    written = safe_snprintf(buffer, buffer_size, "a few seconds %s", suffix);
  } else if (total_seconds < 45) {
    written = safe_snprintf(buffer, buffer_size, "%d seconds %s", (int)total_seconds, suffix);
  } else if (total_seconds < 90) {
    written = safe_snprintf(buffer, buffer_size, "a minute %s", suffix);
  } else if (minutes < 45) {
    written = safe_snprintf(buffer, buffer_size, "%d minutes %s", minutes, suffix);
  } else if (minutes < 90) {
    written = safe_snprintf(buffer, buffer_size, "an hour %s", suffix);
  } else if (hours < 22) {
    written = safe_snprintf(buffer, buffer_size, "%d hours %s", hours, suffix);
  } else if (hours < 36) {
    written = safe_snprintf(buffer, buffer_size, "a day %s", suffix);
  } else if (days < 25) {
    written = safe_snprintf(buffer, buffer_size, "%d days %s", days, suffix);
  } else if (days < 45) {
    written = safe_snprintf(buffer, buffer_size, "a month %s", suffix);
  } else if (months < 11) {
    written = safe_snprintf(buffer, buffer_size, "%d months %s", months, suffix);
  } else if (months < 18) {
    written = safe_snprintf(buffer, buffer_size, "a year %s", suffix);
  } else {
    written = safe_snprintf(buffer, buffer_size, "%d years %s", years, suffix);
  }
 
  return written;
}
 
// ============================================================================
// Core Monotonic Timing Implementation
// ============================================================================
 
void time_sleep_ns(uint64_t ns) {
  // Use platform abstraction for cross-platform sleep
  // Convert nanoseconds to microseconds (1 us = 1000 ns)
  unsigned int usec = (unsigned int)(ns / 1000);
  if (usec == 0 && ns > 0) {
    usec = 1; // Minimum 1 microsecond
  }
  platform_sleep_us(usec);
}
 
uint64_t time_elapsed_ns(uint64_t start_ns, uint64_t end_ns) {
  // Handle wraparound (defensive - uint64_t won't wrap in practice at nanosecond resolution)
  // but this is safe and handles any theoretical edge cases
  if (end_ns >= start_ns) {
    return end_ns - start_ns;
  }
  // Wraparound case (extremely unlikely)
  return (UINT64_MAX - start_ns) + end_ns + 1;
}
 
// ============================================================================
// Conversion Functions (moved from inline in header to avoid circular deps)
// ============================================================================
 
uint64_t time_timespec_to_ns(const struct timespec *ts) {
  if (!ts) {
    SET_ERRNO(ERROR_INVALID_PARAM, "null ts");
    return 0;
  }
  // Use __uint128_t to prevent overflow during multiplication of large time values
  __uint128_t result = (__uint128_t)ts->tv_sec * NS_PER_SEC_INT;
  if (result > UINT64_MAX) {
    SET_ERRNO(ERROR_INVALID_PARAM, "timespec value would overflow");
    return UINT64_MAX;
  }
  return (uint64_t)result + (uint64_t)ts->tv_nsec;
}
 
// ============================================================================
// Timer System Implementation
// ============================================================================
 
bool timer_system_init(void) {
  if (lifecycle_is_initialized(&g_timer_manager.lifecycle)) {
    return true;
  }
 
  // Initialize sokol_time
  stm_setup();
 
  // Initialize rwlock and lifecycle together
  g_timer_manager.lifecycle.sync_type = LIFECYCLE_SYNC_RWLOCK;
  g_timer_manager.lifecycle.sync.rwlock = &g_timer_manager.rwlock;
  if (!lifecycle_init(&g_timer_manager.lifecycle, "timer_manager")) {
    SET_ERRNO(ERROR_PLATFORM_INIT, "Failed to initialize timer system (already initialized by another thread)");
    return true; // Another thread already initialized it
  }
 
  g_timer_manager.timers = NULL;
 
  log_dev("Timer system initialized");
  return true;
}
 
void timer_system_destroy(void) {
  if (!lifecycle_is_initialized(&g_timer_manager.lifecycle)) {
    return;
  }
 
  rwlock_wrlock(&g_timer_manager.rwlock);
 
  // Free all timer records
  int timer_count = 0;
  timer_record_t *current, *tmp;
  HASH_ITER(hh, g_timer_manager.timers, current, tmp) {
    HASH_DEL(g_timer_manager.timers, current);
    SAFE_FREE(current->name);
    SAFE_FREE(current);
    timer_count++;
  }
 
  g_timer_manager.timers = NULL;
 
  rwlock_wrunlock(&g_timer_manager.rwlock);
 
  /* Shutdown lifecycle and destroy rwlock together */
  lifecycle_shutdown(&g_timer_manager.lifecycle);
 
  log_debug("Timer system cleaned up (freed %d timers)", timer_count);
}
 
bool timer_start(const char *name) {
  if (!lifecycle_is_initialized(&g_timer_manager.lifecycle)) {
    SET_ERRNO(ERROR_INVALID_STATE, "Timer system not initialized");
    return false;
  }
 
  if (!name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Timer name is NULL");
    return false;
  }
 
  rwlock_wrlock(&g_timer_manager.rwlock);
 
  // Check if timer already exists - this is an error, timers must be unique
  timer_record_t *existing = NULL;
  HASH_FIND_STR(g_timer_manager.timers, name, existing);
 
  if (existing) {
    rwlock_wrunlock(&g_timer_manager.rwlock);
    SET_ERRNO(ERROR_INVALID_STATE, "Timer '%s' already exists - timers must have unique names", name);
    return false;
  }
 
  // Create new timer record
  timer_record_t *timer = SAFE_MALLOC(sizeof(timer_record_t), timer_record_t *);
  if (!timer) {
    rwlock_wrunlock(&g_timer_manager.rwlock);
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate timer record");
    return false;
  }
 
  // Use platform-safe string duplication
  size_t name_len = strlen(name) + 1;
  timer->name = SAFE_MALLOC(name_len, char *);
  if (!timer->name) {
    SAFE_FREE(timer);
    rwlock_wrunlock(&g_timer_manager.rwlock);
    SET_ERRNO(ERROR_MEMORY, "Failed to allocate timer name");
    return false;
  }
  SAFE_STRNCPY(timer->name, name, name_len);
 
  timer->start_ticks = stm_now();
 
  // Add to hashtable
  HASH_ADD_KEYPTR(hh, g_timer_manager.timers, timer->name, strlen(timer->name), timer);
 
  rwlock_wrunlock(&g_timer_manager.rwlock);
  return true;
}
 
double timer_stop(const char *name) {
  if (!lifecycle_is_initialized(&g_timer_manager.lifecycle)) {
    SET_ERRNO(ERROR_INVALID_STATE, "Timer system not initialized");
    return -1.0;
  }
 
  if (!name) {
    SET_ERRNO(ERROR_INVALID_PARAM, "Timer name is NULL");
    return -1.0;
  }
 
  rwlock_wrlock(&g_timer_manager.rwlock);
 
  // Find timer
  timer_record_t *timer = NULL;
  HASH_FIND_STR(g_timer_manager.timers, name, timer);
 
  if (!timer) {
    rwlock_wrunlock(&g_timer_manager.rwlock);
    log_dev("Timer '%s' not found (may have already been stopped)", name);
    return -1.0;
  }
 
  // Calculate elapsed time in nanoseconds for maximum precision
  uint64_t end_ticks = stm_now();
  uint64_t elapsed_ticks = stm_diff(end_ticks, timer->start_ticks);
  double elapsed_ns = stm_ns(elapsed_ticks);
 
  // Format duration for human-readable logging
  char duration_str[TIME_DURATION_BUFFER_SIZE];
  time_pretty((uint64_t)elapsed_ns, -1, duration_str, sizeof(duration_str));
 
  // Log the result (dev level - only shown with --verbose)
  log_dev("Timer '%s': %s", name, duration_str);
 
  // Save pointers to free BEFORE removing from hashtable
  char *timer_name = timer->name;
 
  // Remove from hashtable (HASH_DEL only removes from hash, doesn't free memory)
  HASH_DEL(g_timer_manager.timers, timer);
 
  // Free timer->name first (this was allocated separately)
  SAFE_FREE(timer_name);
 
  // Nullify the timer->name field so debug_free doesn't try to access it
  // when freeing the timer structure itself
  timer->name = NULL;
 
  // Free the timer record itself
  SAFE_FREE(timer);
 
  rwlock_wrunlock(&g_timer_manager.rwlock);
  return elapsed_ns; // Return nanoseconds
}
 
bool timer_is_initialized(void) {
  return lifecycle_is_initialized(&g_timer_manager.lifecycle);
}
 
// ============================================================================
// Time Formatting Implementation
// ============================================================================
 
int format_uptime_hms(int hours, int minutes, int seconds, char *buffer, size_t buffer_size) {
  if (!buffer || buffer_size == 0) {
    return -1;
  }
 
  // Validate components
  if (hours < 0 || minutes < 0 || minutes >= 60 || seconds < 0 || seconds >= 60) {
    return -1;
  }
 
  // Format as HH:MM:SS with zero-padding
  int written = safe_snprintf(buffer, buffer_size, "%02d:%02d:%02d", hours, minutes, seconds);
 
  if (written < 0 || (size_t)written >= buffer_size) {
    return -1;
  }
 
  return written;
}
 
// ============================================================================
// Pretty Time Formatting with Spaces and Configurable Precision
// ============================================================================

static int strip_trailing_zeros(char *str) {
  if (!str || !*str)
    return 0;
 
  int len = (int)strlen(str);
  if (len <= 0)
    return len;
 
  // Find decimal point
  char *decimal = strchr(str, '.');
  if (!decimal)
    return len; // No decimal point
 
  // Keep the unit suffix while removing zeros from the fractional digits.
  char *suffix = decimal + 1;
  while (*suffix >= '0' && *suffix <= '9')
    ++suffix;
  char *end = suffix;
  while (end > decimal + 1 && end[-1] == '0')
    --end;
  if (end == decimal + 1)
    end = decimal;
  memmove(end, suffix, strlen(suffix) + 1);
 
  return (int)strlen(str);
}
 
int time_pretty(uint64_t nanoseconds, int decimals, char *buffer, size_t buffer_size) {
  if (!buffer || buffer_size == 0) {
    return -1;
  }
 
  // Handle zero
  if (nanoseconds == 0) {
    int written = safe_snprintf(buffer, buffer_size, "0ns");
    return (written < 0 || (size_t)written >= buffer_size) ? -1 : written;
  }
 
  // Determine decimals for this range if not explicitly set
  int actual_decimals = decimals;
  if (decimals == -1) {
    if (nanoseconds < NS_PER_MIN_INT) {
      actual_decimals = (nanoseconds < NS_PER_SEC_INT) ? 3 : 2; // ns/µs/ms or seconds
    } else {
      actual_decimals = 0; // colon notation uses whole seconds
    }
  }
 
  // Clamp decimals to valid range
  if (actual_decimals < 0)
    actual_decimals = 0;
  if (actual_decimals > 9)
    actual_decimals = 9;
 
  int written = 0;
 
  // Nanoseconds (< 1µs)
  if (nanoseconds < NS_PER_US_INT) {
    written = safe_snprintf(buffer, buffer_size, "%lluns", (unsigned long long)nanoseconds);
  }
  // Microseconds (< 1ms)
  else if (nanoseconds < NS_PER_MS_INT) {
    double us = (double)nanoseconds / NS_PER_US;
    char temp_buf[UTIL_TIME_TEMP_BUFFER_SIZE];
    // Use a direct snprintf with large enough buffer first
    snprintf(temp_buf, sizeof(temp_buf), "%.*fµs", actual_decimals, us);
    strip_trailing_zeros(temp_buf);
    written = (int)strlen(temp_buf);
    if (written > 0 && written < (int)buffer_size) {
      SAFE_STRNCPY(buffer, temp_buf, buffer_size);
    } else {
      written = -1;
    }
  }
  // Milliseconds (< 1s)
  else if (nanoseconds < NS_PER_SEC_INT) {
    double ms = (double)nanoseconds / NS_PER_MS;
    char temp_buf[UTIL_TIME_TEMP_BUFFER_SIZE];
    snprintf(temp_buf, sizeof(temp_buf), "%.*fms", actual_decimals, ms);
    strip_trailing_zeros(temp_buf);
    written = (int)strlen(temp_buf);
    if (written > 0 && written < (int)buffer_size) {
      SAFE_STRNCPY(buffer, temp_buf, buffer_size);
    } else {
      written = -1;
    }
  }
  // Seconds (< 1 minute)
  else if (nanoseconds < NS_PER_MIN_INT) {
    double s = (double)nanoseconds / NS_PER_SEC;
    char temp_buf[UTIL_TIME_TEMP_BUFFER_SIZE];
    snprintf(temp_buf, sizeof(temp_buf), "%.*fs", actual_decimals, s);
    strip_trailing_zeros(temp_buf);
    written = (int)strlen(temp_buf);
    if (written > 0 && written < (int)buffer_size) {
      SAFE_STRNCPY(buffer, temp_buf, buffer_size);
    } else {
      written = -1;
    }
  }
  // Minutes omit fractions; days omit seconds.
  else if (nanoseconds < NS_PER_HOUR_INT) {
    uint64_t total_seconds = nanoseconds / NS_PER_SEC_INT;
    written = safe_snprintf(buffer, buffer_size, "%llu:%02llu", (unsigned long long)(total_seconds / 60),
                            (unsigned long long)(total_seconds % 60));
  } else if (nanoseconds >= NS_PER_DAY_INT) {
    uint64_t total_minutes = nanoseconds / NS_PER_MIN_INT;
    written = safe_snprintf(buffer, buffer_size, "%llud %llu:%02llu", (unsigned long long)(total_minutes / (24 * 60)),
                            (unsigned long long)((total_minutes / 60) % 24), (unsigned long long)(total_minutes % 60));
  }
  // Hours use H:MM:SS.
  else {
    uint64_t total_seconds = nanoseconds / NS_PER_SEC_INT;
    uint64_t hours = total_seconds / 3600;
    uint64_t remaining = total_seconds % 3600;
    uint64_t minutes = remaining / 60;
    uint64_t seconds = remaining % 60;
 
    written = safe_snprintf(buffer, buffer_size, "%llu:%02llu:%02llu", (unsigned long long)hours,
                            (unsigned long long)minutes, (unsigned long long)seconds);
  }
 
  if (written < 0 || (size_t)written >= buffer_size) {
    return -1;
  }
 
  return written;
}
 
int time_pretty_now(int decimals, char *buffer, size_t buffer_size) {
  uint64_t ns = time_get_ns();
  return time_pretty(ns, decimals, buffer, buffer_size);
}
 
// ============================================================================
// Human-Readable Time Formatting (moment.js style)
// ============================================================================
 
int time_human_readable_unsigned(uint64_t nanoseconds, char *buffer, size_t buffer_size) {
  if (!buffer || buffer_size == 0) {
    return -1;
  }
 
  // Convert nanoseconds to seconds for threshold checking
  double total_seconds = (double)nanoseconds / NS_PER_SEC;
  int minutes = (int)(total_seconds / 60);
  int hours = minutes / 60;
  int days = hours / 24;
  int months = days / 30; // Approximate
  int years = months / 12;
 
  int written =
      format_human_readable_time_ago(total_seconds, minutes, hours, days, months, years, "ago", buffer, buffer_size);
 
  if (written < 0 || (size_t)written >= buffer_size) {
    return -1;
  }
 
  return written;
}
 
int time_human_readable(int64_t nanoseconds, char *buffer, size_t buffer_size) {
  if (!buffer || buffer_size == 0) {
    return -1;
  }
 
  // Determine direction (past vs future)
  bool is_future = nanoseconds < 0;
  uint64_t abs_ns = is_future ? (uint64_t)(-nanoseconds) : (uint64_t)nanoseconds;
 
  // Convert nanoseconds to seconds for threshold checking
  double total_seconds = (double)abs_ns / NS_PER_SEC;
  int minutes = (int)(total_seconds / 60);
  int hours = minutes / 60;
  int days = hours / 24;
  int months = days / 30; // Approximate
  int years = months / 12;
 
  const char *suffix = is_future ? "from now" : "ago";
  int written =
      format_human_readable_time_ago(total_seconds, minutes, hours, days, months, years, suffix, buffer, buffer_size);
 
  if (written < 0 || (size_t)written >= buffer_size) {
    return -1;
  }
 
  return written;
}
 
int time_human_readable_now(char *buffer, size_t buffer_size) {
  int64_t ns = (int64_t)time_get_ns();
  return time_human_readable(ns, buffer, buffer_size);
}
 
// ============================================================================
// Adaptive Sleep Implementation
// ============================================================================
 
void adaptive_sleep_init(adaptive_sleep_state_t *state, const adaptive_sleep_config_t *config) {
  if (!state || !config) {
    return;
  }
 
  // Copy configuration
  state->config = *config;
 
  // A multiplier of 1.0 preserves the configured interval. Clamp it for
  // configurations whose allowed range does not include the baseline.
  state->current_speed_multiplier = 1.0;
  if (state->current_speed_multiplier < config->min_speed_multiplier) {
    state->current_speed_multiplier = config->min_speed_multiplier;
  }
  if (state->current_speed_multiplier > config->max_speed_multiplier) {
    state->current_speed_multiplier = config->max_speed_multiplier;
  }
 
  state->last_sleep_ns = (uint64_t)(config->baseline_sleep_ns / state->current_speed_multiplier);
}
 
uint64_t adaptive_sleep_calculate(adaptive_sleep_state_t *state, size_t queue_depth, size_t target_depth) {
  if (!state) {
    return 0;
  }
 
  const adaptive_sleep_config_t *cfg = &state->config;
 
  // Determine if we need to speed up or slow down
  double desired_multiplier;
 
  if (queue_depth > target_depth) {
    // Queue is building up - speed up processing
    // The more items in queue, the faster we should process
    size_t backlog = queue_depth - target_depth;
 
    // Calculate desired speed based on backlog
    // Each item above target increases speed proportionally
    // This ensures we drain the queue faster the more backed up we are
    double backlog_factor = 1.0 + ((double)backlog / (double)(target_depth + 1));
    desired_multiplier = cfg->min_speed_multiplier * backlog_factor;
 
    // Clamp to max speed
    if (desired_multiplier > cfg->max_speed_multiplier) {
      desired_multiplier = cfg->max_speed_multiplier;
    }
 
    // Ramp up gradually based on speedup_rate
    double delta = desired_multiplier - state->current_speed_multiplier;
    state->current_speed_multiplier += delta * cfg->speedup_rate;
 
  } else {
    // Queue is at or below target - slow down to baseline
    desired_multiplier = 1.0;
    if (desired_multiplier < cfg->min_speed_multiplier) {
      desired_multiplier = cfg->min_speed_multiplier;
    }
    if (desired_multiplier > cfg->max_speed_multiplier) {
      desired_multiplier = cfg->max_speed_multiplier;
    }
 
    // Ramp down gradually based on slowdown_rate
    double delta = desired_multiplier - state->current_speed_multiplier;
    state->current_speed_multiplier += delta * cfg->slowdown_rate;
  }
 
  // Ensure we stay within configured bounds
  if (state->current_speed_multiplier < cfg->min_speed_multiplier) {
    state->current_speed_multiplier = cfg->min_speed_multiplier;
  }
  if (state->current_speed_multiplier > cfg->max_speed_multiplier) {
    state->current_speed_multiplier = cfg->max_speed_multiplier;
  }
 
  // Calculate actual sleep time: baseline / speed_multiplier
  // Higher multiplier = shorter sleep = faster processing
  uint64_t sleep_ns = (uint64_t)(cfg->baseline_sleep_ns / state->current_speed_multiplier);
 
  // Store for debugging
  state->last_sleep_ns = sleep_ns;
 
  return sleep_ns;
}
 
void adaptive_sleep_do(adaptive_sleep_state_t *state, size_t queue_depth, size_t target_depth) {
  uint64_t sleep_ns = adaptive_sleep_calculate(state, queue_depth, target_depth);
 
  if (sleep_ns > 0) {
    platform_sleep_ns(sleep_ns);
  }
}
 
/* ============================================================================
 * Time Format Validation and Formatting Implementation
 * ============================================================================ */

static const char SUPPORTED_SPECIFIERS[] = "YmmdHMSaAbBjwuIpZzcxXFTsGgV";
 
bool time_format_is_valid_strftime(const char *format_str) {
  if (!format_str) {
    return false;
  }
 
  for (const char *p = format_str; *p; p++) {
    if (*p == '%') {
      p++;
      if (!*p) {
        /* Unterminated % at end of string */
        log_error("Invalid time format: unterminated %% at end");
        return false;
      }
 
      if (*p == '%') {
        /* Escaped %% - this is valid, just skip it */
        continue;
      }
 
      /* Optional: flag characters (-, 0, +, space) */
      if (*p == '-' || *p == '0' || *p == '+' || *p == ' ') {
        p++;
        if (!*p) {
          log_error("Invalid time format: flag character without specifier");
          return false;
        }
      }
 
      /* Optional: width specifier (digits or *) */
      if (*p == '*' || isdigit((unsigned char)*p)) {
        while (*p && (isdigit((unsigned char)*p) || *p == '*')) {
          p++;
        }
        if (!*p) {
          log_error("Invalid time format: width specifier without specifier character");
          return false;
        }
      }
 
      /* Optional: precision specifier (.digits or .*) */
      if (*p == '.') {
        p++;
        if (!*p) {
          log_error("Invalid time format: precision specifier incomplete");
          return false;
        }
        while (*p && (isdigit((unsigned char)*p) || *p == '*')) {
          p++;
        }
        if (!*p) {
          log_error("Invalid time format: precision specifier without specifier character");
          return false;
        }
      }
 
      /* Optional: modifier characters (E for %Ex, O for %Ox) */
      if (*p == 'E' || *p == 'O') {
        p++;
        if (!*p) {
          log_error("Invalid time format: modifier character without specifier");
          return false;
        }
      }
 
      /* Validate that the final character is a supported specifier */
      if (!strchr(SUPPORTED_SPECIFIERS, *p)) {
        log_error("Invalid time format: unsupported specifier %%%c (at position %ld)", *p, (p - format_str));
        return false;
      }
    }
  }
 
  return true;
}
 
int time_format_now(const char *format_str, char *buf, size_t buf_size) {
  if (!format_str || !buf || buf_size < 2) {
    SET_ERRNO(ERROR_INVALID_PARAM, "invalid arguments - format_str=%p, buf=%p, buf_size=%zu", format_str, buf,
              buf_size);
    return 0;
  }
 
  /* Get current wall-clock time in nanoseconds */
  uint64_t ts_ns = time_get_realtime_ns();
 
  /* Extract seconds and nanoseconds */
  time_t seconds = (time_t)(ts_ns / NS_PER_SEC_INT);
 
  /* Convert seconds to struct tm */
  struct tm tm_info;
  platform_localtime(&seconds, &tm_info);
 
  /* Format using strftime */
  size_t len = strftime(buf, buf_size, format_str, &tm_info);
 
  /* Check for strftime errors or buffer overflow */
  if (len == 0) {
    /* strftime returned 0 - either error or exact buffer fill */
    log_debug("strftime returned 0 for format: %s", format_str);
    return 0;
  }
 
  if (len >= buf_size - 1) {
    /* Buffer would overflow - strftime filled entire buffer or hit exact size */
    log_error("buffer too small (need %zu, have %zu)", len + 1, buf_size);
    return 0;
  }
 
  return (int)len;
}
 
asciichat_error_t time_format_safe(const char *format_str, char *buf, size_t buf_size) {
  /* Check NULL pointers */
  if (!format_str) {
    return SET_ERRNO(ERROR_INVALID_STATE, "format_str is NULL");
  }
 
  if (!buf) {
    return SET_ERRNO(ERROR_INVALID_STATE, "buf is NULL");
  }
 
  /* Check minimum buffer size */
  if (buf_size < 64) {
    return SET_ERRNO(ERROR_INVALID_STATE, "buffer too small (minimum 64 bytes, got %zu)", buf_size);
  }
 
  /* Validate format string */
  if (!time_format_is_valid_strftime(format_str)) {
    return SET_ERRNO(ERROR_INVALID_STATE, "invalid time format: %s", format_str);
  }
 
  /* Format the time */
  int result = time_format_now(format_str, buf, buf_size);
  if (result <= 0) {
    return SET_ERRNO(ERROR_INVALID_STATE, "strftime formatting failed");
  }
 
  return ASCIICHAT_OK;
}