[RFC] wasmCloud.toml

[mattwilkinsonn]

Is your feature request related to a problem? Please describe.

Currently the wasmCloud development process uses Makefiles to compile and sign actors. This is split into a "compiler" makefile (actor.mk) the project's Makefile (example), which is basically a config file in a trenchcoat.

Describe the solution you'd like

Create a wasmCloud specific configuration file,wasmcloud.toml to replace the current project Makefiles. This should be usable for actors, interfaces, and providers. This file will be consumed by wash to compile and sign the actor using wash build (see #263).

Describe alternatives you've considered

Remaining with current Makefile setup

Makefiles are tricky for Windows developers, and are not really intended as configuration files. The developer experience is not ideal with the current setup.

Using the language's configuration file (Cargo.toml, go.mod, etc)

This carries some advantages in terms of DX, as we're reducing the number of configuration files a developer needs to manage. However this could become a constraint as we add more language support to wasmCloud, if those languages don't support the features we need in their configuration file.

However, we could allow parameters to be optional in the wasmcloud.toml file, and attempt to parse them out of the language's file if they are missing. This would reduce duplication. For example, the actor's name and version number could be stored only in the language file and parsed out, as opposed to being stored in both files and the developer needing to update them in two places on each change.

Additional context

Issue #263 (wash build) has some more context on this, and these two features are pretty intertwined.

[mattwilkinsonn]

Here's my initial stab at the fields for this file, using the Makefiles in the examples repo as a reference. This WIP, I'm just throwing everything into a comment and will edit it later.

For all configurations:

• language: enum "rust" | "tinygo", more to be added as we expand.
• type: enum "actor" | "provider" | "interface"
• name: optional string, if not provided will attempt to infer from language's config file (Cargo.toml etc)
• version: optional string, should be semver. Same as name, will attempt to infer from language's config file if not provided.

For actors:

• claims: optional array of strings.
• registry: optional string url to the registry, if not provided will ask for it on each command that it is needed.
• push_insecure: optional boolean, default false.
• revision: required int. However I'd like to explore getting rid of this if possible, could someone shine light on why we need it instead of just using the version number?
• actor_name: optional string, but can't we just use the name field?
• key_directory: optional string with path to private key folder.
• filename: optional string with compiled filename. defaults to {project name}_s.wasm
• wasm: optional string of the wasm target type. defaults to wasm32-unknown-unknown

rust actor specific:

• cargo: optional string with path to cargo binary.
• target: optional string. location of cargo build target folder. defaults to ./target

For providers:

• capability_id: required string.
• vendor: possibly optional string? Not sure if this is required or not.

[brooksmtownsend]

A couple of comments here, but it overall looks like a great initial pass

version: optional string, should be semver. big nit, but we don't actually enforce semver and people can version these however we like

revision: required int. However I'd like to explore getting rid of this if possible, could someone shine light on why we need it instead of just using the version number?

The reason for revision is to support hot-upgrades, we want people to be able to quickly patch and upgrade actors in place without changing semver, e.g. to hotfix an issue. We could always explore this option more though, @autodidaddict may have more comments

Under rust actor specific I think we should also add "test_target" as an optional which we can use to run tests, defaults to the target triplet of the host

vendor: possibly optional string? Not sure if this is required or not.

This is required, organizations can use this (we do for wasmCloud and Cosmonic) but we could default this to, say, the username of the person on their machine or just "NoVendor"

[mattwilkinsonn]

The reason for revision is to support hot-upgrades, we want people to be able to quickly patch and upgrade actors in place without changing semver, e.g. to hotfix an issue. We could always explore this option more though, @autodidaddict may have more comments

IMO we should definitely revisit this. I think it would cause confusion for most users coming into the ecosystem. More philosophically, shouldn't a hotfix be a patch number increase in semver anyway?

At the very least i'd like to experiment with it being optional and defaulting to 0 or 1. Or could we sign the actor with a date & time to act as a tiebreaker if needed?

Under rust actor specific I think we should also add "test_target" as an optional which we can use to run tests, defaults to the target triplet of the host

Sounds good!

vendor: possibly optional string? Not sure if this is required or not.

This is required, organizations can use this (we do for wasmCloud and Cosmonic) but we could default this to, say, the username of the person on their machine or just "NoVendor"

Yeah, a default sounds reasonable here.

Thanks for the feedback @brooksmtownsend ! I’ll keep digging into this next week.

[brooksmtownsend]

Thanks for this proposal Matt! This is great stuff 😄

[mattwilkinsonn]

Started working on this at https://github.com/mattwilkinsonn/wasmcloud-config. Making it it's own crate as it could be used outside of wash.

[brooksmtownsend]

Great, we may end up dropping it under a crates/ directory here if it's primarily used in wash as that's likely where some other functionality will end up moving to as well but starting in another repository is fine 👍🏻

[mattwilkinsonn]

Closing this as it was implemented in #297.