Autoschematic

Skeletons, Docs, and Validation

get_skeletons() gives users ready-made example resources. For example, the S3 connector returns a bucket skeleton with placeholder path parts:

res.push(skeleton!(
    S3ResourceAddress::Bucket {
        region: String::from("[region]"),
        name: String::from("[bucket_name]"),
    },
    resource::S3Resource::Bucket(resource::S3Bucket {
        policy: Some(policy_ron_value),
        public_access_block: Some(resource::PublicAccessBlock {
            block_public_acls: true,
            ignore_public_acls: true,
            block_public_policy: true,
            restrict_public_buckets: true,
        }),
        acl: None,
        tags: Tags::default(),
    })
));

get_docstring() allows you to export Rust docstrings from your resource structs to the LSP server (for example, via the vscode extension) with a simple proc macro. For example, in the GithubConnector:

#[derive(Debug, Serialize, Deserialize, PartialEq, Documented, DocumentedFields, FieldTypes)]
#[serde(default, deny_unknown_fields)]
/// A GitHub repository with its configuration settings
pub struct GitHubRepository {
    /// A short description of the repository
    pub description: Option<String>,
    /// A URL with more information about the repository
    pub homepage: Option<String>,
    /// An array of topics to help categorize the repository
    pub topics: Vec<String>,
    /// Whether the repository is private. If false, the repository is public
    pub private: bool,
    [...]
}
// GitHubConnectorConfig, GitHubRepository, BranchProtection are similarly documented and derived...

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, Hash, Documented, DocumentedFields)]
/// A principal that can be granted collaborator access to a repository
pub enum CollaboratorPrincipal {
    /// A GitHub user account by username
    User(String),
    /// A GitHub team by slug/name
    Team(String),
}

async fn get_docstring(&self, _addr: &Path, ident: DocIdent) -> Result<Option<GetDocResponse>, anyhow::Error> {
    doc_dispatch!(
        ident,
        [GitHubConnectorConfig, GitHubRepository, BranchProtection],
        [CollaboratorPrincipal::User(String::new()), CollaboratorPrincipal::Team(String::new())]
    )
}

Connector::eq() compares two resource bodies to determine if they're equivalent. Connector::diag() is where you can provide human-readable parsing errors for your connector's custom resources.

eq() and diag() also have some easy utility functions if you're using RON. Use RON!


    async fn eq(&self, addr: &Path, a: &[u8], b: &[u8]) -> anyhow::Result<bool> {
        let addr = GitHubResourceAddress::from_path(addr)?;

        match addr {
            GitHubResourceAddress::Config => ron_check_eq::<GitHubConnectorConfig>(a, b),
            GitHubResourceAddress::Repository { .. } => ron_check_eq::<resource::GitHubRepository>(a, b),
            GitHubResourceAddress::BranchProtection { .. } => ron_check_eq::<resource::BranchProtection>(a, b),
        }
    }

    async fn diag(&self, addr: &Path, a: &[u8]) -> Result<Option<DiagnosticResponse>, anyhow::Error> {
        let addr = GitHubResourceAddress::from_path(addr)?;

        match addr {
            GitHubResourceAddress::Config => ron_check_syntax::<GitHubConnectorConfig>(a),
            GitHubResourceAddress::Repository { .. } => ron_check_syntax::<resource::GitHubRepository>(a),
            GitHubResourceAddress::BranchProtection { .. } => ron_check_syntax::<resource::BranchProtection>(a),
        }
    }

Reference files:

Autoschematic

A Starter Template

Designing the Address Space

Resource Bodies and filter()

Read Methods (get, list, and subpaths)

Planning and Executing Connector Ops

Outputs and Virtual Addresses

Skeletons, Docs, and Validation

Skeletons, Docs, and Validation