Confusing terms and concepts: "directives" and "phases"

[lfavreli]

Where is the problem?

https://docs.konghq.com/gateway/3.7.x/plugin-development/custom-logic/

What happened?

(Kong Gateway > Develop Custom Plugins > Implementing Custom Logic)

I'm not an Ningx/OpenResty® expert, but I find the use of the "Phase" term on this page confusing.

In the Available contexts table, all the links refer to "directives" rather than "phases", if we adopt the lua-nginx-module terminology. For example, according to the lua-nginx-module documentation:

• "phase init_worker" in Kong -> stands for "starting-worker" phase and "init_worker_by_lua_*" directive
• "phase rewrite" in Kong -> stands for "rewrite tail" phase and "rewrite_by_lua_*" directive
• "phase access" in Kong -> stands for "access tail" phase and "access_by_lua_*" directive
• ...

An other issue concerns the "reponse" function, for which the phase is "access". However, according to the description, it replaces "header_filter()" and "body_filter()". As shown in the diagram in the Directives section, they are part of "Content Phase", not "Access Phase". This seems to be a mistake.

What did you expect to happen?

What could be preferred:

1. Standardize terminology and retain in Kong's documentation only the four main phases described in the lua-nginx-module diagram: Initialization Phase, Rewrite/Access Phase, Content Phase, Log Phase.
2. Replace the term "Phase" by "Directive", and continue to link to each of the lua-nginx-module directives.
3. Another thing?

In any case, I think there's something to clear up! 😀

Hope this helps! 🙏

Code of Conduct and Community Expectations

• I agree to follow this project's Code of Conduct
• I agree to abide by the Community Expectations

[lena-larionova]

@lfavreli You have a very good point here, but looks like Kong is using the term "phases" in a custom way.
I did a bunch of digging into this, and it looks like the term "phases" is referring to Kong-specific phases, not phases as defined by nginx. Here's the list of Kong phases: https://github.com/Kong/kong/blob/master/kong/pdk/private/phases.lua

The documentation is definitely confusing, so the PR linked to this ticket adjusts the doc to clarify the difference between Kong phases and the nginx directives they're related to.

[lfavreli]

Thank you for taking my comment into account and updating the documentation page. 😃