example.md

Timecop Service

Timecop is a service which is handles various public API and SMTP testing tools.

Testing email send round trip

Timecop periodically sends emails to it's self through Mailgun public HTTP and SMTP servers. It attaches a special header with a timestamp of when the email was sent, when timecop receives the email via it's own SMTP server running on port 25, it compares the send timestamp with the current time and emits a round trip metric via prometheus. If the round trip time is longer than a set thresh hold it alerts the pipeline team via pagerduty.

SMTP/API Load testing tool

Timecop also has a load testing tool called 'hammer' which is used to send lots and lots of emails via SMTP or HTTP so we can gauge how well the system handles under heavy load.

Hammer APIs

Hammer API allows a user to create a job which will hammer an SMTP or HTTP endpoint with the given or generated MIME body. It is intended to test the load capacity of our public servers.

Example

Run an SMTP Job

Run an API Job

POST /v1/hammer/job.get

Return information about a specific job

Query Parameters

Name	Description	Required	Type
id	id of the job	true	string

200 Response

{
   "id": "1234",
   "job": {
      "Type": "smtp",
      "messages": 20000,
      "timeout": "10s"
   },
   "start_time": "Thu, 29 Apr 2021 01:50:40 CDT",
   "stop_time": "Thu, 29 Apr 2021 01:50:39 CDT"
}

POST /v1/hammer/job.list

Return a list of active and in-active hammer jobs

200 Response [25/8346]

{
   "Items": [
      {
         "id": "1234",
         "job": {
            "Type": "http",
            "messages": 10000,
            "timeout": "10s"
         },
         "start_time": "Thu, 29 Apr 2021 01:50:39 CDT",
         "stop_time": "Mon, 01 Jan 0001 00:00:00 UTC"
      },
      {
         "id": "3245",
         "job": {
            "Type": "smtp",
            "messages": 20000,
            "timeout": "10s"
         },
         "start_time": "Thu, 29 Apr 2021 01:50:40 CDT",
         "stop_time": "Thu, 29 Apr 2021 01:50:39 CDT"
      }
   ]
}

default Response

{
   "Reason": ""
}

POST /v1/hammer/job.run

Given a hammer spec, start a job that will hammer the specified API

When preforming SMTP jobs you must specify the 'smtp_connection_type'

Options Are

• plain - no tls
• tls - preemptive tls connection
• starttls = connect via plain, but upgrade to TLS via 'STARTTLS' command

Request Schema

Name	Description	Required	Type
If true; will skip TLS host name verification on TLS connect	false	boolean
The type of SMTP connection to make	false	string
The type of job to run; (smtp	http	http.mime)	false
If the body is not provided; you must provide a message size to generate	false	integer
The number of concurrent connections to be made when sending. (default 1)	false	integer
	false	string
The recipient variables for use with the provided Body; ignored if no Body is provided	false	string
If true; use authentication	false	boolean
How long until the client will timeout waiting for request	false	object
The total number of email messages to send	false	integer
List recipient to send the messages too	false	array

Request Example

{
   "Type": "smtp",
   "messages": 1000,
   "connections": 10,
   "msg_size": 100000,
   "timeout": "0s",
   "smtp_connection_type": "plain"
}

200 Response

{
   "id": "1234",
   "job": {
      "Type": "smtp",
      "messages": 20000,
      "timeout": "10s"
   },
   "start_time": "Thu, 29 Apr 2021 01:50:39 CDT",
   "stop_time": "Mon, 01 Jan 0001 00:00:00 UTC"
}

POST /v1/hammer/job.stop

Stops a currently running job

Query Parameters

Name	Description	Required	Type
id	id of the job	true	string

200 Response

{
   "id": "1234",
   "job": {
      "Type": "smtp",
      "messages": 20000,
      "timeout": "10s"
   },
   "start_time": "Thu, 29 Apr 2021 01:50:40 CDT",
   "stop_time": "Thu, 29 Apr 2021 01:50:39 CDT"
}