{"id":13596725,"url":"https://github.com/kevinburke/hamms","last_synced_at":"2025-05-16T05:07:39.978Z","repository":{"id":10010763,"uuid":"12047515","full_name":"kevinburke/hamms","owner":"kevinburke","description":"Malformed servers to test your HTTP client","archived":false,"fork":false,"pushed_at":"2017-01-05T02:00:53.000Z","size":50,"stargazers_count":1209,"open_issues_count":0,"forks_count":29,"subscribers_count":30,"default_branch":"master","last_synced_at":"2025-05-11T12:41:29.118Z","etag":null,"topics":["failure-handling","http","networking","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kevinburke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-08-12T03:58:35.000Z","updated_at":"2025-04-08T20:15:03.000Z","dependencies_parsed_at":"2022-09-10T04:13:31.038Z","dependency_job_id":null,"html_url":"https://github.com/kevinburke/hamms","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevinburke%2Fhamms","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevinburke%2Fhamms/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevinburke%2Fhamms/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kevinburke%2Fhamms/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kevinburke","download_url":"https://codeload.github.com/kevinburke/hamms/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254471060,"owners_count":22076585,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["failure-handling","http","networking","python"],"created_at":"2024-08-01T16:02:43.133Z","updated_at":"2025-05-16T05:07:35.259Z","avatar_url":"https://github.com/kevinburke.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Hamms\n\nHamms is designed to elicit failures in your HTTP Client. Connection failures,\nmalformed response data, slow servers, fat headers, and more!\n\n## Installation\n\nYou can either install hamms via pip:\n\n    pip install hamms\n\nOr clone this project:\n\n    git clone https://github.com/kevinburke/hamms.git\n\n## Usage\n\n1. Start hamms by running it from the command line:\n\n        python -m hamms\n\n    Or use the HammsServer class to start and stop the server on command.\n\n    ```python\n    from hamms import HammsServer\n\n    class MyTest(object):\n        def setUp(self):\n            self.hs = HammsServer()\n            self.hs.start(beginning_port=5500)\n\n        def tearDown(self):\n            self.hs.stop()\n    ```\n\n2. Make requests and test your client. See the reference below for a list of\n   supported failure modes.\n\nBy default, Hamms uses ports 5500-5600. You can customize the port range by\npassing the `beginning_port` parameter to `HammsServer.start()`.\n\n## Reference\n\n### Connection level errors\n\nConnect to the ports listed below to enact the various failure modes.\n\n- **5500** - Nothing is listening on the port. Note, your machine will likely\nsend back a TCP reset (closing the connection) immediately.\n\n    To simulate a connection failure that just hangs forever (a connection\n    timeout), connect to a bad host on a real server, for example\n    `www.google.com:81`, or use a port in the `10.*` range, for example\n    `10.255.255.1`.\n\n- **5501** - The port accepts traffic but never sends back data\n\n- **5502** - The port sends back an empty string immediately upon connection\n\n- **5503** - The port sends back an empty string after the client sends data\n\n- **5504** - The port sends back a malformed response (\"foo bar\") immediately upon connection\n\n- **5505** - The port sends back a malformed response (\"foo bar\") after the client sends data\n\n- **5506** - The client accepts the request, and sends back one byte every 5 seconds\n\n- **5507** - The client accepts the request, and sends back one byte every 30 seconds\n\n- **5508** - Send a request to `localhost:5508?sleep=\u003cfloat\u003e` to sleep\nfor `float` number of seconds. If no value is provided, sleep for 5 seconds.\n\n- **5509** - Send a request to `localhost:5509?status=\u003cint\u003e` to return\n  a response with HTTP status code `status`. If no value is provided, return\n  status code 200.\n\n- **5510** - The server will send a response with a `Content-Length: 3` header,\n  however the response is actually 1 MB in size. This can break clients that\n  reuse a socket.\n\n- **5511** - Send a request to `localhost:5511?size=\u003cint\u003e` to return a `Cookie`\n  header that is `n` bytes long. By default, return a 63KB header. 1KB larger\n  will break many popular clients (curl, requests, for example)\n\n- **5512** - Use this port to test retry logic in your client - to ensure that\nit retries on failure.\n\n    The server maintains a counter for incoming requests. Each time a new\n    request is made, a 500 error is served and the counter is decremented. When\n    the counter reaches zero, a 200 response is served. This server accepts two\n    query arguments:\n\n    - **key** - Specify a `key` to create a new counter. Continue making\n      requests with `key=\u003ckey\u003e` to decrement that particular counter. If no\n      key is provided, 'default' is used.\n    - **tries** - Specify the number of tries before success, as an integer. If\n    no number is provided, you will get a success on the 3rd try.\n\n    The server will let you know the key and how many tries are remaining until\n    you get a successful response. Example error response:\n\n    ```json\n    HTTP/1.1 500 INTERNAL SERVER ERROR\n    Content-Length: 116\n    Content-Type: application/json\n    Date: Wed, 19 Nov 2014 00:59:19 GMT\n    Server: TwistedWeb/14.0.2\n\n    {\n        \"error\": \"The server had an error. Try again 1 more time\",\n        \"key\": \"foobar\",\n        \"success\": false,\n        \"tries_remaining\": 1\n    }\n    ```\n\n    Example usage:\n\n    ```python\n    r = requests.get('http://localhost:5512?key=special-key')\n    assert_equal(r.status_code, 500)\n    r = requests.get('http://localhost:5512?key=special-key')\n    assert_equal(r.status_code, 500)\n    # Third time is the charm\n    r = requests.get('http://localhost:5512?key=special-key')\n    assert_equal(r.status_code, 200)\n\n    # Set tries=1 to serve a 200 right away.\n    r = requests.get('http://localhost:5512?key=my-key\u0026tries=1')\n    assert_equal(r.status_code, 200)\n    ```\n\n    You can see the status of all available counters by making a GET request\n    to `http://localhost:5512/counters`, or reset a counter by making a POST\n    request to `http://localhost:5512/counters` with the `key` you want to\n    reset.\n\n- **5513** - Send a request to `localhost:5513?failrate=\u003cfloat\u003e`. The server\n  will drop requests with a frequency of `failrate`.\n\n- **5514** - The server will try as hard as it can to return a content type\nthat is not parseable by the `Accept` header provided by the request. Specify\na `Accept: application/json` header in your request and the server will return\ndata with the `text/morse` content type. The server will try these\ncontent-types in turn:\n\n- `text/morse`\n- `application/json`\n- `text/html`\n- `text/csv`\n\nIf your Accept header indicates it can accept all of these content-types, the\nserver will return `text/morse`.\n\n- **5515** - The server will return a response with a content-type that matches\nthe request, but it will be incomplete. The server will advertise an incorrect,\ntoo long Content-Length, and the response body will not be complete. The\npractical effect is that the server will hang halfway through the response\ndownload. The server can return partial responses with the following\ncontent-types:\n\n- `application/json`\n- `text/html`\n- `text/plain`\n- `text/xml`\n\nIf your server indicates an Accept header value of `*/*`, or the server cannot\nfind a matching content-type, the server will returnn an incomplete json\nresponse.\n\n- **5516** - Same semantics as port 5515, but the server will close the\nconnection partway through, instead of hanging indefinitely.\n\n#### Not implemented yet\n\n- The server sends back a response without a content-type\n- The server sends back a response with the wrong content-type\n- The server randomly drops bytes from a valid response.\n- Sending back byte data\n\n##### SSL\n\n- Handshake timeout\n- Invalid certificate\n- TLS v1.0 and higher only\n- TLS v1.2 and higher only\n- Server closes connection\n\n## Donating\n\nDonations free up time to make improvements to the library, and respond to\nbug reports. You can send donations via Paypal's \"Send Money\" feature to\nkev@inburke.com. Donations are not tax deductible in the USA.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevinburke%2Fhamms","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkevinburke%2Fhamms","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkevinburke%2Fhamms/lists"}