{"id":30615279,"url":"https://github.com/alexfalkowski/status","last_synced_at":"2026-06-13T23:03:19.462Z","repository":{"id":205081908,"uuid":"713368946","full_name":"alexfalkowski/status","owner":"alexfalkowski","description":"An alternative to https://httpstat.us/.","archived":false,"fork":false,"pushed_at":"2026-06-08T18:21:08.000Z","size":2458,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-06-08T20:13:52.194Z","etag":null,"topics":["cucumber","golang","make","ruby"],"latest_commit_sha":null,"homepage":"https://alexfalkowski.github.io/status","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/alexfalkowski.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2023-11-02T11:34:11.000Z","updated_at":"2026-06-08T18:19:01.000Z","dependencies_parsed_at":"2024-03-31T09:26:02.496Z","dependency_job_id":"b4c82c78-36f2-42b8-be81-25cbb92fb203","html_url":"https://github.com/alexfalkowski/status","commit_stats":null,"previous_names":["alexfalkowski/status"],"tags_count":904,"template":false,"template_full_name":null,"purl":"pkg:github/alexfalkowski/status","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfalkowski%2Fstatus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfalkowski%2Fstatus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfalkowski%2Fstatus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfalkowski%2Fstatus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alexfalkowski","download_url":"https://codeload.github.com/alexfalkowski/status/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alexfalkowski%2Fstatus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34303281,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-13T02:00:06.617Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["cucumber","golang","make","ruby"],"created_at":"2025-08-30T08:01:42.967Z","updated_at":"2026-06-13T23:03:19.454Z","avatar_url":"https://github.com/alexfalkowski.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![CircleCI](https://circleci.com/gh/alexfalkowski/status.svg?style=svg)](https://circleci.com/gh/alexfalkowski/status)\n[![codecov](https://codecov.io/gh/alexfalkowski/status/graph/badge.svg?token=G6T3OIWUFK)](https://codecov.io/gh/alexfalkowski/status)\n[![Go Report Card](https://goreportcard.com/badge/github.com/alexfalkowski/status)](https://goreportcard.com/report/github.com/alexfalkowski/status)\n[![Go Reference](https://pkg.go.dev/badge/github.com/alexfalkowski/status.svg)](https://pkg.go.dev/github.com/alexfalkowski/status)\n[![Stability: Active](https://masterminds.github.io/stability/active.svg)](https://masterminds.github.io/stability/active.html)\n\n# 🩺 Status\n\n`status` is a small Go service for testing HTTP status-code handling and health endpoints.\nIt is intended as a local, controllable alternative to depending on \u003chttps://httpstat.us/\u003e\nfrom automated tests.\n\n\u003e [!NOTE]\n\u003e This service is built for test fixtures, smoke tests, and client behavior checks. It is not a general-purpose public status-code proxy.\n\n## 🧭 Background\n\nExternal status-code services are useful, but their availability can make an\notherwise deterministic test suite fail for reasons outside the project under\ntest. Running this service locally keeps status-code and observability checks\nunder your control.\n\n## ⚡ Quick Start\n\nAfter cloning the repository, initialize the shared `bin` submodule and install\ndependencies:\n\n```sh\ngit submodule update --init\nmake dep\n```\n\nBuild and run the service with the local test configuration:\n\n```sh\nmake build\n./status server -i file:test/.config/server.yml\n```\n\nThe local configuration binds the HTTP server to `localhost:11000`, so you can\ntry it with:\n\n```sh\ncurl -i http://localhost:11000/v1/status/200\ncurl -i \"http://localhost:11000/v1/status/503?sleep=50ms\"\n```\n\n\u003e [!IMPORTANT]\n\u003e The root `Makefile` includes files from the `bin` submodule. Run `git submodule update --init` before using `make` in a fresh checkout.\n\n\u003e [!TIP]\n\u003e If you have `air` installed, `make dev` builds and runs the server in watch mode with `test/.config/server.yml`.\n\n## 🖥️ Server\n\n### 🔢 Status Code\n\nReturns the requested HTTP status code.\n\n#### 📥 Request\n\n```http\nGET /v1/status/{code}\nGET /v1/status/{code}?sleep=50ms\n```\n\n\u003e [!NOTE]\n\u003e `code` must parse as an integer from `200` through `999`. Values below `200`, values above `999`, and non-numeric values return `400 Bad Request`.\n\n| Parameter | Location | Required | Description |\n| --------- | -------- | -------- | ----------- |\n| `code` | Path | Yes | Status code to return. Named codes include their standard reason phrase, such as `200 OK`. |\n| `sleep` | Query | No | Delay before returning the response. Parsed with Go's [`time.ParseDuration`](https://pkg.go.dev/time#ParseDuration), for example `50ms`, `1s`, or `2m`. Must be less than or equal to the effective `max_sleep`. |\n\n\u003e [!CAUTION]\n\u003e `sleep` intentionally delays the response. Keep durations short in tests so client timeouts and CI jobs do not wait longer than expected.\n\n#### 📤 Response\n\nThe response status is the requested code and the body is plain text:\n\n```http\n200 OK\n```\n\nFor codes without a standard reason phrase, the body contains the numeric code:\n\n```http\n999\n```\n\nInvalid status codes or invalid `sleep` values return `400 Bad Request`.\n\nThe maximum accepted sleep duration defaults to `5m`. Configure a lower maximum with:\n\n```yaml\nmax_sleep: 2m\n```\n\nWhen set, `max_sleep` must be greater than `0` and less than or equal to `5m`.\n\n## 💓 Health\n\nThe shared health module exposes health, liveness, readiness, and metrics\nendpoints over HTTP:\n\n| Endpoint | Check | Healthy response |\n| -------- | ----- | ---------------- |\n| `/healthz` | Online connectivity | `SERVING` |\n| `/livez` | No-op liveness check | `SERVING` |\n| `/readyz` | No-op readiness check | `SERVING` |\n| `/metrics` | Prometheus metrics | Metrics including `go_info` |\n\n\u003e [!WARNING]\n\u003e `/healthz` uses the shared online health registration, which checks external internet connectivity by default. In an offline environment, prefer `/livez` or `/readyz` for local process checks.\n\nConfigure health check timing with:\n\n```yaml\nhealth:\n  duration: 1s\n  timeout: 1s\n```\n\nThe repository's local configuration is in `test/.config/server.yml`.\n\n## 🚢 Deployment\n\nThe service builds as a single binary and can also be built into a Docker image\nthrough the shared make targets. In production-like environments, run it behind\nyour normal container orchestration and health-check configuration.\n\n## 🛠️ Development\n\n### 🧱 Structure\n\nThe project follows the common Go service layout:\n\n| Path | Purpose |\n| ---- | ------- |\n| `main.go` | CLI bootstrap. |\n| `internal/cmd/` | Server command registration and module wiring. |\n| `internal/config/` | Application config layered on `github.com/alexfalkowski/go-service/v2/config`. |\n| `internal/api/v1/transport/http/` | HTTP route registration for `/v1/status/{code}`. |\n| `internal/health/` | Health registration and HTTP observers. |\n| `test/` | Ruby nonnative/cucumber integration tests and benchmark harness. |\n\n### 📦 Dependencies\n\nInstall these before running the full local workflow:\n\n- Go `1.26.0`, as declared in `go.mod`.\n- Ruby and Bundler for the `test/` harness.\n- The `bin` submodule, initialized with `git submodule update --init`.\n\n### 🧰 Commands\n\nPrefer the exposed `make` targets from the repository root:\n\n| Command | Purpose |\n| ------- | ------- |\n| `make help` | Show available commands. |\n| `make dep` | Install Go and Ruby test dependencies. |\n| `make build` | Build the release binary named `status`. |\n| `make build-test` | Build the test binary with feature tags and coverage instrumentation. |\n| `make lint` | Lint Go and the Ruby test harness. |\n| `make specs` | Run Go tests with race and coverage reporting. |\n| `make features` | Run cucumber features against the local service. |\n| `make benchmarks` | Run cucumber benchmarks. |\n| `make coverage` | Generate HTML and function coverage reports. |\n| `make sec` | Run configured security checks. |\n| `make dev` | Run the server in watch mode with `air`. |\n\n\u003e [!CAUTION]\n\u003e Some shared git helper targets are intentionally destructive, including `make reset`, `make purge`, and branch deletion helpers. Use `make help` and inspect the target before running shared git workflow commands.\n\n### ✅ Validation\n\nThe main CircleCI `build-service` job runs:\n\n```sh\nmake clean\nmake dep\nmake lint\nmake sec\nmake features\nmake benchmarks\nmake analyse\nmake coverage\n```\n\nFor a local documentation-only change, `make help` is a useful smoke check that\nthe documented command surface is still available.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexfalkowski%2Fstatus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falexfalkowski%2Fstatus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falexfalkowski%2Fstatus/lists"}