config-it

Asynchronous Centralized Configuration Management for Rust

config-it is an asynchronous library that offers centralized configuration management for Rust applications. Here are its key features:

• Define custom configuration templates using structs.
• Create multiple instances with different paths based on a single template.
• Receive notifications when your instance is updated.
• Use serde compatible archive formats to archive your data in your preferred way.
• Manage property-wise dirty flags for precise, responsive updates to your system.

As I'm not very good at writing English sentences, got some help from AI to write this README file. Thanks, robot!

Usage

/// This is a 'Template' struct, which is minimal unit of
/// instantiation. Put required properties to configure
/// your program.
///
/// All 'Template' classes must be 'Clone'able, and
/// 'Default'able.
///
/// (Trying to finding way to remove 'Default' constraint.
///  However, 'Clone' will always be required.)
#[derive(config_it::Template, Clone, Default)]
struct MyConfig {
    /// If you expose any field as config property, the
    /// field must be marked with `config_it` attribute.
    #[config_it]
    string_field: String,

    /// You can also specify default value, or min/max
    /// constraints for this field.
    #[config_it(default = 3, min = 1, max = 5)]
    int_field: i32,

    /// This field will be aliased as 'alias'.
    ///
    /// > **Warning** Don't use `~(tilde)` characters in
    /// > alias name. In current implementation, `~` is
    /// > used to indicate group object in archive
    /// > representation during serialization.
    #[config_it(alias = "alias")]
    non_alias: f32,

    /// Only specified set of values are allowed for
    /// this field, however, default field can be
    /// excluded from this set.
    #[config_it(default = "default", one_of("a", "b", "c"))]
    one_of_field: String,

    /// Any 'serde' compatible type can be used as config field.
    #[config_it]
    c_string_type: Box<std::ffi::CStr>,

    /// This will find value from environment variable
    /// `MY_ENV_VAR`. Currently, only values that can be
    /// `TryParse`d from `str` are supported.
    ///
    /// Environment variables are imported when the
    /// group is firstly instantiated.
    /// i.e. call to `Storage::create_group`
    #[config_it(env = "MY_ARRAY_VAR")]
    env_var: i64,

    /// Complicated default value are represented as expression.
    #[config_it(default_expr = "[1,2,3,4,5].into()")]
    array_init: Vec<i32>,

    /// This field is not part of config_it system.
    _not_part_of: (),

    /// This field won't be imported or exported from
    /// archiving operation
    #[config_it(no_import, no_export)]
    no_imp_exp: Vec<f64>,

    /// `transient` flag is equivalent to `no_import` and
    /// `no_export` flags.
    #[config_it(transient)]
    no_imp_exp_2: Vec<f64>,
}

// USAGE ///////////////////////////////////////////////////////////////////////////////////////

// 1. Storage
//
// Storage is basic and most important class to drive
// the whole config_it system. Before you can use any
// of the features, you must create a storage instance.
let (storage, driver_task) = config_it::create_storage();

// `[config_it::create_storage]` returns a tuple of
// `(Storage, Task)`. `Storage` is the handle to the
// storage, and `Task` is the driver task that must
// be spawned to drive the storage operations(actor).
// You can spawn the task using any async runtime.
//
// Basically, config_it is designed to be used with
// async runtime, we're run this example under async
// environment.
let mut local = futures::executor::LocalPool::new();
let spawn = local.spawner();

// Storage driver task must be running somewhere.
use futures::task::SpawnExt;
spawn.spawn(driver_task).unwrap();

// before starting this, let's set environment variable to see if it works.
std::env::set_var("MY_ARRAY_VAR", "123");

// Let's get into async
local.run_until(async {
    // 2. Groups and Templates
    //
    // A group is an instance of a template. You can
    // create multiple groups from a single template.
    // Each group has its own set of properties, and
    // can be configured independently.
    //
    // When instantiating a group, you must provide a
    // path to the group. Path is a list of short string
    // tokens, which is used to identify the group. You
    // can use any string as path, but it's recommended
    // to use a short string, which does not contain any
    // special characters. (Since it usually encoded as a
    //  key of a key-value store of some kind of data
    //  serialization formats, such as JSON, YAML, etc.)
    let path = &["path", "to", "my", "group"];
    let mut group = storage.create_group::<MyConfig>(path).await.unwrap();

    // Note, duplicated path name is not allowed.
    assert!(storage.create_group::<MyConfig>(path).await.is_err());

    // `update()` call to group, will check for asynchronously
    // queued updates, and apply changes to the group instance.
    // Since this is the first call to update,
    //
    // You can understand `update()` as clearing dirty flag.
    assert!(group.update() == true);

    // After `update()`, as long as there's no new update,
    // `update()` will return false.
    assert!(group.update() == false);

    // Every individual properties has their own dirty flag.
    assert!(true == group.check_elem_update(&group.array_init));
    assert!(true == group.check_elem_update(&group.c_string_type));
    assert!(true == group.check_elem_update(&group.env_var));
    assert!(true == group.check_elem_update(&group.no_imp_exp));
    assert!(true == group.check_elem_update(&group.no_imp_exp_2));
    assert!(true == group.check_elem_update(&group.non_alias));
    assert!(true == group.check_elem_update(&group.int_field));
    assert!(true == group.check_elem_update(&group.one_of_field));
    assert!(true == group.check_elem_update(&group.string_field));

    assert!(false == group.check_elem_update(&group.array_init));
    assert!(false == group.check_elem_update(&group.c_string_type));
    assert!(false == group.check_elem_update(&group.env_var));
    assert!(false == group.check_elem_update(&group.no_imp_exp));
    assert!(false == group.check_elem_update(&group.no_imp_exp_2));
    assert!(false == group.check_elem_update(&group.int_field));
    assert!(false == group.check_elem_update(&group.non_alias));
    assert!(false == group.check_elem_update(&group.one_of_field));
    assert!(false == group.check_elem_update(&group.string_field));

    // Any field that wasn't marked as 'config_it' attribute will not be part of
    // config_it system.

    // // Invoking next line will panic:
    // group.check_elem_update(&group.nothing_here);

    // 3. Properties
    //
    // You can access each field of the group instance in common deref manner.
    assert!(group.string_field == "");
    assert!(group.array_init == &[1, 2, 3, 4, 5]);
    assert!(group.env_var == 123);

    // 4. Importing and Exporting
    //
    // You can export the whole storage using 'Export' method.
    // (currently, there is no way to export a specific group
    //  instance. To separate groups into different archiving
    //  categories, you can use multiple storage instances)
    let archive = storage.export(Default::default()).await.unwrap();

    // `config_it::Archive` implements `serde::Serialize` and
    // `serde::Deserialize`. You can use it to serialize/
    //  deserialize the whole storage.
    let yaml = serde_yaml::to_string(&archive).unwrap();
    let json = serde_json::to_string_pretty(&archive).unwrap();
    println!("{}", yaml);
    // OUTPUT:
    //
    //  ~path: # all path tokens of group hierarchy are prefixed with '~'
    //    ~to: # (in near future, this will be made customizable)
    //      ~my:
    //        ~group:
    //          alias: 0.0
    //          array_init:
    //          - 1
    //          - 2
    //          - 3
    //          - 4
    //          - 5
    //          c_string_type: []
    //          env_var: 0
    //          int_field: 3
    //          one_of_field: default
    //          string_field: ''
    //

    println!("{}", json);
    // {
    //   "~path": {
    //     "~to": {
    //       "~my": {
    //         "~group": {
    //           "alias": 0.0,
    //           "array_init": [
    //             1,
    //             2,
    //             3,
    //             4,
    //             5
    //           ],
    //           "c_string_type": [],
    //           "env_var": 0,
    //           "int_field": 3,
    //           "one_of_field": "default",
    //           "string_field": ""
    //         }
    //       }
    //     }
    //   }
    // }

    // Importing is similar to exporting. You can import a
    // whole storage from an archive. For this, you should
    // create a new archive. Archive can be created using serde either.
    let yaml = r##"
        ~path:
            ~to:
                ~my:
                    ~group:
                        alias: 3.14
                        array_init:
                        - 1
                        - 145
                        int_field: 3 # If there's no change, it won't be updated.
                                        # This behavior can be overridden by import options.
                        env_var: 59
                        one_of_field: "hello" # This is not in the 'one_of' list...
    "##;

    let archive: config_it::Archive = serde_yaml::from_str(yaml).unwrap();
    storage.import(archive, Default::default()).await.unwrap();
    storage.fence().await; // Since import operation is asynchronous, you must fence
                            // to make sure all changes are applied.

    // Now, let's check if the changes are applied.
    assert!(group.update() == true);

    // Data update is regardless of the individual properties' dirty flag control.
    // Data is modified only when `group.update()` is called.
    assert!(group.non_alias == 3.14); // That was aliased property
    assert!(group.array_init == [1, 145]);
    assert!(group.env_var == 59);
    assert!(group.int_field == 3); // No change
    assert!(group.one_of_field == "default"); // Not in the 'one_of' list. no change.

    // Only updated properties' dirty flag will be set.
    assert!(true == group.check_elem_update(&group.non_alias));
    assert!(true == group.check_elem_update(&group.array_init));
    assert!(true == group.check_elem_update(&group.env_var));

    // Since this property had no change, dirty flag was not set.
    assert!(false == group.check_elem_update(&group.int_field));

    // Since this property was not in the 'one_of' list, it was ignored.
    assert!(false == group.check_elem_update(&group.one_of_field));

    // These were simply not in the list.
    assert!(false == group.check_elem_update(&group.c_string_type));
    assert!(false == group.check_elem_update(&group.no_imp_exp));
    assert!(false == group.check_elem_update(&group.no_imp_exp_2));
    assert!(false == group.check_elem_update(&group.string_field));

    // 5. Other features

    // 5.1. Watch update
    // When group is possible to updated, you can be notified
    // through asynchronous channel. This is useful when you
    // want to immediately response to any configuration updates.
    let mut monitor = group.watch_update();
    assert!(false == monitor.try_recv().is_ok());

    let archive: config_it::Archive = serde_yaml::from_str(yaml).unwrap();
    storage
        .import(
            archive,
            config_it::ImportOptions {
                apply_as_patch: false, // This will force all properties to be updated.
                ..Default::default()
            },
        )
        .await
        .unwrap();

    assert!(true == monitor.recv().await.is_ok());
    assert!(group.update());

    // 5.2. Commit
    // Any property value changes on group is usually local,
    // however, if you want to
    // archive those changes, you can commit it.
    group.int_field = 15111; // This does not affected by
                                // constraint and visible from export,
                                // however, in next time you import
                                // it from exported archive,
                                // its constraint will be applied.

    // If you set the second boolean parameter 'true', it will
    // be notified to 'monitor'
    group.commit_elem(&group.int_field, false);
    let archive = storage.export(Default::default()).await.unwrap();

    assert!(
        archive.find_path(path.iter().map(|x| *x)).unwrap().values["int_field"]
            .as_i64()
            .unwrap()
            == 15111
    );

    // As the maximum value of 'int_field' is 5, in next import, it will be 5.
    storage
        .import(
            archive,
            config_it::ImportOptions {
                // Since we create patch from archive content ...
                // Need to forcibly invalidate all
                apply_as_patch: false,
                ..Default::default()
            },
        )
        .await
        .unwrap();
    storage.fence().await;

    assert!(group.update());
    assert!(group.int_field == 5);

    // 5.3. Monitor
    //
    // All events to update storage can be monitored though
    // this channel.
    //
    // As this is advanced topic, and currently its design
    // is not finalized, just give a look for fun and don't
    // use it in production.
    let _ch = storage.monitor_open_replication_channel().await;
});