Proposal: provide a way to detect NGINX context based on line number

[ryepup]

Is your feature request related to a problem? Please describe

I want a better way to find the NGINX context based on line number.

I was attempting to write a language server for NGINX, using nginx-go-crossplane to parse files and then cross-reference with nginx-directive-reference to drive IDE features like autocomplete and accurate documentation.

The problem I have is NGINX directives often re-use a name; if my language server wants to show a tooltip and when the user hovers over a listen directive, I don't have a good way to tell if they mean HTTP listen, stream listen or mail listen.

Sometimes it's possible to walk the Config.Parsed tree to detect parent context.

Sometimes the user might ask for autocomplete suggestions on a blank line, and all I have to work with is a line number. The Payload does not contain enough information to determine NGINX context if there's not a directive on that line.

Describe the solution you'd like

Parse keeps a record of the current NGINX context (blockCtx), I'd like that information to escape.

 type Directive struct {
 	Directive string     `json:"directive"`
 	Line      int        `json:"line"`
+	// EndLine is the line number with the } that ends this block directive. Will be nil for directives that are not blocks.
+	EndLine      *int        `json:"endLine,omitempty"`
 	Args      []string   `json:"args"`

I think this can be captured with some non-trivial refactoring around parser.Parse to return the line number with recursive calls.

Describe alternatives you've considered

I tried to recursively walk Config.Parsed, keeping track of the last directive where d.Line < x && len(d.Block) > 0, but this fails to detect when a context ends.

From F5 internal prototype:

export function findClosestDirective(p: Payload, line: number): Directive | undefined {
    let possibleParent: Directive | undefined = undefined;
    for (const d of allDirectives(p)) { // recursively walks the directive tree and generates a flat list
        if (d.line === line) {
            return d
        }
        if (d.line < line && d.block) {
            possibleParent = d
        }
        if (d.line > line) {
            return possibleParent
        }
    }
    return possibleParent
}

http {
  server { # ✅ I can walk the Config.Parsed tree to see this server is in an http
    # ✅  on a blank the last seen context on this line is "server" 
  }
  # ❌ on a blank the last seen context on this line is "server", as the } is not represented in the payload
}

I considering requesting something easier to implement like:

 type Directive struct {
 	Directive string     `json:"directive"`
 	Line      int        `json:"line"`
+	// Context is the stack of NGINX contexts that contain this directive.
+	Context      []string        `json:"context,omitempty"`
 	Args      []string   `json:"args"`

But doesn't doesn't solve the use case where all I have is a line number.

[ornj]

Keeping track of context (I suspect a slice of strings maybe isn't enough) could get difficult. Endline might get you close in some cases but you'll probably still need to do some guessing. I think both these examples will make it tricky for anyone using Crossplane to modify NGINX configs unless we also provide some tooling to manage this. Pointers might sound like a solution, but I suspect it will be difficult too.

I think you can traverse the payload to determine what the parent context is. This might be more or less tricky depending on the options set when converting from the NGINX config to the JSON payload.

Understanding when you're at an empty line in a block/context could be a little tricky, but you could try checking for gaps between directives/nodes?

The suggestion for tracking where a node ends is interesting. I would probably suggest including it for all directives as even some non-block directives may start and end on a different line:

    log_format compression '$remote_addr - $remote_user [$time_local] '
                           '"$request" $status $body_bytes_sent '
                           '"$http_referer" "$http_user_agent" "$gzip_ratio"';

[ryepup]

I think both these examples will make it tricky for anyone using Crossplane to modify NGINX configs unless we also provide some tooling to manage this.

Definitely. The LSP is line-oriented, so I was largely using crossplane to learn more about what is going on in and around line N. Suggesting changes would be another can of worms that probably wants a more thoughtful AST, but even those are handled in the LSP as line-oriented text.

could try checking for gaps between directives/nodes?

I tried that, it was ambiguous based on walking the directive tree alone; lines A and B below are both between the two server directives, but in different NGINX contexts. I could use the line number of the first server directive to re-scan the config looking for }, but it'd be nice if crossplane handled it.

http {
  server {
    # A
  }
  # B
  server {

  }
}

including it for all directives

good call, I didn't think about multi-line directives but that'd probably be a big help.

At any rate, this work was for a hackathon so might not get much time, but I wanted to note the friction in case it ends up on a roadmap.