Autoschematic

Each connector, like a Terraform provider, forms an adapter to some specific remote API or service. The config file autoschematic.ron is used to specify which connectors are enabled in an Autoschematic repository. A connector is always instantiated under some prefix; a prefix is just a top-level folder used to organize connectors & their resource & output files, whether by environment, team, or any other division within a repo.

autoschematic.ron

AutoschematicConfig(
    prefixes: {
        "main": Prefix(
            connectors: [
                Connector(
                    shortname: "dummy",
                    spec: CargoLocal(
                        // Absolute and relative paths are supported.
                        // path: "/home/chef/prog/ottercorp-connector-mything",
                        path: "./",
                    ),
                    env_file: ".env",
                ),
                Connector(
                    shortname: "aws/s3",
                    env: {
                        "KEY": "value",
                        "SOMETHING": "else",
                    },
                    [...]
                ),
                Connector(
                    shortname: "k8s",
                    [...]
                )
            ]
        ),
        "offices/singapore": Prefix(
            [...]
        ),
        "offices/taipei": Prefix(
            [...]
        ),
    }
)

To be precise, an Autoschematic connector is any executable that implements the autoschematic_core::connector::Connector protocol over gRPC or tarpc, with a particular argument convention.

To get started with building your own Autoschematic connector in Rust, you can first clone autoschematic-sh/autoschematic-connector-template

By starting from the template, you can implement this protocol with some straightforward boilerplate, and hopefully end up with a usable connector for your target API or service.

You'll first want to rename the package in Cargo.toml and rename DummyConnector everywhere to something appropriate. Then, you'll want to think about the data you'll store in your core connector struct, and begin with initialization.

The S3Connector is a typical Connector struct: it stores its prefix, a per-region cache of client objects, and a config object as loaded from some config file.

#[derive(Default)]
pub struct S3Connector {
    prefix: PathBuf,
    client_cache: Mutex<HashMap<String, Arc<aws_sdk_s3::Client>>>,
    config: Mutex<S3ConnectorConfig>,
}

impl Connector for S3Connector {
    async fn new(name: &str, prefix: &Path, outbox: ConnectorOutbox) -> Result<Arc<dyn Connector>, anyhow::Error>
    where
        Self: Sized,
    {
        Ok(Arc::new(S3Connector {
            prefix: prefix.into(),
            ..Default::default()
        }))
    }

    async fn init(&self) -> anyhow::Result<()> {
        let config: S3ConnectorConfig = S3ConnectorConfig::try_load(&self.prefix)?.unwrap_or_default();

        *self.config.lock().await = config;
        Ok(())
    }
    [...]
}

Rules that matter early:

• Connector::new(prefix) should just do basic initialization, and not do any config validation or longer setup. Connector::new(prefix) should basically never fail.
• Connector::init() is where you read config, validate credentials etc, and build e.g. client or session objects for later use. Validation or config errors should be raised in Connector::init() and not Connector::new(prefix)
• Connector methods receive repo-relative addresses like aws/s3/us-east-1/buckets/main.ron, not {prefix}/aws/...: save prefix on the connector if you need it to load config files in init().

Reference files:

• autoschematic-connector-aws/s3/src/connector.rs

• autoschematic-connector-github/src/connector.rs

• autoschematic-connector-k8s/src/connector.rs

• autoschematic-connector-aws/vpc/src/connector.rs

Next: Designing the Address Space