diff --git a/docs/APIv2/swagger-2.0.json b/docs/APIv2/swagger-2.0.json index ca823638..eeb153ad 100644 --- a/docs/APIv2/swagger-2.0.json +++ b/docs/APIv2/swagger-2.0.json @@ -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", diff --git a/docs/APIv2/swagger-2.0.yaml b/docs/APIv2/swagger-2.0.yaml index e70f5f82..a3b48eec 100644 --- a/docs/APIv2/swagger-2.0.yaml +++ b/docs/APIv2/swagger-2.0.yaml @@ -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: | diff --git a/docs/JIM.md b/docs/JIM.md index b20fd876..36c527c5 100644 --- a/docs/JIM.md +++ b/docs/JIM.md @@ -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? @@ -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 | --------------------- | ------- | ---- @@ -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: @@ -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