[Doc] Provide simple examples with doc hints

JosiahParry commented 2 weeks ago

What is the problem your feature solves, or the need it fulfills?

I am unable to get started using pingora due to a dearth of documentation. The /docs/user_guide are great conceptual docs, however they do not help a user actually get started with the crate.

For example, trying to adapt the load balancer quick start example to use local paths e.g.

let upstreams = LoadBalancer::try_from_iter(["127.0.0.1:9000", "127.0.0.1:9001"]).unwrap();

results in a 502 error. The quick start doesn't have any pointers on how you might adapt the examaple to your own needs.

The examples do not have any comments so they're not very helpful in that you have to know what they're doing in order for them to be useful. Sort of a chicken and an egg situation.

Describe the solution you'd like

It would be great if the quick starts and user guides described how to build incrementally more complex services. I am actually blown away by the quality of the conceptual doc (e.g. the flow charts) but they don't connect to the crate.

For example the internals doc is another great example of a brilliant conceptual doc that doesn't connect to the crate's syntax.

Describe alternatives you've considered

Read the user_guide. Try and adapt examples.

Additional context

N/A

drcaramelsyrup commented 1 week ago

For example, trying to adapt the load balancer quick start example to use local paths... results in a 502 error.

Just trying to get a sense of what would be most helpful. Are you looking for pointers on how to debug such issues? and/or comments that explain more about what each line or API call is doing?

kingsmen47 commented 2 days ago

Were you able to overcome that specific issue mentioned above?I am currently stuck at it and I am not able to understand what's the issue here.

JosiahParry commented 2 days ago

Yes i was. In this case the example is creating a reverse proxy to two locations that require TLS.

A very simple example and possibly a common use case is trying to proxy to an internal service that is served over localhost or 127.0.0.1. To access this the SNI (still not sure what that is lol!) is not necessary and most importantly in the example the argument that is set to true should be set to false.

One thing that could help would be to provide the argument names in the examples. I know they show up in the Rust analyzer but since these examples are dependent upon the workspace and thus not actually reproducible by new users using pingora from crates.io any hints are helpful.

I would suggest having a series of simple use cases (with commentary—this is key) to help people. Ideally, these are not park of the pingora workspace.

Some of the things I've been stuck on and have gotten help with either by making my own issue or searching others are:

Proxying to a local service (https://github.com/cloudflare/pingora/issues/288)
Counting active connections using a DashMap and a CTX (https://github.com/cloudflare/pingora/issues/295)
spawning new connections by creating my own faux-loadbalancer (https://github.com/cloudflare/pingora/issues/291)

cloudflare / pingora