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 polling the TDP Command Service for commands. The Agent then parses commands retrieved from the TDP Command Service and sends their corresponding HTTP or HTTPS requests to the target service(s). The response from the requests are 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. The TetraScience context API will return the command responseBody when the command reaches a terminal status. More information on command outcomes is below.

Supported Command Actions

The Tetra HTTP Relay Agent supports the following command actions, which are specified in the action field of the command:

• 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.

Commands whose command.action field does not match one of the supported command actions will be marked as rejected by the agent.

Command Payload Definition

What follows is the definition for the command.payload field, also known as the request body, for the command. The content of the command payload should fully specify a HTTP or HTTPS request to the target system.

Common HTTP Relay-Supported Command Payload fields

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 Response Body format

The HTTP Relay Agent packages HTTP responses from the target system for transit to the requestor in the command responseBody field. For customers using the TetraScience Context API within a TDP Pipeline, this describes the return format from that method when sending commands to the HTTP Relay Agent.

For commands with status SUCCESS and also FAILED commands that were able to complete the HTTP request but received a status code greater than 400, then the command response will be an object with the following definition:

The TetraScience.Connector.http.Request.V2 command response body format is the same as the request body format, described above. Requestors are responsible to decrypt the command response body in order to review details.

For commands with status FAILED that were unable to complete the HTTP request, then the response will have the following format:

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.
• FAILURE: The HTTP request failed, either because the request was unable to be executed, or the response has status code 400 or higher. Rare HTTP or HTTPS workflows featuring status code 100 can fail. Additional information about why the request failed is accessible in the response body visible from the Command Details page.

Troubleshooting

The following are known errors that you can encounter when using the Tetra HTTP Relay Agent, along with steps to resolve each issue.