From 7207661eeb4bef7de073ae75eb345366fe6924e7 Mon Sep 17 00:00:00 2001 From: Taylor Thomas Date: Fri, 12 Jan 2024 14:46:49 -0700 Subject: [PATCH] feat(*): Adds initial config interface implementation (#4) This is the most basic functionality needed to have a shared config interface that all components could use. It's goal is simplicity. There are many things we could add/polish, and all of those are called out in the documentation. For reference, this is what we are using in wasmCloud, but we aren't married to the interface as is. What we want is the ability for any runtime to be able to provide configuration to the components it is running in a standardized way. That will make it possible to actually have the cross runtime/platform experience that components promise Signed-off-by: Taylor Thomas --- README.md | 17 +++++++++++------ config.md | 41 ++++++++++++++++++++++++++++++++++++++++ proposal-template.abi.md | 31 ------------------------------ proposal-template.wit.md | 32 ------------------------------- test/README.md | 11 ----------- wit/runtime_config.wit | 16 ++++++++++++++++ 6 files changed, 68 insertions(+), 80 deletions(-) create mode 100644 config.md delete mode 100644 proposal-template.abi.md delete mode 100644 proposal-template.wit.md delete mode 100644 test/README.md create mode 100644 wit/runtime_config.wit diff --git a/README.md b/README.md index 3c25a4a..03fe932 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,8 @@ A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) A ### Phase 4 Advancement Criteria -`wasi-runtime-config` should have at least two implementations (i.e., from service providers, and or cloud providers), and, at the very minimum, pass the testsuite for Windows, Linux, and MacOS. +`wasi-runtime-config` should have at least two implementations (i.e., from service providers, and or +cloud providers), and, at the very minimum, pass the testsuite for Windows, Linux, and MacOS. ## Table of Contents @@ -22,14 +23,18 @@ A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) A ### Introduction -The `wasi-runtime-config` world aim to provide a set of generic interfaces for dynamic configuration management systems. They are often the source of the configuration truth that lives in external services. Configuration values are often polled by the application for +The `wasi-runtime-config` world aim to provide a set of generic interfaces for providing +configuration to a component. Configuration values are often polled by the application for -1. toggling on/off feature flags -2. A/B testing -3. reading user allow/deny lists +1. Configuring the runtime behavior of a component. Yes, that sounds generic, but applications do + all sorts of crazy things with configuration values! Calling entirely different branches of code, + setting upstream URLs or services, configuring the number of threads to use, etc. +2. toggling on/off feature flags +3. A/B testing and many more use cases. ### TODO -This readme needs to be expanded to cover a number of additional fields suggested in the [WASI Proposal template](https://github.com/WebAssembly/wasi-proposal-template). +This readme needs to be expanded to cover a number of additional fields suggested in the [WASI +Proposal template](https://github.com/WebAssembly/wasi-proposal-template). diff --git a/config.md b/config.md new file mode 100644 index 0000000..23d3b5f --- /dev/null +++ b/config.md @@ -0,0 +1,41 @@ +# Runtime Config API + +## Runtime Types + +### `variant config-error` + +An error type that encapsulates the different errors that can occur fetching config: + +- `upstream(string)`: This indicates an error from an "upstream" config source. As this could be almost _anything_ (such as Vault, Kubernetes ConfigMaps, KeyValue buckets, etc), the error message is a string. +- `io(string)`: This indicates an error from an I/O operation. As this could be almost _anything_ (such as a file read, network connection, etc), the error message is a string. Depending on how this ends up being consumed, we may consider moving this to use the `wasi:io/error` type instead. For simplicity right now in supporting multiple implementations, it is being left as a string. + + +## Runtime Functions + +## `get` + +Gets a single opaque config value set at the given key if it exists + +**Params:** + +- `key`: A string key to fetch + +**Returns:** + +`result>, config-error>` + +An opaque value if the key exists, otherwise `none` + +## `get-all` + +Gets all available configuration values + +**Params:** + +None + +**Returns:** + +`result>>, config-error>` + +A list of key/value tuples diff --git a/proposal-template.abi.md b/proposal-template.abi.md deleted file mode 100644 index 7a1c372..0000000 --- a/proposal-template.abi.md +++ /dev/null @@ -1,31 +0,0 @@ -# Types - -## `api-type-one`: record - - Short description - - Explanation for developers using the API. - -Size: 16, Alignment: 8 - -### Record Fields - -- [`property1`](#api_type_one.property1): `u64` - - -- [`property2`](#api_type_one.property2): `string` - - -# Functions - ----- - -#### `api-function-one` - - Short description - - Explanation for developers using the API. -##### Results - -- [`api-type-one`](#api_type_one) - diff --git a/proposal-template.wit.md b/proposal-template.wit.md deleted file mode 100644 index 3c7e8ef..0000000 --- a/proposal-template.wit.md +++ /dev/null @@ -1,32 +0,0 @@ -# [Proposal Template] API - -[This document contains the actual specification. It should be written in the WIT interface definition format. You can find more documentation on the WIT syntax (coming soon!).] - -[Note that all comments inside of WIT code blocks will be included in the developer facing documentation for language bindings generated using this WIT file. If there is additional information that needs to be communicated to implementers of the API, then these should be captured in text directly below the code block.] - -[If you want to include examples of the API in use, these should be in the README and linked to from this file.] - -## api_type_one - -```wit -/// Short description -/// -/// Explanation for developers using the API. -record api-type-one { - property1: u64, - property2: string, -} -``` - -More rigorous specification details for the implementer go here, if needed. - -## api_function_one - -```wit -/// Short description -/// -/// Explanation for developers using the API. -api-function-one: func() -> api-type-one -``` - -If needed, this would explain what a compliant implementation MUST do, such as never returning an earlier result from a later call. diff --git a/test/README.md b/test/README.md deleted file mode 100644 index c274acd..0000000 --- a/test/README.md +++ /dev/null @@ -1,11 +0,0 @@ -# Testing guidelines - -TK fill in testing guidelines - -## Installing the tools - -TK fill in instructions - -## Running the tests - -TK fill in instructions diff --git a/wit/runtime_config.wit b/wit/runtime_config.wit new file mode 100644 index 0000000..020c072 --- /dev/null +++ b/wit/runtime_config.wit @@ -0,0 +1,16 @@ +package wasi:config@0.1.0; + +interface runtime { + /// Errors that can be returned from config sources + variant config-error { + /// An error occurred on the config source when fetching data + upstream(string), + /// I/O or connection failure when fetching data + io(string), + }; + + /// Gets a single opaque config value set at the given key if it exists + get: func(key: string) -> result>, config-error>; + /// Gets a list of all set config data + get-all: func() -> result>>, config-error>; +}