配置即数据

const std = @import("std");

/// Configuration structure for an application with sensible defaults
/// 应用程序的配置结构，带有合理的默认值
const AppConfig = struct {
    /// Theme options for the application UI
    /// 应用程序UI的主题选项
    pub const Theme = enum { system, light, dark };

    // Default configuration values are specified inline
    // 默认配置值在行内指定
    host: []const u8 = "127.0.0.1",
    port: u16 = 8080,
    log_level: std.log.Level = .info,
    instrumentation: bool = false,
    theme: Theme = .system,
    timeouts: Timeouts = .{},

    /// Nested configuration for timeout settings
    /// 超时设置的嵌套配置
    pub const Timeouts = struct {
        connect_ms: u32 = 200,
        read_ms: u32 = 1200,
    };
};

/// Helper function to print configuration values in a human-readable format
/// writer: any type implementing write() and print() methods
/// label: descriptive text to identify this configuration dump
/// config: the AppConfig instance to display
/// 辅助函数，以人类可读的格式打印配置值
/// writer：实现 write() 和 print() 方法的任何类型
/// label：描述性文本，用于标识此配置转储
/// config：要显示的 AppConfig 实例
fn dumpConfig(writer: anytype, label: []const u8, config: AppConfig) !void {
    // Print the label header
    // 打印标签头部
    try writer.print("{s}\n", .{label});

    // Print each field with proper formatting
    // 以适当格式打印每个字段
    try writer.print("  host = {s}\n", .{config.host});
    try writer.print("  port = {}\n", .{config.port});

    // Use @tagName to convert enum values to strings
    // 使用 @tagName 将枚举值转换为字符串
    try writer.print("  log_level = {s}\n", .{@tagName(config.log_level)});
    try writer.print("  instrumentation = {}\n", .{config.instrumentation});
    try writer.print("  theme = {s}\n", .{@tagName(config.theme)});

    // Print nested struct in single line
    // 在单行中打印嵌套结构
    try writer.print(
        "  timeouts = .{{ connect_ms = {}, read_ms = {} }}\n",
        .{ config.timeouts.connect_ms, config.timeouts.read_ms },
    );
}

pub fn main() !void {
    // Allocate a fixed buffer for stdout operations
    // 为 stdout 操作分配固定缓冲区
    var stdout_buffer: [2048]u8 = undefined;

    // Create a buffered writer for stdout to reduce syscalls
    // 创建带缓冲区的 stdout 写入器以减少系统调用
    var stdout_writer = std.fs.File.stdout().writer(&stdout_buffer);
    const stdout = &stdout_writer.interface;

    // Create a config using all default values (empty initializer)
    // 使用所有默认值创建配置（空初始化器）
    const defaults = AppConfig{};
    try dumpConfig(stdout, "defaults ->", defaults);

    // Create a config with several overridden values
    // Fields not specified here retain their defaults from the struct definition
    // 创建带有几个覆盖值的配置
    // 未在此处指定的字段保留其结构定义中的默认值
    const tuned = AppConfig{
        .host = "0.0.0.0",        // Bind to all interfaces
        // 绑定到所有接口
        .port = 9090,              // Custom port
        // 自定义端口
        .log_level = .debug,       // More verbose logging
        // 更详细的日志记录
        .instrumentation = true,   // Enable performance monitoring
        // 启用性能监控
        .theme = .dark,            // Dark theme instead of system default
        // 深色主题而不是系统默认
        .timeouts = .{             // Override nested timeout values
            // 覆盖嵌套超时值
            .connect_ms = 75,      // Faster connection timeout
            // 更快的连接超时
            .read_ms = 1500,       // Longer read timeout
            // 更长的读取超时
        },
    };

    // Add blank line between the two config dumps
    // 在两个配置转储之间添加空行
    try stdout.writeByte('\n');

    // Display the customized configuration
    // 显示自定义配置
    try dumpConfig(stdout, "overrides ->", tuned);

    // Flush the buffer to ensure all output is written to stdout
    // 刷新缓冲区以确保所有输出都写入 stdout
    try stdout.flush();
}

const std = @import("std");

/// Configuration structure for an application with sensible defaults
/// 应用程序配置结构，携带合理的默认值
const AppConfig = struct {
    /// Theme options for the application UI
    /// 应用程序用户界面的主题选项
    pub const Theme = enum { system, light, dark };

    host: []const u8 = "127.0.0.1",
    port: u16 = 8080,
    log_level: std.log.Level = .info,
    instrumentation: bool = false,
    theme: Theme = .system,
    timeouts: Timeouts = .{},

    /// Nested configuration for timeout settings
    /// 嵌套配置结构，用于超时设置
    pub const Timeouts = struct {
        connect_ms: u32 = 200,
        read_ms: u32 = 1200,
    };
};

/// Structure representing optional configuration overrides
/// Each field is optional (nullable) to indicate whether it should override the base config
/// 表示可选配置覆盖的结构
/// 每个字段都是可选的（可为 null），用于指示是否应覆盖基础配置
const Overrides = struct {
    host: ?[]const u8 = null,
    port: ?u16 = null,
    log_level: ?std.log.Level = null,
    instrumentation: ?bool = null,
    theme: ?AppConfig.Theme = null,
    timeouts: ?AppConfig.Timeouts = null,
};

/// Merges a single layer of overrides into a base configuration
/// base: the starting configuration to modify
/// overrides: optional values that should replace corresponding base fields
/// Returns: a new AppConfig with overrides applied
/// 将单层覆盖合并到基础配置中
/// base：要修改的起始配置
/// overrides：应替换相应基字段的可选值
/// 返回：应用覆盖后的新 AppConfig
fn merge(base: AppConfig, overrides: Overrides) AppConfig {
    // Start with a copy of the base configuration
    // 从基础配置的副本开始
    var result = base;

    // Iterate over all fields in the Overrides struct at compile time
    // 在编译时遍历 Overrides 结构的所有字段
    inline for (std.meta.fields(Overrides)) |field| {
        // Check if this override field has a non-null value
        // 检查此覆盖字段是否具有非空值
        if (@field(overrides, field.name)) |value| {
            // If present, replace the corresponding field in result
            // 如果存在，则替换结果中的相应字段
            @field(result, field.name) = value;
        }
    }

    return result;
}

/// Applies a chain of override layers in sequence
/// base: the initial configuration
/// chain: slice of Overrides to apply in order (left to right)
/// Returns: final configuration after all layers are merged
/// 按顺序应用覆盖层链
/// base：初始配置
/// chain：要按顺序应用（从左到右）的 Overrides 切片
/// 返回：合并所有层后的最终配置
fn apply(base: AppConfig, chain: []const Overrides) AppConfig {
    // Start with the base configuration
    // 从基础配置开始
    var current = base;

    // Apply each override layer in sequence
    // Later layers override earlier ones
    // 按顺序应用每个覆盖层
    // 后面的层覆盖前面的层
    for (chain) |layer| {
        current = merge(current, layer);
    }

    return current;
}

/// Helper function to print configuration values in a human-readable format
/// writer: any type implementing write() and print() methods
/// label: descriptive text to identify this configuration dump
/// config: the AppConfig instance to display
/// 辅助函数，以人类可读的格式打印配置值
/// writer：实现 write() 和 print() 方法的任何类型
/// label：描述性文本，用于标识此配置转储
/// config：要显示的 AppConfig 实例
fn printSummary(writer: anytype, label: []const u8, config: AppConfig) !void {
    try writer.print("{s}:\n", .{label});
    try writer.print("  host = {s}\n", .{config.host});
    try writer.print("  port = {}\n", .{config.port});
    try writer.print("  log = {s}\n", .{@tagName(config.log_level)});
    try writer.print("  instrumentation = {}\n", .{config.instrumentation});
    try writer.print("  theme = {s}\n", .{@tagName(config.theme)});
    try writer.print("  timeouts = {any}\n", .{config.timeouts});
}

pub fn main() !void {
    // Create base configuration with all default values
    // 创建包含所有默认值的基础配置
    const defaults = AppConfig{};

    // Define a profile-level override layer (e.g., development profile)
    // This might come from a profile file or environment-specific settings
    // 定义配置文件级覆盖层（例如开发配置文件）
    // 这可能来自配置文件或特定于环境的设置
    const profile = Overrides{
        .host = "0.0.0.0",
        .port = 9000,
        .log_level = .debug,
        .instrumentation = true,
        .theme = .dark,
        .timeouts = AppConfig.Timeouts{
            .connect_ms = 100,
            .read_ms = 1500,
        },
    };

    // Define environment-level overrides (e.g., from environment variables)
    // These override profile settings
    // 定义环境级覆盖（例如来自环境变量）
    // 这些覆盖配置文件设置
    const env = Overrides{
        .host = "config.internal",
        .port = 9443,
        .log_level = .warn,
        .timeouts = AppConfig.Timeouts{
            .connect_ms = 60,
            .read_ms = 1100,
        },
    };

    // Define command-line overrides (highest priority)
    // Only overrides specific fields, leaving others unchanged
    // 定义命令行覆盖（最高优先级）
    // 仅覆盖特定字段，其他保持不变
    const command_line = Overrides{
        .instrumentation = false,
        .theme = .light,
    };

    // Apply all override layers in precedence order:
    // defaults -> profile -> env -> command_line
    // Later layers take precedence over earlier ones
    // 按优先级顺序应用所有覆盖层：
    // defaults -> profile -> env -> command_line
    // 后面的层优先于前面的层
    const final = apply(defaults, &[_]Overrides{ profile, env, command_line });

    // Set up buffered stdout writer to reduce syscalls
    // 设置带缓冲区的 stdout 写入器以减少系统调用
    var stdout_buffer: [2048]u8 = undefined;
    var stdout_writer = std.fs.File.stdout().writer(&stdout_buffer);
    const stdout = &stdout_writer.interface;

    // Display progression of configuration through each layer
    // 显示配置在各层中的进展情况
    try printSummary(stdout, "defaults", defaults);
    try printSummary(stdout, "profile", merge(defaults, profile));
    try printSummary(stdout, "env", merge(defaults, env));
    try printSummary(stdout, "command_line", merge(defaults, command_line));

    // Add separator before showing final resolved config
    // 在显示最终解析的配置前添加分隔符
    try stdout.writeByte('\n');

    // Display the final merged configuration after all layers applied
    // 显示应用所有层后的最终合并配置
    try printSummary(stdout, "resolved", final);

    // Ensure all buffered output is written
    // 确保所有缓冲输出都被写入
    try stdout.flush();
}

const std = @import("std");

/// Environment mode for the application
/// Determines security requirements and runtime behavior
/// 应用程序的环境模式
/// 确定安全要求和运行时行为
const Mode = enum { development, staging, production };

/// Main application configuration structure with nested settings
/// 带嵌套设置的主要应用程序配置结构
const AppConfig = struct {
    host: []const u8 = "127.0.0.1",
    port: u16 = 8080,
    mode: Mode = .development,
    tls: Tls = .{},
    timeouts: Timeouts = .{},

    /// TLS/SSL configuration for secure connections
    /// TLS/SSL 安全连接配置
    pub const Tls = struct {
        enabled: bool = false,
        cert_path: ?[]const u8 = null,
        key_path: ?[]const u8 = null,
    };

    /// Timeout settings for network operations
    /// 网络操作的超时设置
    pub const Timeouts = struct {
        connect_ms: u32 = 200,
        read_ms: u32 = 1200,
    };
};

/// Explicit error set for all configuration validation failures
/// Each variant represents a specific invariant violation
/// 配置验证失败的所有显式错误集
/// 每个变体代表一个特定的不变式违反
const ConfigError = error{
    InvalidPort,
    InsecureProduction,
    MissingTlsMaterial,
    TimeoutOrdering,
};

/// Validates configuration invariants and business rules
/// config: the configuration to validate
/// Returns: ConfigError if any validation rule is violated
/// 验证配置不变式和业务规则
/// config：要验证的配置
/// 返回：如果违反任何验证规则，则返回 ConfigError
fn validate(config: AppConfig) ConfigError!void {
    // Port 0 is reserved and invalid for network binding
    // 端口 0 被保留，对网络绑定无效
    if (config.port == 0) return error.InvalidPort;

    // Ports below 1024 require elevated privileges (except standard HTTPS)
    // Reject them to avoid privilege escalation requirements
    // 低于 1024 的端口需要提升权限（标准 HTTPS 除外）
    // 拒绝它们以避免权限提升要求
    if (config.port < 1024 and config.port != 443) return error.InvalidPort;

    // Production environments must enforce TLS to protect data in transit
    // 生产环境必须强制使用 TLS 以保护传输中的数据
    if (config.mode == .production and !config.tls.enabled) {
        return error.InsecureProduction;
    }

    // When TLS is enabled, both certificate and private key must be provided
    // 启用 TLS 时，必须提供证书和私钥
    if (config.tls.enabled) {
        if (config.tls.cert_path == null or config.tls.key_path == null) {
            return error.MissingTlsMaterial;
        }
    }

    // Read timeout must exceed connect timeout to allow data transfer
    // Otherwise connections would time out immediately after establishment
    // 读取超时必须超过连接超时以允许数据传输
    // 否则连接将在建立后立即超时
    if (config.timeouts.read_ms < config.timeouts.connect_ms) {
        return error.TimeoutOrdering;
    }
}

/// Reports validation result in human-readable format
/// writer: output destination for the report
/// label: descriptive name for this configuration test case
/// config: the configuration to validate and report on
/// 以人类可读的格式报告验证结果
/// writer：报告的输出目的地
/// label：此配置测试用例的描述性名称
/// config：要验证和报告的配置
fn report(writer: anytype, label: []const u8, config: AppConfig) !void {
    try writer.print("{s}: ", .{label});

    // Attempt validation and catch any errors
    // 尝试验证并捕获任何错误
    validate(config) catch |err| {
        // If validation fails, report the error name and return
        // 如果验证失败，报告错误名称并返回
        return try writer.print("error {s}\n", .{@errorName(err)});
    };

    // If validation succeeded, report success
    // 如果验证成功，报告成功
    try writer.print("ok\n", .{});
}

pub fn main() !void {
    // Test case 1: Valid production configuration
    // All security requirements met: TLS enabled with credentials
    // 测试用例 1：有效的生产配置
    // 满足所有安全要求：启用 TLS 并提供凭据
    const production = AppConfig{
        .host = "example.com",
        .port = 8443,
        .mode = .production,
        .tls = .{
            .enabled = true,
            .cert_path = "certs/app.pem",
            .key_path = "certs/app.key",
        },
        .timeouts = .{
            .connect_ms = 250,
            .read_ms = 1800,
        },
    };

    // Test case 2: Invalid - production mode without TLS
    // Should trigger InsecureProduction error
    // 测试用例 2：无效 - 生产模式但无 TLS
    // 应触发 InsecureProduction 错误
    const insecure = AppConfig{
        .mode = .production,
        .tls = .{ .enabled = false },
    };

    // Test case 3: Invalid - read timeout less than connect timeout
    // Should trigger TimeoutOrdering error
    // 测试用例 3：无效 - 读取超时小于连接超时
    // 应触发 TimeoutOrdering 错误
    const misordered = AppConfig{
        .timeouts = .{
            .connect_ms = 700,
            .read_ms = 500,
        },
    };

    // Test case 4: Invalid - TLS enabled but missing certificate
    // Should trigger MissingTlsMaterial error
    // 测试用例 4：无效 - 启用 TLS 但缺少证书
    // 应触发 MissingTlsMaterial 错误
    const missing_tls_material = AppConfig{
        .mode = .staging,
        .tls = .{
            .enabled = true,
            .cert_path = null,
            .key_path = "certs/dev.key",
        },
    };

    // Set up buffered stdout writer to reduce syscalls
    // 设置带缓冲区的 stdout 写入器以减少系统调用
    var stdout_buffer: [1024]u8 = undefined;
    var stdout_writer = std.fs.File.stdout().writer(&stdout_buffer);
    const stdout = &stdout_writer.interface;

    // Run validation reports for all test cases
    // Each report will validate the config and print the result
    // 运行所有测试用例的验证报告
    // 每个报告将验证配置并打印结果
    try report(stdout, "production", production);
    try report(stdout, "insecure", insecure);
    try report(stdout, "misordered", misordered);
    try report(stdout, "missing_tls_material", missing_tls_material);

    // Ensure all buffered output is written to stdout
    // 确保所有缓冲输出都写入到 stdout
    try stdout.flush();
}