Improve usage examples

[dzvancuks]

Please improve usage examples. Current Readme is hard to understand.

A good usage examples would be small application snippets with all imports and results are visible. I.e. see
https://github.com/nats-io/go-nats-examples/tree/main/api-examples
https://github.com/gnet-io/gnet-examples

[oktalz]

@dzvancuks thx for suggestion,
i do think that adding more to readme would bring confusion.

Current Readme is hard to understand.

in case of existing README,
can you tell me what is hard to understand there ?
additional info is valued, we certainly may see things differently.

it has good basic info how you can setup all parts (with required imports)

usage is quite good covered in tests, there you can see for every resource, how to create/update/read etc....
like for example for backends

copying tests to specific main.go examples would not suffice (we would be just duplicating or even worse simplify solutions), you still need specific configuration and HAProxy paths and both, especially configuration is specific to each user.

that would not bring much more that just examining test cases

[dzvancuks]

@oktalz My intentions were to do following scenario:

1. open API socket (currently only unix is supported, but it's ok)
2. using CreateFrontend and CreateBackend functions dynamically add configuration

I've managed to create socket, connect to it via runtime and that is it. What to do next? How configuration is related with runtime? Is it even possible to achieve my scenario? What other options this client provides?

Having examples would be beneficial to see what client is capable of and how to do all of that.

[shadyabhi]

@dzvancuks +1 to your thought, in isolation, it is difficult to understand how to use this package.

However, it is also nice that this another project uses it extensively, so it really helps going through that source code.
https://github.com/haproxytech/dataplaneapi

[oktalz]

yes, sry,
this issue slipped and it was not answered.

in general you have two parts, configuration one and runtime one, and they are complexly independent.
file changes are not directly applied on runtime and vice versa.
This allows you to have one pretty used pattern where you could, for example temporarily disable server on runtime (to put it it maintenance state), but with not touching configuration file, there is low chance you would leave is disabled permanently.

so runtime and actual state written in configuration file is handled separately.

list of all things you can do through runtime is available through here:

client-native/runtime/interface.go

Line 139 in 31a9d2d

type Runtime interface {

since its interface based (that might change in future)

we could autogenerate documentation, but that imho would not bring much to the table, all functions are commented (mostly), or have meaningful names with params that are self explanatory

what is missing though is, as it was said here, is maybe just an explanation how one side impact (or not) other, so a bit of a explanation why we have configuration part and runtime part (and why are they different)

client native does not have many tests/examples to use with runtime, most of the testing and examples we have done in dataplaneapi project that uses it (+ kubernetes ingress controller one).
to answer additional questions, yes, we should do them here too, since this can be used independently.

I'll add a label to this.