Tetra HTTP Relay Agent User Guide (v1.0.x)
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:
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:
Field | Required | Data Type | Definition |
---|---|---|---|
method | required | string | One of the following HTTP Request methods: 'GET', 'POST', 'PUT', 'PATCH', 'DELETE' 'HEAD', 'OPTIONS'. |
url | required | string | Full URL to the target system and API endpoint (for example, https://localhost:3000/route/to/endpoint?send=true&query=param ). |
ignore_tls_certificate | optional | boolean | Determines if the Tetra HTTP Relay Agent ignores TLS certificates or not. |
headers | optional | JSON object or object[] | Optional headers to add to the HTTP or HTTPS request. |
timeout | optional | number | How long the Tetra HTTP Relay Agent will wait before failing the HTTP or HTTPS request, measured in milliseconds. The default value is 10000 . |
body | optional | JSON | The body must conform to one of the following JSON definitions. |
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:
Field | Required | Data Type | Definition |
---|---|---|---|
nonce | required | base64 string | A one-time-used base64-encoded string. |
tag | required | base64 string | A tag from encrypting and digesting the data. |
ciphertext | required | base64 string | The command body, consistent with other commands, but base64 encoded and encrypted. |
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:
Field | Data Type | Definition |
---|---|---|
body | string | The response data from the target. If the response data is provided as a JSON object, then it is stringified |
statusCode | integer | The HTTP response status code from the target |
headers | object[] | An array of key-value pairs. For example: [{"content-length": "102"}, {"content-type": "application/json"}] |
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:
Field | Data Type | Definition |
---|---|---|
body | string | Commonly a stringified object containing a message field whose value has additional details. For example: "{"message":"An error occurred while handling the command: Error making request: The request was made by the HTTP Relay but no response was received. Additional info: connect ECONNREFUSED 127.0.0.1:12345"}" |
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 code200-399
.FAILURE
: The HTTP request failed, either because the request was unable to be executed, or the response has status code400
or higher. Rare HTTP or HTTPS workflows featuring status code100
can fail. Additional information about why the request failed is accessible in the response body visible from the Command Details page.
Updated about 17 hours ago