Skip to content
Snippets Groups Projects
Select Git revision
  • 6f5e5344d24c69d624afe253afe2c10e735cf8d0
  • main default protected
  • drip-server-timing
  • compress-middleware
  • v2.11.0
  • v2.10.0
  • v2.9.2
  • v2.9.1
  • v2.9.0
  • v2.8.0
  • v2.7.0
  • v2.6.0
  • v2.5.6
  • v2.5.5
  • v2.5.4
  • v2.5.3
  • v2.5.2
  • v2.5.1
  • v2.5.0
  • v2.4.2
  • v2.4.1
  • v2.4.0
  • v2.3.0
  • v2.2.2
24 results

go-httpbin

  • Clone with SSH
  • Clone with HTTPS
  • user avatar
    Bill Mill authored and GitHub committed
    `go-httpbin` was incorrectly returning `http` as the scheme for its URL
    if you ran it with TLS specified via `HTTPS_CERT_FILE` and
    `HTTPS_KEY_FILE`. Update it to return https as the scheme in this case
    by checking if `r.TLS` is not nil
    
    Before:
    
    ```
    $ mkcert test
    $ docker run -e HTTPS_CERT_FILE='/tmp/test.pem' -e HTTPS_KEY_FILE='/tmp/test-key.pem' -p 8080:8080 -v $(pwd):/tmp mccutchen/go-httpbin
    $ curl -sk https://localhost:8080/get | jq -r .url
    http://localhost:8080/get
    ```
    
    After (TLS):
    
    ```
    $ docker run -e HTTPS_CERT_FILE='/tmp/test.pem' -e HTTPS_KEY_FILE='/tmp/test-key.pem' -p 8080:8080 -v $(pwd):/tmp llimllib/go-httpbin
    $ curl -sk https://localhost:8080/get | jq -r .url
    https://localhost:8080/get
    ```
    
    After (no TLS):
    
    ```
    $ docker run -p 8080:8080 llimllib/go-httpbin
    $ curl -sk http://localhost:8080/get | jq -r .url
    http://localhost:8080/get
    ```
    
    I got the idea for how to check the scheme from [this SO
    post](https://stackoverflow.com/a/61446922/42559)
    6f5e5344
    History

    go-httpbin

    A reasonably complete and well-tested golang port of Kenneth Reitz's httpbin service, with zero dependencies outside the go stdlib.

    GoDoc Build status Coverage Docker Pulls

    Usage

    Docker

    Docker images are published to Docker Hub:

    # Run http server
    $ docker run -P mccutchen/go-httpbin
    
    # Run https server
    $ docker run -e HTTPS_CERT_FILE='/tmp/server.crt' -e HTTPS_KEY_FILE='/tmp/server.key' -p 8080:8080 -v /tmp:/tmp mccutchen/go-httpbin

    Standalone binary

    Follow the Installation instructions to install go-httpbin as a standalone binary. (This currently requires a working Go runtime.)

    Examples:

    # Run http server
    $ go-httpbin -host 127.0.0.1 -port 8081
    
    # Run https server
    $ openssl genrsa -out server.key 2048
    $ openssl ecparam -genkey -name secp384r1 -out server.key
    $ openssl req -new -x509 -sha256 -key server.key -out server.crt -days 3650
    $ go-httpbin -host 127.0.0.1 -port 8081 -https-cert-file ./server.crt -https-key-file ./server.key

    Unit testing helper library

    The github.com/mccutchen/go-httpbin/httpbin/v2 package can also be used as a library for testing an application's interactions with an upstream HTTP service, like so:

    package httpbin_test
    
    import (
    	"net/http"
    	"net/http/httptest"
    	"os"
    	"testing"
    	"time"
    
    	"github.com/mccutchen/go-httpbin/v2/httpbin"
    )
    
    func TestSlowResponse(t *testing.T) {
    	app := httpbin.New()
    	testServer := httptest.NewServer(app)
    	defer testServer.Close()
    
    	client := http.Client{
    		Timeout: time.Duration(1 * time.Second),
    	}
    
    	_, err := client.Get(testServer.URL + "/delay/10")
    	if !os.IsTimeout(err) {
    		t.Fatalf("expected timeout error, got %s", err)
    	}
    }

    Configuration

    go-httpbin can be configured via either command line arguments or environment variables (or a combination of the two):

    Argument Env var Documentation Default
    -allowed-redirect-domains ALLOWED_REDIRECT_DOMAINS Comma-separated list of domains the /redirect-to endpoint will allow
    -host HOST Host to listen on "0.0.0.0"
    -https-cert-file HTTPS_CERT_FILE HTTPS Server certificate file
    -https-key-file HTTPS_KEY_FILE HTTPS Server private key file
    -max-body-size MAX_BODY_SIZE Maximum size of request or response, in bytes 1048576
    -max-duration MAX_DURATION Maximum duration a response may take 10s
    -port PORT Port to listen on 8080
    -use-real-hostname USE_REAL_HOSTNAME Expose real hostname as reported by os.Hostname() in the /hostname endpoint false

    Notes:

    • Command line arguments take precedence over environment variables.
    • See Production considerations for recommendations around safe configuration of public instances of go-httpbin

    Installation

    To add go-httpbin to an existing golang project:

    go get -u github.com/mccutchen/go-httpbin/v2

    To install the go-httpbin binary:

    go install github.com/mccutchen/go-httpbin/v2/cmd/go-httpbin

    Production considerations

    Before deploying an instance of go-httpbin on your own infrastructure on the public internet, consider tuning it appropriately:

    1. Restrict the domains to which the /redirect-to endpoint will send traffic to avoid the security issues of an open redirect

      Use the -allowed-redirect-domains CLI argument or the ALLOWED_REDIRECT_DOMAINS env var to configure an appropriate allowlist.

    2. Tune per-request limits

      Because go-httpbin allows clients send arbitrary data in request bodies and control the duration some requests (e.g. /delay/60s), it's important to properly tune limits to prevent misbehaving or malicious clients from taking too many resources.

      Use the -max-body-size/MAX_BODY_SIZE and -max-duration/MAX_DURATION CLI arguments or env vars to enforce appropriate limits on each request.

    3. Decide whether to expose real hostnames in the /hostname endpoint

      By default, the /hostname endpoint serves a dummy hostname value, but it can be configured to serve the real underlying hostname (according to os.Hostname()) using the -use-real-hostname CLI argument or the USE_REAL_HOSTNAME env var to enable this functionality.

      Before enabling this, ensure that your hostnames do not reveal too much about your underlying infrastructure.

    4. Add custom instrumentation

      By default, go-httpbin logs basic information about each request. To add more detailed instrumentation (metrics, structured logging, request tracing), you'll need to wrap this package in your own code, which you can then instrument as you would any net/http server. Some examples:

    Development

    # local development
    make
    make test
    make testcover
    make run
    
    # building & pushing docker images
    make image
    make imagepush

    Motivation & prior art

    I've been a longtime user of Kenneith Reitz's original httpbin.org, and wanted to write a golang port for fun and to see how far I could get using only the stdlib.

    When I started this project, there were a handful of existing and incomplete golang ports, with the most promising being ahmetb/go-httpbin. This project showed me how useful it might be to have an httpbin library available for testing golang applications.

    Known differences from other httpbin versions

    Compared to the original:

    • No /brotli endpoint (due to lack of support in Go's stdlib)
    • The ?show_env=1 query param is ignored (i.e. no special handling of runtime environment headers)
    • Response values which may be encoded as either a string or a list of strings will always be encoded as a list of strings (e.g. request headers, query params, form values)

    Compared to ahmetb/go-httpbin:

    • No dependencies on 3rd party packages
    • More complete implementation of endpoints