Skip to content
Hantera Developer Portal Developer Portal

Reactors

Reactors are stateless collections of methods that can perform actions inside Hantera based on input. Reactors can be used to create custom APIs and automate background work.

A Reactors starts with a Component that is then configured as a Reactor instance. This makes Reactor components re-usable for many different use-cases.

Reactors can be scheduled in Jobs or invoked directly through it’s public API, making it possible to essentially create custom APIs in your Hantera installation.

Reactors methods can take arguments, and return values. Given the nature of Reactors, besides being a bridge between Hantera’s Actors and the outside world, they can often replace serverless functions provided by my of today’s cloud providers.

A Simple Example

To get a better idea of what a Reactor looks like, take a look at the below Reactor Component:

param uri: text


from {
  post = args => web.http(
    uri,
    {
      method = 'POST'
      body = args.body
    }
  )
}

This very simple Reactor allows Rules to make external HTTP requests towards a predetermined URL. Let’s break it down.

param uri: text

This line defines a Reactor Parameter called uri or type text. This is used later to determine the endpoint of the requests. Reactor paramters are set when the Reactor is created. The same component can be re-used in multiple reactors if we need to make requests to many different endpoints.

from

The from keyword makes up the main output of the Reactor. Reactors must only have a single return value, and it must be a record of method handlers.

post = args => web.http(
  uri,
  {
    method = 'POST'
    body = args.body
  }
)

This part defines a record field called post. This will be the name of the method when we call it later. The part that comes next is a function definition which is the handler that runs when the reactor is invoked. In this case, we’re performing an HTTP POST request.

The web.http function takes two arguments. The first is the URL, and the second is a record of options. In this case, we’re setting the method to POST and adding a body which will be included in the request. The args.body means that we’re expecting to get the body as a method argument. This means that any Rule that calls this method, can provide the body to be used for the request.

For more information on the http function, refer to the http article

Testing the Reactor

In order to test this reactor, we must first install the component in Hantera. For the sake of this guide, we will use a manifest file and push the component to Hantera using hantera-cli. We will then create the Reactor instance itself using another manifest file referencing the newly created component.

  1. Start by creating the manifest file for Reactor component:

    component.myReactors.httpPoster.h_manifest.yaml
    uri: /resources/components/myReactors/httpPoster
    spec:
      displayName: 'Http Poster'
      description: 'Makes a POST request to a configured endpoint, allowing the caller to set request body'
      code: |-
        param uri: text
    

        from {
          post = args => web.http(
            uri,
            {
              method = 'POST'
              body = args.body
            }
          )
        }

  2. Next, let’s define the manifest that will instantiate the Reactor resource:

    reactor.my-api.h_manifest.yaml
    uri: /resources/reactors/my-api
    spec:
      componentId: myReactors/httpPoster
      parameters:
        uri: https://my-api.example.com/v1/endpoint
    1. Now let’s apply these manifests to our Hantera instance:
    Terminal window
    h_ manage apply component.myReactor.httpPoster.h_manifest.yaml
    h_ manage apply reactor.my-api.h_manifest.yaml

  3. You should now have a new Reactor resource live in your Hantera. You can verify it by querying the Reactors API. This should return metadata about the Reactor and it’s available methods:

    GET https://<hantera-hostname>/resources/reactors/my-api
    Authorization: Bearer <YOUR TOKEN>

  4. Once you have verified that the Reactor is there, you can now call the method using the API:

    POST https://<hantera-hostname>/resources/reactors/my-api/post
    Authorization: Bearer <YOUR TOKEN>
    Content-Type: application/json
    

    {
      "body": "This will be the body of the request"
    }

That’s it. Notice how the method name defined in the Reactor component code is manifested in it’s public API, while we can name the Reactor anything we want in the actual Reactor resource.

Access Control

You may wonder, how is it safe to make arbitrary external requests available through the public API. This sounds like a recipe for all kinds of denial-of-service problems.

While it’s true that Reactors are powerful and used wrong it can be misused. Reactors are tightly integrated with Hantera’s access control layer, which means that calling Reactor Methods require explicit permission for the session. Additinally, as opposed to many other similar platforms, Hantera makes all effects of Reactors very easy to monitor through the Reactor Logs.

The ACE pattern for reactors looks like this:

reactor[/<id>][/<method>]:read|write|invoke