Mix User Guide — Httpbun

The /mix API endpoint lets us construct URLs with very specific and flexible behaviours. The /mixer is a small and convenient UI to help with creating such /mix URLs. This document is both and introduction, and a reference for the directives available.

This is best illustrated with examples. Consider the following URL:

https://httpbun.com/mix/s=401

This URL responds with the status 401, exactly like the /status/401 endpoint. Now consider this:

https://httpbun.com/mix/s=200/h=x-custom-key:some-value

This URL responds with the status 401, and with the response header X-Custom-Key: some-value as well. Such flexibility isn’t possible with the /status endpoint, or any other endpoint.

In the URLs above, the s= and h=, are termed directives. There’s several directives supported by /mix today. They can all be used together with each other, producing surprisingly versatile and useful endpoints. For another example:

http://localhost:3090/mix/s=401/h=content-type:text%2Fhtml/b64=PHNjcmlwdD5hbGVydCg0Mik8L3NjcmlwdD4=

This URL responds with status 401, content type as text/html, and the response body containing just <script>alert(42)</script> in it. This URL is suddenly handy to test an API client’s XSS protection from such responses.

Directive s

• 1️⃣ Non-repeatable.
• Syntax: /s=200, or /s=200,400,500.
• Mnemonic: Status.

This is the status directive. It can take a single status number, like 200, 400 etc., and the /mix URL will respond with that status code. This can also be a CSV of multiple numbers, like 200,400,500, in which case the response status will be a random choice among them.

Directive h

• ♾️ Repeatable.
• Syntax: /h=key:value.
• Example: h=content-type:text%2Fhtml.
• Mnemonic: Header.

This is for adding headers to the response. The header key and value must be separated by a :. Any special characters, especially / and :, must be URL encoded. For example, if wanted text/html as the header value, we have to use text%2Fhtml in the /mix URL. The Mixer UI can handle this encoding automatically.

Directive c

• ♾️ Repeatable.
• Syntax: /c=name:value.
• Example: /c=email:me%40example.com.
• Mnemonic: Cookie.

The response will set a cookie, with given name and value. Essentially, this works by sending a Set-Cookie: name=value; Path=/ header in the response. Nothing that can’t already be achieved with the h directive, but this exists for convenience.

Directive cd

• ♾️ Repeatable.
• Syntax: /cd=name.
• Example: /cd=email.
• Mnemonic: Cookie Delete.

Deletes the cookie with the given name. Essentially, this works by sending a Set-Cookie header with this name, and expiry date set to 1-Jan-1970, so the cookie will be immediately deemed expired, and generally deleted by clients.

Directive r

• 1️⃣ Non-repeatable.
• Syntax: /r=encoded-url-here.
• Example: /r=https%3A%2F%2Fsharats.me.
• Mnemonic: Redirect.

Responds with a redirect to the given URL. This is the same as /mix/s=301/h:Location=url-here, but exists for the convenience. To control the response states used, use a separate s directive method instead.

Directive d

• 1️⃣ Non-repeatable.
• Syntax: /d=number-of-seconds.
• Example: /d=10.
• Mnemonic: Delay.

Delays response from the server by given number of seconds. Decimal point values are allowed. Must be between 0 and 10.

Directive b64

• 1️⃣ Non-repeatable.
• Syntax: /b64=body-base64-encoded.
• Example: /b64=aGVsbG8=.
• Mnemonic: Base64 Body.

The body of the response will be the base64-decoded content of the given value. The given value has to be valid base64-encoded data, including trailing = if applicable.

Directive t

• 1️⃣ Non-repeatable.
• Syntax: /t=golang-text-template-base64-encoded.
• Example: /t=e3siSGVsbG8gdGhlcmUhIn19.
• Mnemonic: Template.

The given value is base64-decoded, and the result is expected to be a valid Golang text template. This template will be rendered, and the result will be the response body.

This is a very powerful directive, and offers rich and creative ways of constructing the response body. This directive is very much beta, and the API is subject to change (or disappear) with little notice.

Directive end

• 1️⃣ Non-repeatable.
• Syntax: /end.

This directive is unlike the others. It doesn’t take a value after an = sign, and it indicates the end of directive processing. For example, in /s=400/end/d=5, the response status will be 400, but a delay of 5s won’t be applied. But in /s=400/d=5/end, both status and delay will be applicable in the response behaviour.

This directive is useful when we have to submit a URL to a client, that then appends more path to the end of it, which we want Httpbun to ignore.

Template API

This is the reference for APIs available in the t directive. Note that the whole t directive itself, is very beta, very up-in-the-air, and may even disappear one day. It’s an experiment only, for now.

Function seq

A function that produces a list of sequential numbers. Can take one, two or three numeric parameters.

1. One number argument: Generate natural numbers from 0 (including) to the given number (excluding), incremented by 1. Example: seq 5 → [0 1 2 3 4].
2. Two number arguments: Generate natural numbers from the first number (including) to the second number (excluding), incremented by 1 if first < second or -1 otherwise. Example:seq 3 7 → [3 4 5 6].
3. Three number arguments: Generate natural numbers from the first number (including) to the second number (excluding), incremented by the third number.seq 2 13 3 → [2 5 8 11].

Each item in the returned list is an object, with the following keys:

• N: the number represented by this item in the generated list.
• IsFirst: If this item is the very first item in the generated list, this is true.
• IsLast: Similar to above, but for the very last item.

Function toJSON

Takes a single argument, of any type, and attempts to serialise it to JSON. Returns the JSON string.

{{seq 3 | toJSON}}

Produces:

[
  {
    "N": 0,
    "IsFirst": true,
    "IsLast": false
  },
  {
    "N": 1,
    "IsFirst": false,
    "IsLast": false
  },
  {
    "N": 2,
    "IsFirst": false,
    "IsLast": false
  }
]