openresty / openresty/lua-nginx-module

Kindly add documentation regarding phases to the README.

Open
#1,507 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
C
Stars
11.8k
Forks
2.1k
Avg merge
6h 1m
Merged PRs (30d)
6

Description

The README mentions processing phases. In particular, each *by_lua* API mentions in which phase the functionality provided to that API is executed.

But I have not been able to localize documentation regarding those phases. I think it would be beneficial if such documentation would be included in the README, or linked from the README. This is what this issue is about.

The canonical place to check Nginx processing phases seems to be the pertinent section of the Nginx development guide.

However, the phases as mentioned there do not seem to map to the phases given in the README.

In particular, I have seen in one experiment that the phase "content" starts, then the phase "output-header-filter" intervenes, and afterwards, the phase "content" continues. These are two phases given in the README.

On the other hand, the development guide clearly says about its phases that they "... are processed successively".

From this, I conclude that there is no straightforward 1:1 mapping of development guide phases and lua-nginx-module README phases.

Please, kindly add documentation of the phases and their order of execution (or how they interweave) to the README. Or else, add a link to such a documentation if that already exists.

Here is what we presently have:

$ grep -P 'phase:' README.markdown | grep -v 'depends on usage' | sort -u
**phase:** *access tail*
**phase:** *content*
**phase:** *loading-config*
**phase:** *log*
**phase:** *output-body-filter*
**phase:** *output-header-filter*
**phase:** *rewrite*
**phase:** *rewrite tail*
**phase:** *right-after-SSL-handshake*
**phase:** *right-before-SSL-handshake*
**phase:** *starting-worker*

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the phase references in README.markdown and compare them with the linked Nginx development guide's HTTP phases section. Determine and document the execution order or interleaving of the listed lua-nginx-module phases, or add a link to authoritative documentation if it already exists.

Written by the indexing model from the issue text.

Assessment

Tech stack
lua, nginx
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.