Introduce hooks for dynamic completion

[radeksimko]

Background

We currently provide completion based entirely on schemas, which are sourced either from providers (as JSON), declared within terraform-schema, or augmented from the configuration (such as module inputs/outputs based on variables and outputs).

Use Cases

There are use cases for a more dynamic completion however

• Completion of module source and version vscode-terraform#672
• Completion for required_providers source & version vscode-terraform#676

which cannot be served using a static nor purely config-informed schema.

Future Related Use Cases

The solution may not necessarily be ready to solve any of these but these look like the same problems that could be solved by the same solution:

• Terraform: Completion of AWS regions or AZs in provider "aws" blocks
• Nomad: completion of Docker image from Docker Hub, Quay and/or other image sources https://www.nomadproject.io/docs/drivers/docker
• Packer: completion of source_image from GCP https://www.packer.io/plugins/post-processors/googlecompute/googlecompute-export#basic-example

Proposal

hashicorp/hcl-lang

• IntroduceCompletionHooks []lang.CompletionHook to schema.AttributeSchema
• Introduce CompletionHooks CompletionFuncMap to decoder.DecoderContext
• Introduce CompletionResolveHooks CompletionResolveFuncMap to decoder.DecoderContext
• Introduce Meta interface{} field to decoder.PathContext to allow LS to pass extra context (such as which provider/module to pull versions for) to completion hooks
• Introduce MetaFromContext(ctx) to decoder to help obtain the metadata from completion hooks in LS
• Update CandidatesAtPos() in PathDecoder
  • Add ctx context.Context argument (for cancellation)
  • Ensure completion hooks are called if defined within AttributeSchema
    • Pass hcl.Position via ctx to each hook
    • Pass filename via ctx to each hook
    • Pass lang.Path via ctx to each hook
• Introduce ResolveCandidate() to decoder.PathDecoder

type AttributeSchema struct {
// ...
	// CompletionHooks represents any hooks which provide
	// additional completion candidates for the attribute dynamically
	CompletionHooks []lang.CompletionHook
}

type Decoder struct {
// ...
	CompletionHooks        CompletionFuncMap
	CompletionResolveHooks CompletionResolveFuncMap
}

type CompletionFunc func(ctx context.Context, value cty.Value, args ...interface{}) ([]Candidate, error)
type CompletionFuncMap map[string]CompletionFunc

type CompletionResolveFuncMap map[string]CompletionResolveFunc
type CompletionResolveFunc func(ctx context.Context, candidate lang.Candidate, args ...interface{}) (ResolvedCandidate, error)

type Candidate struct {
	// Value represents the value to be inserted
	Value cty.Value

	// Label represents a human-readable name of the candidate
	// if one exists (otherwise Value is used)
	Label string

	// Description represents human-readable description
	// of the candidate
	Description lang.MarkupContent

	// IsDeprecated indicates whether the candidate is deprecated
	IsDeprecated bool

	// ResolveHook represents a resolve hook to call
	// and any arguments to pass to it
	ResolveHook *lang.ResolveHook
}

type ResolvedCandidate struct {
	Description lang.MarkupContent
}

package lang

type CompletionHook struct {
	Name string
	Args []interface{}
}

type ResolveHook struct {
	Name string
	Args []interface{}
}

func (d *PathDecoder) ResolveCandidate(ctx context.Context, candidate lang.Candidate) (lang.Candidate, error) {
    // TODO ...
}

terraform-ls

• langserver/handlers: Introduce completionItem/resolve LSP method which will basically just call PathDecoder.ResolveCandidate()

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.