This guide shows how to use and configure Tetra HTTP Relay Agent versions 1.0.X after the Agent is installed.

Reconfigure the Agent

To reconfigure the Tetra HTTP Relay Agent, you must first stop the Agent's container that's running on the Agent's host server. Then, you can run the container with a new configuration. You can't apply a new configuration to a running Tetra HTTP Relay Agent.

To stop the Agent, run the following command from the local host server's terminal:

Shell

docker stop $CONTAINER_ID

🚧

IMPORTANT

Stopping the Agent can interrupt commands that are still processing. For this reason, it's recommended that you temporarily deactivate any associated pipelines and services while you reconfigure the Agent.

To start your Agent with a new configuration, run the docker run $IMAGE_NAME command with new parameters. For instructions, see the Tetra HTTP Relay Agent Installation Guide (v1.0.x). It may be important to reuse the same Docker parameters that are used in the initial deployment.

Make sure that you review the container status and Agent logs to verify agent health after restarting the container.

Send HTTP or HTTPS Requests to a Target System

The Tetra HTTP Relay Agent relays HTTP and HTTPS requests by using the TDP Command Service. The Agent then parses commands from the TDP Command Service and sends the corresponding HTTP or HTTPS requests to a target service. The response from the request is relayed back to the TDP Command Service.

Customer applications that send commands to the Tetra HTTP Relay Agent can send a POST request to the Command Service directly by using the Create Command API endpoint.

Tetra Data Pipelines that send commands to the Tetra HTTP Relay Agent can use the Context API from within their task scripts. For example, you can use the context.run_cmd() method to send a command to the Agent and await the result of the Agent's command handling. More information is available here.

Supported Command Actions

The Tetra HTTP Relay Agent supports the following command actions:

• TetraScience.Connector.gdc.HttpRequest: This is a legacy command used by the Generic Data Connector, which can also be processed by the Tetra HTTP Relay Agent.
• TetraScience.Connector.http.Request. This command action offers a configurable timeout parameter, enabling the Tetra HTTP Relay AGent to fail commands and HTTP or HTTPS requests that timeout.
• TetraScience.Connector.http.Request.V2. This command action encrypts the contents of the HTTP or HTTP request body.

Command Payload Definition

The Tetra HTTP Relay Agent recognizes the following fields of the TetraScience.Connector.http.Request and TetraScience.Connector.http.Request.V2 command actions:

When the HTTP or HTTPS requests require a body/data to send to the target server, the Tetra HTTP Relay Agent can prepare a corresponding request if the body is in one of the following formats:

Raw Request Body

A raw request body is converted to JSON directly by parsing the .raw field and using that as the HTTP or HTTPS request data.

The following is an example raw request body:

{
    "mode": "raw",
    "raw": "{\"message\":\"Hello world\"}"
}

Formdata Request Body

A formdata request body is converted to RFC 2388 form-data by parsing the .formdata field, which must be a JSON array of objects with fields key and value, and using that as the HTTP or HTTPS request data.

The following is an example formdata request body:

{
    "mode": "formdata",
    "formdata": [{"key": "requestor", "value": "TetraScience"}]
}

URL-Encoded Request Body

A URL-encoded request body is converted to an application/x-www-form-urlencoded request. The HTTP Relay Agent expects a JSON array of objects with fields key and value, and converts that to a URL-encoded body for the HTTP or HTTPS request data.

The following is an example URL-encoded request body:

{
    "mode": "urlencoded",
    "urlencoded": [{"key": "requestor", "value": "TetraScience"}]
}

Encrypted Commands

To apply end-to-end encryption to your commands, use the TetraScience.Connector.http.Request.V2 command. The command uses AES 256 encryption and Pipelines and other requestors that use it must use the same 256-bit key string as the Agent's $SECURE_COMMAND_KEY parameter to decrypt the responses.

📘

NOTE

Pipelines should store the Agent's $SECURE_COMMAND_KEY parameter value as a Shared Secret in the TDP.

The TetraScience.Connector.http.Request.V2 command has a similar body format as the TetraScience.Connector.http.Request command, but uses the following fields to hold the encrypted command body:

Failure to decrypt a TetraScience.Connector.http.Request.V2 command by the Agent results in a FAILURE command status. This failure mode can occur if the $SECURE_COMMAND_KEY differs between the requestor/pipeline and the Agent.

Command Outcomes

The commands that the Tetra HTTP Relay Agent handles all go through the following statuses:

• CREATED: The command was posted to the TDP Command Service.
• PENDING: The command is awaiting recognition by the agent.

Based on how the Agent handles the command, it can then enter any of the following statuses:

• REJECTED: The command was received by the Agent and rejected. Additional information about why the request was rejected is accessible on the Command Details page.
• PROCESSING: The Agent is processing the command.
• SUCCESS: The HTTP or HTTPS request was executed and returned a response with status code 200-399. The Tetra HTTP Relay Agent will return fields statusCode, headers, and response, which contain the HTTP or HTTPS response status code, response headers, and response body.
• FAILURE: The HTTP request failed, either because the request was unable to be executed, or the response has status code 400 or higher. Additional information about why the request failed is accessible on the Command Details page.