Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add swagger definitions for jim APIs and document the APIs #368

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Add swagger definitions for jim APIs and document the APIs #368

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ff029a5
Add swagger definitions for jim APIs and document the APIs
jmholzinger Jun 9, 2021
9c178d0
revert accidental change to "-invite-jim" default
jmholzinger Jun 9, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 114 additions & 0 deletions docs/APIv2/swagger-2.0.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,121 @@
"version": "2.0.0",
"title": "MailHog API"
},
"definitions": {
"jim": {
"type": "object",
"properties": {
"DisconnectChance": {
"type": "number",
"format": "float",
"description": "Chance of randomly disconnecting a session"
},
"AcceptChance": {
"type": "number",
"format": "float",
"description": "Chance of accepting an incoming connection"
},
"LinkSpeedAffect": {
"type": "number",
"format": "float",
"description": "Chance of applying a rate limit"
},
"LinkSpeedMin": {
"type": "number",
"format": "float",
"description": "Minimum link speed (in bytes per second)"
},
"LinkSpeedMax": {
"type": "number",
"format": "float",
"description": "Maximum link speed (in bytes per second)"
},
"RejectSenderChance": {
"type": "number",
"format": "float",
"description": "Chance of rejecting a MAIL FROM command"
},
"RejectRecipientChance": {
"type": "number",
"format": "float",
"description": "Chance of rejecting a RCPT TO command"
},
"RejectAuthChance": {
"type": "number",
"format": "float",
"description": "Chance of rejecting an AUTH command"
}
}
}
},
"paths": {
"/api/v2/jim": {
"get": {
"description": "Get Jim's configuration\n",
"responses": {
"200": {
"description": "Successful response",
"schema": {
"$ref": "#/definitions/jim"
}
},
"404": {
"description": "Jim is not enabled"
}
}
},
"post": {
"description": "Enable Jim\n",
"parameters": [
{
"name": "config",
"in": "body",
"schema": {
"$ref": "#/definitions/jim"
}
}
],
"responses": {
"200": {
"description": "Successful response"
},
"400": {
"description": "Jim is already enabled"
}
}
},
"put": {
"description": "Update Jim\n",
"parameters": [
{
"name": "config",
"in": "body",
"schema": {
"$ref": "#/definitions/jim"
}
}
],
"responses": {
"200": {
"description": "Successful response"
},
"404": {
"description": "Jim is not enabled"
}
}
},
"delete": {
"description": "Disable Jim\n",
"responses": {
"200": {
"description": "Successful response"
},
"404": {
"description": "Jim is not enabled"
}
}
}
},
"/api/v2/messages": {
"get": {
"description": "Retrieve a list of messages\n",
Expand Down
84 changes: 84 additions & 0 deletions docs/APIv2/swagger-2.0.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,91 @@ info:
version: "2.0.0"
title: MailHog API

definitions:
jim:
type: object
properties:
DisconnectChance:
type: number
format: float
description: Chance of randomly disconnecting a session
AcceptChance:
type: number
format: float
description: Chance of accepting an incoming connection
LinkSpeedAffect:
type: number
format: float
description: Chance of applying a rate limit
LinkSpeedMin:
type: number
format: float
description: Minimum link speed (in bytes per second)
LinkSpeedMax:
type: number
format: float
description: Maximum link speed (in bytes per second)
RejectSenderChance:
type: number
format: float
description: Chance of rejecting a MAIL FROM command
RejectRecipientChance:
type: number
format: float
description: Chance of rejecting a RCPT TO command
RejectAuthChance:
type: number
format: float
description: Chance of rejecting an AUTH command

paths:
/api/v2/jim:
get:
description: |
Get Jim's configuration
responses:
'200':
description: Successful response
schema:
$ref: '#/definitions/jim'
'404':
description: Jim is not enabled
post:
description: |
Enable Jim
parameters:
-
name: 'config'
in: body
schema:
$ref: '#/definitions/jim'
responses:
'200':
description: Successful response
'400':
description: Jim is already enabled
put:
description: |
Update Jim
parameters:
-
name: 'config'
in: body
schema:
$ref: '#/definitions/jim'
responses:
'200':
description: Successful response
'404':
description: Jim is not enabled
delete:
description: |
Disable Jim
responses:
'200':
description: Successful response
'404':
description: Jim is not enabled
/api/v2/messages:
get:
description: |
Expand Down
69 changes: 66 additions & 3 deletions docs/JIM.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,10 @@ You can invite Jim to the party using the `invite-jim` flag:

MailHog -invite-jim

Or by making a request to [Jim's API](./APIv2.md):

curl -X POST http://example.com:8025/api/v2/jim

With Jim around, things aren't going to work how you expect.

### What can Jim do?
Expand All @@ -19,7 +23,9 @@ With Jim around, things aren't going to work how you expect.

It does this randomly, but within defined parameters.

You can control these using the following command line flags:
## Control Jim from the command line

You can control Jims behavior using the following command line flags:

| Flag | Default | Description
| --------------------- | ------- | ----
Expand All @@ -36,9 +42,9 @@ You can control these using the following command line flags:
If you enable Jim, you enable all parts. To disable individual parts, set the chance
of it happening to 0, e.g. to disable connection rate limiting:

MailHog -invite-jim -jim-linkspeed-affect=0
MailHog -invite-jim -jim-linkspeed-affect=0

### Examples
### Command line examples

Always rate limit to 1 byte per second:

Expand All @@ -51,3 +57,60 @@ Disconnect clients after approximately 5 commands:
Simulate a mobile connection (at 10-100kbps) for 10% of clients:

MailHog -invite-jim -jim-linkspeed-affect=0.1 -jim-linkspeed-min=1250 -jim-linkspeed-max=12500

## Control Jim from the API

You can control Jim's behavior using [the API](./APIv2.md) at `/api/v2/jim`.

The API accepts a JSON payload with the following properties:

| Property | Default | Description
| --------------------- | -------- | ----
| DisconnectChance | 0.005 | Chance of randomly disconnecting a session
| AcceptChance | 0.99 | Chance of accepting an incoming connection
| LinkSpeedAffect | 0.1 | Chance of applying a rate limit
| LinkSpeedMin | 1024 | Minimum link speed (in bytes per second)
| LinkSpeedMax | 10240 | Maximum link speed (in bytes per second)
| RejectSenderChance | 0.05 | Chance of rejecting a MAIL FROM command
| RejectRecipientChance | 0.05 | Chance of rejecting a RCPT TO command
| RejectAuthChance | 0.05 | Chance of rejecting an AUTH command

The default values are used only when Jim is enabled without providing a JSON payload.
When a JSON payload is sent to the API, any properties that are not provided are set to 0.

When Jim sees this:

```json
{
"DisconnectChance": 1.0
}
```

It assumes you meant this:

```json
{
"DisconnectChance": 1.0,
"AcceptChance": 0,
"LinkSpeedAffect": 0,
"LinkSpeedMin": 0,
"LinkSpeedMax": 0,
"RejectSenderChance": 0,
"RejectRecipientChance": 0,
"RejectAuthChance": 0
}
```

### API examples

Invite Jim with with a specific configuration:

curl -X POST -d '{"DisconnectChance": 1.0}' http://example.com:8025/api/v2/jim

Update Jim's configuration on the fly:

curl -X PUT -d '{"AcceptChance": 0.1}' http://example.com:8025/api/v2/jim

Tell Jim the party is over:

curl -X DELETE http://example.com:8025/api/v2/jim