log/logging.c

Go to the documentation of this file.

 
#include <ascii-chat/common.h>
#include <ascii-chat/options/options.h>
#include <ascii-chat/options/rcu.h> // For RCU-based options access
#include <ascii-chat/platform/abstraction.h>
#include <ascii-chat/platform/system.h>
#include <ascii-chat/util/path.h>
#include <ascii-chat/util/string.h>
#include <ascii-chat/util/time.h>
#include <ascii-chat/util/utf8.h>
#include <stdarg.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <time.h>
#include <fcntl.h>
#include <sys/stat.h>
#include <ctype.h>
 
#include <ascii-chat/log/logging.h>
#include <ascii-chat/log/format.h>
#include <ascii-chat/log/colorize.h>
#include <ascii-chat/log/mmap.h>
#include <ascii-chat/log/grep.h>
#include <ascii-chat/log/json.h>
#include <ascii-chat/platform/terminal.h>
#include <ascii-chat/options/colorscheme.h>
#include <ascii-chat/platform/thread.h>
#include <ascii-chat/platform/mutex.h>
#include <ascii-chat/network/packet.h>
#include <ascii-chat/video/ansi.h>
 
/* Platform-specific log hook (weak, can be overridden by platform implementations) */
__attribute__((weak)) void platform_log_hook(log_level_t level, const char *message) {
  (void)level;
  (void)message;
  // Default: no-op
}
 
/* ============================================================================
 * Logging System Internal State
 * ============================================================================ */
 
/* Log context struct - Lock-free logging with mutex-protected rotation
 *
 * Design: Logging itself is lock-free using atomic operations and atomic write() syscalls.
 * Only log rotation uses a mutex, since it involves multiple file operations that must
 * be atomic as a group (close, read tail, write temp, rename, reopen).
 */
#pragma GCC diagnostic push
#pragma GCC diagnostic ignored "-Wmissing-field-initializers"
static struct log_context_t {
  _Atomic int file;                        /* File descriptor (atomic for safe access) */
  _Atomic int json_file;                   /* JSON output file descriptor (-1 = disabled) */
  _Atomic int level;                       /* Log level as int for atomic ops */
  _Atomic bool initialized;                /* Initialization flag */
  char filename[LOG_MSG_BUFFER_SIZE];      /* Store filename (set once at init) */
  _Atomic size_t current_size;             /* Track current file size */
  _Atomic bool terminal_output_enabled;    /* Control stderr output to terminal */
  _Atomic bool level_manually_set;         /* Track if level was set manually */
  _Atomic bool force_stderr;               /* Force all terminal logs to stderr (client mode) */
  _Atomic bool terminal_locked;            /* True when a thread has exclusive terminal access */
  _Atomic uint64_t terminal_owner_thread;  /* Thread that owns terminal output (stored as uint64) */
  _Atomic unsigned int flush_delay_ms;     /* Delay between each buffered log flush (0 = disabled) */
  mutex_t rotation_mutex;                  /* Mutex for log rotation only (not for logging!) */
  _Atomic bool rotation_mutex_initialized; /* Track if rotation mutex is ready */
  log_template_t *format;                  /* Compiled log format (NULL = use default) */
  log_template_t *format_console_only;     /* Console-only format variant */
  _Atomic bool has_custom_format;          /* True if format was customized */
} g_log = {
    .file = 2, /* STDERR_FILENO - fd 0 is STDIN (read-only!) */
    .json_file = -1,
    .level = DEFAULT_LOG_LEVEL,
    .initialized = false,
    .filename = {0},
    .current_size = 0,
    .terminal_output_enabled = true,
    .level_manually_set = false,
    .force_stderr = false,
    .terminal_locked = false,
    .terminal_owner_thread = 0,
    .flush_delay_ms = 0,
    .rotation_mutex_initialized = false,
    .format = NULL,
    .format_console_only = NULL,
    .has_custom_format = false,
};
#pragma GCC diagnostic pop
 
/* Level strings are defined in format.c (get_level_string_padded / get_level_string) */
 
/* ============================================================================
 * Level Strings
 * ============================================================================
 * The actual default log format is defined in lib/log/format.c
 * and accessed via OPT_LOG_TEMPLATE_DEFAULT macro to support different modes.
 */
 
const char *get_level_string_padded(log_level_t level) {
  const char *result;
  switch (level) {
  case LOG_INFO:
    result = "INFO "; // 5 chars: INFO + 1 space
    break;
  case LOG_WARN:
    result = "WARN "; // 5 chars: WARN + 1 space
    break;
  case LOG_DEV:
    result = "DEV  "; // 5 chars: DEV + 2 spaces
    break;
  case LOG_DEBUG:
    result = "DEBUG"; // 5 chars: DEBUG (no padding needed)
    break;
  case LOG_ERROR:
    result = "ERROR"; // 5 chars: ERROR (no padding needed)
    break;
  case LOG_FATAL:
    result = "FATAL"; // 5 chars: FATAL (no padding needed)
    break;
  default:
    result = "?????"; // Invalid level - return 5 question marks
  }
  // Verify length
  if (strlen(result) != 5) {
    fprintf(stderr, "ERROR: get_level_string_padded() returned non-5-char string: '%s' (len=%zu)\n", result,
            strlen(result));
  }
  return result;
}
 
#define LOG_COLOR_COUNT 8 /* DEV, DEBUG, WARN, INFO, ERROR, FATAL, GREY, RESET */
 
/* NOTE: Color arrays are now generated by the color scheme system in lib/ui/colors.c
 * and stored in g_compiled_colors. The log_get_color_array() function returns pointers
 * to g_compiled_colors.codes_16/256/truecolor based on terminal capabilities. */
 
/* Internal error macro - uses g_log directly, only used in this file */
#ifdef NDEBUG
#define LOGGING_INTERNAL_ERROR(error, message, ...)                                                                    \
  do {                                                                                                                 \
    asciichat_set_errno_with_message(error, NULL, 0, NULL, message, ##__VA_ARGS__);                                    \
    static const char *msg_header = "CRITICAL LOGGING SYSTEM ERROR: ";                                                 \
    safe_fprintf(stderr, "%s %s\n", colored_string(LOG_COLOR_ERROR, msg_header), message);                             \
    platform_write(g_log.file, msg_header, strlen(msg_header));                                                        \
    platform_write(g_log.file, message, strlen(message));                                                              \
    platform_write(g_log.file, "\n", 1);                                                                               \
    platform_print_backtrace(0);                                                                                       \
  } while (0)
#else
#define LOGGING_INTERNAL_ERROR(error, message, ...)                                                                    \
  do {                                                                                                                 \
    asciichat_set_errno_with_message(error, __FILE__, __LINE__, __func__, message, ##__VA_ARGS__);                     \
    static const char *msg_header = "CRITICAL LOGGING SYSTEM ERROR: ";                                                 \
    safe_fprintf(stderr, "%s %s\n", colored_string(LOG_COLOR_ERROR, msg_header), message);                             \
    platform_write(g_log.file, msg_header, strlen(msg_header));                                                        \
    platform_write(g_log.file, message, strlen(message));                                                              \
    platform_write(g_log.file, "\n", 1);                                                                               \
    platform_print_backtrace(0);                                                                                       \
  } while (0)
#endif
 
/* Terminal capabilities cache */
static terminal_capabilities_t g_terminal_caps = {0};
static bool g_terminal_caps_initialized = false;
static bool g_terminal_caps_detecting = false; /* Guard against recursion */
 
/* Color scheme management - logging-specific state */
static compiled_color_scheme_t g_compiled_colors = {0};
static bool g_log_colorscheme_initialized = false;
 
/* Note: g_colorscheme_mutex is defined in lib/ui/colors.c and declared in lib/ui/colors.h */
 
/* Shutdown logging state */
static bool g_shutdown_saved_terminal_output = true; /* Saved state for log_shutdown_begin/end */
static bool g_shutdown_in_progress = false;          /* Track if shutdown phase is active */
 
size_t get_current_time_formatted(char *time_buf) {
  /* Get wall-clock time in nanoseconds */
  uint64_t ts_ns = time_get_realtime_ns();
  // Extract seconds and nanoseconds from total nanoseconds
  time_t seconds = (time_t)(ts_ns / NS_PER_SEC_INT);
  long nanoseconds = (long)(ts_ns % NS_PER_SEC_INT);
  struct tm tm_info;
  platform_localtime(&seconds, &tm_info);
  // Format the time part first
  // strftime returns 0 on error, not negative (and len is size_t/unsigned)
  size_t len = strftime(time_buf, 32, "%H:%M:%S", &tm_info);
  if (len == 0 || len >= 32) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format time");
    return 0;
  }
 
  // Add microseconds manually (convert nanoseconds to microseconds for display)
  long microseconds = nanoseconds / 1000;
  if (microseconds < 0)
    microseconds = 0;
  if (microseconds > 999999)
    microseconds = 999999;
 
  int result = safe_snprintf(time_buf + len, 32 - len, ".%06ld", microseconds);
  if (result < 0 || result >= (int)(32 - len)) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format microseconds");
    return 0;
  }
 
  return len + (size_t)result;
}
 
char *format_message(const char *format, va_list args) {
  if (!format) {
    return NULL;
  }
 
  // First, determine the size needed
  va_list args_copy;
  va_copy(args_copy, args);
  int size = safe_vsnprintf(NULL, 0, format, args_copy);
  va_end(args_copy);
 
  if (size < 0) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format context message");
    return NULL;
  }
 
  // Allocate and format the message
  char *message = SAFE_MALLOC(size + 1, char *);
  int result = safe_vsnprintf(message, (size_t)size + 1, format, args);
  if (result < 0) {
    SAFE_FREE(message);
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format context message");
    return NULL;
  }
 
  return message;
}
 
static int truncate_at_whole_line(char *buffer, int current_len, size_t max_len) {
  if (current_len < 0 || (size_t)current_len <= max_len) {
    return current_len; // No truncation needed
  }
 
  // Search backwards from max_len position for last newline
  int truncate_pos = (int)max_len - 1;
  while (truncate_pos > 0 && buffer[truncate_pos] != '\n') {
    truncate_pos--;
  }
 
  // If we found a newline, truncate after it
  if (truncate_pos > 0 && buffer[truncate_pos] == '\n') {
    truncate_pos++; // Include the newline
    buffer[truncate_pos] = '\0';
    return truncate_pos;
  }
 
  // No newline found, truncate at max_len to be safe
  truncate_pos = (int)max_len - 1;
  buffer[truncate_pos] = '\0';
  return truncate_pos;
}
 
static void validate_log_message_utf8(const char *message, const char *source) {
  if (!message || !source) {
    return;
  }
 
  if (!utf8_is_valid(message)) {
    // Use fprintf instead of log_warn to avoid infinite recursion
    // (this function is called from log_msg, which would create a loop)
    safe_fprintf(stderr, "[WARN] Invalid UTF-8 detected in %s\n", source);
    safe_fprintf(stderr, "[DEBUG] Invalid UTF-8 data: %s\n", message);
  }
}
 
/* ============================================================================
 * Logging Implementation
 * ============================================================================
 */
 
/* Parse LOG_LEVEL environment variable */
static log_level_t parse_log_level_from_env(void) {
  const char *env_level = SAFE_GETENV("LOG_LEVEL");
  if (!env_level) {
    return DEFAULT_LOG_LEVEL; // Default level based on build type
  }
 
  // Case-insensitive comparison
  if (platform_strcasecmp(env_level, "DEV") == 0 || strcmp(env_level, "0") == 0) {
    return LOG_DEV;
  }
  if (platform_strcasecmp(env_level, "DEBUG") == 0 || strcmp(env_level, "1") == 0) {
    return LOG_DEBUG;
  }
  if (platform_strcasecmp(env_level, "INFO") == 0 || strcmp(env_level, "2") == 0) {
    return LOG_INFO;
  }
  if (platform_strcasecmp(env_level, "WARN") == 0 || strcmp(env_level, "3") == 0) {
    return LOG_WARN;
  }
  if (platform_strcasecmp(env_level, "ERROR") == 0 || strcmp(env_level, "4") == 0) {
    return LOG_ERROR;
  }
  if (platform_strcasecmp(env_level, "FATAL") == 0 || strcmp(env_level, "5") == 0) {
    return LOG_FATAL;
  }
 
  // Invalid value - return default
  log_warn("Invalid LOG_LEVEL: %s", env_level);
  return DEFAULT_LOG_LEVEL;
}
 
/* Log rotation function - keeps the tail (recent entries)
 * REQUIRES: rotation_mutex must be held by caller
 * This is the only operation that uses a mutex - regular logging is lock-free.
 */
static void rotate_log_locked(void) {
  int file = atomic_load(&g_log.file);
  size_t current_size = atomic_load(&g_log.current_size);
 
  if (file < 0 || file == STDERR_FILENO || strlen(g_log.filename) == 0) {
    return;
  }
 
  if (current_size < MAX_LOG_SIZE) {
    return;
  }
 
  platform_close(file);
  atomic_store(&g_log.file, -1);
 
  /* Open file for reading to get the tail */
  int read_file = platform_open(g_log.filename, O_RDONLY, 0);
  if (read_file < 0) {
    safe_fprintf(stderr, "Failed to open log file for tail rotation: %s\n", g_log.filename);
    /* Fall back to regular truncation */
    int fd = platform_open(g_log.filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
    atomic_store(&g_log.file, fd);
    atomic_store(&g_log.current_size, 0);
    return;
  }
 
  /* Seek to position where we want to start keeping data (keep last 2MB) */
  size_t keep_size = MAX_LOG_SIZE * 2 / 3; /* Keep last 2MB of 3MB file */
  if (current_size < keep_size) {
    platform_close(read_file);
    /* Fall back to truncation since we don't have enough data to rotate */
    int fd = platform_open(g_log.filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
    atomic_store(&g_log.file, fd);
    atomic_store(&g_log.current_size, 0);
    return;
  }
  if (lseek(read_file, (off_t)(current_size - keep_size), SEEK_SET) == (off_t)-1) {
    platform_close(read_file);
    /* Fall back to truncation */
    int fd = platform_open(g_log.filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
    atomic_store(&g_log.file, fd);
    atomic_store(&g_log.current_size, 0);
    return;
  }
 
  /* Skip to next line boundary to avoid partial lines */
  char c;
  while (platform_read(read_file, &c, 1) > 0 && c != '\n') {
    /* Skip characters until newline */
  }
 
  /* Read the tail into a temporary file */
  char temp_filename[PLATFORM_MAX_PATH_LENGTH];
  int result = safe_snprintf(temp_filename, sizeof(temp_filename), "%s.tmp", g_log.filename);
  if (result <= 0 || result >= (int)sizeof(temp_filename)) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format temp filename");
    platform_close(read_file);
    int fd = platform_open(g_log.filename, O_CREAT | O_RDWR | O_APPEND, FILE_PERM_PRIVATE);
    atomic_store(&g_log.file, fd);
    return;
  }
 
  int temp_file = platform_open(temp_filename, O_CREAT | O_WRONLY | O_TRUNC, FILE_PERM_PRIVATE);
  if (temp_file < 0) {
    platform_close(read_file);
    /* Fall back to truncation */
    int fd = platform_open(g_log.filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
    atomic_store(&g_log.file, fd);
    atomic_store(&g_log.current_size, 0);
    return;
  }
 
  /* Copy tail to temp file */
  char buffer[8192];
  ssize_t bytes_read;
  size_t new_size = 0;
  while ((bytes_read = platform_read(read_file, buffer, sizeof(buffer))) > 0) {
    ssize_t written = platform_write(temp_file, buffer, (size_t)bytes_read);
    if (written != bytes_read) {
      platform_close(read_file);
      platform_close(temp_file);
      unlink(temp_filename);
      /* Fall back to truncation */
      int fd = platform_open(g_log.filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
      atomic_store(&g_log.file, fd);
      atomic_store(&g_log.current_size, 0);
      return;
    }
    new_size += (size_t)bytes_read;
  }
 
  platform_close(read_file);
  platform_close(temp_file);
 
  /* Replace original with temp file */
  if (rename(temp_filename, g_log.filename) != 0) {
    unlink(temp_filename); /* Clean up temp file */
    /* Fall back to truncation */
    int fd = platform_open(g_log.filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
    atomic_store(&g_log.file, fd);
    atomic_store(&g_log.current_size, 0);
    return;
  }
 
  /* Reopen for appending */
  int new_fd = platform_open(g_log.filename, O_CREAT | O_RDWR | O_APPEND, FILE_PERM_PRIVATE);
  if (new_fd < 0) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to reopen rotated log file: %s", g_log.filename);
    atomic_store(&g_log.file, STDERR_FILENO);
    g_log.filename[0] = '\0';
    atomic_store(&g_log.current_size, 0);
    return;
  }
  atomic_store(&g_log.file, new_fd);
  atomic_store(&g_log.current_size, new_size);
 
  char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
  get_current_time_formatted(time_buf);
 
  char log_msg[256];
  int log_msg_len =
      safe_snprintf(log_msg, sizeof(log_msg), "[%s] [INFO] Log tail-rotated (kept %zu bytes)\n", time_buf, new_size);
  if (log_msg_len > 0 && log_msg_len < (int)sizeof(log_msg)) {
    (void)platform_write(new_fd, log_msg, (size_t)log_msg_len);
  }
}
 
/* Check if rotation is needed and perform it (acquires mutex only if needed) */
static void maybe_rotate_log(void) {
  /* Rotation mutex not initialized - skip rotation */
  if (!atomic_load(&g_log.rotation_mutex_initialized)) {
    return;
  }
 
  /* Check mmap path first */
  if (log_mmap_is_active()) {
    size_t used = 0, capacity = 0;
    if (log_mmap_get_usage(&used, &capacity) && capacity > 0) {
      /* Rotate when 90% full to leave room for writes */
      if (used > capacity * 9 / 10) {
        mutex_lock(&g_log.rotation_mutex);
        log_mmap_rotate();
        mutex_unlock(&g_log.rotation_mutex);
      }
    }
    return;
  }
 
  /* File path: quick atomic check - avoid mutex if not needed */
  size_t current_size = atomic_load(&g_log.current_size);
  if (current_size < MAX_LOG_SIZE) {
    return;
  }
 
  /* Size exceeded - acquire mutex and rotate */
  mutex_lock(&g_log.rotation_mutex);
  rotate_log_locked();
  mutex_unlock(&g_log.rotation_mutex);
}
 
void log_init(const char *filename, log_level_t level, bool force_stderr, bool use_mmap) {
  // Initialize rotation mutex (only operation that uses a mutex)
  if (!atomic_load(&g_log.rotation_mutex_initialized)) {
    mutex_init(&g_log.rotation_mutex);
    atomic_store(&g_log.rotation_mutex_initialized, true);
  }
 
  // Set basic config using atomic stores
  atomic_store(&g_log.force_stderr, force_stderr);
  bool preserve_terminal_output = atomic_load(&g_log.terminal_output_enabled);
 
  // Close any existing file (atomic load/store)
  int old_file = atomic_load(&g_log.file);
  if (atomic_load(&g_log.initialized) && old_file >= 0 && old_file != STDERR_FILENO) {
    platform_close(old_file);
    atomic_store(&g_log.file, -1);
  }
 
  // Check LOG_LEVEL environment variable
  const char *env_level_str = SAFE_GETENV("LOG_LEVEL");
  if (env_level_str) {
    atomic_store(&g_log.level, (int)parse_log_level_from_env());
  } else {
    atomic_store(&g_log.level, (int)level);
  }
 
  atomic_store(&g_log.level_manually_set, false);
  atomic_store(&g_log.current_size, 0);
 
  if (filename) {
    SAFE_STRNCPY(g_log.filename, filename, sizeof(g_log.filename) - 1);
 
    if (use_mmap) {
      // Lock-free mmap path - writes go to mmap'd file
      asciichat_error_t mmap_result = log_mmap_init_simple(filename, 0);
      if (mmap_result == ASCIICHAT_OK) {
        atomic_store(&g_log.file, -1); // No regular fd - using mmap for file output
      } else {
        // Mmap failed - use stderr only (atomic writes, lock-free)
        if (preserve_terminal_output) {
          safe_fprintf(stderr, "Mmap logging failed for %s, using stderr only (lock-free)\n", filename);
        }
        atomic_store(&g_log.file, STDERR_FILENO);
        g_log.filename[0] = '\0';
      }
    } else {
      // Lock-free file I/O path - uses atomic write() syscalls
      int fd = platform_open(filename, O_CREAT | O_RDWR | O_TRUNC, FILE_PERM_PRIVATE);
      atomic_store(&g_log.file, (fd >= 0) ? fd : STDERR_FILENO);
      if (fd < 0) {
        if (preserve_terminal_output) {
          safe_fprintf(stderr, "Failed to open log file: %s\n", filename);
        }
        g_log.filename[0] = '\0';
      }
    }
  } else {
    atomic_store(&g_log.file, STDERR_FILENO);
    g_log.filename[0] = '\0';
  }
 
  /* Initialize default log format (NULL means use mode-specific default) */
  log_set_format(NULL, false);
 
  atomic_store(&g_log.initialized, true);
  atomic_store(&g_log.terminal_output_enabled, preserve_terminal_output);
 
  // Reset terminal detection if needed
  if (g_terminal_caps_initialized && !g_terminal_caps.detection_reliable) {
    g_terminal_caps_initialized = false;
  }
 
  // Detect terminal capabilities
  log_redetect_terminal_capabilities();
 
  // NOTE: Color initialization happens separately via log_set_color_scheme()
  // after options are parsed. Logging works without colors until then.
  // NOTE: Grep filter initialization happens in main.c after options_init() completes.
}
 
void log_destroy(void) {
  // Destroy mmap logging first (if active)
  if (log_mmap_is_active()) {
    log_mmap_destroy();
  }
 
  // Cleanup grep filter
  grep_destroy();
 
  // Cleanup custom format structures
  if (g_log.format) {
    log_template_free(g_log.format);
    g_log.format = NULL;
  }
  if (g_log.format_console_only) {
    log_template_free(g_log.format_console_only);
    g_log.format_console_only = NULL;
  }
  atomic_store(&g_log.has_custom_format, false);
 
  // Lock-free cleanup using atomic operations
  int old_file = atomic_load(&g_log.file);
  if (old_file >= 0 && old_file != STDERR_FILENO) {
    platform_close(old_file);
  }
  atomic_store(&g_log.file, -1);
  atomic_store(&g_log.initialized, false);
 
  // Destroy rotation mutex
  if (atomic_load(&g_log.rotation_mutex_initialized)) {
    mutex_destroy(&g_log.rotation_mutex);
    atomic_store(&g_log.rotation_mutex_initialized, false);
  }
}
 
void log_set_level(log_level_t level) {
  atomic_store(&g_log.level, (int)level);
  atomic_store(&g_log.level_manually_set, true);
}
 
log_level_t log_get_level(void) {
  return (log_level_t)atomic_load(&g_log.level);
}
 
void log_set_terminal_output(bool enabled) {
  // Respect --quiet flag: if quiet is set, never enable terminal output
  // But allow disabling even if options are unavailable (for shutdown cleanup)
  const options_t *opts = options_get();
 
  if (enabled && opts && opts->quiet) {
    return; // Silently ignore attempts to enable terminal output when --quiet is set
  }
  atomic_store(&g_log.terminal_output_enabled, enabled);
}
 
bool log_get_terminal_output(void) {
  return atomic_load(&g_log.terminal_output_enabled);
}
 
void log_set_force_stderr(bool enabled) {
  atomic_store(&g_log.force_stderr, enabled);
}
 
bool log_get_force_stderr(void) {
  return atomic_load(&g_log.force_stderr);
}
 
void log_set_json_output(int fd) {
  atomic_store(&g_log.json_file, fd);
}
 
void log_disable_file_output(void) {
  /* Close the current file if it's not stderr */
  int old_file = atomic_load(&g_log.file);
  if (old_file >= 0 && old_file != STDERR_FILENO) {
    platform_close(old_file);
  }
  /* Redirect file output to stderr */
  atomic_store(&g_log.file, STDERR_FILENO);
  g_log.filename[0] = '\0';
}
 
asciichat_error_t log_set_format(const char *format_str, bool console_only) {
  /* Free old format if it exists */
  if (g_log.format) {
    log_template_free(g_log.format);
    g_log.format = NULL;
  }
  if (g_log.format_console_only) {
    log_template_free(g_log.format_console_only);
    g_log.format_console_only = NULL;
  }
 
  /* Use default format if NULL or empty string */
  const char *format_to_use = (format_str && format_str[0] != '\0') ? format_str : OPT_LOG_TEMPLATE_DEFAULT;
  bool is_custom = (format_str && format_str[0] != '\0');
 
  /* Parse the format string (always parse, never skip) */
  log_template_t *parsed_format = log_template_parse(format_to_use, false);
  if (!parsed_format) {
    log_error("Failed to parse log format: %s", format_to_use);
    return SET_ERRNO(ERROR_INVALID_STATE, "Invalid log format string");
  }
 
  /* If console_only is true, we also need the default format for file output */
  if (console_only && is_custom) {
    log_template_t *default_format = log_template_parse(OPT_LOG_TEMPLATE_DEFAULT, false);
    if (!default_format) {
      log_template_free(parsed_format);
      log_error("Failed to parse default log format");
      return SET_ERRNO(ERROR_INVALID_STATE, "Failed to parse default format");
    }
    g_log.format = default_format;
    g_log.format_console_only = parsed_format;
  } else {
    g_log.format = parsed_format;
    g_log.format_console_only = NULL;
  }
 
  atomic_store(&g_log.has_custom_format, is_custom);
  return ASCIICHAT_OK;
}
 
bool log_lock_terminal(void) {
  bool previous_state = atomic_exchange(&g_log.terminal_locked, true);
  atomic_store(&g_log.terminal_owner_thread, (uint64_t)asciichat_thread_self());
  return previous_state;
}
 
void log_unlock_terminal(bool previous_state) {
  atomic_store(&g_log.terminal_locked, previous_state);
  if (!previous_state) {
    atomic_store(&g_log.terminal_owner_thread, 0);
  }
}
 
void log_set_flush_delay(unsigned int delay_ms) {
  atomic_store(&g_log.flush_delay_ms, delay_ms);
}
 
void log_truncate_if_large(void) {
  // Log rotation is inherently racy without locks - best-effort only
  // For reliable rotation, use mmap mode or external logrotate
  int file = atomic_load(&g_log.file);
  if (file >= 0 && file != STDERR_FILENO && strlen(g_log.filename) > 0) {
    struct stat st;
    if (fstat(file, &st) == 0 && st.st_size > MAX_LOG_SIZE) {
      atomic_store(&g_log.current_size, (size_t)st.st_size);
    }
  }
}
 
/* Helper: Write formatted log entry to file using atomic write() syscall
 * POSIX guarantees write() is atomic for sizes <= PIPE_BUF (typically 4096 bytes)
 * Strips ANSI escape codes from the buffer before writing to ensure clean log files.
 */
static void write_to_log_file_atomic(const char *buffer, int length) {
  if (length <= 0 || buffer == NULL) {
    return;
  }
 
  if (length > MAX_LOG_SIZE) {
    return;
  }
 
  int file = atomic_load(&g_log.file);
  if (file < 0 || file == STDERR_FILENO) {
    return;
  }
 
  // Strip ANSI escape codes from the buffer before writing to file
  char *stripped = ansi_strip_escapes(buffer, (size_t)length);
  const char *write_buf = stripped ? stripped : buffer;
  size_t write_len = stripped ? strlen(stripped) : (size_t)length;
 
  // Single atomic write() call - no locking needed
  ssize_t written = platform_write(file, write_buf, write_len);
  if (written > 0) {
    atomic_fetch_add(&g_log.current_size, (size_t)written);
    maybe_rotate_log();
  }
 
  if (stripped) {
    SAFE_FREE(stripped);
  }
}
 
/* Helper: Format log message header using the format system
 * Returns the number of characters written to the buffer
 */
static int format_log_header(char *buffer, size_t buffer_size, log_level_t level, const char *timestamp,
                             const char *file, int line, const char *func, bool use_colors, uint64_t time_nanoseconds) {
  const log_template_t *format = g_log.format;
  if (!format) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Log format not initialized");
    return -1;
  }
 
  /* Use log_template_apply() to generate the complete formatted output */
  int written = log_template_apply(format, buffer, buffer_size, level, timestamp, file, line, func,
                                   asciichat_thread_current_id(), "", use_colors, time_nanoseconds);
  if (written < 0 || written >= (int)buffer_size) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format log header");
    return -1;
  }
 
  return written;
}
 
/* Note: Terminal buffering removed for lock-free design.
 * When terminal is locked, other threads' output goes to file only.
 */
 
/* Helper: Write colored log entry to terminal (lock-free)
 * Uses atomic loads for state checks, skips output if terminal is locked by another thread
 */
static void write_to_terminal_atomic(log_level_t level, const char *timestamp, const char *file, int line,
                                     const char *func, const char *fmt, va_list args, uint64_t time_nanoseconds) {
  // Choose output file descriptor using unified routing logic
  int fd = terminal_choose_log_fd(level);
  FILE *output_stream = (fd == STDERR_FILENO) ? stderr : stdout;
  bool use_colors = terminal_should_color_output(fd);
 
  // Format message first (needed for status screen capture even if terminal output disabled)
  char msg_buffer[LOG_MSG_BUFFER_SIZE];
  va_list args_copy;
  va_copy(args_copy, args);
  int msg_len = safe_vsnprintf(msg_buffer, sizeof(msg_buffer), fmt, args_copy);
  va_end(args_copy);
 
  // Strip ANSI codes from message for accurate grep matching and status screen capture
  char *stripped_msg = NULL;
  const char *clean_msg = msg_buffer;
 
  if (msg_len > 0 && msg_len < (int)sizeof(msg_buffer)) {
    stripped_msg = ansi_strip_escapes(msg_buffer, (size_t)msg_len);
    clean_msg = stripped_msg ? stripped_msg : msg_buffer;
  }
 
  // Use format system to generate the complete log line
  char colored_log_line[LOG_MSG_BUFFER_SIZE + 512];
  char plain_log_line[LOG_MSG_BUFFER_SIZE + 512];
 
  /* Apply format without colors first (plain version for grep matching) */
  int plain_len = log_template_apply(g_log.format, plain_log_line, sizeof(plain_log_line), level, timestamp, file, line,
                                     func, asciichat_thread_current_id(), clean_msg, false, time_nanoseconds);
 
  /* For colored output, apply format with colors enabled */
  int colored_len = 0;
  if (use_colors && plain_len > 0) {
    colored_len = log_template_apply(g_log.format, colored_log_line, sizeof(colored_log_line), level, timestamp, file,
                                     line, func, asciichat_thread_current_id(), clean_msg, true, time_nanoseconds);
    /* If applying with colors failed, fall back to plain text */
    if (colored_len <= 0) {
      // Applying with colors failed - use plain text (no colors)
      colored_len = plain_len;
      if (plain_len > 0 && plain_len < (int)sizeof(colored_log_line)) {
        memcpy(colored_log_line, plain_log_line, (size_t)plain_len + 1);
      }
    }
  } else {
    /* No colors - use plain text */
    colored_len = plain_len;
    if (plain_len > 0 && plain_len < (int)sizeof(colored_log_line)) {
      memcpy(colored_log_line, plain_log_line, (size_t)plain_len + 1);
    }
  }
 
  // Feed log to status screen buffer (use colored version if available, otherwise plain)
  if (colored_len > 0 && colored_len < (int)sizeof(colored_log_line)) {
    extern void server_status_log_append(const char *message);
    server_status_log_append(colored_log_line);
  } else if (plain_len > 0 && plain_len < (int)sizeof(plain_log_line)) {
    extern void server_status_log_append(const char *message);
    server_status_log_append(plain_log_line);
  }
 
  // Check if terminal output is enabled (atomic load)
  bool is_enabled = atomic_load(&g_log.terminal_output_enabled);
  if (!is_enabled) {
    // Terminal output disabled - cleanup and return (status screen already captured)
    if (stripped_msg) {
      SAFE_FREE(stripped_msg);
    }
    return;
  }
 
  // Check if terminal is locked by another thread
  if (atomic_load(&g_log.terminal_locked)) {
    uint64_t owner = atomic_load(&g_log.terminal_owner_thread);
    if (owner != (uint64_t)asciichat_thread_self()) {
      // Terminal locked by another thread - cleanup and return
      if (stripped_msg) {
        SAFE_FREE(stripped_msg);
      }
      return;
    }
  }
 
  // Handle message formatting errors for terminal output
  if (msg_len <= 0 || msg_len >= (int)sizeof(msg_buffer)) {
    // Message formatting failed - skip filtering and try direct output
    (void)vfprintf(output_stream, fmt, args);
    safe_fprintf(output_stream, "\n");
    (void)fflush(output_stream);
    if (stripped_msg) {
      SAFE_FREE(stripped_msg);
    }
    return;
  }
 
  // Handle log formatting errors
  if (colored_len <= 0 || colored_len >= (int)sizeof(colored_log_line) || plain_len <= 0 ||
      plain_len >= (int)sizeof(plain_log_line)) {
    // Formatting failed - try to output something
    safe_fprintf(output_stream, "%s\n", clean_msg);
    (void)fflush(output_stream);
    if (stripped_msg) {
      SAFE_FREE(stripped_msg);
    }
    return;
  }
 
  // Apply grep filter (terminal output only - file logs are unfiltered)
  // Match against PLAIN text (no ANSI codes) so offsets are correct
  size_t match_start = 0, match_len = 0;
  if (!grep_should_output(plain_log_line, &match_start, &match_len)) {
    if (stripped_msg) {
      SAFE_FREE(stripped_msg);
    }
    return; // No match - suppress terminal output
  }
 
  // Output with colors
  if (use_colors) {
    const char **colors = log_get_color_array();
 
    // When grep matches, highlight in the colored line
    if (match_len > 0 && colors != NULL) {
      // Apply highlighting to the full line, respecting existing ANSI codes
      const char *highlighted_line = grep_highlight_colored(colored_log_line, plain_log_line, match_start, match_len);
      safe_fprintf(output_stream, "%s\n", highlighted_line);
    } else {
      // No grep match - output colored line as-is
      safe_fprintf(output_stream, "%s\n", colored_log_line);
    }
  } else {
    // No colors - output plain line
    safe_fprintf(output_stream, "%s\n", plain_log_line);
  }
 
  // Clean up stripped message
  if (stripped_msg) {
    SAFE_FREE(stripped_msg);
  }
 
  (void)fflush(output_stream);
}
 
void log_msg(log_level_t level, const char *file, int line, const char *func, const char *fmt, ...) {
  // All state access uses atomic operations - fully lock-free
  if (!atomic_load(&g_log.initialized)) {
    return;
  }
  if (level < (log_level_t)atomic_load(&g_log.level)) {
    return;
  }
  /* =========================================================================
   * MMAP PATH: When mmap logging is active, writes go to mmap'd file
   * ========================================================================= */
  bool mmap_active = log_mmap_is_active();
  if (mmap_active) {
    maybe_rotate_log();
 
    va_list args;
    va_start(args, fmt);
    char msg_buffer[LOG_MMAP_MSG_BUFFER_SIZE];
    int msg_len = safe_vsnprintf(msg_buffer, sizeof(msg_buffer), fmt, args);
    va_end(args);
 
    // Truncate at whole line boundaries to avoid UTF-8 issues
    if (msg_len > 0) {
      msg_len = truncate_at_whole_line(msg_buffer, msg_len, sizeof(msg_buffer));
    }
 
    // Validate UTF-8 in formatted message
    validate_log_message_utf8(msg_buffer, "mmap log message");
 
    log_mmap_write(level, file, line, func, "%s", msg_buffer);
 
    // Terminal output (check with atomic loads)
    if (atomic_load(&g_log.terminal_output_enabled) && !atomic_load(&g_log.terminal_locked)) {
      char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
      uint64_t time_ns = time_get_realtime_ns();
      get_current_time_formatted(time_buf);
 
      // Choose output stream using unified routing logic
      int fd = terminal_choose_log_fd(level);
      FILE *output_stream = (fd == STDERR_FILENO) ? stderr : stdout;
      // Check if colors should be used
      // Priority 1: If --color was explicitly passed, force colors
      extern bool g_color_flag_passed;
      extern bool g_color_flag_value;
      bool use_colors = true; // Default: enable colors
      if (g_color_flag_passed && !g_color_flag_value) {
        use_colors = false; // --color=false explicitly disables colors
      }
      // Priority 2: If --color NOT explicitly passed, enable colors by default
 
      char header_buffer[512];
      int header_len = format_log_header(header_buffer, sizeof(header_buffer), level, time_buf, file, line, func,
                                         use_colors, time_ns);
 
      if (header_len >= 0 && header_len < (int)sizeof(header_buffer)) {
        // Platform-specific log hook (e.g., for WASM browser console)
        platform_log_hook(level, msg_buffer);
 
        if (use_colors) {
          const char *colorized_msg = colorize_log_message(msg_buffer);
          const char **colors = log_get_color_array();
          if (colors) {
            safe_fprintf(output_stream, "%s%s%s%s\n", header_buffer, colors[LOG_COLOR_RESET], colorized_msg,
                         colors[LOG_COLOR_RESET]);
          } else {
            safe_fprintf(output_stream, "%s%s\n", header_buffer, colorized_msg);
          }
        } else {
          safe_fprintf(output_stream, "%s%s\n", header_buffer, msg_buffer);
        }
        (void)fflush(output_stream);
      }
    }
    return;
  }
  /* =========================================================================
   * FILE I/O PATH: Lock-free using atomic write() syscalls
   * ========================================================================= */
  char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
  uint64_t time_ns = time_get_realtime_ns();
  get_current_time_formatted(time_buf);
  // Format message for file output
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  va_list args;
  va_start(args, fmt);
  int header_len = format_log_header(log_buffer, sizeof(log_buffer), level, time_buf, file, line, func, false, time_ns);
  if (header_len < 0 || header_len >= (int)sizeof(log_buffer)) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format log header");
    va_end(args);
    return;
  }
  int msg_len = header_len;
  int formatted_len = safe_vsnprintf(log_buffer + header_len, sizeof(log_buffer) - (size_t)header_len, fmt, args);
  if (formatted_len < 0) {
    LOGGING_INTERNAL_ERROR(ERROR_INVALID_STATE, "Failed to format log message");
    va_end(args);
    return;
  }
 
  msg_len += formatted_len;
  // Truncate at whole line boundaries to avoid UTF-8 issues
  msg_len = truncate_at_whole_line(log_buffer, msg_len, sizeof(log_buffer));
  // Add newline if there's room and message doesn't already end with one
  if (msg_len > 0 && msg_len < (int)sizeof(log_buffer) - 1) {
    if (log_buffer[msg_len - 1] != '\n') {
      log_buffer[msg_len++] = '\n';
      log_buffer[msg_len] = '\0';
    }
  }
  va_end(args);
  // Validate UTF-8 in formatted message
  validate_log_message_utf8(log_buffer, "leveled log message");
 
  // Extract the user message part (without header) for JSON logging
  const char *user_message = log_buffer + header_len;
 
  // For JSON output: strip automatic trailing newline (keep explicit ones)
  char json_message_buf[LOG_MSG_BUFFER_SIZE];
  const char *json_message = user_message;
  size_t user_msg_len = strlen(user_message);
 
  // If message ends with newline and it was added automatically (not in original message)
  if (user_msg_len > 0 && user_message[user_msg_len - 1] == '\n') {
    // The newline was added automatically if the message part didn't end with one
    // before we added it on line 1067. We can check this by looking at msg_len - 1
    // If msg_len >= header_len + 2, then msg_len - 2 would be the char before the newline
    int msg_content_len = msg_len - header_len;
    if (msg_content_len > 1 && log_buffer[msg_len - 2] != '\n') {
      // Newline was added automatically - strip it for JSON
      if (user_msg_len - 1 < sizeof(json_message_buf)) {
        memcpy(json_message_buf, user_message, user_msg_len - 1);
        json_message_buf[user_msg_len - 1] = '\0';
        json_message = json_message_buf;
      }
    }
  }
 
  // Check if JSON format is enabled
  int json_fd = atomic_load(&g_log.json_file);
  bool json_format_enabled = (json_fd >= 0);
 
  // If JSON format is enabled, output ONLY JSON (skip text output)
  if (json_format_enabled) {
    // Output JSON to the JSON file descriptor
    log_json_write(json_fd, level, time_ns, file, line, func, json_message);
    // Also output JSON to console using unified routing logic, respecting quiet flag
    if (atomic_load(&g_log.terminal_output_enabled)) {
      int console_fd = terminal_choose_log_fd(level);
      log_json_write(console_fd, level, time_ns, file, line, func, json_message);
    }
  } else {
    // Text format: output to file and terminal
    // Write to file (atomic write syscall)
    int file_fd = atomic_load(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      write_to_log_file_atomic(log_buffer, msg_len);
    }
 
    // Write to terminal (atomic state checks)
    va_list args_terminal;
    va_start(args_terminal, fmt);
    write_to_terminal_atomic(level, time_buf, file, line, func, fmt, args_terminal, time_ns);
    va_end(args_terminal);
  }
}
 
void log_terminal_msg(log_level_t level, const char *file, int line, const char *func, const char *fmt, ...) {
  // Lock-free: only uses atomic loads, no mutex
  if (!atomic_load(&g_log.initialized)) {
    return;
  }
 
  if (level < (log_level_t)atomic_load(&g_log.level)) {
    return;
  }
 
  // Terminal output only - no file/mmap writing
  char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
  uint64_t time_ns = time_get_realtime_ns();
  get_current_time_formatted(time_buf);
 
  va_list args;
  va_start(args, fmt);
  write_to_terminal_atomic(level, time_buf, file, line, func, fmt, args, time_ns);
  va_end(args);
}
 
void log_plain_msg(const char *fmt, ...) {
  if (!atomic_load(&g_log.initialized)) {
    return;
  }
 
  if (shutdown_is_requested()) {
    return;
  }
 
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  va_list args;
  va_start(args, fmt);
  int msg_len = safe_vsnprintf(log_buffer, sizeof(log_buffer), fmt, args);
  va_end(args);
 
  if (msg_len <= 0) {
    return;
  }
 
  // Truncate at whole line boundaries to avoid UTF-8 issues
  msg_len = truncate_at_whole_line(log_buffer, msg_len, sizeof(log_buffer));
 
  // Validate UTF-8 in formatted message
  validate_log_message_utf8(log_buffer, "plain text log");
 
  // Write to mmap if active
  if (log_mmap_is_active()) {
    log_mmap_write(LOG_INFO, NULL, 0, NULL, "%s", log_buffer);
  } else {
    // Write to file with headers (atomic write syscall)
    int file_fd = atomic_load(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      // Add header with timestamp and log level to file output
      char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
      uint64_t time_ns = time_get_realtime_ns();
      get_current_time_formatted(time_buf);
 
      char header_buffer[512];
      int header_len = format_log_header(header_buffer, sizeof(header_buffer), LOG_INFO, time_buf, "lib/log/logging.c",
                                         0, "log_plain_msg", false, time_ns);
 
      if (header_len > 0) {
        write_to_log_file_atomic(header_buffer, header_len);
      }
      write_to_log_file_atomic(log_buffer, msg_len);
      write_to_log_file_atomic("\n", 1);
    }
  }
 
  // Terminal output (atomic state checks)
  if (!atomic_load(&g_log.terminal_output_enabled)) {
    return;
  }
  if (atomic_load(&g_log.terminal_locked)) {
    uint64_t owner = atomic_load(&g_log.terminal_owner_thread);
    if (owner != (uint64_t)asciichat_thread_self()) {
      return;
    }
  }
 
  // Check if JSON format is enabled
  int json_fd = atomic_load(&g_log.json_file);
  bool json_format_enabled = (json_fd >= 0);
 
  if (json_format_enabled) {
    // Output JSON for plain messages too
    uint64_t time_ns = time_get_realtime_ns();
    int console_fd = terminal_choose_log_fd(LOG_INFO);
    log_json_write(console_fd, LOG_INFO, time_ns, __FILE__, __LINE__, "log_plain_msg", log_buffer);
  } else {
    // Choose output stream using unified routing logic (LOG_INFO level)
    int fd = terminal_choose_log_fd(LOG_INFO);
    FILE *output_stream = (fd == STDERR_FILENO) ? stderr : stdout;
 
    // Apply colorization for TTY output
    if (terminal_should_color_output(fd)) {
      const char *colorized_msg = colorize_log_message(log_buffer);
      safe_fprintf(output_stream, "%s\n", colorized_msg);
    } else {
      safe_fprintf(output_stream, "%s\n", log_buffer);
    }
    (void)fflush(output_stream);
  }
}
 
// Helper for log_plain_stderr variants (lock-free)
static void log_plain_stderr_internal_atomic(const char *fmt, va_list args, bool add_newline) {
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  int msg_len = safe_vsnprintf(log_buffer, sizeof(log_buffer), fmt, args);
 
  if (msg_len <= 0) {
    return;
  }
 
  // Truncate at whole line boundaries to avoid UTF-8 issues
  msg_len = truncate_at_whole_line(log_buffer, msg_len, sizeof(log_buffer));
 
  // Validate UTF-8 in formatted message
  validate_log_message_utf8(log_buffer, "stderr log");
 
  // Write to mmap if active
  if (log_mmap_is_active()) {
    log_mmap_write(LOG_INFO, NULL, 0, NULL, "%s", log_buffer);
  } else {
    // Write to file with headers (atomic write syscall)
    int file_fd = atomic_load(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      // Add header with timestamp and log level to file output
      char time_buf[LOG_TIMESTAMP_BUFFER_SIZE];
      uint64_t time_ns = time_get_realtime_ns();
      get_current_time_formatted(time_buf);
 
      char header_buffer[512];
      int header_len = format_log_header(header_buffer, sizeof(header_buffer), LOG_INFO, time_buf, "lib/log/logging.c",
                                         0, "log_plain_stderr_msg", false, time_ns);
 
      if (header_len > 0) {
        write_to_log_file_atomic(header_buffer, header_len);
      }
      write_to_log_file_atomic(log_buffer, msg_len);
      if (add_newline) {
        write_to_log_file_atomic("\n", 1);
      }
    }
  }
 
  // Terminal output (atomic state checks)
  if (!atomic_load(&g_log.terminal_output_enabled)) {
    return;
  }
  if (atomic_load(&g_log.terminal_locked)) {
    uint64_t owner = atomic_load(&g_log.terminal_owner_thread);
    if (owner != (uint64_t)asciichat_thread_self()) {
      return;
    }
  }
 
  // Apply colorization for TTY output
  if (terminal_should_color_output(STDERR_FILENO)) {
    const char *colorized_msg = colorize_log_message(log_buffer);
    if (add_newline) {
      safe_fprintf(stderr, "%s\n", colorized_msg);
    } else {
      safe_fprintf(stderr, "%s", colorized_msg);
    }
  } else {
    if (add_newline) {
      safe_fprintf(stderr, "%s\n", log_buffer);
    } else {
      safe_fprintf(stderr, "%s", log_buffer);
    }
  }
  (void)fflush(stderr);
}
 
void log_plain_stderr_msg(const char *fmt, ...) {
  if (!atomic_load(&g_log.initialized)) {
    return;
  }
  if (shutdown_is_requested()) {
    return;
  }
 
  va_list args;
  va_start(args, fmt);
  log_plain_stderr_internal_atomic(fmt, args, true);
  va_end(args);
}
 
void log_plain_stderr_nonewline_msg(const char *fmt, ...) {
  if (!atomic_load(&g_log.initialized)) {
    return;
  }
  if (shutdown_is_requested()) {
    return;
  }
 
  va_list args;
  va_start(args, fmt);
  log_plain_stderr_internal_atomic(fmt, args, false);
  va_end(args);
}
 
void log_file_msg(const char *fmt, ...) {
  if (!atomic_load(&g_log.initialized)) {
    return;
  }
 
  char log_buffer[LOG_MSG_BUFFER_SIZE];
  va_list args;
  va_start(args, fmt);
  int msg_len = safe_vsnprintf(log_buffer, sizeof(log_buffer), fmt, args);
  va_end(args);
 
  if (msg_len <= 0) {
    return;
  }
 
  // Truncate at whole line boundaries to avoid UTF-8 issues
  msg_len = truncate_at_whole_line(log_buffer, msg_len, sizeof(log_buffer));
 
  // Validate UTF-8 in formatted message
  validate_log_message_utf8(log_buffer, "file-only log");
 
  // Write to mmap if active, else to file
  if (log_mmap_is_active()) {
    log_mmap_write(LOG_INFO, NULL, 0, NULL, "%s", log_buffer);
  } else {
    int file_fd = atomic_load(&g_log.file);
    if (file_fd >= 0 && file_fd != STDERR_FILENO) {
      write_to_log_file_atomic(log_buffer, msg_len);
      write_to_log_file_atomic("\n", 1);
    }
  }
}
 
static const char *log_network_direction_label(remote_log_direction_t direction) {
  switch (direction) {
  case REMOTE_LOG_DIRECTION_SERVER_TO_CLIENT:
    return "server→client";
  case REMOTE_LOG_DIRECTION_CLIENT_TO_SERVER:
    return "client→server";
  default:
    return "network";
  }
}
 
static asciichat_error_t log_network_message_internal(socket_t sockfd, const struct crypto_context_t *crypto_ctx,
                                                      log_level_t level, remote_log_direction_t direction,
                                                      const char *file, int line, const char *func, const char *fmt,
                                                      va_list args) {
  if (!fmt) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Format string is NULL");
  }
 
  va_list args_copy;
  va_copy(args_copy, args);
  char *formatted = format_message(fmt, args_copy);
  va_end(args_copy);
 
  if (!formatted) {
    asciichat_error_t current_error = GET_ERRNO();
    if (current_error == ASCIICHAT_OK) {
      current_error = SET_ERRNO(ERROR_MEMORY, "Failed to format network log message");
    }
    return current_error;
  }
 
  asciichat_error_t send_result = ASCIICHAT_OK;
  if (sockfd == INVALID_SOCKET_VALUE) {
    send_result = SET_ERRNO(ERROR_INVALID_PARAM, "Invalid socket descriptor");
    log_msg(LOG_WARN, file, line, func, "Skipping remote log message: invalid socket descriptor");
  } else {
    send_result = packet_send_remote_log(sockfd, (const crypto_context_t *)crypto_ctx, level, direction, 0, formatted);
    if (send_result != ASCIICHAT_OK) {
      log_msg(LOG_WARN, file, line, func, "Failed to send remote log message: %s", asciichat_error_string(send_result));
    }
  }
 
  const char *direction_label = log_network_direction_label(direction);
  log_msg(level, file, line, func, "[NET %s] %s", direction_label, formatted);
 
  SAFE_FREE(formatted);
  return send_result;
}
 
asciichat_error_t log_network_message(socket_t sockfd, const struct crypto_context_t *crypto_ctx, log_level_t level,
                                      remote_log_direction_t direction, const char *fmt, ...) {
  va_list args;
  va_start(args, fmt);
  asciichat_error_t result =
      log_network_message_internal(sockfd, crypto_ctx, level, direction, NULL, 0, NULL, fmt, args);
  va_end(args);
  return result;
}
 
asciichat_error_t log_net_message(socket_t sockfd, const struct crypto_context_t *crypto_ctx, log_level_t level,
                                  remote_log_direction_t direction, const char *file, int line, const char *func,
                                  const char *fmt, ...) {
  va_list args;
  va_start(args, fmt);
  asciichat_error_t result =
      log_network_message_internal(sockfd, crypto_ctx, level, direction, file, line, func, fmt, args);
  va_end(args);
  return result;
}
 
/* ============================================================================
 * Color Helper Functions
 * ============================================================================ */
 
/* Initialize terminal capabilities if not already done */
static void init_terminal_capabilities(void) {
  // Guard against recursion - this can be called indirectly via log_get_color_array()
  // from detect_terminal_capabilities() which uses logging
  if (g_terminal_caps_detecting) {
    return;
  }
 
  if (!g_terminal_caps_initialized) {
    // Set detecting flag to prevent recursion
    g_terminal_caps_detecting = true;
 
    // NEVER call detect_terminal_capabilities() from here - it causes infinite recursion
    // because detect_terminal_capabilities() uses log_debug() which calls log_get_color_array()
    // which calls init_terminal_capabilities() again.
    // Always use defaults here - log_redetect_terminal_capabilities() will do the actual detection
    // Use safe fallback during logging initialization to avoid recursion
    g_terminal_caps.color_level = TERM_COLOR_16;
    g_terminal_caps.capabilities = TERM_CAP_COLOR_16;
    g_terminal_caps.color_count = 16;
    g_terminal_caps.detection_reliable = false;
    g_terminal_caps_initialized = true;
 
    // Clear detecting flag
    g_terminal_caps_detecting = false;
  }
}
 
/* Re-detect terminal capabilities after logging is initialized */
void log_redetect_terminal_capabilities(void) {
  // Guard against recursion
  if (g_terminal_caps_detecting) {
    return;
  }
 
  // Detect if not initialized, or if we're using defaults (not reliably detected)
  // This ensures we get proper detection after logging is ready, replacing any defaults
  // Once we have reliable detection, never re-detect to keep colors consistent
  if (!g_terminal_caps_initialized || !g_terminal_caps.detection_reliable) {
    g_terminal_caps_detecting = true;
    g_terminal_caps = detect_terminal_capabilities();
    g_terminal_caps_detecting = false;
    g_terminal_caps_initialized = true;
 
    // Now log the capabilities AFTER colors are set, so this log uses the correct colors
    log_debug("Terminal capabilities: color_level=%d, capabilities=0x%x, utf8=%s, fps=%d", g_terminal_caps.color_level,
              g_terminal_caps.capabilities, g_terminal_caps.utf8_support ? "yes" : "no", g_terminal_caps.desired_fps);
 
    // Now that we've detected once with reliable results, keep these colors consistent for all future logs
  }
  // Once initialized with reliable detection, never re-detect to keep colors consistent
}
 
/* Get the appropriate color array based on terminal capabilities */
const char **log_get_color_array(void) {
  init_terminal_capabilities();
  /* Initialize colors if not already done */
  if (!g_log_colorscheme_initialized) {
    log_init_colors();
  }
 
  /* Safety check: if colors are not initialized, return NULL to prevent crashes from null pointers */
  if (!g_log_colorscheme_initialized) {
    return NULL;
  }
 
  /* Return the compiled color scheme based on terminal capabilities
   * codes_16, codes_256, codes_truecolor are now proper arrays of pointers (const char *[8]),
   * so we can safely cast them to const char **. */
  if (g_terminal_caps.color_level >= TERM_COLOR_TRUECOLOR) {
    return (const char **)g_compiled_colors.codes_truecolor;
  } else if (g_terminal_caps.color_level >= TERM_COLOR_256) {
    return (const char **)g_compiled_colors.codes_256;
  } else {
    return (const char **)g_compiled_colors.codes_16;
  }
}
 
const char *log_level_color(log_color_t color) {
  const char **colors = log_get_color_array();
  if (colors == NULL) {
    return ""; /* Return empty string if colors not available */
  }
  if (color >= 0 && color <= LOG_COLOR_RESET) {
    return colors[color];
  }
  return colors[LOG_COLOR_RESET]; /* Return reset color if invalid */
}
 
/* ============================================================================
 * Color Scheme Management
 * ============================================================================ */
 
void log_init_colors(void) {
  /* Skip color initialization during terminal detection to avoid mutex deadlock */
  if (g_terminal_caps_detecting) {
    return;
  }
 
  /* Skip color initialization before logging is fully initialized */
  if (!atomic_load(&g_log.initialized)) {
    return;
  }
 
  if (g_log_colorscheme_initialized) {
    return;
  }
 
  /* Get active color scheme - this ensures color system is initialized */
  const color_scheme_t *scheme = colorscheme_get_active_scheme();
  if (!scheme) {
    /* Don't mark as initialized if we can't get a color scheme - return NULL instead */
    return;
  }
 
  /* Acquire mutex for compilation (mutex is now initialized by colorscheme_init) */
  mutex_lock(&g_colorscheme_mutex);
  /* Debug: Check if g_compiled_colors is actually zero-initialized */
  /* Zero the structure on first use to avoid freeing garbage pointers */
  /* (static = {0} produces garbage in this build for unknown reasons) */
  static bool first_compile = true;
  if (first_compile) {
    memset(&g_compiled_colors, 0, sizeof(g_compiled_colors));
    first_compile = false;
  }
 
  /* Detect terminal background */
  terminal_background_t background = detect_terminal_background();
  /* Determine color mode for compilation */
  terminal_color_mode_t mode;
  if (g_terminal_caps.color_level >= TERM_COLOR_TRUECOLOR) {
    mode = TERM_COLOR_TRUECOLOR;
  } else if (g_terminal_caps.color_level >= TERM_COLOR_256) {
    mode = TERM_COLOR_256;
  } else {
    mode = TERM_COLOR_16;
  }
  /* Compile the color scheme to ANSI codes */
  asciichat_error_t result = colorscheme_compile_scheme(scheme, mode, background, &g_compiled_colors);
  g_log_colorscheme_initialized = true;
  mutex_unlock(&g_colorscheme_mutex);
 
  /* Log outside of mutex lock to avoid recursive lock deadlock */
  if (result != ASCIICHAT_OK) {
    log_debug("Failed to compile color scheme: %d", result);
  }
}
 
void log_set_color_scheme(const color_scheme_t *scheme) {
  if (!scheme) {
    return;
  }
 
  /* Mutex is managed by colors.c - just use it */
  mutex_lock(&g_colorscheme_mutex);
 
  /* Detect terminal background */
  terminal_background_t background = detect_terminal_background();
 
  /* Determine color mode for compilation */
  terminal_color_mode_t mode;
  if (g_terminal_caps.color_level >= TERM_COLOR_TRUECOLOR) {
    mode = TERM_COLOR_TRUECOLOR;
  } else if (g_terminal_caps.color_level >= TERM_COLOR_256) {
    mode = TERM_COLOR_256;
  } else {
    mode = TERM_COLOR_16;
  }
 
  /* Compile the new color scheme */
  asciichat_error_t result = colorscheme_compile_scheme(scheme, mode, background, &g_compiled_colors);
 
  g_log_colorscheme_initialized = true;
  mutex_unlock(&g_colorscheme_mutex);
 
  /* Log outside of mutex lock to avoid recursive lock deadlock */
  if (result != ASCIICHAT_OK) {
    log_debug("Failed to compile color scheme: %d", result);
  }
}
 
/* ============================================================================
 * Lock-Free MMAP Logging Integration
 * ============================================================================ */
 
asciichat_error_t log_enable_mmap(const char *log_path) {
  return log_enable_mmap_sized(log_path, 0); /* Use default size */
}
 
asciichat_error_t log_enable_mmap_sized(const char *log_path, size_t max_size) {
  if (!log_path) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "log_path is required");
  }
 
  // Initialize mmap logging - text is written directly to the mmap'd file
  asciichat_error_t result = log_mmap_init_simple(log_path, max_size);
  if (result != ASCIICHAT_OK) {
    return result;
  }
 
  log_info("Lock-free mmap logging enabled: %s", log_path);
  return ASCIICHAT_OK;
}
 
void log_disable_mmap(void) {
  if (log_mmap_is_active()) {
    log_mmap_destroy();
    log_info("Lock-free mmap logging disabled");
  }
}
 
/* ============================================================================
 * Shutdown Logging Control
 * ============================================================================ */
 
void log_shutdown_begin(void) {
  if (g_shutdown_in_progress) {
    return; /* Already in shutdown phase */
  }
 
  /* Save current terminal output state and disable console output */
  g_shutdown_saved_terminal_output = atomic_load(&g_log.terminal_output_enabled);
  atomic_store(&g_log.terminal_output_enabled, false);
  g_shutdown_in_progress = true;
}
 
void log_shutdown_end(void) {
  if (!g_shutdown_in_progress) {
    return; /* Not in shutdown phase, skip terminal state restoration */
  }
 
  /* Restore previous terminal output state */
  atomic_store(&g_log.terminal_output_enabled, g_shutdown_saved_terminal_output);
  g_shutdown_in_progress = false;
}
 
void log_cleanup_colors(void) {
  colorscheme_cleanup_compiled(&g_compiled_colors);
}
 
/* ============================================================================
 * Log Recoloring for Plain Text Entries
 * ============================================================================ */
 
size_t log_recolor_plain_entry(const char *plain_line, char *colored_buf, size_t buf_size) {
  if (!plain_line || !colored_buf || buf_size < 128) {
    return 0;
  }
 
  static char work_buffer[LOG_MSG_BUFFER_SIZE + 1024];
 
  // Parse format FIRST, regardless of color availability
  // Parse format: [TIMESTAMP] [LEVEL] [tid:THREAD_ID] FILE:LINE in FUNC(): MESSAGE
  const char *p = plain_line;
 
  // Extract timestamp [TIMESTAMP]
  if (*p != '[') {
    return 0; // Invalid format
  }
  p++;
  const char *timestamp_start = p;
 
  // Find the closing ] for timestamp - look for pattern that ends with proper timestamp format
  // Valid timestamp: HH:MM:SS.UUUUUU (time with microseconds, no date)
  while (*p && *p != ']') {
    p++;
  }
  if (*p != ']') {
    return 0; // Malformed - no closing bracket
  }
 
  size_t timestamp_len = p - timestamp_start;
  char timestamp[64];
  if (timestamp_len >= sizeof(timestamp) || timestamp_len == 0) {
    return 0; // Invalid timestamp - empty or too long
  }
  SAFE_STRNCPY(timestamp, timestamp_start, timestamp_len);
  timestamp[timestamp_len] = '\0';
  p++; // Skip ]
 
  // Skip whitespace after timestamp
  while (*p && *p == ' ') {
    p++;
  }
 
  // Extract level [LEVEL]
  if (*p != '[') {
    return 0; // Missing opening bracket for level
  }
  p++;
  const char *level_start = p;
  while (*p && *p != ']') {
    p++;
  }
  if (*p != ']') {
    return 0; // Missing closing bracket for level
  }
  size_t level_len = p - level_start;
  char level_str[16];
  if (level_len >= sizeof(level_str) || level_len == 0) {
    return 0; // Level string too long or empty
  }
  /* Use strncpy directly for substring extraction (not null-terminated source) */
  strncpy(level_str, level_start, level_len);
  level_str[level_len] = '\0';
 
  // Determine log level for color selection
  log_level_t level = LOG_INFO; // Default
  if (strstr(level_str, "DEV") || strstr(level_str, "DEBUG")) {
    level = LOG_DEBUG;
  } else if (strstr(level_str, "INFO")) {
    level = LOG_INFO;
  } else if (strstr(level_str, "WARN")) {
    level = LOG_WARN;
  } else if (strstr(level_str, "ERROR")) {
    level = LOG_ERROR;
  } else if (strstr(level_str, "FATAL")) {
    level = LOG_FATAL;
  }
 
  p++; // Skip ]
 
  // Skip whitespace after level
  while (*p && *p == ' ') {
    p++;
  }
 
  // Extract thread ID [tid:THREAD_ID] - optional field
  uint64_t tid = 0;
  if (*p == '[' && strncmp(p, "[tid:", 5) == 0) {
    p += 5;
    char *tid_end = NULL;
    tid = strtoull(p, &tid_end, 10);
    if (!tid_end || *tid_end != ']') {
      // tid parsing failed, but continue anyway (might still recover)
      // Try to find the closing bracket
      while (*p && *p != ']') {
        p++;
      }
      if (*p == ']') {
        p++;
      }
    } else {
      p = tid_end + 1; // Skip past the ]
    }
    // Skip whitespace after tid
    while (*p && *p == ' ') {
      p++;
    }
  }
  // tid is optional - continue parsing if not present
 
  // Extract file path (everything up to :LINE)
  const char *file_start = p;
  while (*p && *p != ':') {
    p++;
  }
  if (*p != ':') {
    return 0; // Malformed
  }
  size_t file_len = p - file_start;
  char file_path[256];
  if (file_len >= sizeof(file_path)) {
    return 0;
  }
  /* Use strncpy directly for substring extraction (not null-terminated source) */
  strncpy(file_path, file_start, file_len);
  file_path[file_len] = '\0';
  p++; // Skip :
 
  // Extract line number (digits only)
  int line_num = 0;
  const char *line_start = p;
  while (*p && isdigit((unsigned char)*p)) {
    p++;
  }
  if (p == line_start) {
    return 0; // No line number
  }
  line_num = (int)strtol(line_start, NULL, 10);
 
  // Skip whitespace and find "in" keyword (be very lenient)
  while (*p && (*p == ' ' || *p == '\t' || *p == '\n' || *p == '\r')) {
    p++;
  }
 
  // Try to find "in " - if not found, might still be valid, just harder to parse
  if (strncmp(p, "in ", 3) == 0) {
    p += 3; // Skip "in "
  } else if (*p == 'i' && *(p + 1) == 'n' && (*(p + 2) == ' ' || *(p + 2) == '\t')) {
    // Allow tab after "in"
    p += 2; // Skip "in"
    while (*p && (*p == ' ' || *p == '\t')) {
      p++;
    }
  } else {
    // Missing "in" keyword - this is a format error
    return 0;
  }
 
  // Extract function name (everything up to "()")
  const char *func_start = p;
  while (*p && *p != '(') {
    p++;
  }
  if (*p != '(' || func_start == p) {
    return 0; // Missing function name or parentheses
  }
  size_t func_len = p - func_start;
 
  // Trim trailing whitespace from function name
  while (func_len > 0 && (func_start[func_len - 1] == ' ' || func_start[func_len - 1] == '\t')) {
    func_len--;
  }
 
  char func_name[256];
  if (func_len >= sizeof(func_name)) {
    func_len = sizeof(func_name) - 1;
  }
  if (func_len > 0) {
    /* Use strncpy directly for substring extraction (not null-terminated source) */
    strncpy(func_name, func_start, func_len);
  }
  func_name[func_len] = '\0';
 
  // Skip "(" and ")" - be lenient about what's between them
  if (*p == '(') {
    p++;
    while (*p && *p != ')') {
      p++;
    }
    if (*p == ')') {
      p++;
    }
  }
 
  // Skip whitespace and optional colon(s) and other separators
  while (*p && (*p == ' ' || *p == ':' || *p == '\t')) {
    p++;
  }
 
  // Remaining is the message
  const char *message = p;
 
  // Format is valid, get colors from logging system
  const char **colors = log_get_color_array();
  if (!colors) {
    // No colors available, return plain text
    static bool warned_once = false;
    if (!warned_once) {
      log_debug("WARNING: log_recolor_plain_entry() called but colors not initialized - returning plain text");
      warned_once = true;
    }
    size_t len = strlen(plain_line);
    if (len >= buf_size) {
      return 0;
    }
    SAFE_STRNCPY(colored_buf, plain_line, buf_size - 1);
    colored_buf[buf_size - 1] = '\0';
    return len;
  }
 
  // Build colored output
  const char *level_color = colors[level];
  const char *reset = colors[LOG_COLOR_RESET];
  const char *file_color = colors[1]; // DEBUG/Cyan
  const char *line_color = colors[6]; // GREY (matching tid)
  const char *func_color = colors[0]; // DEV/Orange
  const char *tid_color = colors[6];  // GREY
 
  int len = safe_snprintf(work_buffer, sizeof(work_buffer),
                          "[%s%s%s] [%s%s%s] [tid:%s%llu%s] %s%s%s:%s%d%s in %s%s%s(): %s", level_color, timestamp,
                          reset, level_color, level_str, reset, tid_color, (unsigned long long)tid, reset, file_color,
                          file_path, reset, line_color, line_num, reset, func_color, func_name, reset, message);
 
  if (len <= 0 || len >= (int)sizeof(work_buffer)) {
    return 0;
  }
 
  // Colorize the message part
  const char *colorized_msg = colorize_log_message(message);
  len = safe_snprintf(work_buffer, sizeof(work_buffer),
                      "[%s%s%s] [%s%s%s] [tid:%s%llu%s] %s%s%s:%s%d%s in %s%s%s(): %s", level_color, timestamp, reset,
                      level_color, level_str, reset, tid_color, (unsigned long long)tid, reset, file_color, file_path,
                      reset, line_color, line_num, reset, func_color, func_name, reset, colorized_msg);
 
  if (len <= 0 || len >= (int)sizeof(work_buffer) || len >= (int)buf_size) {
    return 0;
  }
 
  SAFE_STRNCPY(colored_buf, work_buffer, buf_size - 1);
  colored_buf[buf_size - 1] = '\0';
  return (size_t)len;
}
 
// Internal implementation - don't use directly, use log_console_impl macro
void log_console_impl(log_level_t level, const char *file, int line, const char *func, const char *message) {
  if (!message) {
    return;
  }
 
  int fd = terminal_choose_log_fd(level);
  if (fd < 0) {
    return;
  }
 
  // Check if JSON output is enabled (json_file >= 0 means enabled)
  int json_fd = atomic_load(&g_log.json_file);
  bool use_json = (json_fd >= 0);
 
  if (use_json) {
    // Use async-safe JSON formatter (safe for signal handlers)
    extern void log_json_async_safe(int fd, log_level_t level, const char *file, int line, const char *func,
                                    const char *message);
    log_json_async_safe(fd, level, file, line, func, message);
  } else {
    // Text output to console using platform_write_all to handle partial writes
    size_t msg_len = strlen(message);
    platform_write_all(fd, (const uint8_t *)message, msg_len);
    if (msg_len == 0 || message[msg_len - 1] != '\n') {
      platform_write_all(fd, (const uint8_t *)"\n", 1);
    }
  }
}
 
void *log_get_template(void) {
  return (void *)g_log.format;
}