operator-rs

The stackable-versioned crate allows you to declare multiple versions for a struct (and eventually enums) using the #[versioned] attribute macro. This is primarily used to support Kubernetes API versioning by declaring a sequence of version names on a single data type.

You can also annotate individual fields within the struct to track their lifecycle, including when they were added, when they changed (including name changes), or when they were deprecated.

use stackable_versioned::versioned;

#[versioned(
    version(name = "v1alpha1"),
    version(name = "v1beta1"),
    version(name = "v1"),
    version(name = "v2"),
    version(name = "v3")
)]
struct Foo {
    /// My docs
    #[versioned(
        added(since = "v1alpha1"),
        changed(since = "v1beta1", from_name = "gau"),
        deprecated(since = "v2", note = "not required anymore")
    )]
    deprecated_bar: usize,
    baz: bool,
}

The config-utils utility supports templating to fill configuration files with values from environment variables or external files. This process involves replacing placeholders in your configuration with actual data, while automatically applying the appropriate escaping for the file format (e.g., XML escaping).

Placeholder Syntax

• Environment Variables: Use ${env:VARIABLE_NAME} to inject the value of an environment variable.
• Files: Use ${file:ENCODING:PATH} to inject the contents of a file. For example, ${file:UTF-8:example-password} reads the file example-password using UTF-8 encoding.
• Nested Templating: You can nest placeholders. For example, ${env:${env:ENV_TEST_PASSWORD_ENV_NAME}} allows the name of the environment variable to be determined by another environment variable.

Supported Formats

config-utils automatically detects the file type based on the extension, but you can also specify it manually via CLI arguments. Currently supported formats are:

• .properties files
• XML files

# Example setup
export EXAMPLE_USERNAME=my-user
echo 'example-password <123>!' > example-password

# Create a template file
cat > example.xml << 'EOF'
<credentials>
  <username>${env:EXAMPLE_USERNAME}</username>
  <password>${file:UTF-8:example-password}</password>
</credentials>
EOF

# Run templating
config-utils template example.xml

When using the stackable-versioned macros, you can manage the lifecycle of struct fields or enum variants using versioned attributes. These attributes allow you to track when an item was added, when its name or type changed, and when it was deprecated.

Supported Actions

1. added: Marks the version in which the field or variant was introduced.

   • since: The version when it was added.
   • default_fn: (Optional) The path to a function used to provide a default value for this item. Defaults to ::std::default::Default::default.

2. changed: Marks a modification to an existing item.

   • since: The version when the change occurred.
   • from_name: (Optional) The previous name of the item. This must not include the deprecation prefix.
   • from_type: (Optional) The previous type of the item. If provided, you can use upgrade_with and downgrade_with.
   • upgrade_with: (Optional) A path to a function used to upgrade the value from the old type to the new type. Only valid if from_type is set.
   • downgrade_with: (Optional) A path to a function used to downgrade the value from the new type to the old type. Only valid if from_type is set.

3. deprecated: Marks the version in which the item should no longer be used.

   • since: The version when it was deprecated.
   • note: (Optional) A descriptive note about the deprecation.
   • Requirement: When an item is marked as deprecated, its name must include the configured deprecation prefix.

Usage Rules

• Chronology: added < changed < deprecated.
• Exclusivity: You cannot use added and deprecated (or added and changed) in the same version.
• Naming: If an item is deprecated, it must use the deprecation prefix. If it is not deprecated, it must not use the prefix.
• No direct #[deprecated]: Do not use the standard Rust #[deprecated] attribute on items. Instead, use the macro-provided #[versioned(deprecated(since = "..."))] syntax.

// Example of versioning a field
struct MyStruct {
    #[versioned(added(since = "0.1.0"))]
    new_field: String,

    #[versioned(changed(since = "0.2.0", from_name = "old_field", from_type = "u32"))]
    current_field: String,

    #[versioned(deprecated(since = "0.3.0", note = "Use current_field instead"))]
    deprecated_field_name: String,
}

The stackable-versioned-macros crate provides a mechanism for versioning multiple containers (structs or enums) simultaneously within a single module block. This allows developers to manage multiple API versions (e.g., v1alpha1, v1) without creating conflicting definitions.

Core Concepts

• Versioned Modules: A macro-driven module block that contains definitions for different versions of the same data structures.
• Containers: The actual data structures (structs or enums) that are versioned. The macro identifies these within the module block and generates version-specific implementations.
• Submodules: Used to manage imports or re-exports for specific versions. Submodules must be defined as mod blocks within the versioned module and can only contain use statements.
• Preserving the Module: By default, the macro may erase the wrapping module. However, if the preserve_module option is enabled, the macro generates a public module that wraps the versioned submodules, making them accessible via the original module name.

Constraints

• Submodule Naming: Submodule names must match the names defined in the version attributes.
• Submodule Content: Submodules are restricted to use statements only. Any other items (structs, functions, etc.) inside a submodule will trigger a compilation error.
• Disallowed Items: Any items placed inside the versioned module that are not recognized as containers (structs/enums) or submodules (mod blocks with use statements) are disallowed and must be moved outside the macro block.