Dependencies between content blocks

[traut]

Background

With https://github.com/blackstork-io/fabric/issues/17 implemented, it will be possible to query the template tree in the content blocks. Extending this approach, the block should be able to query the already processed blocks.

This issue covers the dependencies of content blocks. The dependencies allow us to support the introspective logic in the plugins, which processes already rendered content.

It will also be valuable to have the dependencies for the data blocks. Still, since the data blocks do not support the query attribute and the context processing, implementing the dependency hook requires a separate issue.

Design

By default, the content blocks do not depend on the execution of the other content blocks, making it possible to run them concurrently. An exception to that is the blocks that explicitly depend on the results of the execution of the other blocks.

To make the content block depend on the execution of the other blocks new attributes are introduced:

• depends_on -- (optional) a list attribute that accepts a list of block signatures (see below on the exact format)
• depends_on_above -- (optional) a bool attribute

The content blocks can depend on the evaluation of

• other content blocks
• section blocks

[!NOTE] Some content blocks can be nested deeply in the template tree. To avoid encoding the full path into the block signature and to limit the discovery scope, we must introduce some constraints:

• only the content/section blocks present in the document (normal or ref blocks) can be linked
• the blocks are referenced via the signature in the format of this_doc.content.<content-provider>.<name> or this_doc.section.<name>. Since the signature is NOT unique in the scope of the current document (see #), it can match multiple blocks. this_doc is a shortcut that points to the document scope, allowing us to explore the dependency targets outside the doc in the future without changing the format.

Behaviour:

• If the content block sets depends_on attribute, it is evaluated after all the dependencies are evaluated
• if the block sets depends_on_above attribute, it is evaluated after all the content / section blocks above it are evaluated.
  • implementation-wise, the list of dependencies can be calculated from the template structure, removing the need to execute blocks sequentially.
• the context the block with the dependencies receives contains the results of the dependencies under output top-level field. The individual results are accessible using the path output.content.<content-provider>.<name>

In the case of circular dependency (the block depends on itself or its parent block), the error should be raised.

document "test_doc" {

  data inline "foo" {
    items = ["aaa", "bbb", "ccc"]
  }

  content text "foo_text" {
    query = ".data.inline.foo.items | length"
    text = "There are {{ .query_result }} items"
  }

  content text "bar_text" {
    depends_on = [this_doc.content.text.footext]
    query = ".output.content.text.foo_text"

    text = "The other block produced this text: '{{ .query_result }}'"
  }

  content text "baz_text" {
    depends_on_above = true

    text = "The other blocks produced this text:  '{{ .output.content.text.foo_text}}'  and '{{ .output.content.text.bar_text}}'"
  }
}

will produce

There are 3 items

The other block produced this text: 'There are 3 items'

The other blocks produced this text: 'There are 3 items' and 'The other block produced this text: 'There are 3 items''

References

• https://github.com/blackstork-io/fabric/issues/17
• https://developer.hashicorp.com/terraform/tutorials/configuration-language/dependencies

[traut]

with #142 bringing the blocks that have conditions in them, it makes sense that the dependent block is not included if any of the dependencies is not included (condition_query result is false)

[traut]

I moved to draft to re-think this issue. There might be a way to implement it through the conditions in the dynamic block