Concepts

The TriggerMesh Integration Language allows to declaratively express a messaging system called a Bridge. At its core, a Bridge is composed of interconnected messaging components that exchange data via Events, often asynchronously over data channels.

This document describes the main concepts of the language.

Contents

• Syntax
• Component Blocks
• Identifiers
• References
• Expressions

---

Syntax

The constructs of the TriggerMesh Integration Language build upon the HCL syntax, which was created by HashiCorp Inc. and popularized by products such as Terraform, Nomad or Packer.

The different components of a given Bridge are represented as configuration blocks which are identified by labels and contain configuration attributes.

An example of direct point-to-point integration between two services could be expressed with the following code snippet:

bridge "github_to_splunk" { }

/* Event source block 
   Sources events from a GitHub repository
*/
source github "my_repo" {
  owner_and_repository = "triggermesh/bridges"
  tokens = secret_name("github-source-tokens")

  event_types = [
    "push", 
    "pull_request",
  ]

  to = target.github_archive_index
}

/* Event target block 
   Receives events and stores them into a Splunk index
*/
target splunk "github_archive_index" {
  endpoint = "https://prd-x-12345.splunkcloud.com"
  auth = secret_name("my-splunk-credentials")

  index = "github_events"
}

Most configuration attributes are component-specific. All available attributes are documented in details in the Availaible Implementations section of the documentation.

The rest of this document focuses on the general language constructs available in the TriggerMesh Integration Language, some of which are demonstrated in the previous snippet.

Component Blocks

Each configuration block represents a logical messaging component within a Bridge. These components are expressed as HCL blocks.

The first keyword in a component block definition is the category of the component to represent. There are five categories of components available in the TriggerMesh Integration Language, which are described in details in the Component Categories section of the documentation.

For example, the following component, taken from the previous code snippet, falls into the source category:

source github "my_repo" { }

NOTE: While all components are ultimately translated to Kubernetes manifests, there is not always a 1:1 relationship between a Bridge component and a Kubernetes API object.

Identifiers

A Bridge component accepts exactly two labels after the category keyword.

The first label is the component type. It determines the schema of the configuration within the component block: its nested blocks and attributes, their type, whether they are mandatory or optional, etc. Its value must be a supported component type.

The second label is the component identifier. It is used to uniquely identify the instance of a component within a given component category. Its value can be arbitrarily chosen.

For example, the following component, taken from the previous code snippet, is of type github and is identified as my_repo:

source github "my_repo" { }

NOTE: Labels that appear in component blocks must be valid HCL identifiers, and can therefore be written either as quoted literal strings or naked identifiers (unquoted). By convention, all examples in this documentation use a naked identifier for the type label, and a quoted identifier for the component identifier label.

References

Any messaging component that can send events is required to support references to other components. These references are used to determine the dependencies between components of a Bridge, and are automatically resolved to event addresses.

A block reference is always expressed as a HCL variable expression in the format <CATEGORY>.<IDENTIFIER>. The referenced component must be defined within the Bridge.

For example, the following component, taken from the previous code snippet, sends events to a component of type target identified as github_archive_index:

source github "my_repo" {
  to = target.github_archive_index
}

NOTE: Although there is no restriction in the language about what attribute name may represent a block reference, most component implementations use the attribute name to or reply_to by convention to represent such reference.

Expressions

In some contexts, the value of a given attribute may be determined by evaluating a HCL expression.

For example, the following component, taken from the previous code snippet, has a tokens attribute which value is evaluated by calling a function named secret_name:

source github "my_repo" {
  tokens = secret_name("github-source-tokens")
}

NOTE: Function expressions are documented in details in the Function Expressions section of the documentation.