Improve lacking documentation

[NickUfer]

As a developer who wants to create filters using Proxy-WASM it is hard to understand the exact lifecycle of filters. It doesn't seem to be documented anywhere.

It would be great if this project had some page like Pingora's Life of a request which shows using a diagram the call tree of all methods:

 graph TD;
    start("new request")-->early_request_filter;
    early_request_filter-->request_filter;
    request_filter-->upstream_peer;

    upstream_peer-->Connect{{IO: connect to upstream}};

    Connect--connection success-->connected_to_upstream;
    Connect--connection failure-->fail_to_connect;

    connected_to_upstream-->upstream_request_filter;
    upstream_request_filter --> SendReq{{IO: send request to upstream}};
    SendReq-->RecvResp{{IO: read response from upstream}};
    RecvResp-->upstream_response_filter-->response_filter-->upstream_response_body_filter-->response_body_filter-->logging-->endreq("request done");

    fail_to_connect --can retry-->upstream_peer;
    fail_to_connect --can't retry-->fail_to_proxy--send error response-->logging;

    RecvResp--failure-->IOFailure;
    SendReq--failure-->IOFailure;
    error_while_proxy--can retry-->upstream_peer;
    error_while_proxy--can't retry-->fail_to_proxy;

    request_filter --send response-->logging


    Error>any response filter error]-->error_while_proxy
    IOFailure>IO error]-->error_while_proxy

Loading

[PiotrSikora]

Patches welcome? Although, it's not clear to me whether this repo or specific host implementations would be the best place for documenting this.

cc @kyessenov

[NickUfer]

Well, I would contribute, if I knew how the lifecycle looks like in the first place. I think before I figure it out through trial and error, someone with knowledge about it would be faster with solving that.

[martijneken]

Thanks for the idea! Some existing docs from the plugin/filter/extension author perspective, covering root and stream contexts:

• https://github.com/proxy-wasm/proxy-wasm-cpp-sdk/blob/main/docs/api_overview.md
• https://github.com/tetratelabs/proxy-wasm-go-sdk/blob/bf3aaeb4671acefad8012083a35fe66db820223f/doc/OVERVIEW.md

The host/proxy controls when a plugin/filter/extension is launched/evicted/restarted/etc so that may vary from deployment to deployment.