Consider alternative formats for documenting config parameters about quilkin HOT 6 CLOSED

By alternative formats are we considering other data formats or just different schemas? If we're considering alternative data formats TOML is quite nice for avoiding rightward drift. I've pasted what the schema linked to in the original comment could look like if it was TOML. Obviously TOML is a less powerful format than YAML with references and such, but personally I find complex TOML much easier than complex YAML.

type = "object"
required = ["version"]

[properties.version]
type = "string"
description = "The configuration file version to use."
enum = ["v1alpha1"]

[properties.proxy]
type = "object"
description = "Configuration of core proxy behavior."

[properties.proxy.properties]
type = "string"
description = "The mode in which the proxy should run."
enum = ["SERVER", "CLIENT"]
default = "SERVER"
id = { type = "string", default = "<uuid> A unique ID is generated for the proxy.", description = "An identifier for the proxy instance." }
port = { type = "integer", default = 7_000, description = "The listening port for the proxy." }

[properties.admin]
type = "object"
description = "Configuration of operational proxy behavior."

[properties.admin.properties]
type = "object"
description = "Metrics related configuration."
port = { type = "integer", description = "Port on which to expose metrics.", default = 9_091 }
static = { type = "object", description = "Static configuration of endpoints and filters.", required = [ "endpoints" ], }
filter = { type = "array", description = "A filter chain.", items = [] }
endpoints = { type = "array", description = "A list of upstream endpoints to forward packets to." }

from quilkin.

Maybe https://docs.microsoft.com/en-us/azure/devops/pipelines/yaml-schema?view=azure-devops&tabs=schema%2Cparameter-schema#job might be a better alternative? it's not as precise but its simpler to read at least. Or something else?

One thing I do like about the above format is that the structure mimics what the actual implementation looks like. So it's easier to flow from one to another.

Meta question:

Is the issue the format, or is the issue that we aren't breaking apart the reference into manageable chunks that can be digested individually (maybe via headers, or seperate pages)? I would posit that no matter what format we choose, as over time the configuration options expand, the singular reference page for configuration is going to be a struggle to process a single unit.

from quilkin.

Hmm yeah, thinking on this for the schema itself, I think we'd be better off just documenting it through our Rust API docs, as I think it explains (or should explain) all of these parameters.

from quilkin.

Hmm yeah, thinking on this for the schema itself, I think we'd be better off just documenting it through our Rust API docs, as I think it explains (or should explain) all of these parameters.

I think that could make a lot of sense actually yes. And we'd have it documented all in one place too

from quilkin.

I like this idea too! Sounds like something we can transition to once we have our release out.

from quilkin.

I think we're sufficiently documenting the configuration in enough different ways, both in JSON schema and in the Rust documentation, so I'm going to close this.

from quilkin.