config.c File Reference

📋 TOML configuration file parser with schema validation and CLI override support More...

Go to the source code of this file.

Data Structures
union	option_parsed_value_t
	Union holding all possible parsed option values. More...
struct	option_type_handler_t
	Type handler - encapsulates all 4 operations for one option type. More...
struct	config_builder_t
	Helper structure for building config content in a buffer. More...

Macros
Internal Macros
#define	CONFIG_WARN(fmt, ...)
	Print configuration warning using the logging system.
#define	CONFIG_DEBUG(fmt, ...)
	Print configuration debug message.

Functions
asciichat_error_t	config_load_and_apply (asciichat_mode_t detected_mode, const char *config_path, bool strict, options_t *opts)
	Main function to load configuration from file and apply to global options.
asciichat_error_t	config_create_default (const char *config_path)
asciichat_error_t	config_load_system_and_user (asciichat_mode_t detected_mode, bool strict, options_t *opts)
TOML Value Extraction Helpers
Helper functions to safely extract typed values from TOML datum structures.
Schema-Based Configuration Parser

Detailed Description

📋 TOML configuration file parser with schema validation and CLI override support

Definition in file config.c.

Macro Definition Documentation

CONFIG_DEBUG

#define CONFIG_DEBUG	(		fmt,
			...
	)

Value:

  do {                                                                                                                 \
    /* Debug messages are only shown in debug builds after logging is initialized */                                   \
    /* Use log_debug which safely checks initialization itself */                                                      \
    log_debug(fmt, ##__VA_ARGS__);                                                                                     \
  } while (0)

Print configuration debug message.

Debug messages use the logging system if it's initialized, otherwise they are silently dropped.

Definition at line 57 of file config.c.

     {                                                                                                                 \
    /* Debug messages are only shown in debug builds after logging is initialized */                                   \
    /* Use log_debug which safely checks initialization itself */                                                      \
    log_debug(fmt, ##__VA_ARGS__);                                                                                     \
  } while (0)

CONFIG_WARN

#define CONFIG_WARN	(		fmt,
			...
	)

Value:

  do {                                                                                                                 \
    log_warn("Config file: " fmt, ##__VA_ARGS__);                                                                      \
  } while (0)

Print configuration warning using the logging system.

Uses log_warn so that config warnings respect the –quiet flag and are routed through the logging system for proper filtering.

Definition at line 46 of file config.c.

     {                                                                                                                 \
    log_warn("Config file: " fmt, ##__VA_ARGS__);                                                                      \
  } while (0)

Function Documentation

config_create_default()

asciichat_error_t config_create_default

(

const char *

config_path

)

Definition at line 1250 of file config.c.

                                                                 {
  char *config_path_expanded = NULL;
 
  defer(SAFE_FREE(config_path_expanded));
 
  // Create fresh options with all OPT_*_DEFAULT values
  options_t defaults = options_t_new();
 
  // Allocate buffer for building config content (256KB should be plenty)
  const size_t BUFFER_CAPACITY = 256 * 1024;
  config_builder_t builder = {0};
  builder.buffer = SAFE_MALLOC(BUFFER_CAPACITY, char *);
  if (!builder.buffer) {
    return SET_ERRNO(ERROR_MEMORY, "Failed to allocate config buffer");
  }
  defer(SAFE_FREE(builder.buffer));
  builder.capacity = BUFFER_CAPACITY;
 
  // Build version comment in buffer
  if (!config_builder_append(&builder, "# ascii-chat configuration file\n")) {
    return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
  }
  if (!config_builder_append(&builder, "# Generated by ascii-chat v%d.%d.%d-%s\n", ASCII_CHAT_VERSION_MAJOR,
                             ASCII_CHAT_VERSION_MINOR, ASCII_CHAT_VERSION_PATCH, ASCII_CHAT_GIT_VERSION)) {
    return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
  }
  if (!config_builder_append(&builder, "#\n")) {
    return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
  }
  if (!config_builder_append(&builder, "# All options below are commented out because some configuration options\n")) {
    return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
  }
  if (!config_builder_append(&builder, "# conflict with each other (e.g., --file vs --url, --loop vs --url).\n")) {
    return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
  }
  if (!config_builder_append(&builder, "# Uncomment only the options you need and avoid conflicting combinations.\n")) {
    return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
  }
  if (!config_builder_append(&builder, "#\n")) {
    return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
  }
  if (!config_builder_append(&builder,
                             "# If you upgrade ascii-chat and this version comment changes, you may need to\n")) {
    return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
  }
  if (!config_builder_append(&builder, "# delete and regenerate this file with: ascii-chat --config-create\n")) {
    return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
  }
  if (!config_builder_append(&builder, "#\n\n")) {
    return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
  }
 
  // Get all options from schema
  size_t metadata_count = 0;
  const config_option_metadata_t *metadata = config_schema_get_all(&metadata_count);
 
  // Build list of unique categories in order of first appearance
  const char *categories[16] = {0}; // Max expected categories
  size_t category_count = 0;
 
  for (size_t i = 0; i < metadata_count && category_count < 16; i++) {
    const char *category = metadata[i].category;
    if (!category) {
      continue;
    }
 
    // Check if category already in list
    bool found = false;
    for (size_t j = 0; j < category_count; j++) {
      if (categories[j] && strcmp(categories[j], category) == 0) {
        found = true;
        break;
      }
    }
 
    if (!found) {
      categories[category_count++] = category;
    }
  }
 
  // Build each section dynamically from schema
  for (size_t cat_idx = 0; cat_idx < category_count; cat_idx++) {
    const char *category = categories[cat_idx];
    if (!category) {
      continue;
    }
 
    // Get all options for this category
    size_t cat_option_count = 0;
    const config_option_metadata_t **cat_options = config_schema_get_by_category(category, &cat_option_count);
 
    if (!cat_options || cat_option_count == 0) {
      continue;
    }
 
    // Add section header
    if (!config_builder_append(&builder, "[%s]\n", category)) {
      return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
    }
 
    // Track which options we've written (to avoid duplicates)
    bool written_flags[64] = {0}; // Max options per category
 
    // Add each option in this category
    for (size_t opt_idx = 0; opt_idx < cat_option_count && opt_idx < 64; opt_idx++) {
      const config_option_metadata_t *meta = cat_options[opt_idx];
      if (!meta || !meta->toml_key) {
        continue;
      }
 
      // Skip if already written (duplicate)
      if (written_flags[opt_idx]) {
        continue;
      }
 
      // Skip if this is a duplicate of another option (check by TOML key, not field_offset)
      // Note: Multiple options can map to the same field (e.g., server_log_file, client_log_file)
      bool is_duplicate = false;
      for (size_t j = 0; j < opt_idx; j++) {
        if (cat_options[j] && cat_options[j]->toml_key && meta->toml_key &&
            strcmp(cat_options[j]->toml_key, meta->toml_key) == 0) {
          is_duplicate = true;
          break;
        }
      }
      if (is_duplicate) {
        continue;
      }
 
      // Get field pointer from default options (or mode-specific default if available)
      const char *field_ptr = ((const char *)&defaults) + meta->field_offset;
 
      // Buffer to hold mode-specific default value if needed
      char mode_default_buffer[OPTIONS_BUFF_SIZE] = {0};
      int mode_default_int = 0;
 
      // If this option has a mode_default_getter, use it to get the correct default
      if (meta->mode_default_getter) {
        asciichat_mode_t mode = extract_mode_from_bitmask(meta->mode_bitmask);
        if (mode != MODE_INVALID) {
          const void *default_value = meta->mode_default_getter(mode);
          if (default_value) {
            // Copy the default value to our buffer based on type
            if (meta->type == OPTION_TYPE_STRING || meta->type == OPTION_TYPE_CALLBACK) {
              const char *str_value = (const char *)default_value;
              SAFE_STRNCPY(mode_default_buffer, str_value, sizeof(mode_default_buffer));
              field_ptr = mode_default_buffer;
            } else if (meta->type == OPTION_TYPE_INT) {
              mode_default_int = *(const int *)default_value;
              field_ptr = (const char *)&mode_default_int;
            }
          }
        }
      }
 
      // Add description comment if available
      if (meta->description && strlen(meta->description) > 0) {
        if (!config_builder_append(&builder, "# %s\n", meta->description)) {
          return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
        }
      }
 
      // Format and add the option value using handler (commented out to avoid conflicts)
      if (g_type_handlers[meta->type].format_output) {
        char formatted_value[BUFFER_SIZE_MEDIUM] = {0};
        g_type_handlers[meta->type].format_output(field_ptr, meta->field_size, meta, formatted_value,
                                                  sizeof(formatted_value));
        const char *output_key = meta->toml_key;
        size_t category_len = strlen(category);
        if (strncmp(meta->toml_key, category, category_len) == 0 && meta->toml_key[category_len] == '.') {
          output_key = meta->toml_key + category_len + 1; // Strip "<category>."
        }
 
        if (config_key_should_be_commented(meta->toml_key)) {
          if (!config_builder_append(&builder, "# %s = %s\n", output_key, formatted_value)) {
            return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
          }
        } else {
          if (!config_builder_append(&builder, "%s = %s\n", output_key, formatted_value)) {
            return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
          }
        }
      }
 
      // Add blank line after each option
      if (!config_builder_append(&builder, "\n")) {
        return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
      }
 
      written_flags[opt_idx] = true;
    }
 
    // Add blank line between sections (but not after the last section)
    if (cat_idx < category_count - 1) {
      if (!config_builder_append(&builder, "\n")) {
        return SET_ERRNO(ERROR_CONFIG, "Config too large to fit in buffer");
      }
    }
  }
 
  // Now write the buffer to either stdout or a file
  if (config_path && strlen(config_path) > 0) {
    // User provided a filepath - write to that file with overwrite prompt
 
    // Expand and validate the path
    config_path_expanded = expand_path(config_path);
    if (!config_path_expanded) {
      config_path_expanded = platform_strdup(config_path);
    }
 
    if (!config_path_expanded) {
      return SET_ERRNO(ERROR_CONFIG, "Failed to resolve config file path");
    }
 
    char *validated_config_path = NULL;
    asciichat_error_t validate_result =
        path_validate_user_path(config_path_expanded, PATH_ROLE_CONFIG_FILE, &validated_config_path);
    if (validate_result != ASCIICHAT_OK) {
      SAFE_FREE(validated_config_path);
      SAFE_FREE(config_path_expanded);
      return validate_result;
    }
    // Free the old path before reassigning (defer will free the new one)
    if (config_path_expanded != validated_config_path) {
      SAFE_FREE(config_path_expanded);
    }
    config_path_expanded = validated_config_path;
 
    // Check if file already exists
    struct stat st;
    if (stat(config_path_expanded, &st) == 0) {
      // File exists - ask user if they want to overwrite
      log_plain("Config file already exists: %s", config_path_expanded);
 
      bool overwrite = platform_prompt_yes_no("Overwrite", false); // Default to No
      if (!overwrite) {
        log_plain("Config file creation cancelled.");
        return SET_ERRNO(ERROR_CONFIG, "User cancelled overwrite");
      }
 
      log_plain("Overwriting existing config file...");
    }
 
    // Create directory if needed
    char *dir_path = platform_strdup(config_path_expanded);
    if (!dir_path) {
      return SET_ERRNO(ERROR_MEMORY, "Failed to allocate memory for directory path");
    }
    defer(SAFE_FREE(dir_path));
 
    // Find the last path separator
    char *last_sep = strrchr(dir_path, PATH_DELIM);
 
    if (last_sep) {
      *last_sep = '\0';
      // Create directory recursively
      asciichat_error_t mkdir_result = platform_mkdir_recursive(dir_path, DIR_PERM_PRIVATE);
      if (mkdir_result != ASCIICHAT_OK) {
        return mkdir_result;
      }
    }
 
    // Open file for writing
    FILE *output_file = platform_fopen(config_path_expanded, "w");
    if (!output_file) {
      return SET_ERRNO_SYS(ERROR_CONFIG, "Failed to open config file for writing: %s", config_path_expanded);
    }
    defer(SAFE_FCLOSE(output_file));
 
    // Write buffer to file
    size_t written = fwrite(builder.buffer, 1, builder.size, output_file);
    if (written != builder.size) {
      return SET_ERRNO_SYS(ERROR_CONFIG, "Failed to write config to file: %s", config_path_expanded);
    }
  } else {
    // No filepath provided - write buffer to stdout with automatic retry on transient errors
    (void)platform_write_all(STDOUT_FILENO, builder.buffer, builder.size);
    // Flush C stdio buffer and terminal to ensure piped output is written immediately
    (void)fflush(stdout);
    (void)terminal_flush(STDOUT_FILENO);
  }
 
  return ASCIICHAT_OK;
}

References config_builder_t::buffer, config_builder_t::capacity, config_schema_get_all(), config_schema_get_by_category(), expand_path(), option_type_handler_t::format_output, options_t_new(), path_validate_user_path(), platform_fopen(), platform_mkdir_recursive(), platform_prompt_yes_no(), platform_strdup(), platform_write_all(), config_builder_t::size, and terminal_flush().

Referenced by action_create_config(), and options_init().

config_load_and_apply()

asciichat_error_t config_load_and_apply	(	asciichat_mode_t	detected_mode,
		const char *	config_path,
		bool	strict,
		options_t *	opts
	)

Main function to load configuration from file and apply to global options.

Parameters

is_client	true if loading client configuration, false for server configuration
config_path	Optional path to config file (NULL uses default location)
strict	If true, errors are fatal; if false, errors are non-fatal warnings

Returns

ASCIICHAT_OK on success, error code on failure (if strict) or non-fatal (if !strict)

This is the main entry point for configuration loading. It:

1. Expands the config file path (default location or custom path)
2. Checks if the file exists and is a regular file
3. Parses the TOML file using tomlc17
4. Applies configuration from each section (network, client, palette, crypto, logging)
5. Frees resources and returns

Configuration file errors are non-fatal if strict is false:

• Missing file: Returns ASCIICHAT_OK (config file is optional)
• Not a regular file: Warns and returns ASCIICHAT_OK
• Parse errors: Warns and returns ASCIICHAT_OK
• Invalid values: Individual values are skipped with warnings

If strict is true, any error causes immediate return with error code.

Note

This function should be called before options_init() parses command-line arguments to ensure CLI arguments can override config file values.

Configuration warnings are printed to stderr because logging may not be initialized yet when this function is called.

Definition at line 1044 of file config.c.

                                                         {
  // detected_mode is used in config_apply_schema for bitmask validation
  char *config_path_expanded = NULL;
  defer(SAFE_FREE(config_path_expanded));
 
  if (config_path) {
    // Use custom path provided
    config_path_expanded = expand_path(config_path);
    if (!config_path_expanded) {
      // If expansion fails, try using as-is (might already be absolute)
      config_path_expanded = platform_strdup(config_path);
    }
  } else {
    // Use default location with XDG support
    char *config_dir = get_config_dir();
    defer(SAFE_FREE(config_dir));
    if (config_dir) {
      size_t len = strlen(config_dir) + strlen("config.toml") + 1;
      config_path_expanded = SAFE_MALLOC(len, char *);
      if (config_path_expanded) {
        safe_snprintf(config_path_expanded, len, "%sconfig.toml", config_dir);
      }
    }
 
    // Fallback to ~/.ascii-chat/config.toml
    if (!config_path_expanded) {
      config_path_expanded = expand_path("~/.ascii-chat/config.toml");
    }
  }
 
  if (!config_path_expanded) {
    if (strict) {
      return SET_ERRNO(ERROR_CONFIG, "Failed to resolve config file path");
    }
    return ASCIICHAT_OK;
  }
 
  char *validated_config_path = NULL;
  asciichat_error_t validate_result =
      path_validate_user_path(config_path_expanded, PATH_ROLE_CONFIG_FILE, &validated_config_path);
  if (validate_result != ASCIICHAT_OK) {
    SAFE_FREE(validated_config_path);
    SAFE_FREE(config_path_expanded);
    return validate_result;
  }
  // Free the old path before reassigning (defer will free the new one)
  if (config_path_expanded != validated_config_path) {
    SAFE_FREE(config_path_expanded);
  }
  config_path_expanded = validated_config_path;
 
  // Determine display path for error messages (before any early returns)
  const char *display_path = config_path ? config_path : config_path_expanded;
 
  // Log that we're attempting to load config (before logging is initialized, use stderr)
  // Only print if terminal output is enabled (suppress with --quiet)
  if (config_path && log_get_terminal_output()) {
    log_debug("Loading configuration from: %s", display_path);
  }
 
  // Check if config file exists
  struct stat st;
  if (stat(config_path_expanded, &st) != 0) {
    if (strict) {
      return SET_ERRNO(ERROR_CONFIG, "Config file does not exist: '%s'", display_path);
    }
    // File doesn't exist, that's OK - not required (non-strict mode)
    return ASCIICHAT_OK;
  }
 
  // Verify it's a regular file
  if (!S_ISREG(st.st_mode)) {
    if (strict) {
      return SET_ERRNO(ERROR_CONFIG, "Config file exists but is not a regular file: '%s'", display_path);
    }
    CONFIG_WARN("Config file exists but is not a regular file: '%s' (skipping)", display_path);
    return ASCIICHAT_OK;
  }
 
  // Parse TOML file
  toml_result_t result = toml_parse_file_ex(config_path_expanded);
  // Ensure TOML resources are freed at ALL function exit points (defer handles cleanup)
  defer(toml_free(result));
 
  if (!result.ok) {
    // result.errmsg is an array, so check its first character
    const char *errmsg = (strlen(result.errmsg) > 0) ? result.errmsg : "Unknown parse error";
 
    if (strict) {
      // For strict mode, return detailed error message directly
      // Note: SET_ERRNO stores the message in context, but asciichat_error_string() only returns generic codes
      // So we need to format the error message ourselves here
      char error_buffer[BUFFER_SIZE_MEDIUM];
      safe_snprintf(error_buffer, sizeof(error_buffer), "Failed to parse config file '%s': %s", display_path, errmsg);
      toml_free(result); // Explicit cleanup before return (defer transformation not applied)
      return SET_ERRNO(ERROR_CONFIG, "%s", error_buffer);
    }
    CONFIG_WARN("Failed to parse config file '%s': %s (skipping)", display_path, errmsg);
    toml_free(result);   // Explicit cleanup before return (defer transformation not applied)
    return ASCIICHAT_OK; // Non-fatal error
  }
 
  // Apply configuration using schema-driven parser with bitmask validation
  asciichat_error_t schema_result = config_apply_schema(result.toptab, detected_mode, opts, strict);
 
  if (schema_result != ASCIICHAT_OK && strict) {
    toml_free(result); // Explicit cleanup before return (defer transformation not applied)
    return schema_result;
  }
  // In non-strict mode, continue even if some options failed validation
 
  CONFIG_DEBUG("Loaded configuration from %s", display_path);
 
  // Log successful config load (use stderr since logging may not be initialized yet)
  // Only print if terminal output is enabled (suppress with --quiet)
  if (log_get_terminal_output()) {
    log_debug("Loaded configuration from: %s", display_path);
  }
 
  // Update RCU system with modified options (for test compatibility)
  // In real usage, options_state_set is called later after CLI parsing
  asciichat_error_t rcu_result = options_state_set(opts);
  if (rcu_result != ASCIICHAT_OK) {
    // Non-fatal - RCU might not be initialized yet in some test scenarios
    // But log as warning so tests can see if this is the issue
    CONFIG_WARN("Failed to update RCU options state: %d (values may not be persisted)", rcu_result);
  }
 
  toml_free(result); // Explicit cleanup before return (defer transformation not applied)
  return ASCIICHAT_OK;
}

References CONFIG_DEBUG, CONFIG_WARN, expand_path(), get_config_dir(), log_get_terminal_output(), options_state_set(), path_validate_user_path(), platform_strdup(), and safe_snprintf().

Referenced by config_load_system_and_user().

config_load_system_and_user()

asciichat_error_t config_load_system_and_user	(	asciichat_mode_t	detected_mode,
		bool	strict,
		options_t *	opts
	)

Definition at line 1535 of file config.c.

                                                                                                            {
  // Use platform abstraction to find all config.toml files across standard locations
  config_file_list_t config_files = {0};
  asciichat_error_t search_result = platform_find_config_file("config.toml", &config_files);
  defer(config_file_list_destroy(&config_files));
 
  if (search_result != ASCIICHAT_OK) {
    CONFIG_DEBUG("Failed to search for config files: %d", search_result);
    config_file_list_destroy(&config_files);
    return search_result;
  }
 
  // Cascade load: Load all found configs in reverse order (lowest priority first)
  // This allows higher-priority configs to override lower-priority values.
  // Example: System configs load first, then user configs override them.
 
  asciichat_error_t result = ASCIICHAT_OK;
  for (size_t i = config_files.count; i > 0; i--) {
    const config_file_result_t *file = &config_files.files[i - 1];
 
    // Determine strictness based on whether this is a system or user config
    // System configs are non-strict (values can be missing, errors are non-fatal)
    // User config is strict or non-strict based on parameter
    bool is_user_config = !file->is_system_config;
    bool file_strict = is_user_config ? strict : false;
 
    CONFIG_DEBUG("Loading config from %s (system=%s, strict=%s)", file->path, file->is_system_config ? "yes" : "no",
                 file_strict ? "true" : "false");
 
    asciichat_error_t load_result = config_load_and_apply(detected_mode, file->path, file_strict, opts);
 
    if (load_result != ASCIICHAT_OK) {
      if (file_strict) {
        // Strict mode: errors are fatal
        CONFIG_DEBUG("Strict config loading failed for %s", file->path);
        result = load_result;
      } else {
        // Non-strict mode: errors are non-fatal, just log and continue
        CONFIG_DEBUG("Non-strict config loading warning for %s: %d (continuing)", file->path, load_result);
        CLEAR_ERRNO(); // Clear error context for next file
      }
    }
  }
 
  config_file_list_destroy(&config_files);
  return result;
}

References CONFIG_DEBUG, config_file_list_destroy(), config_load_and_apply(), and platform_find_config_file().

Referenced by options_init().