{"id":13521338,"url":"https://github.com/mccutchen/go-httpbin","last_synced_at":"2026-01-07T22:13:19.215Z","repository":{"id":10745797,"uuid":"66816998","full_name":"mccutchen/go-httpbin","owner":"mccutchen","description":"A reasonably complete and well-tested golang port of httpbin, with zero dependencies outside the go stdlib.","archived":false,"fork":false,"pushed_at":"2025-04-04T11:26:02.000Z","size":943,"stargazers_count":647,"open_issues_count":12,"forks_count":132,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-12T05:59:42.373Z","etag":null,"topics":["golang","http","httpbin","testing"],"latest_commit_sha":null,"homepage":"https://httpbingo.org","language":"Go","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/mccutchen.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":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-08-29T06:20:42.000Z","updated_at":"2025-04-11T16:38:37.000Z","dependencies_parsed_at":"2023-02-16T15:15:43.772Z","dependency_job_id":"f5000bea-e743-4da2-a471-418c0ef3c0f0","html_url":"https://github.com/mccutchen/go-httpbin","commit_stats":null,"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mccutchen%2Fgo-httpbin","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mccutchen%2Fgo-httpbin/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mccutchen%2Fgo-httpbin/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mccutchen%2Fgo-httpbin/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mccutchen","download_url":"https://codeload.github.com/mccutchen/go-httpbin/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254041783,"owners_count":22004770,"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":["golang","http","httpbin","testing"],"created_at":"2024-08-01T06:00:32.925Z","updated_at":"2026-01-07T22:13:19.210Z","avatar_url":"https://github.com/mccutchen.png","language":"Go","readme":"# go-httpbin\n\nA reasonably complete and well-tested golang port of [Kenneth Reitz][kr]'s\n[httpbin][httpbin-org] service, with zero dependencies outside the go stdlib.\n\n[![GoDoc](https://pkg.go.dev/badge/github.com/mccutchen/go-httpbin/v2)](https://pkg.go.dev/github.com/mccutchen/go-httpbin/v2)\n[![Build status](https://github.com/mccutchen/go-httpbin/actions/workflows/ci.yaml/badge.svg)](https://github.com/mccutchen/go-httpbin/actions/workflows/ci.yaml)\n[![Coverage](https://codecov.io/gh/mccutchen/go-httpbin/branch/main/graph/badge.svg)](https://codecov.io/gh/mccutchen/go-httpbin)\n[![Docker Pulls](https://badgen.net/docker/pulls/mccutchen/go-httpbin?icon=docker\u0026label=pulls)](https://hub.docker.com/r/mccutchen/go-httpbin/)\n\n\n## Usage\n\n### Docker/OCI images\n\nPrebuilt images for the `linux/amd64` and `linux/arm64` architectures are\nautomatically published to these public registries for every tagged release:\n- [ghcr.io/mccutchen/go-httpbin][ghcr] (recommended)\n- [mccutchen/go-httpbin][docker-hub]\n\n```bash\n$ docker run -P ghcr.io/mccutchen/go-httpbin\n```\n\n\u003e [!NOTE]\n\u003e Prebuilt image versions \u003e= 2.19.0 run as a non-root user by default. See\n\u003e [Configuring non-root docker images](#configuring-non-root-docker-images)\n\u003e below for details.\n\n### Kubernetes\n\n```\n$ kubectl apply -k github.com/mccutchen/go-httpbin/kustomize\n```\n\nSee `./kustomize` directory for further information\n\n### Standalone binary\n\nFollow the [Installation](#installation) instructions to install go-httpbin as\na standalone binary, or use `go run` to install it on demand:\n\nExamples:\n\n```bash\n# Run http server\n$ go run github.com/mccutchen/go-httpbin/v2/cmd/go-httpbin@latest -host 127.0.0.1 -port 8081\n\n# Run https server\n$ openssl genrsa -out server.key 2048\n$ openssl ecparam -genkey -name secp384r1 -out server.key\n$ openssl req -new -x509 -sha256 -key server.key -out server.crt -days 3650\n$ go run github.com/mccutchen/go-httpbin/v2/cmd/go-httpbin@latest -host 127.0.0.1 -port 8081 -https-cert-file ./server.crt -https-key-file ./server.key\n```\n\n### Unit testing helper library\n\nThe `github.com/mccutchen/go-httpbin/httpbin/v2` package can also be used as a\nlibrary for testing an application's interactions with an upstream HTTP\nservice, like so:\n\n```go\npackage httpbin_test\n\nimport (\n\t\"net/http\"\n\t\"net/http/httptest\"\n\t\"os\"\n\t\"testing\"\n\t\"time\"\n\n\t\"github.com/mccutchen/go-httpbin/v2/httpbin\"\n)\n\nfunc TestSlowResponse(t *testing.T) {\n\tapp := httpbin.New()\n\ttestServer := httptest.NewServer(app)\n\tdefer testServer.Close()\n\n\tclient := http.Client{\n\t\tTimeout: time.Duration(1 * time.Second),\n\t}\n\n\t_, err := client.Get(testServer.URL + \"/delay/10\")\n\tif !os.IsTimeout(err) {\n\t\tt.Fatalf(\"expected timeout error, got %s\", err)\n\t}\n}\n```\n\n### GitHub Actions/Workflows\n\nThe 3rd-party [lfreleng-actions/go-httpbin-action][] action is an easy way\nto make a local instance of go-httpbin available to other steps in a GitHub\nActions workflow.\n\n## Configuration\n\ngo-httpbin can be configured via either command line arguments or environment\nvariables (or a combination of the two):\n\n| Argument| Env var | Documentation | Default |\n| - | - | - | - |\n| `-allowed-redirect-domains` | `ALLOWED_REDIRECT_DOMAINS` | Comma-separated list of domains the /redirect-to endpoint will allow | |\n| `-exclude-headers` | `EXCLUDE_HEADERS` | Drop platform-specific headers. Comma-separated list of headers key to drop, supporting wildcard suffix matching. For example: `\"foo,bar,x-fc-*\"` | - |\n| `-host` | `HOST` | Host to listen on | \"0.0.0.0\" |\n| `-https-cert-file` | `HTTPS_CERT_FILE` | HTTPS Server certificate file | |\n| `-https-key-file` | `HTTPS_KEY_FILE` | HTTPS Server private key file | |\n| `-log-format` | `LOG_FORMAT` | Log format (text or json) | \"text\" |\n| `-max-body-size` | `MAX_BODY_SIZE` | Maximum size of request or response, in bytes | 1048576 |\n| `-max-duration` | `MAX_DURATION` | Maximum duration a response may take | 10s |\n| `-port` | `PORT` | Port to listen on | 8080 |\n| `-prefix` | `PREFIX` | Prefix of path to listen on (must start with slash and does not end with slash) | |\n| `-srv-max-header-bytes` | `SRV_MAX_HEADER_BYTES` | Value to use for the http.Server's MaxHeaderBytes option | 16384 |\n| `-srv-read-header-timeout` | `SRV_READ_HEADER_TIMEOUT` | Value to use for the http.Server's ReadHeaderTimeout option | 1s |\n| `-srv-read-timeout` | `SRV_READ_TIMEOUT` | Value to use for the http.Server's ReadTimeout option | 5s |\n| `-use-real-hostname` | `USE_REAL_HOSTNAME` | Expose real hostname as reported by os.Hostname() in the /hostname endpoint | false |\n\n\u003e [!WARNING]\n\u003e These configuration options are dangerous and/or deprecated and should be\n\u003e avoided unless backwards compatibility is absolutely required.\n\n| Argument| Env var | Documentation | Default |\n| - | - | - | - |\n| `-unsafe-allow-dangerous-responses` | `UNSAFE_ALLOW_DANGEROUS_RESPONSES` | Allow endpoints to return unescaped HTML when clients control response Content-Type (enables XSS attacks) | false |\n\n**Notes:**\n- Command line arguments take precedence over environment variables.\n- See [Production considerations] for recommendations around safe configuration\n  of public instances of go-httpbin\n\n#### Configuring non-root docker images\n\nPrebuilt image versions \u003e= 2.19.0 run as a non-root user by default to improve\ncontainer security at the cost of additional complexity for some non-standard\ndeployments:\n\n- To run the go-httpbin image a) on a privileged port (i.e. below 1024) _and_\n  b) using the Docker host network, you may need to run the container as root\n  in order to enable the `CAP_NET_BIND_SERVICE` capability:\n\n  ```bash\n  $ docker run \\\n    --network host \\\n    --user root \\\n    --cap-drop ALL \\\n    --cap-add CAP_NET_BIND_SERVICE \\\n    ghcr.io/mccutchen/go-httpbin \\\n    /bin/go-httpbin -port=80\n  ```\n\n- If you enable HTTPS directly in the image, make sure that the certificate\n  and private key files are readable by the user running the process:\n\n  ```bash\n  $ chmod 644 /tmp/server.crt\n  $ chmod 640 /tmp/server.key\n  # GID 65532: primary group of the nonroot user in distroless/static:nonroot.\n  $ chown root:65532 /tmp/server.crt /tmp/server.key\n  ```\n\n## Installation\n\nTo add go-httpbin as a dependency to an existing golang project (e.g. for use\nin unit tests):\n\n```\ngo get -u github.com/mccutchen/go-httpbin/v2\n```\n\nTo install the `go-httpbin` binary:\n\n```\ngo install github.com/mccutchen/go-httpbin/v2/cmd/go-httpbin@latest\n```\n\n\n## Production considerations\n\nBefore deploying an instance of go-httpbin on your own infrastructure on the\npublic internet, consider tuning it appropriately:\n\n1. **Restrict the domains to which the `/redirect-to` endpoint will send\n   traffic to avoid the security issues of an open redirect**\n\n   Use the `-allowed-redirect-domains` CLI argument or the\n   `ALLOWED_REDIRECT_DOMAINS` env var to configure an appropriate allowlist.\n\n2. **Tune per-request limits**\n\n   Because go-httpbin allows clients send arbitrary data in request bodies and\n   control the duration some requests (e.g. `/delay/60s`), it's important to\n   properly tune limits to prevent misbehaving or malicious clients from taking\n   too many resources.\n\n   Use the `-max-body-size`/`MAX_BODY_SIZE` and `-max-duration`/`MAX_DURATION`\n   CLI arguments or env vars to enforce appropriate limits on each request.\n\n3. **Decide whether to expose real hostnames in the `/hostname` endpoint**\n\n   By default, the `/hostname` endpoint serves a dummy hostname value, but it\n   can be configured to serve the real underlying hostname (according to\n   `os.Hostname()`) using the `-use-real-hostname` CLI argument or the\n   `USE_REAL_HOSTNAME` env var to enable this functionality.\n\n   Before enabling this, ensure that your hostnames do not reveal too much\n   about your underlying infrastructure.\n\n4. **Add custom instrumentation**\n\n   By default, go-httpbin logs basic information about each request. To add\n   more detailed instrumentation (metrics, structured logging, request\n   tracing), you'll need to wrap this package in your own code, which you can\n   then instrument as you would any net/http server. Some examples:\n\n   - [examples/custom-instrumentation] instruments every request using DataDog,\n     based on the built-in [Observer] mechanism.\n\n   - [mccutchen/httpbingo.org] is the code that powers the public instance of\n     go-httpbin deployed to [httpbingo.org], which adds customized structured\n     logging using [zerolog] and further hardens the HTTP server against\n     malicious clients by tuning lower-level timeouts and limits.\n\n5. **Prevent leaking sensitive headers**\n\n   By default, go-httpbin will return any request headers sent by the client\n   (and any intermediate proxies) in the response. If go-httpbin is deployed\n   into an environment where some incoming request headers might reveal\n   sensitive information, use the `-exclude-headers` CLI argument or\n   `EXCLUDE_HEADERS` env var to configure a denylist of sensitive header keys.\n\n   For example, the Alibaba Cloud Function Compute platform adds\n   [a variety of `x-fc-*` headers][alibaba-headers] to each incoming request,\n   some of which might be sensitive. To have go-httpbin filter **all** of these\n   headers in its own responses, set:\n\n       EXCLUDE_HEADERS=\"x-fc-*\"\n\n   To have go-httpbin filter only specific headers, you can get more specific:\n\n       EXCLUDE_HEADERS=\"x-fc-access-key-*,x-fc-security-token,x-fc-region\"\n\n## Development\n\nSee [DEVELOPMENT.md][].\n\n## Security\n\nSee [SECURITY.md][].\n\n## Motivation \u0026 prior art\n\nI've been a longtime user of [Kenneith Reitz][kr]'s original\n[httpbin.org][httpbin-org], and wanted to write a golang port for fun and to\nsee how far I could get using only the stdlib.\n\nWhen I started this project, there were a handful of existing and incomplete\ngolang ports, with the most promising being [ahmetb/go-httpbin][ahmet]. This\nproject showed me how useful it might be to have an `httpbin` _library_\navailable for testing golang applications.\n\n### Known differences from other httpbin versions\n\nCompared to [the original][httpbin-org]:\n - No `/brotli` endpoint (due to lack of support in Go's stdlib)\n - The `?show_env=1` query param is ignored (i.e. no special handling of\n   runtime environment headers)\n - Response values which may be encoded as either a string or a list of strings\n   will always be encoded as a list of strings (e.g. request headers, query\n   params, form values)\n\nCompared to [ahmetb/go-httpbin][ahmet]:\n - No dependencies on 3rd party packages\n - More complete implementation of endpoints\n\n\n[ahmet]: https://github.com/ahmetb/go-httpbin\n[alibaba-headers]: https://www.alibabacloud.com/help/en/fc/user-guide/specification-details#section-3f8-5y1-i77\n[DEVELOPMENT.md]: ./DEVELOPMENT.md\n[docker-hub]: https://hub.docker.com/r/mccutchen/go-httpbin/\n[examples/custom-instrumentation]: ./examples/custom-instrumentation/\n[ghcr]: https://github.com/mccutchen/go-httpbin/pkgs/container/go-httpbin\n[httpbin-org]: https://httpbin.org/\n[httpbin-repo]: https://github.com/kennethreitz/httpbin\n[httpbingo.org]: https://httpbingo.org/\n[kr]: https://github.com/kennethreitz\n[mccutchen/httpbingo.org]: https://github.com/mccutchen/httpbingo.org\n[Observer]: https://pkg.go.dev/github.com/mccutchen/go-httpbin/v2/httpbin#Observer\n[Production considerations]: #production-considerations\n[SECURITY.md]: ./SECURITY.md\n[zerolog]: https://github.com/rs/zerolog\n[lfreleng-actions/go-httpbin-action]: https://github.com/lfreleng-actions/go-httpbin-action/\n","funding_links":[],"categories":["Testing","Go","Template Engines","Members","测试"],"sub_categories":["Testing Frameworks"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmccutchen%2Fgo-httpbin","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmccutchen%2Fgo-httpbin","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmccutchen%2Fgo-httpbin/lists"}