Components

[PascalSenn]

The following section represent the part in the README and is up for dicussion

Components

In Confix, "components" are a key construct designed to streamline shared code usage. A typical use case involves shared packages that contain reusable code, such as a logging module that's frequently used across multiple applications or (micro)services.

Each component in Confix defines its own schema. This schema acts as a blueprint for configuration validation, ensuring that the configuration matches the predefined structure.

The schema of a component is a JSON schema. Don't worry about having to write this yourself - Confix is designed to simplify schema creation for developers. Confix provides a variety of schema compilers that can generate a schema based on your code. For example, the GraphQL compiler generates a schema based on a GraphQL file, while the .NET annotations compiler produces a schema derived from the configuration.

Creating a new component in Confix is as simple as running the command confix component create <componentName>. This command generates a new .confix.component file which is then stored in ./components/<componentName>. This file contains the component's configuration, including the component's name, inputs, and outputs.

e.g.

{
  "name": "Logging",
  "inputs": [
    {
      "type": "graphql"
      // additional properties specific to the graphql compiler
    }
  ],
  "outputs": [
    {
      "type": "dotnet-options-classes",
        // additional properties specific to the json output
    }
  ]
}

The inputs and outputs properties are optional. If you do not specify any inputs or outputs, Confix will use the default inputs that are defined in the .confixrc or the .confix.project file.

File Structure

All components are saved in the Components folder, situated at the root of your project. Each .confix.component file is a JSON file that encapsulates the details of the component's configuration. This file must contain a 'name' property specifying the component's name.

myProject
├── Components
│   ├── Logging
│   │   ├── .confix.component
│   │   ├── schema.json
│   │   └── schema.graphql
│   └── DistributedCache
│       ├── .confix.component
│       ├── schema.json
│       └── schema.graphql
├── ...

Package Distribution

Confix has different methods for distributing packages. The most common method is to bundle the schema with the package itself. When you distribute your package, whether through NuGet, NPM, or Azure DevOps, the corresponding schema is included within the package itself. This practice automatically versions your component schema together with your code. For example, when you reference version 1.20.4 of your package, you also obtain the matching version of the schema.

Additional distribution methods will be elaborated upon in the 'Distributing Components' section of this documentation.

Component Inputs and Outputs

A Confix component can have one or multiple 'inputs'. These inputs function as schema compilers, which create new schema.json files or update existing ones based on the input provided. Inputs are executed in the sequence they are defined in the .confix.component file.

Examples of inputs are the GraphQL compiler, which generates a JSON schema based on a GraphQL file, and the .NET annotations compiler, which produces a schema derived from the configuration.

In addition to inputs, a component can also have one or multiple outputs. These outputs are generated from the finalized schema.json file. By default, Confix searches for a .confix.component file in the shipped bundle to locate the schema.json file, which is then used as the JSON schema for configuration.

Commands

Several commands are available for managing components in Confix:

• To create a new component, use: confix component create <componentName>
• To build a component, use: confix component build <componentName>
• To list all existing components, use: confix component list
• To delete a component, use: confix component delete <componentName>

These commands provide a user-friendly way to manage and interact with your Confix components effectively.

[PascalSenn]

Proposal: Pipeline Instead of Separate Inputs and Outputs

Currently, Confix uses a two-stage process with inputs processed first, followed by outputs. This structure behaves somewhat like a pipeline, sequentially processing tasks in a predefined order. To enhance flexibility, we could reconfigure this into a single 'pipeline' property that determines the execution sequence.

While a single pipeline could increase configuration complexity, it offers more control over the transformation and processing of schemas.

For instance, after a GraphQL schema has been compiled, you might want to cleanse it and then generate a new schema based on the cleansed version. A pipeline setup would make such processes straightforward.

Here's an illustrative example of what a pipeline configuration might look like:

{
  "name": "Logging",
  "pipeline": [
    {
      "type": "graphql-compiler",  // Initial schema generation from GraphQL
    },
    {
      "type": "dotnet-generator",  // Generate C# classes from the schema
    },
    {
      "type": "schema-cleaner",  // Clean the schema removing unnecessary details
    },
    {
      "type": "dotnet-schema-compiler",  // Compile a new schema.json based on the cleaned schema
    },
    {
      "type": "dotnet-config-doc-generator"  // Generate documentation based on the final schema
    }
  ]
}

In this example, each step of the pipeline is defined by a type. These types specify what operation to perform on the schema or the resulting data, moving through compiling, cleaning, and finally, documentation generation.

Despite the benefits of a single pipeline structure, one trade-off to consider is the increase in complexity when adjusting the configuration. For instance, if you only want to modify a project's output - say, to generate additional JavaScript code - you'd need to override the entire pipeline instead of simply adding a new output. This requirement might add an extra layer of complexity to managing your project's configuration. Therefore, it's essential to weigh the flexibility benefits against potential configuration challenges when considering a pipeline approach.

[TimHolzherr]

Why are Outputs needed?

From the description of components alone I dont get why Outputs are needed. I assume it is so that I can generate a C# file which represents the configuration of a component. But normally the consumer of a component does not need to interact with the configuration of that component in code but only to configure it in his json file. I would propose to either remove outputs or to motivate them better in the Components chapter.

[TimHolzherr]

File structure: Differentiating between Consumer and Producer of Components.

To my understanding components are a mechanism to define / create a configuration part in one project / repository in order to consume it in another project / repository. In the file structure chapter we should distinguish between the structure in the originating project from the one in the consuming project. I don't think the structure in the consumer and and the producer should be the same as the consumer should not care about how the json schema he consumes was created.