Httpbun

A service to help test the behaviour of HTTP clients like browsers, libraries, developer tools or anything else. Inspired by httpbin. Built because httpbin lacked some things I needed, like:

1. The /mix endpoint, and the Mixer, with powerful ingredients like:
   • A RequestBin-like functionality with the slack directive.
   • Build response body by writing a Golang template, with the t directive.
   • Learn more at the Mixer guide.
2. The /run endpoint, and the Runner. (Beta).
3. A mock OAuth2 provider. (Beta).
4. A mock LLM API endpoint, compatible with OpenAI SDK for chat completions. (Beta).
5. Ability to run on a custom path prefix.
6. The /payload endpoint.
7. Allowing request body in /get endpoint.
8. Accept any method in /headers and most other such endpoints.
9. Not hiding some headers in responses.
10. More practical handling of unescaped special characters in x-www-form-urlencoded payloads.

Hosted versions:

1. Canonical version is at httpbun.com.
2. At ant.httpbun.com, bat.httpbun.com, cat.httpbun.com, dog.httpbun.com as alternate hosts to the same thing as the canonical version. These can be useful when testing load balancers and load balancing algorithms.
3. At any.httpbun.com, with --root-is-any enabled.
4. https://self-signed-cert.httpbun.com that uses a self-signed HTTPS certificate.

★ Star this project on GitHub.

Endpoints ¶

Mix ¶

/mix

Combine behaviour from multiple of other endpoints, into one. For example, if we want an endpoint with some response headers, as well as a specific status code, we can use:

/mix/s=400/h=x-custom-header:some-value

The s= and h= are directives that /mix understands. Supported directives are:

1. s: HTTP response status code.
2. h: Set a response header, in the form name:value.
3. c: Set a cookie, in the form name:value.
4. r: Set a redirect URL. Uses status code 307. To change, use s= directive.
5. b64: Set the response body to the base64 decoded value.
6. t: The base64 decoded value of this, is rendered as a Golang text template, and the result is used as the response body.
7. end: Takes no value, marks the end of directive processing. Path segment after this is ignored by Httpbun.

Learn more in the guide, and use the mixer for a UI to build these URLs.

Methods ¶

/get

/post

/put

/patch

/delete

Accepts GET/POST/... requests and responds with a JSON object with form body, query params, headers and a few other information about the request.

Examples

curl httpbun.com/get

curl -X POST -d 'one=1' httpbun.com/post

curl -X POST -d '{"one": 1}' -H 'content-type:application/json' httpbun.com/post

curl -X PUT httpbun.com/put

curl -X PATCH httpbun.com/patch

curl -X DELETE httpbun.com/delete

/any

/any/{extraPath}

Acts like /get, /post etc., but works on any method, and any extra path after /any is also accepted.

Responds with a JSON object with a single field, headers which is an object of all the headers in the request, as keys and values. If a header repeats in the request, then its values are concatenated with a comma and treated as a single header value.

Examples

curl -H 'x-custom: custom header value' httpbun.com/headers

/payload

Responds with the same Content-Type header as the request and the body of the request as is.

Examples

curl -H 'Content-Type: text/plain' -d 'plain body' httpbun.com/payload

curl -H 'Content-Type: application/json' -d '{"a": 1}' httpbun.com/payload

Authentication ¶

/basic-auth/{username}/{password}

Requires basic authentication with username and password as the credentials.

Examples

curl -H 'Authorization: Basic c2NvdHQ6dGlnZXI=' httpbun.com/basic-auth/scott/tiger

/bearer

/bearer/{expectedToken}

Requires bearer authentication. Which needs an Authorization header in the request, that takes the form Bearer some-auth-token-here. If no expectedToken is given, any token will be treated as valid. If no Authorization header is present in the request, this results in a 401 response.

Examples

curl -H 'Authorization: Bearer auth_token_here' httpbun.com/bearer

curl -H 'Authorization: Bearer expected_token' httpbun.com/bearer/expected_token

/digest-auth/{username}/{password}

/digest-auth/{qop}/{username}/{password}

Digest authentication. The endpoint /digest-auth/auth/scott/tiger requires to be authenticated with the credentials scott and tiger as username and password. The implementation is based on this example from Wikipedia. The value of qop can be one of auth (default), auth-int or auth,auth-int.

Mock OAuth2 authorization endpoint. Displays a consent page where the user enters their email and approves or denies access. The email is later retrievable via the /oauth2/userinfo endpoint.

Required query parameters:

• response_type: Must be code.
• client_id: Your application's client ID (any non-empty string).
• redirect_uri: The URI to redirect to after authorization.

Optional query parameters:

• state: An opaque value to maintain state between request and callback.
• scope: Requested scope (displayed on consent page, not validated).

On approval, redirects to redirect_uri with code and state parameters. On denial, redirects with error=access_denied.

Example

httpbun.com/oauth2/authorize?response_type=code&client_id=my-app&redirect_uri=https://example.com/callback&state=abc123

/oauth2/token

Mock OAuth2 token endpoint. Exchanges an authorization code for an access token.

Required form parameters (POST):

• grant_type: Must be authorization_code.
• code: The authorization code received from the authorize endpoint.
• client_id: Your application's client ID (must match the authorization request).
• client_secret: Your application's client secret (any non-empty string).
• redirect_uri: Must match the redirect_uri from the authorization request.

Returns a JSON response with access_token, token_type, and expires_in.

Examples

curl -X POST httpbun.com/oauth2/token \
  -d 'grant_type=authorization_code' \
  -d 'code=AUTH_CODE_HERE' \
  -d 'client_id=my-app' \
  -d 'client_secret=my-secret' \
  -d 'redirect_uri=https://example.com/callback'

# Response:
{
  "access_token": "...",
  "token_type": "Bearer",
  "expires_in": 3600
}

/oauth2/userinfo

Mock OAuth2 userinfo endpoint. Returns the email address that was entered on the consent page.

Authorization: Requires a Bearer token in the Authorization header.

Returns a JSON response with the user's email.

Examples

curl -H 'Authorization: Bearer ACCESS_TOKEN_HERE' httpbun.com/oauth2/userinfo

# Response:
{
  "email": "user@example.com"
}

Client Details ¶

/ip

/ip.txt

Responds with a JSON object with a single field, origin, with the client's IP Address for value.

Caching ¶

/cache

If the request contains an If-Modified-Since or If-None-Match header, returns a 304 response. Otherwise, it behaves the same as /get for GET requests, /post for POST requests, etc.

/cache/{age}

Sets a Cache-Control header for age seconds.

/etag/{etag}

Assumes the resource has the given etag and responds to If-None-Match and If-Match headers appropriately.

Client Tuned Response ¶

/status/{codes}

Responds with the HTTP status as given by codes. It can be a comma-separated list of multiple status codes, of which a random one is chosen for the response.

Sends given query parameters as headers in the response. For example, in the response from /response-headers?one=two, there is a header called One, whose value is two. The response body contains all the headers again, in the form of a JSON object. (This JSON object in the response should be considered deprecated, and may be removed in the future.)

/deny

Returns page denied by robots.txt rules.

/html

Returns a small HTML document than can trigger XSS, in vulnerable places.

/svg/{text}

Renders an SVG circle image with fill color determined by the text. The first two letters of the text are also shown at the center of the circle. Examples: for svg/bun, for svg/foo.

/robots.txt

Returns some robots.txt rules.

/base64

/base64/{encoded}

Decodes the encoded text with base64 encoding scheme. Defaults to SFRUUEJVTiBpcyBhd2Vzb21lciE=.

/bytes/{count}

Returns count random bytes in the response. The Content-Type header is set to application/octet-stream. The randomness is not cryptographically secure. The maximum number of bytes can be set with --endpoint-bytes-size-limit CLI argument, defaults to 90.

/delay/{seconds}

Respond with a delay of seconds seconds. The seconds parameter can be a positive integer or floating point number.

/drip

/drip-lines

Drips data over a duration, with an interval between each piece of data. The piece of data is the * character. The following query params can be used to configure this endpoint:

• duration: Total number of seconds over which to stream the data. Default: 2.
• numbytes: Total number of bytes to stream. Default: 10.
• code: The HTTP status code to be used in their response. Default: 200.
• delay: An initial delay, in seconds. Default: 2.

When using /drip-lines, a newline character is written after every piece of data.

/sse

Responds with 10 Server sent events, each after 1s of delay. The count and delay can be set as query params. Count should be between 1 and 100. Delay should be between 1 and 10.

/links/{count}

/links/{count}/{offset}

Returns an HTML document with count links, which in turn respond with HTML documents with links again. You mostly want to use the first version (i.e., without offset).

/range/{count}

Returns count random bytes, that are generated with the same random seed every time. The value of count is capped to 1000.

Cookie Data ¶

/cookies

Returns cookie data from the request headers.

/cookies/set

Sets cookies for all given query params.

/cookies/set/{name}/{value}

Set the cookie name to value.

/cookies/delete

Returns a response that will delete cookies in the browser. Cookies to be deleted should be given as query params. The values of these query params are ignored and can be empty.

Redirects ¶

/redirect

/redirect-to

Responds with a redirect to the URL given by the url query param. If a status query param is also given, it is used as the HTTP Status code in the response. Otherwise, 302 is used.

/redirect/{count}

/relative-redirect/{count}

Redirect count times. For example, /redirect/3 will redirect three times before settling on a response. The redirect URLs specified in the Location header will be relative URLs.

/absolute-redirect/{count}

Redirect count times. For example, /redirect/3 will redirect three times before settling on a response. The redirect URLs specified in the Location header will be absolute URLs.

LLM Mock API ¶

/llm/{...}

A mock LLM API endpoint, compatible with OpenAI SDK for chat completions. Ready to be used as the base_url in calls from the SDK. Useful for testing applications that use the OpenAI SDK without making real API calls.
Custom responses: Use the httpbun field in the request body to customize the mock response content:

{
  "model": "gpt-4",
  "messages": [{"role": "user", "content": "Hello!"}],
  "httpbun": {"content": "Your custom response here"}
}

This can also be set in the `extra_body` field of the Python and other supporting OpenAI SDKs. If httpbun.content is not provided, a default placeholder response is returned.

Examples

# Basic request
curl -X POST httpbun.com/llm/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "Hello!"}]}'

# With custom response
curl -X POST httpbun.com/llm/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [...], "httpbun": {"content": "Custom reply!"}}'

# Streaming
curl -N httpbun.com/llm/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [...], "stream": true}'

# Python with OpenAI SDK
from openai import OpenAI

client = OpenAI(
    base_url="httpbun.com/llm",
    api_key="not-needed",
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={"httpbun": {"content": "Hi! How can I help?"}},
)
print(response.choices[0].message.content)
# Output: Hi! How can I help?

Self Hosting ¶

With Docker: docker run -p 80:80 sharat87/httpbun

From source, with task installed: task run

If using for your project's CI, please consider running a self-hosted version using the Docker container. An example of this is in the container-run.yml workflow.

Configuration ¶

--bind

The network address to bind the server to. Defaults to localhost:3090, which configures the server to listen on TCP port 3090 on localhost.
This option can also be set with the HTTPBUN_BIND environment variable.

--path-prefix

Sets a path prefix for all the paths in Httpbun. For example, if this is set to the-one, then the /get endpoint will be available on /the-one/get. Similarly, all other endpoints are also prefixed with the value of this argument.

--root-is-any

If provided, all endpoint routes are disabled, and all endpoints behave like /any. This means that when this option is given, all HTML pages will also become inaccessible. Like the homepage, Mixer UI, help pages etc. A hosted instance with this option enabled is available at any.httpbun.com.

Sets a banner on the homepage. Only used for decorative purposes.

--endpoint-bytes-size-limit

Maximum number of bytes allowed in the /bytes endpoint.

License

Httpbun is distributed with the Apache-2.0 License. Please refer to the LICENSE and NOTICE files present in the source distribution of this project.

Credits

1. httpbin. This project might not have existed, if not for httpbin.
2. Go's excellent documentation. This project might've taken a hell of a lot longer, if not for Go's docs.

The bun icon was generated using the following graphics from Twitter Twemoji:

• Graphics Title: 1fad3.svg.
• Graphics Author: Copyright 2020 Twitter, Inc and other contributors.
• Graphics Source.
• Graphics License: CC-BY 4.0.